GeneralManager 0.16.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

general_manager/api/graphql.py

@@ -1,33 +1,47 @@
 """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,
+    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 +50,14 @@ 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 MeasurementType(graphene.ObjectType):
     value = graphene.Float()
     unit = graphene.String()
@@ -71,18 +93,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(
@@ -104,19 +126,106 @@ class GraphQL:
 
     _query_class: type[graphene.ObjectType] | None = None
     _mutation_class: type[graphene.ObjectType] | None = None
+    _subscription_class: type[graphene.ObjectType] | None = None
     _mutations: dict[str, Any] = {}
     _query_fields: dict[str, Any] = {}
+    _subscription_fields: dict[str, Any] = {}
     _page_type_registry: dict[str, type[graphene.ObjectType]] = {}
+    _subscription_payload_registry: dict[str, type[graphene.ObjectType]] = {}
     graphql_type_registry: dict[str, type] = {}
     graphql_filter_type_registry: dict[str, type] = {}
+    manager_registry: dict[str, type[GeneralManager]] = {}
+    _schema: graphene.Schema | None = None
+
+    @staticmethod
+    def _get_channel_layer(strict: bool = False) -> BaseChannelLayer | None:
+        """
+        Return the configured channel layer used for GraphQL subscriptions.
+        
+        Parameters:
+        	strict (bool): If True, raise an error when no channel layer is configured.
+        
+        Returns:
+        	BaseChannelLayer | None: The channel layer instance if configured, otherwise `None`.
+        
+        Raises:
+        	RuntimeError: If `strict` is True and no channel layer is configured.
+        """
+        layer = cast(BaseChannelLayer | None, get_channel_layer())
+        if layer is None and strict:
+            raise RuntimeError(
+                "No channel layer configured. Configure CHANNEL_LAYERS to enable GraphQL subscriptions."
+            )
+        return layer
 
     @classmethod
-    def createGraphqlMutation(cls, generalManagerClass: type[GeneralManager]) -> None:
+    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:
+        """
+        Build a consistent channel group name for subscriptions tied to a manager and its identification.
+        
+        Parameters:
+        	manager_class (type[GeneralManager]): Manager class used to namespace the group.
+        	identification (dict[str, Any]): Mapping of identifying fields for a manager instance; will be JSON-normalized and included in the group name.
+        
+        Returns:
+        	group_name (str): A deterministic string usable as a channel group identifier for subscription events.
+        """
+        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.
         """
-        Register create, update, and delete mutations for ``generalManagerClass``.
+        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 GraphQL mutations for a manager class when its Interface overrides the default CRUD methods.
+        
+        For each of `create`, `update`, and `deactivate` that is implemented on the manager's `Interface` (i.e., differs from InterfaceBase), this method generates a corresponding mutation class and stores it on the class-level mutation registry (`cls._mutations`) under the names `create<ManagerName>`, `update<ManagerName>`, and `delete<ManagerName>`. The generated mutations return a `success` flag and the created/updated/deactivated object field keyed by the manager class name.
+        
         Parameters:
-            generalManagerClass (type[GeneralManager]): Manager class whose interface drives mutation generation.
+            generalManagerClass (type[GeneralManager]): Manager class whose `Interface` drives which mutations are generated and registered.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -150,12 +259,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 +327,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 (
@@ -322,16 +432,18 @@ class GraphQL:
 
     @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"
@@ -713,9 +825,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.
-
-        The returned ObjectType includes an `items` field (a required list of the item type) and a `pageInfo` field (pagination metadata).
+        Provide or retrieve a GraphQL ObjectType that represents a paginated page for the given item type.
+        
+        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,16 +850,50 @@ class GraphQL:
             )
         return cls._page_type_registry[page_type_name]
 
+    @classmethod
+    def _buildIdentificationArguments(
+        cls, generalManagerClass: Type[GeneralManager]
+    ) -> dict[str, Any]:
+        """
+        Builds GraphQL arguments required to uniquely identify an instance of the given manager class.
+        
+        Parameters:
+            generalManagerClass (Type[GeneralManager]): Manager class whose Interface.input_fields are used to derive identification arguments.
+        
+        Returns:
+            dict[str, Any]: Mapping from argument name to a Graphene argument/field. Fields for related manager inputs use "<name>_id" as an ID, the "id" input uses an ID, and other inputs are mapped to appropriate Graphene read fields with `required=True`.
+        """
+        identification_fields: dict[str, graphene.Argument] = {}
+        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(
@@ -776,42 +932,448 @@ class GraphQL:
 
         # 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:
+            """
+            Resolve a single manager instance from provided identification arguments.
+            
+            Parameters:
+                identification (dict): Mapping of identification argument names to their values; used as keyword arguments when instantiating the manager.
+            
+            Returns:
+                GeneralManager: The instantiated manager corresponding to the given identification.
+            """
             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 createWriteFields(cls, interface_cls: InterfaceBase) -> dict[str, Any]:
+    def _dependencies_from_tracker(
+        cls, dependency_records: Iterable[Dependency]
+    ) -> list[tuple[type[GeneralManager], dict[str, Any]]]:
+        """
+        Convert DependencyTracker records into tuples of (manager class, identification dict).
+        
+        Filters input records to those whose operation is "identification", whose manager name maps to a registered GeneralManager class, and whose identifier can be parsed to a dict; returns one tuple per successfully resolved record.
+        
+        Parameters:
+            dependency_records (Iterable[Dependency]): Iterable of dependency records as (manager_name, operation, identifier).
+        
+        Returns:
+            list[tuple[type[GeneralManager], dict[str, Any]]]: A list of (manager_class, identification_dict) tuples for each 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]:
+        """
+        Identify GraphQLProperty names selected within the subscription payload's `item` field.
+        
+        Parameters:
+            info (GraphQLResolveInfo): Resolve info containing the parsed selection set and fragments.
+            manager_class (type[GeneralManager]): Manager class 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 if none or if the manager has no Interface.
         """
-        Generate Graphene input fields for writable interface attributes.
+        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:
+            """
+            Recursively traverse a GraphQL SelectionSet and delegate the subselection of any field named "item" to collect_from_selection.
+            
+            Parameters:
+            	selection_set (SelectionSetNode | None): The AST selection set to inspect. If None, the function does nothing.
+            
+            Description:
+            	Visits FieldNode, FragmentSpreadNode, and InlineFragmentNode entries:
+            	- For FieldNode named "item", calls collect_from_selection with that field's subselection.
+            	- For other FieldNode entries and inline fragments, continues recursion into their subselections.
+            	- For fragment spreads, resolves the fragment from `info.fragments` (if present) and inspects its 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:
-            interface_cls (InterfaceBase): Interface whose attributes drive the input field map.
+            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]:
+            """
+            Open a subscription stream for a specific manager instance identified by the provided arguments.
+            
+            The iterator first yields a `SubscriptionEvent` with action `"snapshot"` containing the current item, then yields subsequent `SubscriptionEvent`s for each received action. If an item cannot be re-instantiated while producing an update event, the yielded `SubscriptionEvent.item` will be `None`. The subscription registers the caller on the manager's channel groups and automatically unsubscribes and cancels background listeners 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 produces subscription events (initial snapshot then updates).
+            """
+            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]:
+                """
+                Asynchronously yields subscription events for a manager instance: an initial "snapshot" event followed by events for subsequent actions.
+                
+                Yields:
+                    SubscriptionEvent: First yields a `SubscriptionEvent` with `action` set to "snapshot" and `item` containing the current manager instance (or `None` if instantiation failed). Afterwards yields `SubscriptionEvent` values for each action received, where `action` is the action string and `item` is the (re-)instantiated manager or `None` if instantiation failed.
+                
+                Notes:
+                    On exit the function cancels the background listener task and discards the channel subscriptions for all groups associated with the subscription.
+                """
+                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 Exception:
+                            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 attributes defined by an Interface.
+        
+        Skips system fields ("changed_by", "created_at", "updated_at") and derived attributes.
+        For relation attributes referencing another GeneralManager, produces ID or list-of-ID fields.
+        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 attribute metadata (types, required, default, editable, derived) is used to build 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] = {}
 
@@ -1075,13 +1637,18 @@ class GraphQL:
     @staticmethod
     def _handleGraphQLError(error: Exception) -> None:
         """
-        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.
+            GraphQLError: GraphQL error containing the original message and an `extensions['code']` indicating the error category.
         """
         if isinstance(error, PermissionError):
             raise GraphQLError(
@@ -1104,3 +1671,51 @@ class GraphQL:
                     "code": "INTERNAL_SERVER_ERROR",
                 },
             )
+
+    @classmethod
+    def _handle_data_change(
+        cls,
+        sender: type[GeneralManager] | GeneralManager,
+        instance: GeneralManager | None,
+        action: str,
+        **_: Any,
+    ) -> None:
+        """
+        Send a subscription event to the channel group for a changed GeneralManager instance.
+        
+        If `instance` is a GeneralManager of a registered manager type and a channel layer is available,
+        publish a "gm.subscription.event" message containing the provided `action` to the group identified
+        by the manager class and the instance's identification. If `instance` is missing, the manager is
+        not registered, or no channel layer is available, the function returns without side effects.
+        
+        Parameters:
+            sender: The signal sender; either a GeneralManager subclass or an instance.
+            instance: The GeneralManager instance that changed.
+            action: 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)