docs: explain two-phase flow-sequence handling in sync() (#53)

* docs: explain two-phase flow-sequence handling in sync()

* docs: refine two-phase flow-sequence comment in sync()

Author: nathanjmcdougall

src/yamltrip/document.py

@@ -468,8 +468,16 @@ def sync(self, *keys: KeyPart, value: Any) -> Document:
         except (ValueError, KeyError):
             return self.upsert(*normalized, value=value)
 
-        # Pre-convert any flow sequences that will be modified.
-        # This targets only the affected leaf paths, preserving sibling formatting.
+        # Two-phase flow-sequence handling:
+        #
+        # Phase 1 (_flow_seq_replacements) pre-converts only the flow sequences
+        # that will be modified.  A full replace at a higher path would
+        # re-serialize the whole mapping with the default indentation, losing
+        # the document's existing indent for nested lists.
+        #
+        # Phase 2 (except PatchError below) catches cases phase 1 misses.  The
+        # known gap is list reordering: new indices in the diff weren't in the
+        # original tree, so phase 1 couldn't anticipate them.
         doc: Document = self
         flow_patches = _flow_seq_replacements(
             self._core_doc, old_value, value, normalized
@@ -488,7 +496,8 @@ def sync(self, *keys: KeyPart, value: Any) -> Document:
             if _classify_patch_error(e) != _PatchErrorKind.BLOCK_SEQUENCE_EXPECTED:
                 raise
             # Fallback: a flow sequence was missed by pre-detection (e.g. due to
-            # list reordering). Replace the entire synced value.
+            # list reordering).  Full replace from original doc; phase 1 work
+            # is superseded.
             route = _make_route(normalized)
             op = Op.replace(value)
             return self._apply_patches([Patch(route=route, operation=op)])