Fix spurious KeyAlreadyPresent on valid out-of-order child table (#571)

_validate_table_candidate treated only Table/AoT as table-like. When a table
is spread across out-of-order headers, its existing entry is an
OutOfOrderTableProxy, so the isinstance(existing, (Table, AoT)) check was False
while the candidate was a Table. The mismatch raised KeyAlreadyPresent for a
document that tomllib and tomlkit <= 0.15.0 accept (a regression introduced by
the concrete+super validation in 0.15.1).

Recognise OutOfOrderTableProxy as table-like in the type-conflict check, and
when the existing entry is a proxy recurse into each of its concrete table
fragments so genuine duplicates are still rejected.

Adds a regression test and a CHANGELOG entry. Full suite passes (1053 tests).

Fixes #571.

Signed-off-by: Vladimir Babin <vovababin@gmail.com>

Author: chiliec

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## [Unreleased]
+
+### Fixed
+
+- Fix a regression (since 0.15.1) where a valid out-of-order child table was rejected with `KeyAlreadyPresent` when its concrete parent was declared afterwards and another table separated a later sibling child. The existing entry is an `OutOfOrderTableProxy`, which was not recognised as table-like during table-candidate validation. ([#571](https://github.com/python-poetry/tomlkit/issues/571))
+
 ## [0.15.1] - 2026-07-17
 
 ### Changed

tests/test_api.py

@@ -480,6 +480,30 @@ def test_parse_rejects_collisions_across_out_of_order_fragments(
         parse(content)
 
 
+def test_parse_accepts_out_of_order_child_with_intervening_table() -> None:
+    """A valid out-of-order child table must not be rejected just because its
+    concrete parent is declared afterwards and another table separates a later
+    sibling child. Regression for #571 (broken in 0.15.1): the existing entry
+    is an OutOfOrderTableProxy, which was not recognised as table-like and
+    raised a spurious KeyAlreadyPresent."""
+    content = (
+        "[tool.ruff]\n"
+        "[tool.ruff.lint.a]\n"
+        "[tool.ruff.lint]\n"
+        "[[tool.poetry.source]]\n"
+        "[tool.ruff.lint.b]\n"
+    )
+    doc = parse(content)
+    assert doc.unwrap() == {
+        "tool": {
+            "ruff": {"lint": {"a": {}, "b": {}}},
+            "poetry": {"source": [{}]},
+        }
+    }
+    # Round-trip must be preserved exactly.
+    assert dumps(doc) == content
+
+
 def test_create_super_table_with_table() -> None:
     data = {"foo": {"bar": {"a": 1}}}
     assert dumps(data) == "[foo.bar]\na = 1\n"

tomlkit/container.py

@@ -424,11 +424,23 @@ def _validate_table_candidate(self, current: Table, candidate: Table) -> None:
 
             if k in current.value._map:
                 existing = current.value.item(k)
-                if isinstance(existing, (Table, AoT)) != isinstance(v, (Table, AoT)):
+                # An out-of-order table is represented by an OutOfOrderTableProxy
+                # rather than a Table. It is still table-like, so treat it as a
+                # table both for the type-conflict check and when recursing into
+                # the subtree (see #571).
+                existing_is_table = isinstance(existing, (Table, AoT, OutOfOrderTableProxy))
+                if existing_is_table != isinstance(v, (Table, AoT)):
                     raise KeyAlreadyPresent(k)
                 if k.is_dotted():
                     raise TOMLKitError("Redefinition of an existing table")
-                if isinstance(existing, Table) and isinstance(v, Table):
+                if isinstance(existing, OutOfOrderTableProxy) and isinstance(v, Table):
+                    # The existing table is spread across several out-of-order
+                    # headers; a duplicate (if any) is nested deeper, so keep
+                    # checking against each concrete fragment rather than
+                    # rejecting outright (see #571).
+                    for fragment in existing._tables:
+                        self._validate_table_candidate(fragment, v)
+                elif isinstance(existing, Table) and isinstance(v, Table):
                     if not existing.is_super_table() and not v.is_super_table():
                         # Both sides are concrete `[table]` definitions of the
                         # same name; the table is declared twice.