fix: route nested dicts through complex-replace in _create_at

MergeInto is scoped to flat mappings (uniform indent); nested values
produced incorrect indentation due to yamlpatch's trim_start() logic.

Gate the two-step add+replace fallback on whether the dict contains
nested dicts/lists, preserving merge_into for the common flat case.

- Add depth check in _create_at to select the correct code path
- Document merge_into's flat-only scope in ops.rs docstring
- Update design spec to reflect the flat/nested split
- Add regression test for nested dict via intermediate keys

Author: nathanjmcdougall

doc/specs/2026-05-13-yamltrip-design.md

@@ -115,8 +115,11 @@ All return a new `Document`.
 
 1. **Full path exists:** delegates to `replace()`.
 2. **Partial path exists:** walks down to the deepest existing key, then uses
-   yamlpatch `MergeInto` to create the remaining nested structure in a single
-   operation.
+   yamlpatch `MergeInto` for flat mapping values (scalar-only entries) or a
+   two-step `Add` placeholder + `Replace` for nested values (dicts/lists inside
+   the value). `MergeInto` uses uniform-indent serialization that only handles
+   one nesting level; the `Replace` path routes through complex-replace which
+   preserves relative indentation at arbitrary depth.
 3. **No path exists:** uses yamlpatch `Add` with a nested value to create the
    entire path in a single operation.
 

src/ops.rs

@@ -71,6 +71,12 @@ impl PyOp {
     }
 
     /// Merge key-value pairs into an existing mapping.
+    ///
+    /// The `updates` map must contain flat (scalar) values only. Nested
+    /// mappings will produce incorrect indentation due to yamlpatch's
+    /// uniform-indent serialization in `handle_block_mapping_addition`.
+    /// For nested values, use `Op.add` + `Op.replace` to route through
+    /// the complex-replace path which preserves relative indentation.
     #[staticmethod]
     fn merge_into(key: &str, updates: &Bound<'_, PyAny>) -> PyResult<Self> {
         let dict = updates.cast::<pyo3::types::PyDict>().map_err(|_| {

src/yamltrip/document.py

@@ -286,7 +286,20 @@ def _create_at(
         for k in reversed(child_keys[1:]):
             nested_value = {k: nested_value}
         route = _make_route(parent_keys)
-        if isinstance(nested_value, dict):
+        if isinstance(nested_value, dict) and any(
+            isinstance(v, (dict, list)) for v in nested_value.values()
+        ):
+            # Op.merge_into is scoped to flat mappings (uniform indent); for
+            # nested values, add a placeholder then replace via complex-replace
+            # which preserves relative indentation.
+            op = _core.Op.add(first_key, None)
+            patch = _core.Patch(route=route, operation=op)
+            doc = self._apply_patches([patch])
+            replace_route = _make_route((*parent_keys, first_key))
+            replace_op = _core.Op.replace(nested_value)
+            replace_patch = _core.Patch(route=replace_route, operation=replace_op)
+            return doc._apply_patches([replace_patch])
+        elif isinstance(nested_value, dict):
             op = _core.Op.merge_into(first_key, nested_value)
         else:
             op = _core.Op.add(first_key, nested_value)

tests/test_document.py

@@ -409,6 +409,14 @@ def test_upsert_missing_with_list(self):
         doc2 = doc.upsert("items", value=["a", "b"])
         assert doc2["items"] == ["a", "b"]
 
+    def test_upsert_missing_nested_path_with_dict(self):
+        """Nested dict via intermediate keys must not flatten."""
+        doc = Document("a: 1\n")
+        doc2 = doc.upsert("parent", "child", value={"x": 1, "y": 2})
+        assert doc2["parent", "child", "x"] == 1
+        assert doc2["parent", "child", "y"] == 2
+        assert doc2["parent", "child"] == {"x": 1, "y": 2}
+
 
 class TestDocumentRemove:
     def test_remove_key(self):