GeneralManager 0.16.1__py3-none-any.whl → 0.18.0__py3-none-any.whl

general_manager/api/graphql.py

@@ -1,33 +1,53 @@
 """GraphQL schema utilities for exposing GeneralManager models via Graphene."""
 
 from __future__ import annotations
-import graphene  # type: ignore[import]
+
+import ast as py_ast
+import asyncio
+from contextlib import suppress
+import json
+from dataclasses import dataclass
+from copy import deepcopy
+from datetime import date, datetime
+from decimal import Decimal
+import hashlib
+from types import UnionType
 from typing import (
     Any,
+    AsyncIterator,
     Callable,
-    get_args,
-    get_origin,
+    ClassVar,
+    Generator,
+    Iterable,
     TYPE_CHECKING,
-    cast,
     Type,
-    Generator,
     Union,
+    cast,
+    get_args,
+    get_origin,
 )
-from types import UnionType
 
-from decimal import Decimal
-from datetime import date, datetime
-import json
+import graphene  # type: ignore[import]
 from graphql.language import ast
+from graphql.language.ast import (
+    FieldNode,
+    FragmentSpreadNode,
+    InlineFragmentNode,
+    SelectionSetNode,
+)
+from asgiref.sync import async_to_sync
+from channels.layers import BaseChannelLayer, get_channel_layer
 
-from general_manager.measurement.measurement import Measurement
-from general_manager.manager.generalManager import GeneralManagerMeta, GeneralManager
-from general_manager.api.property import GraphQLProperty
+from general_manager.cache.cacheTracker import DependencyTracker
+from general_manager.cache.dependencyIndex import Dependency
+from general_manager.cache.signals import post_data_change
 from general_manager.bucket.baseBucket import Bucket
 from general_manager.interface.baseInterface import InterfaceBase
-from django.db.models import NOT_PROVIDED
-from django.core.exceptions import ValidationError
+from general_manager.manager.generalManager import GeneralManager
+from general_manager.measurement.measurement import Measurement
 
+from django.core.exceptions import ValidationError
+from django.db.models import NOT_PROVIDED
 from graphql import GraphQLError
 
 
@@ -36,6 +56,95 @@ if TYPE_CHECKING:
     from graphene import ResolveInfo as GraphQLResolveInfo
 
 
+@dataclass(slots=True)
+class SubscriptionEvent:
+    """Payload delivered to GraphQL subscription resolvers."""
+
+    item: Any | None
+    action: str
+
+
+class InvalidMeasurementValueError(TypeError):
+    """Raised when a scalar receives a value that is not a Measurement instance."""
+
+    def __init__(self, value: object) -> None:
+        """
+        Initialize the error raised when a scalar value is not a Measurement instance.
+
+        Parameters:
+            value (object): The value that failed validation; its type name is included in the exception message.
+        """
+        super().__init__(f"Expected Measurement, got {type(value).__name__}.")
+
+
+class MissingChannelLayerError(RuntimeError):
+    """Raised when GraphQL subscriptions run without a configured channel layer."""
+
+    def __init__(self) -> None:
+        """
+        Indicates that Django Channels channel layer is not configured for GraphQL subscriptions.
+
+        Raised when subscription functionality requires a configured channel layer (e.g., CHANNEL_LAYERS) but none is present.
+        """
+        super().__init__(
+            "No channel layer configured. Configure CHANNEL_LAYERS to enable GraphQL subscriptions."
+        )
+
+
+class UnsupportedGraphQLFieldTypeError(TypeError):
+    """Raised when attempting to map an unsupported Python type to GraphQL."""
+
+    def __init__(self, field_type: type) -> None:
+        """
+        Exception raised when a Python `dict` type is encountered while mapping a field to GraphQL, which is not supported.
+
+        Parameters:
+            field_type (type): The offending Python type that was provided for the field. The exception message includes this type's `__name__`.
+        """
+        super().__init__(
+            f"GraphQL does not support dict fields (received {field_type.__name__})."
+        )
+
+
+class InvalidGeneralManagerClassError(TypeError):
+    """Raised when a non-GeneralManager subclass is used in the GraphQL registry."""
+
+    def __init__(self, received_class: type) -> None:
+        """
+        Initialize the exception indicating the provided class is not a GeneralManager subclass.
+
+        Parameters:
+            received_class (type): The class that was supplied but is not a subclass of GeneralManager.
+        """
+        super().__init__(
+            f"{received_class.__name__} must be a subclass of GeneralManager to create a GraphQL interface."
+        )
+
+
+class MissingManagerIdentifierError(ValueError):
+    """Raised when a GraphQL mutation is missing the required manager identifier."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the exception indicating a required manager identifier is missing.
+
+        This exception instance carries the default message "id is required.".
+        """
+        super().__init__("id is required.")
+
+
+HANDLED_MANAGER_ERRORS: tuple[type[Exception], ...] = (
+    PermissionError,
+    ValidationError,
+    ValueError,
+    LookupError,
+    TypeError,
+    AttributeError,
+    GraphQLError,
+    RuntimeError,
+)
+
+
 class MeasurementType(graphene.ObjectType):
     value = graphene.Float()
     unit = graphene.String()
@@ -48,8 +157,20 @@ class MeasurementScalar(graphene.Scalar):
 
     @staticmethod
     def serialize(value: Measurement) -> str:
+        """
+        Convert a Measurement to its string representation.
+
+        Parameters:
+            value (Measurement): Measurement to serialize.
+
+        Returns:
+            str: String representation of the given Measurement.
+
+        Raises:
+            InvalidMeasurementValueError: If `value` is not a Measurement instance.
+        """
         if not isinstance(value, Measurement):
-            raise TypeError(f"Expected Measurement, got {type(value)}")
+            raise InvalidMeasurementValueError(value)
         return str(value)
 
     @staticmethod
@@ -71,18 +192,18 @@ class PageInfo(graphene.ObjectType):
 
 
 def getReadPermissionFilter(
-    generalManagerClass: GeneralManagerMeta,
+    generalManagerClass: Type[GeneralManager],
     info: GraphQLResolveInfo,
 ) -> list[tuple[dict[str, Any], dict[str, Any]]]:
     """
-    Return permission-derived filter and exclude pairs for the given manager class.
+    Produce a list of permission-derived filter and exclude mappings for queries against a manager class.
 
     Parameters:
-        generalManagerClass (GeneralManagerMeta): Manager class being queried.
-        info (GraphQLResolveInfo): GraphQL resolver info containing the request user.
+        generalManagerClass (Type[GeneralManager]): Manager class to derive permission filters for.
+        info (GraphQLResolveInfo): GraphQL resolver info whose context provides the current user.
 
     Returns:
-        list[tuple[dict[str, Any], dict[str, Any]]]: List of ``(filter, exclude)`` mappings.
+        list[tuple[dict[str, Any], dict[str, Any]]]: A list of `(filter, exclude)` tuples where each `filter` and `exclude` is a mapping of query constraints produced by the manager's Permission class.
     """
     filters = []
     PermissionClass: type[BasePermission] | None = getattr(
@@ -102,21 +223,108 @@ def getReadPermissionFilter(
 class GraphQL:
     """Static helper that builds GraphQL types, queries, and mutations for managers."""
 
-    _query_class: type[graphene.ObjectType] | None = None
-    _mutation_class: type[graphene.ObjectType] | None = None
-    _mutations: dict[str, Any] = {}
-    _query_fields: dict[str, Any] = {}
-    _page_type_registry: dict[str, type[graphene.ObjectType]] = {}
-    graphql_type_registry: dict[str, type] = {}
-    graphql_filter_type_registry: dict[str, type] = {}
+    _query_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _mutation_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _subscription_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _mutations: ClassVar[dict[str, Any]] = {}
+    _query_fields: ClassVar[dict[str, Any]] = {}
+    _subscription_fields: ClassVar[dict[str, Any]] = {}
+    _page_type_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
+    _subscription_payload_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
+    graphql_type_registry: ClassVar[dict[str, type]] = {}
+    graphql_filter_type_registry: ClassVar[dict[str, type]] = {}
+    manager_registry: ClassVar[dict[str, type[GeneralManager]]] = {}
+    _schema: ClassVar[graphene.Schema | None] = None
+
+    @staticmethod
+    def _get_channel_layer(strict: bool = False) -> BaseChannelLayer | None:
+        """
+        Retrieve the configured channel layer for GraphQL subscriptions.
+
+        Parameters:
+            strict (bool): When True, raise MissingChannelLayerError if no channel layer is configured.
+
+        Returns:
+            BaseChannelLayer | None: The configured channel layer instance if available, otherwise None.
+
+        Raises:
+            MissingChannelLayerError: If `strict` is True and no channel layer is configured.
+        """
+        layer = cast(BaseChannelLayer | None, get_channel_layer())
+        if layer is None and strict:
+            raise MissingChannelLayerError()
+        return layer
+
+    @classmethod
+    def get_schema(cls) -> graphene.Schema | None:
+        """
+        Get the currently configured Graphene schema for the GraphQL registry.
+
+        Returns:
+            The active `graphene.Schema` instance, or `None` if no schema has been created.
+        """
+        return cls._schema
+
+    @staticmethod
+    def _group_name(
+        manager_class: type[GeneralManager], identification: dict[str, Any]
+    ) -> str:
+        """
+        Builds a deterministic channel group name for subscription events for a specific manager instance.
+
+        Parameters:
+            manager_class (type[GeneralManager]): GeneralManager subclass used to namespace the group.
+            identification (dict[str, Any]): Identifying fields for the manager instance; the mapping is JSON-normalized (sorted keys) before being incorporated.
+
+        Returns:
+            group_name (str): A deterministic channel group identifier derived from the manager class and normalized identification.
+        """
+        normalized = json.dumps(identification, sort_keys=True, default=str)
+        digest = hashlib.sha256(
+            f"{manager_class.__module__}.{manager_class.__name__}:{normalized}".encode(
+                "utf-8"
+            )
+        ).hexdigest()[:32]
+        return f"gm_subscriptions.{manager_class.__name__}.{digest}"
+
+    @staticmethod
+    async def _channel_listener(
+        channel_layer: BaseChannelLayer,
+        channel_name: str,
+        queue: asyncio.Queue[str],
+    ) -> None:
+        """
+        Listen to a channel layer for "gm.subscription.event" messages and enqueue their `action` values.
+
+        Continuously receives messages from the given channel_name on the channel_layer, and when a message of type "gm.subscription.event" contains an `action`, that action string is put into the provided asyncio queue. Ignores messages of other types. The loop exits silently when the task is cancelled.
+
+        Parameters:
+                channel_layer (BaseChannelLayer): Channel layer to receive messages from.
+                channel_name (str): Name of the channel to listen on.
+                queue (asyncio.Queue[str]): Async queue to which received action strings will be enqueued.
+        """
+        try:
+            while True:
+                message = cast(
+                    dict[str, Any], await channel_layer.receive(channel_name)
+                )
+                if message.get("type") != "gm.subscription.event":
+                    continue
+                action = cast(str | None, message.get("action"))
+                if action is not None:
+                    await queue.put(action)
+        except asyncio.CancelledError:
+            pass
 
     @classmethod
     def createGraphqlMutation(cls, generalManagerClass: type[GeneralManager]) -> None:
         """
-        Register create, update, and delete mutations for ``generalManagerClass``.
+        Register GraphQL mutation classes for a GeneralManager based on its Interface.
+
+        If the manager's Interface overrides the default `create`, `update`, or `deactivate` methods, corresponding mutation classes are generated and stored in the class-level mutation registry under the names `create<ManagerName>`, `update<ManagerName>`, and `delete<ManagerName>`. Each generated mutation exposes a `success` flag and a field named for the manager class that returns the created/updated/deactivated object.
 
         Parameters:
-            generalManagerClass (type[GeneralManager]): Manager class whose interface drives mutation generation.
+            generalManagerClass (type[GeneralManager]): Manager class whose `Interface` determines which mutations are generated and registered.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -150,12 +358,14 @@ class GraphQL:
             )
 
     @classmethod
-    def createGraphqlInterface(cls, generalManagerClass: GeneralManagerMeta) -> None:
+    def createGraphqlInterface(cls, generalManagerClass: Type[GeneralManager]) -> None:
         """
-        Build and register a Graphene ``ObjectType`` for the supplied manager class.
+        Create and register a Graphene ObjectType for a GeneralManager class and expose its queries and subscription.
+
+        Builds a Graphene type by mapping the manager's Interface attributes and GraphQLProperties to Graphene fields and resolvers, registers the resulting type and manager in the GraphQL registries, and adds corresponding query and subscription fields to the schema.
 
         Parameters:
-            generalManagerClass (GeneralManagerMeta): Manager class whose attributes drive field generation.
+            generalManagerClass (Type[GeneralManager]): The manager class whose Interface and GraphQLProperties are used to generate Graphene fields and resolvers.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -216,20 +426,19 @@ class GraphQL:
 
         graphene_type = type(graphene_type_name, (graphene.ObjectType,), fields)
         cls.graphql_type_registry[generalManagerClass.__name__] = graphene_type
+        cls.manager_registry[generalManagerClass.__name__] = generalManagerClass
         cls._addQueriesToSchema(graphene_type, generalManagerClass)
+        cls._addSubscriptionField(graphene_type, generalManagerClass)
 
     @staticmethod
     def _sortByOptions(
-        generalManagerClass: GeneralManagerMeta,
+        generalManagerClass: Type[GeneralManager],
     ) -> type[graphene.Enum] | None:
         """
-        Build an enum of sortable fields for the provided manager class.
-
-        Parameters:
-            generalManagerClass (GeneralManagerMeta): Manager class being inspected.
+        Builds an enum of sortable field names for the given manager class.
 
         Returns:
-            type[graphene.Enum] | None: Enum of sortable fields, or ``None`` when no options exist.
+            An Enum type whose members are the sortable field names for the manager, or `None` if no sortable fields exist.
         """
         sort_options = []
         for (
@@ -266,7 +475,9 @@ class GraphQL:
         )
 
     @staticmethod
-    def _getFilterOptions(attribute_type: type, attribute_name: str) -> Generator[
+    def _getFilterOptions(
+        attribute_type: type, attribute_name: str
+    ) -> Generator[
         tuple[
             str, type[graphene.ObjectType] | MeasurementScalar | graphene.List | None
         ],
@@ -274,14 +485,18 @@ class GraphQL:
         None,
     ]:
         """
-        Yield filter field names and Graphene types for a given attribute.
+        Produce filter field names and corresponding Graphene input types for a given attribute.
 
         Parameters:
-            attribute_type (type): Python type declared for the attribute.
-            attribute_name (str): Name of the attribute.
+            attribute_type (type): The Python type declared for the attribute.
+            attribute_name (str): The attribute's name used as the base for generated filter field names.
 
         Yields:
-            tuple[str, Graphene type | None]: Filter name and corresponding Graphene type.
+            tuple[str, type | MeasurementScalar | graphene.List | None]:
+                A pair where the first element is a filter field name (e.g., "age", "price__gte",
+                "name__icontains") and the second element is the Graphene input type for that filter
+                or `None` when no Graphene input type should be exposed (for example, nested
+                GeneralManager references).
         """
         number_options = ["exact", "gt", "gte", "lt", "lte"]
         string_options = [
@@ -300,13 +515,19 @@ class GraphQL:
             for option in number_options:
                 yield f"{attribute_name}__{option}", MeasurementScalar()
         else:
-            yield attribute_name, GraphQL._mapFieldToGrapheneRead(
-                attribute_type, attribute_name
+            yield (
+                attribute_name,
+                GraphQL._mapFieldToGrapheneRead(attribute_type, attribute_name),
             )
             if issubclass(attribute_type, (int, float, Decimal, date, datetime)):
                 for option in number_options:
-                    yield f"{attribute_name}__{option}", (
-                        GraphQL._mapFieldToGrapheneRead(attribute_type, attribute_name)
+                    yield (
+                        f"{attribute_name}__{option}",
+                        (
+                            GraphQL._mapFieldToGrapheneRead(
+                                attribute_type, attribute_name
+                            )
+                        ),
                     )
             elif issubclass(attribute_type, str):
                 base_type = GraphQL._mapFieldToGrapheneBaseType(attribute_type)
@@ -314,24 +535,29 @@ class GraphQL:
                     if option == "in":
                         yield f"{attribute_name}__in", graphene.List(base_type)
                     else:
-                        yield f"{attribute_name}__{option}", (
-                            GraphQL._mapFieldToGrapheneRead(
-                                attribute_type, attribute_name
-                            )
+                        yield (
+                            f"{attribute_name}__{option}",
+                            (
+                                GraphQL._mapFieldToGrapheneRead(
+                                    attribute_type, attribute_name
+                                )
+                            ),
                         )
 
     @staticmethod
     def _createFilterOptions(
-        field_type: GeneralManagerMeta,
+        field_type: Type[GeneralManager],
     ) -> type[graphene.InputObjectType] | None:
         """
-        Create a Graphene ``InputObjectType`` for filters on ``field_type``.
+        Create a Graphene InputObjectType that exposes available filter fields for a GeneralManager subclass.
+
+        Builds filter fields from the manager's Interface attributes and any GraphQLProperty marked filterable. Returns None when no filterable fields are found.
 
         Parameters:
-            field_type (GeneralManagerMeta): Manager class whose attributes drive filter generation.
+            field_type (Type[GeneralManager]): Manager class whose Interface and GraphQLProperties determine the filter fields.
 
         Returns:
-            type[graphene.InputObjectType] | None: Input type containing filter fields, or ``None`` if not applicable.
+            type[graphene.InputObjectType] | None: Generated InputObjectType class for filters, or `None` if no filter fields are applicable.
         """
 
         graphene_filter_type_name = f"{field_type.__name__}FilterType"
@@ -390,7 +616,7 @@ class GraphQL:
             return graphene.Field(MeasurementType, target_unit=graphene.String())
         elif issubclass(field_type, GeneralManager):
             if field_name.endswith("_list"):
-                attributes = {
+                attributes: dict[str, Any] = {
                     "reverse": graphene.Boolean(),
                     "page": graphene.Int(),
                     "page_size": graphene.Int(),
@@ -420,29 +646,37 @@ class GraphQL:
     @staticmethod
     def _mapFieldToGrapheneBaseType(field_type: type) -> Type[Any]:
         """
-        Map a Python type to the corresponding Graphene scalar/class.
+        Map a Python interface type to the corresponding Graphene scalar or custom scalar.
 
         Parameters:
-            field_type (type): Python type declared on the interface.
+            field_type (type): Python type from the interface to map.
 
         Returns:
-            Type[Any]: Graphene scalar or type implementing the field.
+            Type[Any]: The Graphene scalar or custom scalar type used to represent the input type (e.g., graphene.String, graphene.Int, MeasurementScalar).
+
+        Raises:
+            UnsupportedGraphQLFieldTypeError: If `field_type` is `dict`, which is not supported for GraphQL mapping.
         """
-        if issubclass(field_type, dict):
-            raise TypeError("GraphQL does not support dict fields")
-        if issubclass(field_type, str):
+        base_type = (
+            get_origin(field_type) or field_type
+        )  # Handle typing generics safely.
+        if not isinstance(base_type, type):
             return graphene.String
-        elif issubclass(field_type, bool):
+        if issubclass(base_type, dict):
+            raise UnsupportedGraphQLFieldTypeError(field_type)
+        if issubclass(base_type, str):
+            return graphene.String
+        elif issubclass(base_type, bool):
             return graphene.Boolean
-        elif issubclass(field_type, int):
+        elif issubclass(base_type, int):
             return graphene.Int
-        elif issubclass(field_type, (float, Decimal)):
+        elif issubclass(base_type, (float, Decimal)):
             return graphene.Float
-        elif issubclass(field_type, datetime):
+        elif issubclass(base_type, datetime):
             return graphene.DateTime
-        elif issubclass(field_type, date):
+        elif issubclass(base_type, date):
             return graphene.Date
-        elif issubclass(field_type, Measurement):
+        elif issubclass(base_type, Measurement):
             return MeasurementScalar
         else:
             return graphene.String
@@ -450,20 +684,22 @@ class GraphQL:
     @staticmethod
     def _parseInput(input_val: dict[str, Any] | str | None) -> dict[str, Any]:
         """
-        Normalise filter/exclude input into a dictionary.
+        Normalize a filter or exclude input into a dictionary.
+
+        Accepts a dict, a JSON-encoded string, or None. If given None or an invalid JSON string, returns an empty dict.
 
         Parameters:
-            input_val (dict[str, Any] | str | None): Raw filter/exclude value.
+            input_val: Filter or exclude input provided as a dict, a JSON-encoded string, or None.
 
         Returns:
-            dict[str, Any]: Parsed dictionary suitable for queryset filtering.
+            dict: Mapping of filter keys to values; empty dict if input is None or invalid JSON.
         """
         if input_val is None:
             return {}
         if isinstance(input_val, str):
             try:
                 return json.loads(input_val)
-            except Exception:
+            except (json.JSONDecodeError, ValueError):
                 return {}
         return input_val
 
@@ -585,6 +821,8 @@ class GraphQL:
                 A dictionary containing the paginated items under "items" and pagination metadata under "pageInfo".
             """
             base_queryset = base_getter(self)
+            if base_queryset is None:
+                base_queryset = fallback_manager_class.all()
             # use _manager_class from the attribute if available, otherwise fallback
             manager_class = getattr(
                 base_queryset, "_manager_class", fallback_manager_class
@@ -713,9 +951,19 @@ class GraphQL:
         item_type: type[graphene.ObjectType] | Callable[[], type[graphene.ObjectType]],
     ) -> type[graphene.ObjectType]:
         """
-        Returns a paginated GraphQL ObjectType for the specified item type, creating and caching it if it does not already exist.
+        Provide or retrieve a GraphQL ObjectType that represents a paginated page for the given item type.
 
-        The returned ObjectType includes an `items` field (a required list of the item type) and a `pageInfo` field (pagination metadata).
+        Creates and caches a GraphQL ObjectType with two fields:
+        - `items`: a required list of the provided item type.
+        - `pageInfo`: a required PageInfo object containing pagination metadata.
+
+        Parameters:
+            page_type_name (str): The name to use for the generated GraphQL ObjectType.
+            item_type (type[graphene.ObjectType] | Callable[[], type[graphene.ObjectType]]):
+                The Graphene ObjectType used for items, or a zero-argument callable that returns it (to support forward references).
+
+        Returns:
+            type[graphene.ObjectType]: A Graphene ObjectType with `items` and `pageInfo` fields.
         """
         if page_type_name not in cls._page_type_registry:
             cls._page_type_registry[page_type_name] = type(
@@ -728,28 +976,65 @@ class GraphQL:
             )
         return cls._page_type_registry[page_type_name]
 
+    @classmethod
+    def _buildIdentificationArguments(
+        cls, generalManagerClass: Type[GeneralManager]
+    ) -> dict[str, Any]:
+        """
+        Build the GraphQL arguments required to uniquely identify an instance of the given manager class.
+
+        For each input field defined on the manager's Interface: use "<name>_id" as a required ID argument for fields that reference another GeneralManager, use "id" as a required ID argument when present, and map other fields to their corresponding Graphene base type marked required.
+
+        Parameters:
+            generalManagerClass: GeneralManager subclass whose Interface.input_fields are used to derive identification arguments.
+
+        Returns:
+            dict[str, Any]: Mapping of argument name to a Graphene Argument suitable for identifying a single manager instance.
+        """
+        identification_fields: dict[str, Any] = {}
+        for (
+            input_field_name,
+            input_field,
+        ) in generalManagerClass.Interface.input_fields.items():
+            if issubclass(input_field.type, GeneralManager):
+                key = f"{input_field_name}_id"
+                identification_fields[key] = graphene.Argument(
+                    graphene.ID, required=True
+                )
+            elif input_field_name == "id":
+                identification_fields[input_field_name] = graphene.Argument(
+                    graphene.ID, required=True
+                )
+            else:
+                base_type = cls._mapFieldToGrapheneBaseType(input_field.type)
+                identification_fields[input_field_name] = graphene.Argument(
+                    base_type, required=True
+                )
+        return identification_fields
+
     @classmethod
     def _addQueriesToSchema(
-        cls, graphene_type: type, generalManagerClass: GeneralManagerMeta
+        cls, graphene_type: type, generalManagerClass: Type[GeneralManager]
     ) -> None:
         """
-        Register list and detail query fields for ``generalManagerClass``.
+        Registers list and detail GraphQL query fields for the given manager type into the class query registry.
 
         Parameters:
-            graphene_type (type): Graphene ``ObjectType`` representing the manager.
-            generalManagerClass (GeneralManagerMeta): Manager class being exposed.
+            graphene_type (type): The Graphene ObjectType that represents the manager's GraphQL type.
+            generalManagerClass (Type[GeneralManager]): The GeneralManager subclass to expose via queries.
+
+        Raises:
+            TypeError: If `generalManagerClass` is not a subclass of GeneralManager.
         """
         if not issubclass(generalManagerClass, GeneralManager):
-            raise TypeError(
-                "generalManagerClass must be a subclass of GeneralManager to create a GraphQL interface"
-            )
+            raise InvalidGeneralManagerClassError(generalManagerClass)
 
         if not hasattr(cls, "_query_fields"):
             cls._query_fields = cast(dict[str, Any], {})
 
         # resolver and field for the list query
         list_field_name = f"{generalManagerClass.__name__.lower()}_list"
-        attributes = {
+        attributes: dict[str, Any] = {
             "reverse": graphene.Boolean(),
             "page": graphene.Int(),
             "page_size": graphene.Int(),
@@ -768,50 +1053,465 @@ class GraphQL:
         )
         list_field = graphene.Field(page_type, **attributes)
 
-        list_resolver = cls._createListResolver(
-            lambda self: generalManagerClass.all(), generalManagerClass
-        )
+        def _all_items(_: Any) -> Any:
+            """
+            Return all instances for the associated GeneralManager class.
+
+            Returns:
+                All instances for the associated GeneralManager class, typically provided as a Bucket/QuerySet-like iterable.
+            """
+            return generalManagerClass.all()
+
+        list_resolver = cls._createListResolver(_all_items, generalManagerClass)
         cls._query_fields[list_field_name] = list_field
         cls._query_fields[f"resolve_{list_field_name}"] = list_resolver
 
         # resolver and field for the single item query
         item_field_name = generalManagerClass.__name__.lower()
-        identification_fields = {}
-        for (
-            input_field_name,
-            input_field,
-        ) in generalManagerClass.Interface.input_fields.items():
-            if issubclass(input_field.type, GeneralManager):
-                key = f"{input_field_name}_id"
-                identification_fields[key] = graphene.Int(required=True)
-            elif input_field_name == "id":
-                identification_fields[input_field_name] = graphene.ID(required=True)
-            else:
-                identification_fields[input_field_name] = cls._mapFieldToGrapheneRead(
-                    input_field.type, input_field_name
-                )
-                identification_fields[input_field_name].required = True
-
+        identification_fields = cls._buildIdentificationArguments(generalManagerClass)
         item_field = graphene.Field(graphene_type, **identification_fields)
 
         def resolver(
             self: GeneralManager, info: GraphQLResolveInfo, **identification: dict
         ) -> GeneralManager:
+            """
+            Instantiate and return a GeneralManager for the provided identification arguments.
+
+            Parameters:
+                identification (dict): Mapping of identification argument names to values passed to the manager constructor.
+
+            Returns:
+                GeneralManager: The manager instance identified by the provided arguments.
+            """
             return generalManagerClass(**identification)
 
         cls._query_fields[item_field_name] = item_field
         cls._query_fields[f"resolve_{item_field_name}"] = resolver
 
+    @staticmethod
+    def _prime_graphql_properties(
+        instance: GeneralManager, property_names: Iterable[str] | None = None
+    ) -> None:
+        """
+        Eagerly evaluate GraphQLProperty attributes on a manager instance to capture dependency metadata.
+
+        When GraphQLProperty descriptors are accessed they may record dependency information on the instance; this function forces those properties to be read so their dependency tracking is populated. If `property_names` is provided, only those property names that exist on the Interface are evaluated; otherwise all GraphQLProperties from the Interface are evaluated.
+
+        Parameters:
+            instance (GeneralManager): The manager instance whose GraphQLProperty attributes should be evaluated.
+            property_names (Iterable[str] | None): Optional iterable of property names to evaluate. Names not present in the Interface's GraphQLProperties are ignored.
+        """
+        interface_cls = getattr(instance.__class__, "Interface", None)
+        if interface_cls is None:
+            return
+        available_properties = interface_cls.getGraphQLProperties()
+        if property_names is None:
+            names = available_properties.keys()
+        else:
+            names = [name for name in property_names if name in available_properties]
+        for prop_name in names:
+            getattr(instance, prop_name)
+
+    @classmethod
+    def _dependencies_from_tracker(
+        cls, dependency_records: Iterable[Dependency]
+    ) -> list[tuple[type[GeneralManager], dict[str, Any]]]:
+        """
+        Convert dependency tracker records into resolved (manager class, identification dict) pairs.
+
+        Parses records whose operation is "identification", looks up the corresponding GeneralManager class by name in the registry, and parses the identifier into a dict. Records that do not meet these criteria are skipped.
+
+        Parameters:
+            dependency_records (Iterable[Dependency]): Iterable of dependency records as (manager_name, operation, identifier).
+
+        Returns:
+            list[tuple[type[GeneralManager], dict[str, Any]]]: List of (manager_class, identification_dict) tuples for each successfully resolved record.
+        """
+        resolved: list[tuple[type[GeneralManager], dict[str, Any]]] = []
+        for manager_name, operation, identifier in dependency_records:
+            if operation != "identification":
+                continue
+            manager_class = cls.manager_registry.get(manager_name)
+            if manager_class is None:
+                continue
+            try:
+                parsed = py_ast.literal_eval(identifier)
+            except (ValueError, SyntaxError):
+                continue
+            if not isinstance(parsed, dict):
+                continue
+            resolved.append((manager_class, parsed))
+        return resolved
+
+    @classmethod
+    def _subscription_property_names(
+        cls,
+        info: GraphQLResolveInfo,
+        manager_class: type[GeneralManager],
+    ) -> set[str]:
+        """
+        Determine which GraphQLProperty names are selected under the subscription payload's `item` field.
+
+        Parameters:
+            info (GraphQLResolveInfo): Resolve info containing the parsed selection set and fragments.
+            manager_class (type[GeneralManager]): GeneralManager subclass whose Interface defines available GraphQLProperty names.
+
+        Returns:
+            property_names (set[str]): Set of GraphQLProperty names referenced under the `item` selection in the subscription request; empty set if none or if the manager has no Interface.
+        """
+        interface_cls = getattr(manager_class, "Interface", None)
+        if interface_cls is None:
+            return set()
+        available_properties = set(interface_cls.getGraphQLProperties().keys())
+        if not available_properties:
+            return set()
+
+        property_names: set[str] = set()
+
+        def collect_from_selection(selection_set: SelectionSetNode | None) -> None:
+            """
+            Recursively collect selected GraphQL property names from a SelectionSetNode into the enclosing `property_names` set.
+
+            Processes each selection in the provided selection_set:
+            - Adds a field's name to `property_names` when the name is present in the surrounding `available_properties` set.
+            - For fragment spreads, resolves the fragment via `info.fragments` (from the enclosing scope) and recurses into its selection set.
+            - For inline fragments, recurses into the fragment's selection set.
+
+            Parameters:
+                selection_set (SelectionSetNode | None): GraphQL selection set to traverse; no action is taken if None.
+            """
+            if selection_set is None:
+                return
+            for selection in selection_set.selections:
+                if isinstance(selection, FieldNode):
+                    name = selection.name.value
+                    if name in available_properties:
+                        property_names.add(name)
+                elif isinstance(selection, FragmentSpreadNode):
+                    fragment = info.fragments.get(selection.name.value)
+                    if fragment is not None:
+                        collect_from_selection(fragment.selection_set)
+                elif isinstance(selection, InlineFragmentNode):
+                    collect_from_selection(selection.selection_set)
+
+        def inspect_selection_set(selection_set: SelectionSetNode | None) -> None:
+            """
+            Traverse a GraphQL SelectionSet and collect subselections of any field named "item".
+
+            Parameters:
+                selection_set (SelectionSetNode | None): The AST selection set to inspect. If None, the function returns without action.
+
+            Description:
+                - Visits FieldNode, FragmentSpreadNode, and InlineFragmentNode entries.
+                - For a FieldNode named "item", delegates its subselection to collect_from_selection.
+                - For other FieldNode entries and InlineFragmentNode entries, recurses into their subselections.
+                - For FragmentSpreadNode entries, attempts to resolve the referenced fragment (via the surrounding `info.fragments` if available) and inspects that fragment's subselection.
+            """
+            if selection_set is None:
+                return
+            for selection in selection_set.selections:
+                if isinstance(selection, FieldNode):
+                    if selection.name.value == "item":
+                        collect_from_selection(selection.selection_set)
+                    else:
+                        inspect_selection_set(selection.selection_set)
+                elif isinstance(selection, FragmentSpreadNode):
+                    fragment = info.fragments.get(selection.name.value)
+                    if fragment is not None:
+                        inspect_selection_set(fragment.selection_set)
+                elif isinstance(selection, InlineFragmentNode):
+                    inspect_selection_set(selection.selection_set)
+
+        for node in info.field_nodes:
+            inspect_selection_set(node.selection_set)
+        return property_names
+
+    @classmethod
+    def _resolve_subscription_dependencies(
+        cls,
+        manager_class: type[GeneralManager],
+        instance: GeneralManager,
+        dependency_records: Iterable[Dependency] | None = None,
+    ) -> list[tuple[type[GeneralManager], dict[str, Any]]]:
+        """
+        Builds a list of dependency pairs (manager class, identification) for subscription wiring from an instance and optional dependency records.
+
+        Given a manager class and its instantiated item, returns deduplicated dependency definitions derived from:
+        - any Dependency records produced by a dependency tracker, and
+        - the manager Interface's input fields that reference other GeneralManager types and are populated on the instance.
+
+        Parameters:
+            manager_class (type[GeneralManager]): The manager type whose subscription dependencies are being resolved.
+            instance (GeneralManager): The instantiated manager item whose inputs and identification are inspected.
+            dependency_records (Iterable[Dependency] | None): Optional dependency-tracker records to include.
+
+        Returns:
+            list[tuple[type[GeneralManager], dict[str, Any]]]: A list of (dependent_manager_class, identification) pairs.
+            Each identification is a dict of identification fields. The list excludes the (manager_class, instance.identification) pair and contains no duplicates.
+        """
+        dependencies: list[tuple[type[GeneralManager], dict[str, Any]]] = []
+        seen: set[tuple[str, str]] = set()
+        if dependency_records:
+            for (
+                dependency_class,
+                dependency_identification,
+            ) in cls._dependencies_from_tracker(dependency_records):
+                if (
+                    dependency_class is manager_class
+                    and dependency_identification == instance.identification
+                ):
+                    continue
+                key = (dependency_class.__name__, repr(dependency_identification))
+                if key in seen:
+                    continue
+                seen.add(key)
+                dependencies.append((dependency_class, dependency_identification))
+        interface_cls = manager_class.Interface
+
+        for (
+            input_name,
+            input_field,
+        ) in interface_cls.input_fields.items():
+            if not issubclass(input_field.type, GeneralManager):
+                continue
+
+            raw_value = instance._interface.identification.get(input_name)
+            if raw_value is None:
+                continue
+
+            values = raw_value if isinstance(raw_value, list) else [raw_value]
+            for value in values:
+                if isinstance(value, GeneralManager):
+                    identification = deepcopy(value.identification)
+                    key = (input_field.type.__name__, repr(identification))
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    dependencies.append(
+                        (
+                            cast(type[GeneralManager], input_field.type),
+                            identification,
+                        )
+                    )
+                elif isinstance(value, dict):
+                    identification_dict = deepcopy(cast(dict[str, Any], value))
+                    key = (input_field.type.__name__, repr(identification_dict))
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    dependencies.append(
+                        (
+                            cast(type[GeneralManager], input_field.type),
+                            identification_dict,
+                        )
+                    )
+
+        return dependencies
+
+    @staticmethod
+    def _instantiate_manager(
+        manager_class: type[GeneralManager],
+        identification: dict[str, Any],
+        *,
+        collect_dependencies: bool = False,
+        property_names: Iterable[str] | None = None,
+    ) -> tuple[GeneralManager, set[Dependency]]:
+        """
+        Create a GeneralManager instance for the given identification and optionally prime its GraphQL properties to capture dependency records.
+
+        Parameters:
+            manager_class (type[GeneralManager]): Manager class to instantiate.
+            identification (dict[str, Any]): Mapping of identification field names to values used to construct the instance.
+            collect_dependencies (bool): If True, prime GraphQL properties while tracking and return the captured Dependency records.
+            property_names (Iterable[str] | None): Specific GraphQLProperty names to prime; if None, all relevant properties are primed.
+
+        Returns:
+            tuple[GeneralManager, set[Dependency]]: The instantiated manager and a set of captured Dependency objects (empty if collect_dependencies is False).
+        """
+        if collect_dependencies:
+            with DependencyTracker() as captured_dependencies:
+                instance = manager_class(**identification)
+                GraphQL._prime_graphql_properties(instance, property_names)
+            return instance, captured_dependencies
+
+        instance = manager_class(**identification)
+        return instance, set()
+
+    @classmethod
+    def _addSubscriptionField(
+        cls,
+        graphene_type: type[graphene.ObjectType],
+        generalManagerClass: Type[GeneralManager],
+    ) -> None:
+        """
+        Register a GraphQL subscription field that publishes change events for the given manager type.
+
+        Creates (or reuses) a SubscriptionEvent payload GraphQL type and adds three entries to the class subscription registry:
+        - a field exposing the subscription with identification arguments,
+        - an async subscribe function that yields an initial "snapshot" event and subsequent change events for the identified instance and its dependencies,
+        - and a resolve function that returns the delivered payload.
+
+        Parameters:
+            graphene_type (type[graphene.ObjectType]): GraphQL ObjectType representing the manager's item type used as the payload `item` field.
+            generalManagerClass (Type[GeneralManager]): The GeneralManager subclass whose changes the subscription will publish.
+
+        Notes:
+        - The subscribe function requires an available channel layer and subscribes the caller to channel groups derived from the instance identification and its resolved dependencies.
+        - The subscribe coroutine yields SubscriptionEvent objects with fields `item` (the current instance or None if it cannot be instantiated) and `action` (a string such as `"snapshot"` or other change actions).
+        - On termination the subscription cleans up listener tasks and unsubscribes from channel groups.
+        """
+        field_name = f"on_{generalManagerClass.__name__.lower()}_change"
+        if field_name in cls._subscription_fields:
+            return
+
+        payload_type = cls._subscription_payload_registry.get(
+            generalManagerClass.__name__
+        )
+        if payload_type is None:
+            payload_type = type(
+                f"{generalManagerClass.__name__}SubscriptionEvent",
+                (graphene.ObjectType,),
+                {
+                    "item": graphene.Field(graphene_type),
+                    "action": graphene.String(required=True),
+                },
+            )
+            cls._subscription_payload_registry[generalManagerClass.__name__] = (
+                payload_type
+            )
+
+        identification_args = cls._buildIdentificationArguments(generalManagerClass)
+        subscription_field = graphene.Field(payload_type, **identification_args)
+
+        async def subscribe(
+            _root: Any,
+            info: GraphQLResolveInfo,
+            **identification: Any,
+        ) -> AsyncIterator[SubscriptionEvent]:
+            """
+            Stream subscription events for a specific manager instance identified by the provided arguments.
+
+            Yields an initial `SubscriptionEvent` with `action` set to `"snapshot"` containing the current manager instance, then yields `SubscriptionEvent`s for each subsequent action. For update events, `item` will be the re-instantiated manager instance or `None` if instantiation fails. The subscriber is registered on the manager's channel groups (including dependent managers' groups) and the channel subscriptions and background listener are cleaned up when the iterator is closed or cancelled.
+
+            Parameters:
+                identification: Identification fields required to locate the manager instance (maps to the manager's identification signature).
+
+            Returns:
+                AsyncIterator[SubscriptionEvent]: An asynchronous iterator that first yields a snapshot event and then yields update events; each event's `item` is the manager instance or `None` if it could not be instantiated.
+            """
+            identification_copy = deepcopy(identification)
+            property_names = cls._subscription_property_names(
+                info, cast(type[GeneralManager], generalManagerClass)
+            )
+            try:
+                instance, dependency_records = await asyncio.to_thread(
+                    cls._instantiate_manager,
+                    cast(type[GeneralManager], generalManagerClass),
+                    identification_copy,
+                    collect_dependencies=True,
+                    property_names=property_names,
+                )
+            except Exception as exc:  # pragma: no cover - bubbled to GraphQL
+                raise GraphQLError(str(exc)) from exc
+
+            try:
+                channel_layer = cast(
+                    BaseChannelLayer, cls._get_channel_layer(strict=True)
+                )
+            except RuntimeError as exc:
+                raise GraphQLError(str(exc)) from exc
+            channel_name = cast(str, await channel_layer.new_channel())
+            queue: asyncio.Queue[str] = asyncio.Queue[str]()
+
+            group_names = {
+                cls._group_name(
+                    cast(type[GeneralManager], generalManagerClass),
+                    instance.identification,
+                )
+            }
+            dependencies = cls._resolve_subscription_dependencies(
+                cast(type[GeneralManager], generalManagerClass),
+                instance,
+                dependency_records,
+            )
+            for dependency_class, dependency_identification in dependencies:
+                group_names.add(
+                    cls._group_name(dependency_class, dependency_identification)
+                )
+
+            for group in group_names:
+                await channel_layer.group_add(group, channel_name)
+
+            listener_task = asyncio.create_task(
+                cls._channel_listener(channel_layer, channel_name, queue)
+            )
+
+            async def event_stream() -> AsyncIterator[SubscriptionEvent]:
+                """
+                Yield subscription events for a manager instance, starting with an initial snapshot followed by subsequent updates.
+
+                Returns:
+                    AsyncIterator[SubscriptionEvent]: An asynchronous iterator that first yields a `SubscriptionEvent` with `action` set to `"snapshot"` and `item` containing the current manager instance (or `None` if instantiation failed). Subsequent yields provide `SubscriptionEvent` values for each received action, where `action` is the action string and `item` is the (re-)instantiated manager or `None` if instantiation failed.
+
+                Notes:
+                    When the iterator is closed or exits, the background listener task is cancelled and the subscription's channel group memberships are discarded.
+                """
+                try:
+                    yield SubscriptionEvent(item=instance, action="snapshot")
+                    while True:
+                        action = await queue.get()
+                        try:
+                            item, _ = await asyncio.to_thread(
+                                cls._instantiate_manager,
+                                cast(type[GeneralManager], generalManagerClass),
+                                identification_copy,
+                                property_names=property_names,
+                            )
+                        except HANDLED_MANAGER_ERRORS:
+                            item = None
+                        yield SubscriptionEvent(item=item, action=action)
+                finally:
+                    listener_task.cancel()
+                    with suppress(asyncio.CancelledError):
+                        await listener_task
+                    for group in group_names:
+                        await channel_layer.group_discard(group, channel_name)
+
+            return event_stream()
+
+        def resolve(
+            payload: SubscriptionEvent,
+            info: GraphQLResolveInfo,
+            **_: Any,
+        ) -> SubscriptionEvent:
+            """
+            Passes a subscription payload through unchanged.
+
+            Parameters:
+                payload (SubscriptionEvent): The subscription event payload to deliver to the client.
+                info (GraphQLResolveInfo): GraphQL resolver info (unused).
+
+            Returns:
+                SubscriptionEvent: The same payload instance provided as input.
+            """
+            return payload
+
+        cls._subscription_fields[field_name] = subscription_field
+        cls._subscription_fields[f"subscribe_{field_name}"] = subscribe
+        cls._subscription_fields[f"resolve_{field_name}"] = resolve
+
     @classmethod
     def createWriteFields(cls, interface_cls: InterfaceBase) -> dict[str, Any]:
         """
-        Generate Graphene input fields for writable interface attributes.
+        Create Graphene input fields for writable attributes defined by an Interface.
+
+        Skips system fields ("changed_by", "created_at", "updated_at") and attributes marked as derived. For attributes whose type is a GeneralManager, produces an ID field or a list of ID fields for names ending with "_list". Each generated field is annotated with an `editable` attribute reflecting the interface metadata. Always includes an optional `history_comment` string field marked editable.
 
         Parameters:
-            interface_cls (InterfaceBase): Interface whose attributes drive the input field map.
+            interface_cls (InterfaceBase): Interface providing attribute metadata (type, required, default, editable, derived) used to build the input fields.
 
         Returns:
-            dict[str, Any]: Mapping of attribute names to Graphene field definitions.
+            dict[str, Any]: Mapping from attribute name to a Graphene input field instance.
         """
         fields: dict[str, Any] = {}
 
@@ -825,6 +1525,7 @@ class GraphQL:
             req = info["is_required"]
             default = info["default"]
 
+            fld: Any
             if issubclass(typ, GeneralManager):
                 if name.endswith("_list"):
                     fld = graphene.List(
@@ -845,12 +1546,13 @@ class GraphQL:
                 )
 
             # mark for generate* code to know what is editable
-            setattr(fld, "editable", info["is_editable"])
+            cast(Any, fld).editable = info["is_editable"]
             fields[name] = fld
 
         # history_comment is always optional without a default value
-        fields["history_comment"] = graphene.String()
-        setattr(fields["history_comment"], "editable", True)
+        history_field = graphene.String()
+        cast(Any, history_field).editable = True
+        fields["history_comment"] = history_field
 
         return fields
 
@@ -861,12 +1563,14 @@ class GraphQL:
         default_return_values: dict[str, Any],
     ) -> type[graphene.Mutation] | None:
         """
-        Dynamically generates a Graphene mutation class for creating an instance of a specified GeneralManager subclass.
+        Generate a Graphene Mutation class that creates instances of the given GeneralManager subclass.
 
-        The generated mutation class uses the manager's interface to define input arguments, filters out fields with `NOT_PROVIDED` values, and invokes the manager's `create` method with the provided data and the current user's ID. On success, it returns a dictionary with a success flag and the created instance; on failure, it raises a GraphQL error. Returns `None` if the manager class does not define an interface.
+        Parameters:
+            generalManagerClass (type[GeneralManager]): The GeneralManager subclass to expose a create mutation for.
+            default_return_values (dict[str, Any]): Base mutation return fields to include on the generated class.
 
         Returns:
-            The generated Graphene mutation class, or `None` if the manager class does not define an interface.
+            type[graphene.Mutation] | None: A Mutation class named `Create<ManagerName>` that implements creation for the manager (exposes appropriate Arguments and a `mutate` implementation), or `None` if the manager class does not define an `Interface`.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -880,9 +1584,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Creates a new instance of the manager class using the provided arguments.
+            Create a new instance of the manager using the provided input fields.
 
-            Filters out any fields set to `NOT_PROVIDED` before invoking the creation method. Returns a dictionary with a success flag and the created instance keyed by the manager class name. If creation fails, raises a GraphQL error and returns a dictionary with `success` set to `False`.
+            Parameters:
+                info (GraphQLResolveInfo): GraphQL resolve info whose context user ID is used as the creator_id.
+                kwargs (Any): Input fields for the new instance; fields equal to `NOT_PROVIDED` are ignored.
+
+            Returns:
+                result (dict): A dictionary containing `success` (`True` if creation succeeded, `False` otherwise). On success the dictionary also includes the created instance under a key matching the manager class name.
             """
             try:
                 kwargs = {
@@ -893,11 +1602,8 @@ class GraphQL:
                 instance = generalManagerClass.create(
                     **kwargs, creator_id=info.context.user.id
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -951,27 +1657,24 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Updates an instance of a GeneralManager subclass with the specified field values.
+            Update a GeneralManager instance identified by its `id` with the provided field values.
 
             Parameters:
-                info (GraphQLResolveInfo): The GraphQL resolver context, including user and request data.
-                **kwargs: Field values to update, including the required 'id' of the instance.
+                info (GraphQLResolveInfo): GraphQL resolver context (contains the requesting user and request data).
+                **kwargs: Field values to update. Must include `id` to identify the target instance; other keys are treated as fields to update.
 
             Returns:
-                dict: A dictionary with 'success' (bool) and the updated instance keyed by its class name.
+                dict: Contains `success` (`True` if the update succeeded, `False` otherwise`) and, on success, the updated instance under a key matching the manager class name.
             """
+            manager_id = kwargs.pop("id", None)
+            if manager_id is None:
+                raise GraphQL._handleGraphQLError(MissingManagerIdentifierError())
             try:
-                manager_id = kwargs.pop("id", None)
-                if manager_id is None:
-                    raise ValueError("id is required")
                 instance = generalManagerClass(id=manager_id).update(
                     creator_id=info.context.user.id, **kwargs
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -1028,23 +1731,20 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Deactivates an instance of a GeneralManager subclass and returns the operation result.
+            Deactivates the identified GeneralManager instance.
 
             Returns:
-                dict: A dictionary with a "success" boolean and the deactivated instance keyed by its class name.
+                dict: `success` key with `True` if deactivation succeeded, `False` otherwise. On success, includes an additional key equal to the manager class name containing the deactivated instance.
             """
+            manager_id = kwargs.pop("id", None)
+            if manager_id is None:
+                raise GraphQL._handleGraphQLError(MissingManagerIdentifierError())
             try:
-                manager_id = kwargs.pop("id", None)
-                if manager_id is None:
-                    raise ValueError("id is required")
                 instance = generalManagerClass(id=manager_id).deactivate(
                     creator_id=info.context.user.id
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -1073,34 +1773,84 @@ class GraphQL:
         )
 
     @staticmethod
-    def _handleGraphQLError(error: Exception) -> None:
+    def _handleGraphQLError(error: Exception) -> GraphQLError:
         """
-        Raise a ``GraphQLError`` with a code based on the exception type.
+        Convert an exception into a GraphQL error with an appropriate extensions['code'].
+
+        Maps:
+            PermissionError -> "PERMISSION_DENIED"
+            ValueError, ValidationError, TypeError -> "BAD_USER_INPUT"
+            other exceptions -> "INTERNAL_SERVER_ERROR"
 
         Parameters:
-            error (Exception): Exception raised during mutation execution.
+            error (Exception): The original exception to convert.
 
-        Raises:
-            GraphQLError: Error with an appropriate ``extensions['code']`` value.
+        Returns:
+            GraphQLError: GraphQL error containing the original message and an `extensions['code']` indicating the error category.
         """
         if isinstance(error, PermissionError):
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "PERMISSION_DENIED",
                 },
             )
         elif isinstance(error, (ValueError, ValidationError, TypeError)):
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "BAD_USER_INPUT",
                 },
             )
         else:
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "INTERNAL_SERVER_ERROR",
                 },
             )
+
+    @classmethod
+    def _handle_data_change(
+        cls,
+        sender: type[GeneralManager] | GeneralManager,
+        instance: GeneralManager | None,
+        action: str,
+        **_: Any,
+    ) -> None:
+        """
+        Send a "gm.subscription.event" message to the channel group corresponding to a changed GeneralManager instance.
+
+        If the provided instance is a registered GeneralManager and a channel layer is configured, publish a message containing the given action to the channel group derived from the manager class and the instance's identification. If the instance is None, the manager type is not registered, or no channel layer is available, the function returns without side effects.
+
+        Parameters:
+            sender (type[GeneralManager] | GeneralManager): The signal sender; either a GeneralManager subclass or an instance.
+            instance (GeneralManager | None): The GeneralManager instance that changed.
+            action (str): A string describing the change action (e.g., "created", "updated", "deleted").
+        """
+        if instance is None or not isinstance(instance, GeneralManager):
+            return
+
+        if isinstance(sender, type) and issubclass(sender, GeneralManager):
+            manager_class: type[GeneralManager] = sender
+        else:
+            manager_class = instance.__class__
+
+        if manager_class.__name__ not in cls.manager_registry:
+            return
+
+        channel_layer = cls._get_channel_layer()
+        if channel_layer is None:
+            return
+
+        group_name = cls._group_name(manager_class, instance.identification)
+        async_to_sync(channel_layer.group_send)(
+            group_name,
+            {
+                "type": "gm.subscription.event",
+                "action": action,
+            },
+        )
+
+
+post_data_change.connect(GraphQL._handle_data_change, weak=False)