fix: add GetValues buffer-length validation and bounds documentation

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/16db7628-2cc2-4c51-982b-0264a04d7157

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

src/PolylineAlgorithm/PolylineFormatter.cs

@@ -60,8 +60,17 @@ internal PolylineFormatter(FormatterRule<T>[] rules) {
     /// Output buffer that receives the scaled values.
     /// Its length must equal <see cref="Width"/>.
     /// </param>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="values"/>.Length does not equal <see cref="Width"/>.
+    /// </exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void GetValues(T item, Span<long> values) {
+        if (values.Length != Width) {
+            throw new ArgumentException(
+                $"Buffer length {values.Length} does not match the formatter width {Width}.",
+                nameof(values));
+        }
+
         var rules = _rules; // local copy avoids repeated bounds check on the field
         for (var i = 0; i < rules.Length; i++) {
             ref var rule = ref rules[i];
@@ -73,7 +82,10 @@ public void GetValues(T item, Span<long> values) {
     /// Returns the baseline for the column at <paramref name="index"/>, or <c>0</c> if none is configured.
     /// The encoder subtracts this value from the first item's scaled column value during encoding.
     /// </summary>
-    /// <param name="index">The zero-based column index. Must be in the range <c>[0, Width)</c>.</param>
+    /// <param name="index">
+    /// The zero-based column index. Must be in the range <c>[0, <see cref="Width"/>)</c>.
+    /// An <see cref="IndexOutOfRangeException"/> is thrown if the index is out of range.
+    /// </param>
     /// <returns>The baseline value, or <c>0</c> when no baseline has been defined for the column.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public long GetBaseline(int index) => _rules[index].Baseline ?? 0L;

tests/PolylineAlgorithm.Tests/PolylineFormatterTests.cs

@@ -353,6 +353,37 @@ public void GetValues_Scales_Multiple_Columns_Independently() {
         Assert.AreEqual(-12025000L, output[1]);
     }
 
+    [TestMethod]
+    public void GetValues_With_Wrong_Buffer_Length_Throws_ArgumentException() {
+        // Arrange — formatter has Width = 2 but buffer has length 1
+        PolylineFormatter<(double X, double Y)> formatter = FormatterBuilder<(double X, double Y)>.Create()
+            .AddValue("X", static t => t.X)
+            .AddValue("Y", static t => t.Y)
+            .Build();
+
+        long[] tooShort = new long[1];
+
+        // Act & Assert
+        ArgumentException ex = Assert.ThrowsExactly<ArgumentException>(
+            () => formatter.GetValues((1.0, 2.0), tooShort.AsSpan()));
+        Assert.AreEqual("values", ex.ParamName);
+    }
+
+    [TestMethod]
+    public void GetValues_With_Oversized_Buffer_Throws_ArgumentException() {
+        // Arrange — formatter has Width = 1 but buffer has length 3
+        PolylineFormatter<double> formatter = FormatterBuilder<double>.Create()
+            .AddValue("Value", static v => v)
+            .Build();
+
+        long[] tooLong = new long[3];
+
+        // Act & Assert
+        ArgumentException ex = Assert.ThrowsExactly<ArgumentException>(
+            () => formatter.GetValues(1.0, tooLong.AsSpan()));
+        Assert.AreEqual("values", ex.ParamName);
+    }
+
     [TestMethod]
     public void GetValues_With_Zero_Returns_Zero() {
         // Arrange