🐛 preserve overflow merge value shape

Author: techouse

src/qs_codec/utils/utils.py

@@ -17,6 +17,7 @@
 - Several routines use an object-identity `visited` set to avoid infinite recursion when user inputs contain cycles.
 """
 
+import copy
 import typing as t
 from collections import deque
 from collections.abc import Mapping as ABCMapping
@@ -46,6 +47,13 @@ def _numeric_key_pairs(mapping: t.Mapping[t.Any, t.Any]) -> t.List[t.Tuple[int,
     return pairs
 
 
+def _copy_overflow_append_value(value: t.Any) -> t.Any:
+    """Copy container values before storing them in an overflow append slot."""
+    if isinstance(value, (ABCMapping, list, tuple)):
+        return copy.copy(value)
+    return value
+
+
 @dataclass
 class _MergeFrame:
     target: t.Any
@@ -523,6 +531,14 @@ def combine(
         """
         Concatenate two values, treating non-sequences as singletons.
 
+        Normal list/tuple inputs are flattened into the combined result. When
+        ``a`` is already an :class:`OverflowDict`, however, ``b`` is appended as
+        one value at the next numeric key, even if ``b`` is a list, tuple, or
+        another :class:`OverflowDict`. This preserves qs parity for duplicate
+        values after list-limit overflow: a later comma-split or bracket-array
+        payload remains a nested value instead of being flattened into the
+        overflowed container.
+
         If `list_limit` is exceeded, converts the list to an `OverflowDict`
         (a dict with numeric keys) to prevent memory exhaustion.
         When `options` is provided, its ``list_limit`` controls when a list is
@@ -537,33 +553,15 @@ def combine(
         list to :class:`OverflowDict`.
         """
         if Utils.is_overflow(a):
-            # a is already an OverflowDict. Append b to a *copy* at the next numeric index.
-            # We assume sequential keys; len(a_copy) gives the next index.
+            # a is already an OverflowDict. Append b as one value at the next numeric index.
             orig_a = t.cast(OverflowDict, a)
             a_copy = orig_a.__class__({k: v for k, v in orig_a.items() if not isinstance(v, Undefined)})
             # Use max key + 1 to handle sparse dicts safely, rather than len(a)
             key_pairs = _numeric_key_pairs(a_copy)
             idx = (max(key for key, _ in key_pairs) + 1) if key_pairs else 0
 
-            if isinstance(orig_a, CommaOverflowDict):
-                if not isinstance(b, Undefined):
-                    a_copy[str(idx)] = b
-            elif isinstance(b, (list, tuple)):
-                for item in b:
-                    if not isinstance(item, Undefined):
-                        a_copy[str(idx)] = item
-                        idx += 1
-            elif Utils.is_overflow(b):
-                b = t.cast(OverflowDict, b)
-                # Iterate in numeric key order to preserve list semantics
-                for _, k in sorted(_numeric_key_pairs(b), key=lambda item: item[0]):
-                    val = b[k]
-                    if not isinstance(val, Undefined):
-                        a_copy[str(idx)] = val
-                        idx += 1
-            else:
-                if not isinstance(b, Undefined):
-                    a_copy[str(idx)] = b
+            if not isinstance(b, Undefined):
+                a_copy[str(idx)] = _copy_overflow_append_value(b)
             return a_copy
 
         # Normal combination: flatten lists/tuples

tests/unit/decode_test.py

@@ -1654,6 +1654,12 @@ def test_mapping_bracket_comma_list_over_zero_limit_raises(self) -> None:
                 },
                 id="overflow-comma-list-then-overflow-comma-list",
             ),
+            pytest.param(
+                "a[]=1&a[]=2&a[]=3,4",
+                DecodeOptions(comma=True, list_limit=1),
+                {"a": {"0": "1", "1": "2", "2": [["3", "4"]]}},
+                id="bracket-overflow-then-comma-list",
+            ),
         ],
     )
     def test_comma_overflow_duplicates_keep_overflow_values_nested(

tests/unit/utils_test.py

@@ -775,7 +775,7 @@ def test_combine_overflow_dict_with_overflow_dict(self) -> None:
         combined = Utils.combine(a, b)
         assert isinstance(combined, OverflowDict)
         assert combined["0"] == "x"
-        assert combined["1"] == "y"
+        assert combined["1"] == {"0": "y"}
         assert len(combined) == 2
 
     def test_compact_removes_undefined_entries_and_avoids_cycles(self) -> None:
@@ -1149,12 +1149,13 @@ def test_combine_list_with_overflow_dict(self) -> None:
         result = Utils.combine(a, b)
         assert result == ["start", "x", "y"]
 
-    def test_combine_skips_undefined_in_overflow_dict_append(self) -> None:
+    def test_combine_overflow_dict_appends_list_as_single_value(self) -> None:
         a = OverflowDict({"0": "x"})
         b = ["y", Undefined(), "z"]
         result = Utils.combine(a, b)
         assert isinstance(result, OverflowDict)
-        assert result == {"0": "x", "1": "y", "2": "z"}
+        assert result == {"0": "x", "1": ["y", Undefined(), "z"]}
+        assert result["1"] is not b
 
     def test_combine_skips_undefined_in_list_flattening(self) -> None:
         a = ["x", Undefined()]
@@ -1178,13 +1179,14 @@ def test_combine_overflow_dict_skips_existing_undefined_and_ignores_non_numeric_
         assert result["skip"] == "keep"
         assert "1" in a  # Original should remain unchanged
 
-    def test_combine_overflow_dict_source_skips_non_numeric_keys(self) -> None:
+    def test_combine_overflow_dict_appends_overflow_source_as_single_value(self) -> None:
         a = OverflowDict({"0": "x"})
         b = OverflowDict({"foo": "bar", "1": "y", "0": "z"})
         result = Utils.combine(a, b)
         assert isinstance(result, OverflowDict)
-        assert result == {"0": "x", "1": "z", "2": "y"}
-        assert "foo" not in result
+        assert result == {"0": "x", "1": {"foo": "bar", "1": "y", "0": "z"}}
+        assert isinstance(result["1"], OverflowDict)
+        assert result["1"] is not b
 
     def test_merge_overflow_dict_source_preserves_non_numeric_keys(self) -> None:
         target = "a"