refactor: address review feedback

- Short-circuit list diffing in merge (replace entirely per spec)
- Add root-exists comment to merge() for consistency with sync()
- Add flow sequence tests to test_merge.py

Author: nathanjmcdougall

src/yamltrip/document.py

@@ -555,6 +555,7 @@ def merge(self, *keys: KeyPart, value: Any) -> Document:
         normalized = _normalize_keys(keys) if keys else ()
 
         # If path doesn't exist, delegate to upsert.
+        # Root (empty keys) always exists, so skip the check.
         if normalized:
             route = _make_route(normalized)
             if not self._core_doc.query_exists(route):

src/yamltrip/sync.py

@@ -32,6 +32,10 @@ def _compute_patches(
     new_is_list = isinstance(new_value, list)
 
     if old_is_list and new_is_list:
+        if not remove_extra:
+            # merge semantics: lists replace entirely (no element-wise diff)
+            route = _core.Route(list(path))
+            return [_core.Patch(route=route, operation=_core.Op.replace(new_value))]
         return _diff_lists(old_value, new_value, path)
 
     # Type mismatch or scalar change — replace

tests/test_merge.py

@@ -40,6 +40,20 @@ def test_nested_list_replaced(self):
         assert doc2["cfg", "name"] == "foo"
 
 
+class TestMergeFlowSequence:
+    def test_flow_sequence_replaced(self):
+        doc = Document("cfg:\n  tags: [alpha, beta]\n  name: foo\n")
+        doc2 = doc.merge("cfg", value={"tags": ["gamma"], "extra": 1})
+        assert doc2["cfg", "tags"] == ["gamma"]
+        assert doc2["cfg", "name"] == "foo"
+        assert doc2["cfg", "extra"] == 1
+
+    def test_flow_sequence_at_path(self):
+        doc = Document("items: [a, b, c]\n")
+        doc2 = doc.merge("items", value=["x", "y"])
+        assert doc2["items"] == ["x", "y"]
+
+
 class TestMergeTypePromotion:
     def test_scalar_to_mapping(self):
         doc = Document("settings: defaults\n")