fix(protocol): encode catalog items with map keys in sorted order

Arrow writes a map column in dict iteration order, so equal items whose tags /
estimated_object_count / column_comments were filled in different orders encoded
differently. catalog_contents promises deterministic, byte-identical items (and
its content-hash etag hashes them); the Go, Java, C# and TypeScript SDKs already
sort map keys.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: Rusty Conover

tests/catalog/test_catalog_contents.py

@@ -512,3 +512,26 @@ def test_client_round_trip(client_transport: Any) -> None:
         assert hit.schemas == []
         assert hit.etag == "gen-1"
         client.catalog_detach(attach_opaque_data=reval.attach_opaque_data)
+
+
+def test_item_encoding_sorts_map_keys() -> None:
+    """Equal items whose maps were filled in different orders encode identically."""
+    from vgi.catalog import SchemaInfo
+    from vgi.protocol import _item_ipc_bytes
+
+    a = SchemaInfo(
+        attach_opaque_data=b"x",
+        path=["s"],
+        comment=None,
+        tags={"b": "2", "a": "1"},
+        estimated_object_count={"view": 0, "table": 3},
+    )
+    b = SchemaInfo(
+        attach_opaque_data=b"x",
+        path=["s"],
+        comment=None,
+        tags={"a": "1", "b": "2"},
+        estimated_object_count={"table": 3, "view": 0},
+    )
+    assert _item_ipc_bytes(a) == _item_ipc_bytes(b)
+    assert SchemaInfo.deserialize_from_bytes(_item_ipc_bytes(a)).tags == {"a": "1", "b": "2"}

vgi/protocol.py

@@ -867,13 +867,41 @@ def _item_ipc_bytes(info: Any) -> bytes:
     """
     memo = getattr(info, "__dict__", None)
     if memo is None:
-        return info.serialize_to_bytes()  # type: ignore[no-any-return]
+        return _with_sorted_maps(info).serialize_to_bytes()  # type: ignore[no-any-return]
     encoded = memo.get(_ITEM_IPC_MEMO)
     if encoded is None:
-        encoded = memo[_ITEM_IPC_MEMO] = info.serialize_to_bytes()
+        encoded = memo[_ITEM_IPC_MEMO] = _with_sorted_maps(info).serialize_to_bytes()
     return encoded  # type: ignore[no-any-return]
 
 
+def _with_sorted_maps(info: Any) -> Any:
+    """Return *info* with every map-valued field in sorted key order.
+
+    Arrow writes a map column in the dict's iteration order, so two equal
+    items whose ``tags`` (or ``estimated_object_count``, ``column_comments``,
+    ...) were filled in different orders would encode to different bytes.
+    Catalog items must encode deterministically: ``catalog_contents`` promises
+    items byte-identical to the per-schema RPCs, its content-hash etag hashes
+    them, and every other VGI SDK sorts map keys the same way.
+
+    Args:
+        info: The catalog item (a frozen dataclass).
+
+    Returns:
+        *info* itself when no map field needs reordering, else a copy.
+    """
+    if not dataclasses.is_dataclass(info) or isinstance(info, type):
+        return info
+    changes: dict[str, dict[Any, Any]] = {}
+    for f in dataclasses.fields(info):
+        if not f.init:
+            continue
+        value = getattr(info, f.name, None)
+        if isinstance(value, dict) and list(value) != sorted(value):
+            changes[f.name] = dict(sorted(value.items()))
+    return dataclasses.replace(info, **changes) if changes else info
+
+
 def _catalog_items_response(item_type: type) -> type:
     """Generate a catalog items response class for the given `ArrowSerializableDataclass` type.