fix(base): remove misleading DataclassProtocol annotation mapping (#771)

## Summary

Closes #477.

`create_registry()` currently seeds `type_annotation_map` with
`DataclassProtocol: JsonB`. That entry does not provide structural
dataclass support:

- SQLAlchemy resolves `type_annotation_map` through exact and `__mro__`
dictionary lookups; it does not call `isinstance()` or otherwise perform
runtime Protocol validation.
- A concrete dataclass used as `Mapped[SomeDataclass]` does not inherit
`DataclassProtocol`, so it does not match that entry and raises
`MappedAnnotationError`.
- An exact `Mapped[DataclassProtocol]` annotation can select `JsonB`,
but it does not validate assigned values against the Protocol or
preserve the concrete dataclass type for reconstruction.

The default entry is therefore misleading: it appears to support
arbitrary concrete dataclasses, but concrete dataclass annotations must
be registered explicitly.

## Changes

- Remove the default `DataclassProtocol: JsonB` entry and its now-unused
import from `advanced_alchemy/base.py`.
- Add regression coverage for the default registry map.
- Document the supported path: register each concrete dataclass with
`custom_annotation_map={MyDataclass: JsonB}` so SQLAlchemy can resolve
the exact annotation.

## Compatibility

This changes the narrow case where a model is annotated literally as
`Mapped[DataclassProtocol]`; that exact annotation previously selected
`JsonB`. It did not validate Protocol conformance or provide concrete
dataclass reconstruction.

Concrete annotations such as `Mapped[SomeDataclass]` did not resolve
through this entry before this change and continue to require an
explicit concrete mapping.

## Supported replacement

```python
from dataclasses import dataclass

from advanced_alchemy.base import create_registry
from advanced_alchemy.types import JsonB


@DataClass
class ExtraData:
    before: int


registry = create_registry(custom_annotation_map={ExtraData: JsonB})
```

Author: hasansezertasan

advanced_alchemy/base.py

@@ -34,7 +34,6 @@
     UUIDv7PrimaryKey,
 )
 from advanced_alchemy.types import GUID, DateTimeUTC, FileObject, FileObjectList, JsonB, StoredObject
-from advanced_alchemy.utils.dataclass import DataclassProtocol
 
 if TYPE_CHECKING:
     from sqlalchemy.sql import FromClause
@@ -405,7 +404,6 @@ def create_registry(
         dict: JsonB,
         dict[str, Any]: JsonB,
         dict[str, str]: JsonB,
-        DataclassProtocol: JsonB,
         FileObject: StoredObject,
         FileObjectList: StoredObject,
     }

tests/unit/test_base.py

@@ -282,3 +282,40 @@ class SQLiteIdentityAuditBaseModel(IdentityAuditBase):
 
     # Should not raise any errors
     assert True  # If we get here, it worked
+
+
+def test_registry_type_annotation_map_has_no_protocol_keys() -> None:
+    """Regression test for https://github.com/litestar-org/advanced-alchemy/issues/477.
+
+    ``type_annotation_map`` is resolved by SQLAlchemy through an exact/``__mro__``
+    dictionary lookup that rejects supertype matches. A ``Protocol`` (such as the
+    now-removed ``DataclassProtocol`` entry) is never present in the ``__mro__`` of
+    a class that structurally satisfies it, so a Protocol key can never match and
+    is misleading dead configuration. Guard against reintroducing one.
+    """
+    from advanced_alchemy.base import orm_registry
+
+    protocol_keys = [key for key in orm_registry.type_annotation_map if getattr(key, "_is_protocol", False)]
+    assert protocol_keys == []
+
+
+def test_dataclass_column_resolves_via_custom_annotation_map() -> None:
+    """A concrete dataclass resolves only when registered explicitly.
+
+    This is the supported replacement for the removed ``DataclassProtocol`` entry:
+    users map their own concrete dataclass type, which lands in the registry as an
+    exact key and therefore resolves.
+    """
+    from dataclasses import dataclass
+
+    from advanced_alchemy.base import create_registry
+    from advanced_alchemy.types import JsonB
+
+    @dataclass
+    class ExtraData:
+        before: int
+
+    registry = create_registry(custom_annotation_map={ExtraData: JsonB})
+
+    resolved = registry._resolve_type(ExtraData)  # pyright: ignore[reportPrivateUsage]
+    assert resolved is not None