GeneralManager 0.82.3__tar.gz → 0.82.5__tar.gz

{generalmanager-0.82.3/src/GeneralManager.egg-info → generalmanager-0.82.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.82.3
+Version: 0.82.5
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.82.3 → generalmanager-0.82.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.82.3"
+version = "0.82.5"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.82.3 → generalmanager-0.82.5/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.82.3
+Version: 0.82.5
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/GeneralManager.egg-info/SOURCES.txt

@@ -274,6 +274,7 @@ src/general_manager/search/backend.py
 src/general_manager/search/backend_registry.py
 src/general_manager/search/checks.py
 src/general_manager/search/config.py
+src/general_manager/search/identity.py
 src/general_manager/search/indexer.py
 src/general_manager/search/invalidation.py
 src/general_manager/search/m2m_invalidation.py

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/_types/search.py

@@ -18,10 +18,12 @@ __all__ = [
     "SearchConfigSpec",
     "SearchDocument",
     "SearchHit",
+    "SearchIdentityFilterGroup",
     "SearchIndexer",
     "SearchInvalidationRule",
     "SearchResult",
     "TypesenseBackend",
+    "build_search_filters",
     "configure_search_backend",
     "configure_search_backend_from_settings",
     "get_search_backend",
@@ -44,10 +46,12 @@ from general_manager.search.config import SearchConfigProtocol
 from general_manager.search.config import SearchConfigSpec
 from general_manager.search.backend import SearchDocument
 from general_manager.search.backend import SearchHit
+from general_manager.search.identity import SearchIdentityFilterGroup
 from general_manager.search.indexer import SearchIndexer
 from general_manager.search.config import SearchInvalidationRule
 from general_manager.search.backend import SearchResult
 from general_manager.search.backends.typesense import TypesenseBackend
+from general_manager.search.identity import build_search_filters
 from general_manager.search.backend_registry import configure_search_backend
 from general_manager.search.backend_registry import (
     configure_search_backend_from_settings,

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/api/graphql.py

@@ -100,6 +100,7 @@ from general_manager.api.graphql_mutations import (
     generate_delete_mutation_class as _generate_delete_mutation_class_fn,
 )
 from general_manager.api.graphql_output import (
+    GraphQLOutputIdentityMetadataError,
     create_output_field_resolver,
     map_graphql_output_annotation,
     resolve_output_type_hints,
@@ -518,6 +519,11 @@ class GraphQL:
         )
         fields: dict[str, graphene.Field] = {}
         for declared_field in dataclasses.fields(output_class):
+            is_identifier = declared_field.metadata.get("is_identifier", False)
+            if not isinstance(is_identifier, bool):
+                raise GraphQLOutputIdentityMetadataError(
+                    output_name, declared_field.name, is_identifier
+                )
             mapped = map_graphql_output_annotation(
                 hints[declared_field.name],
                 owner_name=output_name,
@@ -528,6 +534,7 @@ class GraphQL:
                 output_type_registry=cls.graphql_output_type_registry,
                 measurement_type=MeasurementType,
                 scalar_mapper=cls._map_field_to_graphene_base_type,
+                is_identifier=is_identifier,
             )
             field = cast(graphene.Field, mapped.field)
             field.resolver = create_output_field_resolver(

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/api/graphql_output.py

@@ -9,6 +9,7 @@ from decimal import Decimal
 import sys
 from types import UnionType
 from typing import Any, ForwardRef, Union, get_args, get_origin, get_type_hints
+from uuid import UUID
 
 import graphene
 
@@ -40,6 +41,16 @@ class GraphQLOutputAnnotationError(TypeError):
         )
 
 
+class GraphQLOutputIdentityMetadataError(TypeError):
+    """Raised when an output field's identity flag is not boolean."""
+
+    def __init__(self, owner_name: str, field_name: str, flag: object) -> None:
+        super().__init__(
+            f"Invalid is_identifier metadata for {owner_name}.{field_name}: "
+            f"expected bool, got {flag!r}"
+        )
+
+
 @dataclass(frozen=True, slots=True)
 class _MappedAnnotation:
     """Internal Graphene type metadata before a field wrapper is mounted."""
@@ -144,6 +155,7 @@ def _map_collection_annotation(
     output_type_registry: Mapping[str, type[graphene.ObjectType]],
     measurement_type: type[graphene.ObjectType],
     scalar_mapper: Callable[[type], type],
+    is_identifier: bool = False,
 ) -> _MappedAnnotation:
     origin = get_origin(annotation)
     if origin not in (list, tuple, set):
@@ -159,6 +171,13 @@ def _map_collection_annotation(
             raise _annotation_error(owner_name, field_name, annotation)
         element_annotation = args[0]
 
+    if is_identifier:
+        _, identity_type = _unwrap_optional_annotation(
+            element_annotation, owner_name=owner_name, field_name=field_name
+        )
+        if identity_type not in (int, str, UUID):
+            raise _annotation_error(owner_name, field_name, annotation)
+
     element = _map_annotation(
         element_annotation,
         owner_name=owner_name,
@@ -169,6 +188,7 @@ def _map_collection_annotation(
         output_type_registry=output_type_registry,
         measurement_type=measurement_type,
         scalar_mapper=scalar_mapper,
+        is_identifier=is_identifier,
     )
     element_type = element.graphene_type
     if not element.nullable:
@@ -192,6 +212,7 @@ def _map_non_optional_value(
     output_type_registry: Mapping[str, type[graphene.ObjectType]],
     measurement_type: type[graphene.ObjectType],
     scalar_mapper: Callable[[type], type],
+    is_identifier: bool = False,
 ) -> _MappedAnnotation:
     annotation = _resolve_registered_name(
         annotation,
@@ -220,6 +241,17 @@ def _map_non_optional_value(
             output_type_registry=output_type_registry,
             measurement_type=measurement_type,
             scalar_mapper=scalar_mapper,
+            is_identifier=is_identifier,
+        )
+
+    if is_identifier:
+        if annotation not in (int, str, UUID):
+            raise _annotation_error(owner_name, field_name, annotation)
+        return _MappedAnnotation(
+            graphene.ID,
+            annotation,
+            nullable=False,
+            contains_measurement=False,
         )
 
     if safe_issubclass(annotation, GraphQLType):
@@ -290,6 +322,7 @@ def _map_annotation(
     output_type_registry: Mapping[str, type[graphene.ObjectType]],
     measurement_type: type[graphene.ObjectType],
     scalar_mapper: Callable[[type], type],
+    is_identifier: bool = False,
 ) -> _MappedAnnotation:
     nullable, concrete = _unwrap_optional_annotation(
         annotation,
@@ -306,6 +339,7 @@ def _map_annotation(
         output_type_registry=output_type_registry,
         measurement_type=measurement_type,
         scalar_mapper=scalar_mapper,
+        is_identifier=is_identifier,
     )
     return replace(mapped, nullable=nullable)
 
@@ -322,6 +356,7 @@ def _map_non_optional_annotation(
     measurement_type: type[graphene.ObjectType],
     scalar_mapper: Callable[[type], type],
     required: bool,
+    is_identifier: bool = False,
 ) -> MappedGraphQLOutput:
     """Map one non-optional annotation to a Graphene field."""
     mapped = _map_non_optional_value(
@@ -334,6 +369,7 @@ def _map_non_optional_annotation(
         output_type_registry=output_type_registry,
         measurement_type=measurement_type,
         scalar_mapper=scalar_mapper,
+        is_identifier=is_identifier,
     )
     field_kwargs: dict[str, object] = {}
     if mapped.contains_measurement:
@@ -355,8 +391,14 @@ def map_graphql_output_annotation(
     output_type_registry: Mapping[str, type[graphene.ObjectType]],
     measurement_type: type[graphene.ObjectType],
     scalar_mapper: Callable[[type], type],
+    is_identifier: bool = False,
 ) -> MappedGraphQLOutput:
-    """Map a strict GraphQL output annotation to a mounted Graphene field."""
+    """Map a strict output hint, preserving nullability and native values.
+
+    Explicit identity fields accept int, str, UUID, and supported flat
+    collections of those types. Their resolver type stays native while the
+    generated scalar is ID. Unmarked fields retain the strict legacy mapping.
+    """
     nullable, concrete_type = _unwrap_optional_annotation(
         annotation,
         owner_name=owner_name,
@@ -374,6 +416,7 @@ def map_graphql_output_annotation(
             measurement_type=measurement_type,
             scalar_mapper=scalar_mapper,
             required=not nullable,
+            is_identifier=is_identifier,
         )
     except GraphQLOutputAnnotationError as error:
         # Preserve the annotation written on the owning field in diagnostics,

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/api/graphql_search.py

@@ -41,6 +41,7 @@ from general_manager.measurement.measurement import Measurement
 from general_manager.utils.type_checks import safe_issubclass
 from general_manager.search.backend_registry import get_search_backend
 from general_manager.search.backend import SearchHit
+from general_manager.search.identity import SearchFilters, build_search_filters
 from general_manager.search.registry import (
     get_search_config,
     get_type_label,
@@ -1257,7 +1258,7 @@ def register_search_query(
                 permission_plan,
                 backend_shape=backend_shape,
             )
-            filter_groups = (
+            filter_groups: SearchFilters = (
                 manager_filters or None
                 if decision == "allow_all"
                 else merge_permission_filters(
@@ -1265,6 +1266,9 @@ def register_search_query(
                     permission_plan.filters,
                 )
             )
+            filter_groups = build_search_filters(
+                manager_class, index_name, filter_groups
+            )
             total_hits_for_manager = 0
             candidate_hits_for_manager = 0
             offset_cursor = 0

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/api/graphql_type.py

@@ -29,7 +29,14 @@ class GraphQLTypeMeta(type):
 
 
 class GraphQLType(metaclass=GraphQLTypeMeta):
-    """Frozen annotated value exposed only as a GraphQL output object."""
+    """Frozen annotated value exposed only as a GraphQL output object.
+
+    Use ``dataclasses.field(metadata={"is_identifier": True})`` to declare
+    native int, str, or UUID identity fields and their supported homogeneous
+    collections. Schema generation preserves annotation nullability and native
+    values while exposing ID scalars. Missing or false metadata keeps existing
+    output types; other flag values fail schema generation with TypeError.
+    """
 
 
 def get_registered_graphql_types() -> tuple[type[GraphQLType], ...]:

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/management/commands/search_index.py

@@ -9,9 +9,8 @@ from django.core.management.base import BaseCommand
 
 from general_manager.logging import get_logger
 from general_manager.search.backend_registry import get_search_backend
-from general_manager.search.indexer import SearchIndexer
+from general_manager.search.indexer import SearchIndexer, _ensure_index
 from general_manager.search.registry import (
-    collect_index_settings,
     get_index_names,
     iter_searchable_managers,
 )
@@ -99,16 +98,7 @@ class Command(BaseCommand):
             target_indexes = get_index_names()
 
         for index_name in sorted(target_indexes):
-            settings_payload = collect_index_settings(index_name)
-            backend.ensure_index(
-                index_name,
-                {
-                    "searchable_fields": settings_payload.searchable_fields,
-                    "filterable_fields": settings_payload.filterable_fields,
-                    "sortable_fields": settings_payload.sortable_fields,
-                    "field_boosts": settings_payload.field_boosts,
-                },
-            )
+            _ensure_index(backend, index_name)
             logger.info(
                 "search index ensured",
                 context={"index": index_name},

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/public_api_registry.py

@@ -793,6 +793,11 @@ RULE_EXPORTS: LazyExportMap = {
 }
 
 SEARCH_EXPORTS: LazyExportMap = {
+    "SearchIdentityFilterGroup": (
+        "general_manager.search.identity",
+        "SearchIdentityFilterGroup",
+    ),
+    "build_search_filters": ("general_manager.search.identity", "build_search_filters"),
     "FieldConfig": ("general_manager.search.config", "FieldConfig"),
     "IndexConfig": ("general_manager.search.config", "IndexConfig"),
     "SearchConfigProtocol": ("general_manager.search.config", "SearchConfigProtocol"),

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/search/backend.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import builtins
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Protocol, runtime_checkable
 
 
@@ -20,7 +21,10 @@ class SearchDocument:
     protocol does not require adapters to reject mismatches between
     `document.index` and an `index_name` argument. `data` contains
     searchable/stored fields. `field_boosts` and `index_boost` are hints for
-    adapters that support weighted matching. The payload mappings, including
+    adapters that support weighted matching. `identity_fields` maps explicit
+    identity names to native scalar types (`int`, `str`, or `UUID`), including
+    nullable/collection element types. It never coerces document values.
+    The payload mappings, including
     `identification`, are not copied by the model; callers should treat them as
     immutable after handing them to a backend. Dataclass field annotations are
     the validation boundary; this model does not coerce or validate runtime
@@ -36,6 +40,7 @@ class SearchDocument:
     data: Mapping[str, object]
     field_boosts: Mapping[str, float]
     index_boost: float | None = None
+    identity_fields: Mapping[str, builtins.type] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/search/backends/dev.py

@@ -10,6 +10,11 @@ from threading import RLock
 from general_manager.search.backend import SearchDocument, SearchHit, SearchResult
 from general_manager.bucket._ordering import normalize_ordering, sort_items
 from general_manager.utils.filter_parser import apply_lookup
+from general_manager.search.identity import (
+    SearchIdentityFilterGroup,
+    identity_lookup,
+    canonical_identity,
+)
 
 
 @dataclass
@@ -176,6 +181,10 @@ class DevSearchBackend:
                 case-sensitive, missing fields behave like `None`, incompatible
                 mixed-type comparisons and invalid lookup/value combinations
                 return `False`, and `None` compares only through `exact`.
+                Explicit `SearchIdentityFilterGroup` equality/membership uses
+                native casts and owner scope without changing these operator
+                rules. Matching document metadata and a present field are
+                required. Plain mappings retain raw comparisons.
             filter_expression (str | None): Unsupported in this backend; passing a value raises NotImplementedError.
             sort (Sequence[str] | None): Signed document data field names.
                 Prefix a field with ``-`` for descending order. If omitted,
@@ -392,12 +401,38 @@ class DevSearchBackend:
             if not all(isinstance(group, Mapping) for group in filters):
                 return False
             return any(self._passes_filters(document, group) for group in filters)
+        if isinstance(filters, SearchIdentityFilterGroup):
+            if filters.type_label is not None and document.type != filters.type_label:
+                return False
         for key, value in filters.items():
-            if "__" in key:
+            identity = None
+            if isinstance(filters, SearchIdentityFilterGroup):
+                identity = identity_lookup(key, filters.identity_fields)
+            if identity is not None:
+                field_name, lookup, native_type = identity
+                if (
+                    field_name not in document.data
+                    or document.identity_fields.get(field_name) is not native_type
+                ):
+                    return False
+            elif "__" in key:
                 field_name, lookup = key.split("__", 1)
             else:
                 field_name, lookup = key, "exact"
             doc_value = document.data.get(field_name)
+            if identity is not None and (
+                lookup != "in" or isinstance(value, (list, tuple, set))
+            ):
+                doc_value = (
+                    [canonical_identity(native_type, item) for item in doc_value]
+                    if isinstance(doc_value, (list, tuple, set))
+                    else canonical_identity(native_type, doc_value)
+                )
+                value = (
+                    [canonical_identity(native_type, item) for item in value]
+                    if isinstance(value, (list, tuple, set))
+                    else canonical_identity(native_type, value)
+                )
             if lookup == "exact" and isinstance(value, (list, tuple, set)):
                 if isinstance(doc_value, (list, tuple, set)):
                     if not set(doc_value).intersection(value):

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/search/backends/meilisearch.py

@@ -8,6 +8,7 @@ from collections.abc import Callable, Iterable
 from importlib import import_module
 from inspect import signature
 from typing import Mapping, Protocol, Sequence, cast
+from uuid import UUID
 
 from general_manager.search.backend import (
     SearchBackendClientMissingError,
@@ -17,6 +18,14 @@ from general_manager.search.backend import (
     SearchResult,
 )
 from general_manager.bucket._ordering import normalize_ordering
+from general_manager.search.identity import (
+    SearchIdentityFilterGroup,
+    bind_search_filters,
+    identity_field_key,
+    identity_token,
+    meilisearch_identity_filters,
+    SearchIdentityConfigurationError,
+)
 
 
 def _load_meilisearch_api_error() -> type[Exception] | None:
@@ -155,6 +164,9 @@ class MeilisearchBackend:
                 - "searchable_fields": iterable of field names to set as searchableAttributes.
                 - "filterable_fields": iterable of field names to set as filterableAttributes.
                 - "sortable_fields": iterable of field names to set as sortableAttributes.
+                - "identity_fields": contracts keyed by document type; each
+                  maps identity names to int/str/UUID. Shadow filterability is
+                  added only for names listed in "filterable_fields".
 
         Non-iterable setting values and strings/bytes are ignored; iterable
         values such as lists, tuples, and sets are converted to strings. This
@@ -169,6 +181,29 @@ class MeilisearchBackend:
         index = self._get_or_create_index(index_name)
         searchable_fields = self._string_sequence_setting(settings, "searchable_fields")
         filterable_fields = self._string_sequence_setting(settings, "filterable_fields")
+        contracts = settings.get("identity_fields", {})
+        if not isinstance(contracts, Mapping):
+            raise SearchIdentityConfigurationError(
+                "identity_fields", "expected a mapping of type contracts"
+            )
+        identity_names: set[str] = set()
+        for owner, contract in contracts.items():
+            if not isinstance(contract, Mapping):
+                raise SearchIdentityConfigurationError(
+                    str(owner), "expected a native field mapping"
+                )
+            validated = SearchIdentityFilterGroup({}, identity_fields=contract)
+            identity_names.update(validated.identity_fields)
+        if filterable_fields is not None:
+            shadow_fields = {
+                "gm_identity." + identity_field_key(name)
+                for name in identity_names
+                if name in filterable_fields
+            }
+            filterable_fields = [
+                *filterable_fields,
+                *sorted(shadow_fields - set(filterable_fields)),
+            ]
         sortable_fields = self._string_sequence_setting(settings, "sortable_fields")
         ranking_rules = self._ranking_rules_with_sort_first(index, settings)
         task = index.update_settings({"rankingRules": ranking_rules})
@@ -322,7 +357,13 @@ class MeilisearchBackend:
             with structured filters. String rendering uses ``str(value)`` and
             escapes backslashes and double quotes; this also applies to numbers,
             booleans, and ``None``. Empty `in` lists produce an empty
-            parenthesized clause. ``sort`` is normalized as signed field names
+            parenthesized clause. Declared identity equality/membership uses
+            separate versioned tokens without changing source values. Plain
+            structured filters inherit registered manager/index contracts;
+            `SearchIdentityFilterGroup` supports unregistered documents.
+            Old documents without tokens require reindexing; raw
+            `filter_expression` bypasses identity transport.
+            ``sort`` is normalized as signed field names
             and forwarded as ordered Meilisearch ``field:direction`` entries.
             A sorted query reads the index settings and raises
             ``MeilisearchOrderingConfigurationError`` unless ``sort`` has the
@@ -342,7 +383,9 @@ class MeilisearchBackend:
         filter_expr = (
             filter_expression
             if filter_expression is not None
-            else self._build_filter_expression(filters, types)
+            else self._build_filter_expression(
+                bind_search_filters(index_name, filters, types), types
+            )
         )
         if filter_expr:
             payload["filter"] = filter_expr
@@ -447,22 +490,48 @@ class MeilisearchBackend:
                 - `data`: the original data mapping,
                 - additional top-level keys copied from `document.data` except
                   reserved keys (`id`, `gm_document_id`, `type`,
-                  `identification`, `data`).
+                  `identification`, `data`, `gm_identity`).
+                - `gm_identity`: bounded equality tokens for declared present
+                  identity fields. UUID/set JSON conversion affects only the
+                  payload copy, never the source document.
         """
-        reserved_keys = {"id", "gm_document_id", "type", "identification", "data"}
+        reserved_keys = {
+            "id",
+            "gm_document_id",
+            "type",
+            "identification",
+            "data",
+            "gm_identity",
+        }
         extra_data = {
             key: value
             for key, value in document.data.items()
             if key not in reserved_keys
         }
-        return {
-            "id": MeilisearchBackend._normalize_document_id(document.id),
-            "gm_document_id": document.id,
-            "type": document.type,
-            "identification": document.identification,
-            "data": document.data,
-            **extra_data,
-        }
+        identities: dict[str, object] = {}
+        for name, native_type in document.identity_fields.items():
+            if name not in document.data:
+                continue
+            value = document.data[name]
+            identities[identity_field_key(name)] = (
+                [identity_token(native_type, item) for item in value]
+                if isinstance(value, (list, tuple, set))
+                else identity_token(native_type, value)
+            )
+        return cast(
+            dict[str, object],
+            _json_search_value(
+                {
+                    "id": MeilisearchBackend._normalize_document_id(document.id),
+                    "gm_document_id": document.id,
+                    "type": document.type,
+                    "identification": document.identification,
+                    "data": document.data,
+                    **extra_data,
+                    "gm_identity": identities,
+                }
+            ),
+        )
 
     @staticmethod
     def _build_filter_expression(
@@ -485,6 +554,9 @@ class MeilisearchBackend:
                 fields in one mapping are combined with AND; multiple mappings
                 are combined with OR. Empty `in` lists produce the exact clause
                 ``()``.
+                Explicit identity groups instead target versioned `gm_identity`
+                fields. Null has its own token; empty identity `in` operands
+                produce an always-false clause.
             types (Sequence[str] | None):
                 Sequence of type names to restrict results to; these are combined with OR against the `type` field.
 
@@ -502,12 +574,22 @@ class MeilisearchBackend:
             group_clauses: list[str] = []
             for group in filter_groups:
                 parts: list[str] = []
-                for key, value in group.items():
+                if (
+                    isinstance(group, SearchIdentityFilterGroup)
+                    and group.type_label is not None
+                ):
+                    parts.append(f'type = "{_escape_filter_value(group.type_label)}"')
+                for key, value in meilisearch_identity_filters(group):
                     if "__" in key:
                         field_name, lookup = key.split("__", 1)
                     else:
                         field_name, lookup = key, "exact"
                     if lookup == "in" and isinstance(value, (list, tuple, set)):
+                        if field_name.startswith("gm_identity.") and not value:
+                            parts.append(
+                                f"({field_name} EXISTS AND {field_name} NOT EXISTS)"
+                            )
+                            continue
                         options = " OR ".join(
                             [
                                 f'{field_name} = "{_escape_filter_value(item)}"'
@@ -808,6 +890,17 @@ def _is_meilisearch_already_exists(error: Exception) -> bool:
     return status == 409 or "already_exists" in code
 
 
+def _json_search_value(value: object) -> object:
+    """Copy native document values into JSON-compatible provider payloads."""
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, Mapping):
+        return {key: _json_search_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_json_search_value(item) for item in value]
+    return value
+
+
 def _escape_filter_value(value: object) -> str:
     """
     Escape a value for inclusion in a Meilisearch filter expression.

{generalmanager-0.82.3 → generalmanager-0.82.5}/src/general_manager/search/config.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Literal, Protocol, cast
+from uuid import UUID
 
 from general_manager.manager.general_manager import GeneralManager
 
 
 _RESERVED_DOCUMENT_FIELD_NAMES = frozenset(
-    {"id", "gm_document_id", "type", "identification", "data"}
+    {"id", "gm_document_id", "type", "identification", "data", "gm_identity"}
 )
 
 
@@ -110,6 +111,10 @@ class IndexConfig:
         sorts: Field names allowed for backend sorting.
         boost: Optional positive index-level boost.
         min_score: Optional non-negative minimum relevance score.
+        identity_fields: Native scalar kinds (`int`, `str`, `UUID`) for configured
+            document aliases, including nullable/collection element types.
+            Manager identity metadata is inherited automatically; conflicting
+            overrides fail when the index contract is resolved.
 
     Raises:
         InvalidIndexBoostError: If `boost` is not `None` and is less than or
@@ -126,6 +131,7 @@ class IndexConfig:
     sorts: Sequence[str] = field(default_factory=tuple)
     boost: float | None = None
     min_score: float | None = None
+    identity_fields: Mapping[str, type] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         """Validate index-level boost and minimum score after initialization."""
@@ -143,6 +149,25 @@ class IndexConfig:
         for field_name in (*self.filters, *self.sorts):
             if field_name in _RESERVED_DOCUMENT_FIELD_NAMES:
                 raise ReservedDocumentFieldNameError(field_name)
+        from general_manager.search.identity import SearchIdentityConfigurationError
+
+        serialized_fields = {
+            *(
+                entry.name if isinstance(entry, FieldConfig) else entry
+                for entry in self.fields
+            ),
+            *self.filters,
+            *self.sorts,
+        }
+        for field_name, native_type in self.identity_fields.items():
+            if field_name not in serialized_fields:
+                raise SearchIdentityConfigurationError(
+                    field_name, "field is not configured"
+                )
+            if native_type not in (int, str, UUID):
+                raise SearchIdentityConfigurationError(
+                    field_name, "expected int, str or UUID"
+                )
         if self.boost is not None and self.boost <= 0:
             raise InvalidIndexBoostError
         if self.min_score is not None and self.min_score < 0: