chore: replace hard-coded -1 sentinels with named constexpr constants

src/include/mx/api/ApiCommon.h

@@ -24,6 +24,14 @@ inline bool areSame(Double left, Double right)
 constexpr int DEFAULT_TICKS_PER_QUARTER = 3 * 4 * 5 * 7;
 constexpr int TICK_TIME_INFINITY = std::numeric_limits<int>::max();
 
+// Named sentinels for legacy fields that predate std::optional, where -1 (or -1.0) means
+// "unspecified" or "absent". Do not use these for new fields; new absent-able fields use
+// std::optional instead (see "mx::api conventions" in AGENTS.md and issue #249).
+constexpr int INDEX_UNSPECIFIED = -1;        // staff/part indices and numbers, e.g. KeyData::staffIndex
+constexpr int NUMBER_LEVEL_UNSPECIFIED = -1; // MusicXML 'number' attributes, e.g. SpannerStart::numberLevel
+constexpr int VALUE_UNSPECIFIED = -1;        // other absent-able ints, e.g. DirectionData::voice
+constexpr Double DOUBLE_UNSPECIFIED = -1.0;  // absent-able doubles, e.g. StaffData::staffSize
+
 // Intentional ternary: absent-able bools use Bool::unspecified, not std::optional<bool>.
 // See "mx::api conventions" in AGENTS.md.
 enum class Bool

src/include/mx/api/CurveData.h

@@ -100,8 +100,9 @@ struct CurveStart
     ColorData colorData;
 
     CurveStart(CurveType inCurveType)
-        : curveType{inCurveType}, numberLevel{-1}, curvePoints{}, curveOrientation{CurveOrientation::unspecified},
-          placement{Placement::unspecified}, lineData{}, isColorSpecified{false}, colorData{}
+        : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{},
+          curveOrientation{CurveOrientation::unspecified}, placement{Placement::unspecified}, lineData{},
+          isColorSpecified{false}, colorData{}
     {
     }
 };
@@ -119,8 +120,8 @@ struct CurveContinue
     double bezierOffset2;
 
     CurveContinue(CurveType inCurveType)
-        : curveType{inCurveType}, numberLevel{-1}, curvePoints{}, isBezierX2Specified{false}, bezierX2{0.0},
-          isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}
+        : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{}, isBezierX2Specified{false},
+          bezierX2{0.0}, isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}
     {
     }
 };
@@ -131,7 +132,7 @@ struct CurveStop
     int numberLevel;
     CurvePoints curvePoints;
 
-    CurveStop(CurveType inCurveType) : curveType{inCurveType}, numberLevel{-1}, curvePoints{}
+    CurveStop(CurveType inCurveType) : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{}
     {
     }
 };

src/include/mx/api/DefaultsData.h

@@ -140,8 +140,8 @@ class DefaultsData
     MeasureNumbering measureNumbering;
 
     DefaultsData()
-        : scalingMillimeters{-1.0}, scalingTenths{-1.0}, pageLayout{}, systemLayout{}, appearance{}, musicFont{},
-          wordFont{}, lyricFonts{}, measureNumbering{MeasureNumbering::unspecified}
+        : scalingMillimeters{DOUBLE_UNSPECIFIED}, scalingTenths{DOUBLE_UNSPECIFIED}, pageLayout{}, systemLayout{},
+          appearance{}, musicFont{}, wordFont{}, lyricFonts{}, measureNumbering{MeasureNumbering::unspecified}
     {
     }
 };

src/include/mx/api/DirectionData.h

@@ -84,7 +84,7 @@ struct DirectionData
     // direction includes a default-x attribute, the offset value will be ignored when determining
     // the appearance of that element.
 
-    // voice value of -1 means unspecified
+    // a voice value of VALUE_UNSPECIFIED means unspecified
     int voice;
 
     // Direction elements are placed inside the StaffData object in mx api.  This would mean that
@@ -128,7 +128,7 @@ struct DirectionData
     std::vector<DirectionComponent> orderedComponents;
 
     DirectionData()
-        : tickTimePosition{0}, placement{Placement::unspecified}, voice{-1}, isStaffValueSpecified{true},
+        : tickTimePosition{0}, placement{Placement::unspecified}, voice{VALUE_UNSPECIFIED}, isStaffValueSpecified{true},
           isSoundDataSpecified{false}, soundData{}, marks{}, wedgeStarts{}, wedgeStops{}, ottavaStarts{}, ottavaStops{},
           bracketStarts{}, bracketStops{}, dashesStarts{}, dashesStops{}, pedalStarts{}, pedalStops{}, words{},
           chords{}, segnos{}

src/include/mx/api/EncodingData.h

@@ -44,7 +44,7 @@ class EncodingDate
     int month;
     int day;
 
-    EncodingDate() : year(-1), month(-1), day(-1)
+    EncodingDate() : year(VALUE_UNSPECIFIED), month(VALUE_UNSPECIFIED), day(VALUE_UNSPECIFIED)
     {
     }
 

src/include/mx/api/FiguredBassData.h

@@ -48,7 +48,7 @@ class FiguredBassData
     // The optional <duration>, in ticks. A value less than 0 means 'unspecified' (no duration child).
     int durationTimeTicks;
 
-    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{-1}
+    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{VALUE_UNSPECIFIED}
     {
     }
 };

src/include/mx/api/FontData.h

@@ -69,7 +69,7 @@ struct FontData
     int lineThrough;
 
     FontData()
-        : sizeType{FontSizeType::unspecified}, sizePoint{-1.0}, sizeCss{CssSize::unspecified},
+        : sizeType{FontSizeType::unspecified}, sizePoint{DOUBLE_UNSPECIFIED}, sizeCss{CssSize::unspecified},
           style{FontStyle::unspecified}, weight{FontWeight::unspecified}, fontFamily{}, underline{0}, overline{0},
           lineThrough{0}
     {

src/include/mx/api/KeyData.h

@@ -3,6 +3,7 @@
 // Distributed under the MIT License
 
 #pragma once
+#include "mx/api/ApiCommon.h"
 #include "mx/api/KeyComponent.h"
 
 namespace mx
@@ -66,7 +67,7 @@ struct KeyData
     // Supports changing the key somewhere other than at the start of a measure.
     int tickTimePosition;
 
-    // this value is optional. -1 means unspecified. when value is
+    // this value is optional. INDEX_UNSPECIFIED means unspecified. when value is
     // unspecified it means that the key signature applies to all staves
     // within the part
     int staffIndex;
@@ -77,7 +78,9 @@ struct KeyData
     // alterations. When custom is non-empty, then fifths and mode are ignored.
     std::vector<KeyComponent> nonTraditional;
 
-    KeyData() : fifths{0}, cancel{0}, mode{KeyMode::unspecified}, tickTimePosition{0}, staffIndex{-1}, nonTraditional{}
+    KeyData()
+        : fifths{0}, cancel{0}, mode{KeyMode::unspecified}, tickTimePosition{0}, staffIndex{INDEX_UNSPECIFIED},
+          nonTraditional{}
     {
     }
 };

src/include/mx/api/MeasureData.h

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/BarlineData.h"
 #include "mx/api/ClefData.h"
 #include "mx/api/DirectionData.h"
@@ -91,8 +92,9 @@ class MeasureData
     std::optional<PartSymbolData> partSymbol;
 
     MeasureData()
-        : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified}, multiMeasureRest{-1},
-          implicit{Bool::unspecified}, nonControlling{Bool::unspecified}, width{-1.0}
+        : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified},
+          multiMeasureRest{VALUE_UNSPECIFIED}, implicit{Bool::unspecified}, nonControlling{Bool::unspecified},
+          width{DOUBLE_UNSPECIFIED}
     {
     }
 };

src/include/mx/api/PageImageData.h

@@ -44,7 +44,8 @@ class PageImageData
     /// modeled here.)
     PositionData positionData;
 
-    PageImageData() : source{}, type{}, height{-1.0}, width{-1.0}, pageNumber{0}, positionData{}
+    PageImageData()
+        : source{}, type{}, height{DOUBLE_UNSPECIFIED}, width{DOUBLE_UNSPECIFIED}, pageNumber{0}, positionData{}
     {
     }
 };

src/include/mx/api/PartData.h

@@ -31,16 +31,16 @@ struct MidiData
     std::string device;
     std::string name;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int bank;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int channel;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int program;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int unpitched;
 
     // percent, valid range 0.0 to 100.0
@@ -56,9 +56,9 @@ struct MidiData
     bool isElevationSpecified;
 
     MidiData()
-        : virtualLibrary{}, virtualName{}, device{}, name{}, bank{-1}, channel{-1}, program{-1}, unpitched{-1},
-          volume{0.0}, isVolumeSpecified{false}, pan{0.0}, isPanSpecified{false}, elevation{0.0},
-          isElevationSpecified{false}
+        : virtualLibrary{}, virtualName{}, device{}, name{}, bank{VALUE_UNSPECIFIED}, channel{VALUE_UNSPECIFIED},
+          program{VALUE_UNSPECIFIED}, unpitched{VALUE_UNSPECIFIED}, volume{0.0}, isVolumeSpecified{false}, pan{0.0},
+          isPanSpecified{false}, elevation{0.0}, isElevationSpecified{false}
     {
     }
 };

src/include/mx/api/PartGroupData.h

@@ -4,6 +4,8 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
+
 #include <string>
 #include <vector>
 
@@ -63,12 +65,13 @@ class PartGroupData
 
     // The number attribute is used to distinguish overlapping
     // and nested part-groups, not the sequence of groups.
-    // -1 indicates the absence of a number attribute
+    // NUMBER_LEVEL_UNSPECIFIED indicates the absence of a number attribute
     int number;
 
     PartGroupData()
-        : firstPartIndex{-1}, lastPartIndex{-1}, name{}, bracketType{BracketType::unspecified},
-          groupBarline{GroupBarline::unspecified}, number{-1}
+        : firstPartIndex{INDEX_UNSPECIFIED}, lastPartIndex{INDEX_UNSPECIFIED}, name{},
+          bracketType{BracketType::unspecified}, groupBarline{GroupBarline::unspecified},
+          number{NUMBER_LEVEL_UNSPECIFIED}
     {
     }
 };

src/include/mx/api/PartSymbolData.h

@@ -18,11 +18,11 @@ class PartSymbolData
     BracketType value;
 
     // 1-based staff numbers indicating which staves the symbol spans.
-    // -1 means unspecified (the symbol covers all staves in the part).
+    // INDEX_UNSPECIFIED means unspecified (the symbol covers all staves in the part).
     int topStaff;
     int bottomStaff;
 
-    PartSymbolData() : value{BracketType::unspecified}, topStaff{-1}, bottomStaff{-1}
+    PartSymbolData() : value{BracketType::unspecified}, topStaff{INDEX_UNSPECIFIED}, bottomStaff{INDEX_UNSPECIFIED}
     {
     }
 };

src/include/mx/api/SoundData.h

@@ -53,8 +53,8 @@ struct SoundData
     std::string fine;
 
     SoundData()
-        : tempo{-1.0}, dynamics{-1.0}, dacapo{Bool::unspecified}, forwardRepeat{Bool::unspecified},
-          pizzicato{Bool::unspecified}, segno{}, dalsegno{}, coda{}, tocoda{}, fine{}
+        : tempo{DOUBLE_UNSPECIFIED}, dynamics{DOUBLE_UNSPECIFIED}, dacapo{Bool::unspecified},
+          forwardRepeat{Bool::unspecified}, pizzicato{Bool::unspecified}, segno{}, dalsegno{}, coda{}, tocoda{}, fine{}
     {
     }
 

src/include/mx/api/SpannerData.h

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -23,7 +24,7 @@ struct SpannerStart
     PrintData printData;
     LineData lineData;
 
-    SpannerStart() : numberLevel{-1}, tickTimePosition{0}, positionData{}, printData{}, lineData{}
+    SpannerStart() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, tickTimePosition{0}, positionData{}, printData{}, lineData{}
     {
     }
 };
@@ -35,7 +36,7 @@ struct SpannerStop
     PositionData positionData;
     LineData lineData;
 
-    SpannerStop() : numberLevel{-1}, tickTimePosition{0}, positionData{}, lineData{}
+    SpannerStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, tickTimePosition{0}, positionData{}, lineData{}
     {
     }
 };

src/include/mx/api/StaffData.h

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/ClefData.h"
 #include "mx/api/DirectionData.h"
 #include "mx/api/KeyData.h"
@@ -18,15 +19,15 @@ namespace api
 class StaffData
 {
   public:
-    int staffLines = -1;
+    int staffLines = VALUE_UNSPECIFIED;
 
     // Specifies the staff space size relative the the global staff space size
-    double staffSize = -1.0;
+    double staffSize = DOUBLE_UNSPECIFIED;
 
     // Specifies the scaling of the notation. The MusicXml spec calls out the case
     // of percussion staves with wider spaced lines as an example where this differs
     // from staffSize. For example it might be staffSize=150, staffScaling = 100.
-    double staffScaling = -1.0;
+    double staffScaling = DOUBLE_UNSPECIFIED;
 
     std::vector<ClefData> clefs;
 

src/include/mx/api/TempoData.h

@@ -3,6 +3,7 @@
 // Distributed under the MIT License
 
 #pragma once
+#include "mx/api/ApiCommon.h"
 #include "mx/api/DurationData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -25,7 +26,8 @@ struct BeatsPerMinute
     int dots;
     int beatsPerMinute;
 
-    BeatsPerMinute() : durationName{DurationName::unspecified}, dots{-1}, beatsPerMinute{-1}
+    BeatsPerMinute()
+        : durationName{DurationName::unspecified}, dots{VALUE_UNSPECIFIED}, beatsPerMinute{VALUE_UNSPECIFIED}
     {
     }
 };
@@ -39,8 +41,8 @@ struct MetricModulation
     BeatsPerMinute playbackBeatsPerMinute;
 
     MetricModulation()
-        : leftDurationName{DurationName::unspecified}, leftDots{-1}, rightDurationName{DurationName::unspecified},
-          rightDots{-1}, playbackBeatsPerMinute{}
+        : leftDurationName{DurationName::unspecified}, leftDots{VALUE_UNSPECIFIED},
+          rightDurationName{DurationName::unspecified}, rightDots{VALUE_UNSPECIFIED}, playbackBeatsPerMinute{}
     {
     }
 };

src/include/mx/api/TupletData.h

@@ -22,7 +22,7 @@ class TupletStart
 {
   public:
     // used to id when nested
-    // -1 means unspecified
+    // NUMBER_LEVEL_UNSPECIFIED means unspecified
     int numberLevel;
 
     PositionData positionData;
@@ -47,9 +47,11 @@ class TupletStart
     Bool bracket;
 
     TupletStart()
-        : numberLevel{-1}, positionData{}, actualNumber{-1}, actualDurationName{api::DurationName::unspecified},
-          actualDots{-1}, normalNumber{-1}, normalDurationName{api::DurationName::unspecified}, normalDots{-1},
-          showActualNumber{Bool::unspecified}, showNormalNumber{Bool::unspecified}, bracket{Bool::unspecified}
+        : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, actualNumber{VALUE_UNSPECIFIED},
+          actualDurationName{api::DurationName::unspecified}, actualDots{VALUE_UNSPECIFIED},
+          normalNumber{VALUE_UNSPECIFIED}, normalDurationName{api::DurationName::unspecified},
+          normalDots{VALUE_UNSPECIFIED}, showActualNumber{Bool::unspecified}, showNormalNumber{Bool::unspecified},
+          bracket{Bool::unspecified}
     {
     }
 };
@@ -58,12 +60,12 @@ class TupletStop
 {
   public:
     // used to id when nested
-    // -1 means unspecified
+    // NUMBER_LEVEL_UNSPECIFIED means unspecified
     int numberLevel;
 
     PositionData positionData;
 
-    TupletStop() : numberLevel{-1}, positionData{}
+    TupletStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}
     {
     }
 };

src/include/mx/api/WedgeData.h

@@ -31,8 +31,8 @@ struct WedgeStart
     ColorData colorData;
 
     WedgeStart()
-        : numberLevel{-1}, wedgeType{WedgeType::unspecified}, isSpreadSpecified{false}, spread{0.0}, lineData{},
-          positionData{}, colorData{}
+        : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, wedgeType{WedgeType::unspecified}, isSpreadSpecified{false},
+          spread{0.0}, lineData{}, positionData{}, colorData{}
     {
     }
 };
@@ -44,7 +44,7 @@ struct WedgeStop
     bool isSpreadSpecified;
     double spread;
 
-    WedgeStop() : numberLevel{-1}, positionData{}, isSpreadSpecified{false}, spread{0.0}
+    WedgeStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, isSpreadSpecified{false}, spread{0.0}
     {
     }
 };

src/private/mx/api/MarkData.cpp

@@ -220,7 +220,7 @@ int numTremoloSlashes(MarkType markType)
         return 5;
     }
 
-    return -1;
+    return VALUE_UNSPECIFIED;
 }
 
 MarkData::MarkData()