django-bulk-hooks 0.2.9__py3-none-any.whl → 0.2.93__py3-none-any.whl

django_bulk_hooks/operations/coordinator.py

@@ -1,472 +1,928 @@
-"""
-Bulk operation coordinator - Single entry point for all bulk operations.
-
-This facade hides the complexity of wiring up multiple services and provides
-a clean, simple API for the QuerySet to use.
-"""
-
-import logging
-from django.db import transaction
-from django.db.models import QuerySet as BaseQuerySet
-
-from django_bulk_hooks.helpers import (
-    build_changeset_for_create,
-    build_changeset_for_update,
-    build_changeset_for_delete,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class BulkOperationCoordinator:
-    """
-    Single entry point for coordinating bulk operations.
-
-    This coordinator manages all services and provides a clean facade
-    for the QuerySet. It wires up services and coordinates the hook
-    lifecycle for each operation type.
-
-    Services are created lazily and cached.
-    """
-
-    def __init__(self, queryset):
-        """
-        Initialize coordinator for a queryset.
-
-        Args:
-            queryset: Django QuerySet instance
-        """
-        self.queryset = queryset
-        self.model_cls = queryset.model
-
-        # Lazy initialization
-        self._analyzer = None
-        self._mti_handler = None
-        self._executor = None
-        self._dispatcher = None
-
-    @property
-    def analyzer(self):
-        """Get or create ModelAnalyzer"""
-        if self._analyzer is None:
-            from django_bulk_hooks.operations.analyzer import ModelAnalyzer
-
-            self._analyzer = ModelAnalyzer(self.model_cls)
-        return self._analyzer
-
-    @property
-    def mti_handler(self):
-        """Get or create MTIHandler"""
-        if self._mti_handler is None:
-            from django_bulk_hooks.operations.mti_handler import MTIHandler
-
-            self._mti_handler = MTIHandler(self.model_cls)
-        return self._mti_handler
-
-    @property
-    def executor(self):
-        """Get or create BulkExecutor"""
-        if self._executor is None:
-            from django_bulk_hooks.operations.bulk_executor import BulkExecutor
-
-            self._executor = BulkExecutor(
-                queryset=self.queryset,
-                analyzer=self.analyzer,
-                mti_handler=self.mti_handler,
-            )
-        return self._executor
-
-    @property
-    def dispatcher(self):
-        """Get or create Dispatcher"""
-        if self._dispatcher is None:
-            from django_bulk_hooks.dispatcher import get_dispatcher
-
-            self._dispatcher = get_dispatcher()
-        return self._dispatcher
-
-    # ==================== PUBLIC API ====================
-
-    @transaction.atomic
-    def create(
-        self,
-        objs,
-        batch_size=None,
-        ignore_conflicts=False,
-        update_conflicts=False,
-        update_fields=None,
-        unique_fields=None,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
-        """
-        Execute bulk create with hooks.
-
-        Args:
-            objs: List of model instances to create
-            batch_size: Number of objects per batch
-            ignore_conflicts: Ignore conflicts if True
-            update_conflicts: Update on conflict if True
-            update_fields: Fields to update on conflict
-            unique_fields: Fields to check for conflicts
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            List of created objects
-        """
-        if not objs:
-            return objs
-
-        # Validate
-        self.analyzer.validate_for_create(objs)
-
-        # Build initial changeset
-        changeset = build_changeset_for_create(
-            self.model_cls,
-            objs,
-            batch_size=batch_size,
-            ignore_conflicts=ignore_conflicts,
-            update_conflicts=update_conflicts,
-            update_fields=update_fields,
-            unique_fields=unique_fields,
-        )
-
-        # Execute with hook lifecycle
-        def operation():
-            return self.executor.bulk_create(
-                objs,
-                batch_size=batch_size,
-                ignore_conflicts=ignore_conflicts,
-                update_conflicts=update_conflicts,
-                update_fields=update_fields,
-                unique_fields=unique_fields,
-            )
-
-        return self._execute_with_mti_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="create",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    @transaction.atomic
-    def update(
-        self,
-        objs,
-        fields,
-        batch_size=None,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
-        """
-        Execute bulk update with hooks.
-
-        Args:
-            objs: List of model instances to update
-            fields: List of field names to update
-            batch_size: Number of objects per batch
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Number of objects updated
-        """
-        if not objs:
-            return 0
-
-        # Validate
-        self.analyzer.validate_for_update(objs)
-
-        # Fetch old records using analyzer (single source of truth)
-        old_records_map = self.analyzer.fetch_old_records_map(objs)
-
-        # Build changeset
-        from django_bulk_hooks.changeset import ChangeSet, RecordChange
-
-        changes = [
-            RecordChange(
-                new_record=obj,
-                old_record=old_records_map.get(obj.pk),
-                changed_fields=fields,
-            )
-            for obj in objs
-        ]
-        changeset = ChangeSet(self.model_cls, changes, "update", {"fields": fields})
-
-        # Execute with hook lifecycle
-        def operation():
-            return self.executor.bulk_update(objs, fields, batch_size=batch_size)
-
-        return self._execute_with_mti_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="update",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    @transaction.atomic
-    def update_queryset(
-        self, update_kwargs, bypass_hooks=False, bypass_validation=False
-    ):
-        """
-        Execute queryset update with hooks.
-        
-        ARCHITECTURE: Application-Layer Update with Expression Resolution
-        ===================================================================
-        
-        When hooks are enabled, queryset.update() is transformed into bulk_update()
-        to allow BEFORE hooks to modify records. This is a deliberate design choice:
-        
-        1. Fetch instances from the queryset (we need them for hooks anyway)
-        2. Resolve SQL expressions (F(), Subquery, Case, etc.) to concrete values
-        3. Apply resolved values to instances
-        4. Run BEFORE hooks (which can now modify the instances)
-        5. Use bulk_update() to persist the (possibly modified) instances
-        6. Run AFTER hooks with final state
-        
-        This approach:
-        - ✅ Allows BEFORE hooks to modify values (feature request)
-        - ✅ Preserves SQL expression semantics (materializes them correctly)
-        - ✅ Eliminates the double-fetch (was fetching before AND after)
-        - ✅ More efficient than previous implementation
-        - ✅ Maintains Salesforce-like hook contract
-        
-        SQL expressions are resolved per-instance using Django's annotate(),
-        which ensures correct evaluation of:
-        - F() expressions: F('balance') + 100
-        - Subquery: Subquery(related.aggregate(...))
-        - Case/When: Case(When(...))
-        - Database functions: Upper(), Concat(), etc.
-        - Any other Django Expression
-        
-        Trade-off:
-        - Uses bulk_update() internally (slightly different SQL than queryset.update)
-        - Expression resolution may add overhead for complex expressions
-        - But eliminates the refetch, so overall more efficient
-
-        Args:
-            update_kwargs: Dict of fields to update
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Number of objects updated
-        """
-        # Fetch instances from queryset
-        instances = list(self.queryset)
-        if not instances:
-            return 0
-
-        # Check both parameter and context for bypass_hooks
-        from django_bulk_hooks.context import get_bypass_hooks
-        should_bypass = bypass_hooks or get_bypass_hooks()
-        
-        if should_bypass:
-            # No hooks - use original queryset.update() for max performance
-            return BaseQuerySet.update(self.queryset, **update_kwargs)
-
-        # Resolve expressions and apply to instances
-        # Delegate to analyzer for expression resolution and value application
-        fields_to_update = self.analyzer.apply_update_values(instances, update_kwargs)
-        
-        # Now instances have the resolved values applied
-        # Fetch old records for comparison (single bulk query)
-        old_records_map = self.analyzer.fetch_old_records_map(instances)
-
-        # Build changeset for VALIDATE and BEFORE hooks
-        # instances now have the "intended" values from update_kwargs
-        changeset = build_changeset_for_update(
-            self.model_cls,
-            instances,
-            update_kwargs,
-            old_records_map=old_records_map,
-        )
-
-        # Execute VALIDATE and BEFORE hooks
-        # Hooks can now modify the instances and changes will persist
-        if not bypass_validation:
-            self.dispatcher.dispatch(changeset, "validate_update", bypass_hooks=False)
-        self.dispatcher.dispatch(changeset, "before_update", bypass_hooks=False)
-
-        # COORDINATION LOGIC: Determine all fields to persist
-        # Hooks may have modified fields beyond the original update_kwargs.
-        # We need to detect those changes and include them in bulk_update.
-        # This is coordination between: hooks → field detection → executor
-        additional_changed_fields = self.analyzer.detect_changed_fields(instances)
-        all_fields_to_update = list(set(fields_to_update) | set(additional_changed_fields))
-        
-        # Use bulk_update with all modified fields (original + hook modifications)
-        result = self.executor.bulk_update(instances, all_fields_to_update, batch_size=None)
-
-        # Build changeset for AFTER hooks
-        # No refetch needed! instances already have final state from bulk_update
-        changeset_after = build_changeset_for_update(
-            self.model_cls,
-            instances,
-            update_kwargs,
-            old_records_map=old_records_map,
-        )
-
-        # Execute AFTER hooks with final state
-        self.dispatcher.dispatch(changeset_after, "after_update", bypass_hooks=False)
-
-        return result
-
-    @transaction.atomic
-    def delete(self, bypass_hooks=False, bypass_validation=False):
-        """
-        Execute delete with hooks.
-
-        Args:
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Tuple of (count, details dict)
-        """
-        # Get objects
-        objs = list(self.queryset)
-        if not objs:
-            return 0, {}
-
-        # Validate
-        self.analyzer.validate_for_delete(objs)
-
-        # Build changeset
-        changeset = build_changeset_for_delete(self.model_cls, objs)
-
-        # Execute with hook lifecycle
-        def operation():
-            # Call base Django QuerySet.delete() to avoid recursion
-            return BaseQuerySet.delete(self.queryset)
-
-        return self._execute_with_mti_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="delete",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    def clean(self, objs, is_create=None):
-        """
-        Execute validation hooks only (no database operations).
-
-        This is used by Django's clean() method to hook VALIDATE_* events
-        without performing the actual operation.
-
-        Args:
-            objs: List of model instances to validate
-            is_create: True for create, False for update, None to auto-detect
-
-        Returns:
-            None
-        """
-        if not objs:
-            return
-
-        # Auto-detect if is_create not specified
-        if is_create is None:
-            is_create = objs[0].pk is None
-
-        # Build changeset based on operation type
-        if is_create:
-            changeset = build_changeset_for_create(self.model_cls, objs)
-            event = "validate_create"
-        else:
-            # For update validation, no old records needed - hooks handle their own queries
-            changeset = build_changeset_for_update(self.model_cls, objs, {})
-            event = "validate_update"
-
-        # Dispatch validation event only
-        self.dispatcher.dispatch(changeset, event, bypass_hooks=False)
-
-    # ==================== MTI PARENT HOOK SUPPORT ====================
-
-    def _build_changeset_for_model(self, original_changeset, target_model_cls):
-        """
-        Build a changeset for a specific model in the MTI inheritance chain.
-        
-        This allows parent model hooks to receive the same instances but with
-        the correct model_cls for hook registration matching.
-        
-        Args:
-            original_changeset: The original changeset (for child model)
-            target_model_cls: The model class to build changeset for (parent model)
-            
-        Returns:
-            ChangeSet for the target model
-        """
-        from django_bulk_hooks.changeset import ChangeSet
-        
-        # Create new changeset with target model but same record changes
-        return ChangeSet(
-            model_cls=target_model_cls,
-            changes=original_changeset.changes,
-            operation_type=original_changeset.operation_type,
-            operation_meta=original_changeset.operation_meta,
-        )
-
-    def _execute_with_mti_hooks(
-        self, 
-        changeset, 
-        operation, 
-        event_prefix, 
-        bypass_hooks=False, 
-        bypass_validation=False
-    ):
-        """
-        Execute operation with hooks for entire MTI inheritance chain.
-        
-        This method dispatches hooks for both child and parent models when
-        dealing with MTI models, ensuring parent model hooks fire when
-        child instances are created/updated/deleted.
-        
-        Args:
-            changeset: ChangeSet for the child model
-            operation: Callable that performs the actual DB operation
-            event_prefix: 'create', 'update', or 'delete'
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-            
-        Returns:
-            Result of operation
-        """
-        if bypass_hooks:
-            return operation()
-
-        # Get all models in inheritance chain
-        models_in_chain = [changeset.model_cls]
-        if self.mti_handler.is_mti_model():
-            parent_models = self.mti_handler.get_parent_models()
-            models_in_chain.extend(parent_models)
-
-        # VALIDATE phase - for all models in chain
-        if not bypass_validation:
-            for model_cls in models_in_chain:
-                model_changeset = self._build_changeset_for_model(changeset, model_cls)
-                self.dispatcher.dispatch(model_changeset, f"validate_{event_prefix}", bypass_hooks=False)
-
-        # BEFORE phase - for all models in chain
-        for model_cls in models_in_chain:
-            model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(model_changeset, f"before_{event_prefix}", bypass_hooks=False)
-
-        # Execute the actual operation
-        result = operation()
-
-        # AFTER phase - for all models in chain
-        # Use result if operation returns modified data (for create operations)
-        if result and isinstance(result, list) and event_prefix == "create":
-            # Rebuild changeset with assigned PKs for AFTER hooks
-            from django_bulk_hooks.helpers import build_changeset_for_create
-            changeset = build_changeset_for_create(changeset.model_cls, result)
-
-        for model_cls in models_in_chain:
-            model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(model_changeset, f"after_{event_prefix}", bypass_hooks=False)
-
-        return result
+"""
+Bulk operation coordinator - Single entry point for all bulk operations.
+
+This facade hides the complexity of wiring up multiple services and provides
+a clean, simple API for the QuerySet to use.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Set
+from typing import Tuple
+
+from django.core.exceptions import FieldDoesNotExist
+from django.db import transaction
+from django.db.models import Model
+from django.db.models import QuerySet
+
+from django_bulk_hooks.changeset import ChangeSet
+from django_bulk_hooks.changeset import RecordChange
+from django_bulk_hooks.context import get_bypass_hooks
+from django_bulk_hooks.helpers import build_changeset_for_create
+from django_bulk_hooks.helpers import build_changeset_for_delete
+from django_bulk_hooks.helpers import build_changeset_for_update
+from django_bulk_hooks.helpers import extract_pks
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InstanceSnapshot:
+    """Snapshot of instance state for modification tracking."""
+
+    field_values: Dict[str, Any]
+
+
+class BulkOperationCoordinator:
+    """
+    Single entry point for coordinating bulk operations.
+
+    This coordinator manages all services and provides a clean facade
+    for the QuerySet. It wires up services and coordinates the hook
+    lifecycle for each operation type.
+
+    Services are created lazily and cached for performance.
+    """
+
+    # Constants
+    UPSERT_TIMESTAMP_THRESHOLD_SECONDS = 1.0
+
+    def __init__(self, queryset: QuerySet):
+        """
+        Initialize coordinator for a queryset.
+
+        Args:
+            queryset: Django QuerySet instance
+        """
+        self.queryset = queryset
+        self.model_cls = queryset.model
+
+        # Lazy-initialized services
+        self._analyzer = None
+        self._mti_handler = None
+        self._record_classifier = None
+        self._executor = None
+        self._dispatcher = None
+
+    # ==================== SERVICE PROPERTIES ====================
+
+    def _get_or_create_service(self, service_name: str, service_class: type, *args, **kwargs) -> Any:
+        """
+        Generic lazy service initialization with caching.
+
+        Args:
+            service_name: Name of the service attribute (e.g., 'analyzer')
+            service_class: The class to instantiate
+            *args, **kwargs: Arguments to pass to the service constructor
+
+        Returns:
+            The service instance
+        """
+        attr_name = f"_{service_name}"
+        service = getattr(self, attr_name)
+
+        if service is None:
+            service = service_class(*args, **kwargs)
+            setattr(self, attr_name, service)
+
+        return service
+
+    @property
+    def analyzer(self):
+        """Get or create ModelAnalyzer."""
+        from django_bulk_hooks.operations.analyzer import ModelAnalyzer
+
+        return self._get_or_create_service("analyzer", ModelAnalyzer, self.model_cls)
+
+    @property
+    def mti_handler(self):
+        """Get or create MTIHandler."""
+        from django_bulk_hooks.operations.mti_handler import MTIHandler
+
+        return self._get_or_create_service("mti_handler", MTIHandler, self.model_cls)
+
+    @property
+    def record_classifier(self):
+        """Get or create RecordClassifier."""
+        from django_bulk_hooks.operations.record_classifier import RecordClassifier
+
+        return self._get_or_create_service("record_classifier", RecordClassifier, self.model_cls)
+
+    @property
+    def executor(self):
+        """Get or create BulkExecutor."""
+        from django_bulk_hooks.operations.bulk_executor import BulkExecutor
+
+        return self._get_or_create_service(
+            "executor",
+            BulkExecutor,
+            queryset=self.queryset,
+            analyzer=self.analyzer,
+            mti_handler=self.mti_handler,
+            record_classifier=self.record_classifier,
+        )
+
+    @property
+    def dispatcher(self):
+        """Get or create Dispatcher."""
+        from django_bulk_hooks.dispatcher import get_dispatcher
+
+        return self._get_or_create_service("dispatcher", get_dispatcher)
+
+    @property
+    def inheritance_chain(self) -> List[type]:
+        """Single source of truth for MTI inheritance chain."""
+        return self.mti_handler.get_inheritance_chain()
+
+    # ==================== PUBLIC API ====================
+
+    @transaction.atomic
+    def create(
+        self,
+        objs: List[Model],
+        batch_size: Optional[int] = None,
+        ignore_conflicts: bool = False,
+        update_conflicts: bool = False,
+        update_fields: Optional[List[str]] = None,
+        unique_fields: Optional[List[str]] = None,
+        bypass_hooks: bool = False,
+    ) -> List[Model]:
+        """
+        Execute bulk create with hooks.
+
+        Args:
+            objs: List of model instances to create
+            batch_size: Number of objects per batch
+            ignore_conflicts: Ignore conflicts if True
+            update_conflicts: Update on conflict if True
+            update_fields: Fields to update on conflict
+            unique_fields: Fields to check for conflicts
+            bypass_hooks: Skip all hooks if True
+
+        Returns:
+            List of created objects
+        """
+        if not objs:
+            return objs
+
+        self.analyzer.validate_for_create(objs)
+
+        # Handle upsert classification upfront
+        existing_record_ids, existing_pks_map = self._classify_upsert_records(objs, update_conflicts, unique_fields)
+
+        changeset = build_changeset_for_create(
+            self.model_cls,
+            objs,
+            batch_size=batch_size,
+            ignore_conflicts=ignore_conflicts,
+            update_conflicts=update_conflicts,
+            update_fields=update_fields,
+            unique_fields=unique_fields,
+        )
+
+        def operation():
+            return self.executor.bulk_create(
+                objs,
+                batch_size=batch_size,
+                ignore_conflicts=ignore_conflicts,
+                update_conflicts=update_conflicts,
+                update_fields=update_fields,
+                unique_fields=unique_fields,
+                existing_record_ids=existing_record_ids,
+                existing_pks_map=existing_pks_map,
+            )
+
+        return self._execute_with_mti_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="create",
+            bypass_hooks=bypass_hooks,
+        )
+
+    @transaction.atomic
+    def update(
+        self,
+        objs: List[Model],
+        fields: List[str],
+        batch_size: Optional[int] = None,
+        bypass_hooks: bool = False,
+    ) -> int:
+        """
+        Execute bulk update with hooks.
+
+        Args:
+            objs: List of model instances to update
+            fields: List of field names to update
+            batch_size: Number of objects per batch
+            bypass_hooks: Skip all hooks if True
+
+        Returns:
+            Number of objects updated
+        """
+        if not objs:
+            return 0
+
+        self.analyzer.validate_for_update(objs)
+
+        old_records_map = self.analyzer.fetch_old_records_map(objs)
+        changeset = self._build_update_changeset(objs, fields, old_records_map)
+
+        def operation():
+            return self.executor.bulk_update(objs, fields, batch_size=batch_size)
+
+        return self._execute_with_mti_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="update",
+            bypass_hooks=bypass_hooks,
+        )
+
+    @transaction.atomic
+    def update_queryset(
+        self,
+        update_kwargs: Dict[str, Any],
+        bypass_hooks: bool = False,
+    ) -> int:
+        """
+        Execute queryset.update() with full hook support.
+
+        ARCHITECTURE & PERFORMANCE TRADE-OFFS
+        ======================================
+
+        To support hooks with queryset.update(), we must:
+        1. Fetch old state (SELECT all matching rows)
+        2. Execute database update (UPDATE in SQL)
+        3. Fetch new state (SELECT all rows again)
+        4. Run VALIDATE_UPDATE hooks (validation only)
+        5. Run BEFORE_UPDATE hooks (CAN modify instances)
+        6. Persist BEFORE_UPDATE modifications (bulk_update)
+        7. Run AFTER_UPDATE hooks (read-only side effects)
+
+        Performance Cost:
+        - 2 SELECT queries (before/after)
+        - 1 UPDATE query (actual update)
+        - 1 bulk_update (if hooks modify data)
+
+        Trade-off: Hooks require loading data into Python. If you need
+        maximum performance and don't need hooks, use bypass_hooks=True.
+
+        Args:
+            update_kwargs: Dict of fields to update
+            bypass_hooks: Skip all hooks if True
+
+        Returns:
+            Number of rows updated
+        """
+        if bypass_hooks or get_bypass_hooks():
+            return QuerySet.update(self.queryset, **update_kwargs)
+
+        return self._execute_queryset_update_with_hooks(update_kwargs)
+
+    @transaction.atomic
+    def delete(self, bypass_hooks: bool = False) -> Tuple[int, Dict[str, int]]:
+        """
+        Execute delete with hooks.
+
+        Args:
+            bypass_hooks: Skip all hooks if True
+
+        Returns:
+            Tuple of (count, details dict)
+        """
+        objs = list(self.queryset)
+        if not objs:
+            return (0, {})
+
+        self.analyzer.validate_for_delete(objs)
+
+        changeset = build_changeset_for_delete(self.model_cls, objs)
+
+        def operation():
+            return QuerySet.delete(self.queryset)
+
+        return self._execute_with_mti_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="delete",
+            bypass_hooks=bypass_hooks,
+        )
+
+    def clean(self, objs: List[Model], is_create: Optional[bool] = None) -> None:
+        """
+        Execute validation hooks only (no database operations).
+
+        This is used by Django's clean() method to hook VALIDATE_* events
+        without performing the actual operation.
+
+        Args:
+            objs: List of model instances to validate
+            is_create: True for create, False for update, None to auto-detect
+        """
+        if not objs:
+            return
+
+        # Auto-detect operation type
+        if is_create is None:
+            is_create = objs[0].pk is None
+
+        # Validate based on operation type
+        if is_create:
+            self.analyzer.validate_for_create(objs)
+            changeset = build_changeset_for_create(self.model_cls, objs)
+            event = "validate_create"
+        else:
+            self.analyzer.validate_for_update(objs)
+            changeset = build_changeset_for_update(self.model_cls, objs, {})
+            event = "validate_update"
+
+        # Dispatch validation event
+        models_in_chain = self.inheritance_chain
+        self._dispatch_hooks_for_models(models_in_chain, changeset, event)
+
+    # ==================== QUERYSET UPDATE IMPLEMENTATION ====================
+
+    def _execute_queryset_update_with_hooks(
+        self,
+        update_kwargs: Dict[str, Any],
+    ) -> int:
+        """
+        Execute queryset update with full hook lifecycle support.
+
+        Implements the fetch-update-fetch pattern required to support hooks
+        with queryset.update(). BEFORE_UPDATE hooks can modify instances
+        and modifications are auto-persisted.
+
+        Args:
+            update_kwargs: Dict of fields to update
+
+        Returns:
+            Number of rows updated
+        """
+        # Step 1: Fetch old state with relationships preloaded
+        hook_relationships = self._extract_hook_relationships()
+        old_instances = self._fetch_instances_with_relationships(self.queryset, hook_relationships)
+
+        if not old_instances:
+            return 0
+
+        old_records_map = {inst.pk: inst for inst in old_instances}
+
+        # Step 2: Execute native Django update
+        update_count = QuerySet.update(self.queryset, **update_kwargs)
+        if update_count == 0:
+            return 0
+
+        # Step 3: Fetch new state after update
+        pks = extract_pks(old_instances)
+        new_queryset = self.model_cls.objects.filter(pk__in=pks)
+        new_instances = self._fetch_instances_with_relationships(new_queryset, hook_relationships)
+
+        # Step 4: Build changeset and run hook lifecycle
+        changeset = build_changeset_for_update(
+            self.model_cls,
+            new_instances,
+            update_kwargs,
+            old_records_map=old_records_map,
+        )
+        changeset.operation_meta["is_queryset_update"] = True
+        changeset.operation_meta["allows_modifications"] = True
+
+        models_in_chain = self.inheritance_chain
+
+        # Step 5: VALIDATE phase
+        self._dispatch_hooks_for_models(models_in_chain, changeset, "validate_update", bypass_hooks=False)
+
+        # Step 6: BEFORE_UPDATE phase with modification tracking
+        modified_fields = self._run_before_update_hooks_with_tracking(new_instances, models_in_chain, changeset)
+
+        # Step 7: Auto-persist BEFORE_UPDATE modifications
+        if modified_fields:
+            self._persist_hook_modifications(new_instances, modified_fields)
+
+        # Step 8: AFTER_UPDATE phase (read-only)
+        pre_after_state = self._snapshot_instance_state(new_instances)
+        self._dispatch_hooks_for_models(models_in_chain, changeset, "after_update", bypass_hooks=False)
+
+        # Step 9: Auto-persist any AFTER_UPDATE modifications (should be rare)
+        after_modified_fields = self._detect_modifications(new_instances, pre_after_state)
+        if after_modified_fields:
+            logger.warning("AFTER_UPDATE hooks modified fields: %s. Consider moving modifications to BEFORE_UPDATE.", after_modified_fields)
+            self._persist_hook_modifications(new_instances, after_modified_fields)
+
+        return update_count
+
+    def _run_before_update_hooks_with_tracking(self, instances: List[Model], models_in_chain: List[type], changeset: ChangeSet) -> Set[str]:
+        """
+        Run BEFORE_UPDATE hooks and detect modifications.
+
+        Returns:
+            Set of field names that were modified by hooks
+        """
+        pre_hook_state = self._snapshot_instance_state(instances)
+        self._dispatch_hooks_for_models(models_in_chain, changeset, "before_update", bypass_hooks=False)
+        return self._detect_modifications(instances, pre_hook_state)
+
+    # ==================== MTI HOOK ORCHESTRATION ====================
+
+    def _execute_with_mti_hooks(
+        self,
+        changeset: ChangeSet,
+        operation: Callable,
+        event_prefix: str,
+        bypass_hooks: bool = False,
+    ) -> Any:
+        """
+        Execute operation with hooks for entire MTI inheritance chain.
+
+        This ensures parent model hooks fire when child instances are
+        created/updated/deleted in MTI scenarios.
+
+        Args:
+            changeset: ChangeSet for the child model
+            operation: Callable that performs the actual DB operation
+            event_prefix: 'create', 'update', or 'delete'
+            bypass_hooks: Skip all hooks if True
+
+        Returns:
+            Result of operation
+        """
+        if bypass_hooks:
+            return operation()
+
+        self.dispatcher._reset_executed_hooks()
+        logger.debug("Starting %s operation for %s", event_prefix, changeset.model_cls.__name__)
+
+        models_in_chain = self.inheritance_chain
+
+        # Preload relationships needed by hook conditions (prevents N+1)
+        self._preload_condition_relationships_for_operation(changeset, models_in_chain)
+
+        # VALIDATE phase
+        self._dispatch_hooks_for_models(models_in_chain, changeset, f"validate_{event_prefix}")
+
+        # BEFORE phase
+        self._dispatch_hooks_for_models(models_in_chain, changeset, f"before_{event_prefix}")
+
+        # Execute operation
+        result = operation()
+
+        # AFTER phase (handle upsert splitting for create operations)
+        if result and isinstance(result, list) and event_prefix == "create":
+            if self._is_upsert_operation(result):
+                self._dispatch_upsert_after_hooks(result, models_in_chain)
+            else:
+                after_changeset = build_changeset_for_create(changeset.model_cls, result)
+                self._dispatch_hooks_for_models(models_in_chain, after_changeset, f"after_{event_prefix}")
+        else:
+            self._dispatch_hooks_for_models(models_in_chain, changeset, f"after_{event_prefix}")
+
+        return result
+
+    def _dispatch_hooks_for_models(
+        self,
+        models_in_chain: List[type],
+        changeset: ChangeSet,
+        event_suffix: str,
+        bypass_hooks: bool = False,
+    ) -> None:
+        """
+        Dispatch hooks for all models in inheritance chain.
+
+        Args:
+            models_in_chain: List of model classes in MTI inheritance chain
+            changeset: The changeset to use as base
+            event_suffix: Event name suffix (e.g., 'before_create')
+            bypass_hooks: Whether to skip hook execution
+        """
+        logger.debug("Dispatching %s to %d models: %s", event_suffix, len(models_in_chain), [m.__name__ for m in models_in_chain])
+
+        for model_cls in models_in_chain:
+            model_changeset = self._build_changeset_for_model(changeset, model_cls)
+            self.dispatcher.dispatch(model_changeset, event_suffix, bypass_hooks=bypass_hooks)
+
+    def _build_changeset_for_model(self, original_changeset: ChangeSet, target_model_cls: type) -> ChangeSet:
+        """
+        Build a changeset for a specific model in the MTI inheritance chain.
+
+        This allows parent model hooks to receive the same instances but with
+        the correct model_cls for hook registration matching.
+
+        Args:
+            original_changeset: The original changeset (for child model)
+            target_model_cls: The model class to build changeset for
+
+        Returns:
+            ChangeSet for the target model
+        """
+        return ChangeSet(
+            model_cls=target_model_cls,
+            changes=original_changeset.changes,
+            operation_type=original_changeset.operation_type,
+            operation_meta=original_changeset.operation_meta,
+        )
+
+    # ==================== UPSERT HANDLING ====================
+
+    def _classify_upsert_records(
+        self,
+        objs: List[Model],
+        update_conflicts: bool,
+        unique_fields: Optional[List[str]],
+    ) -> Tuple[Set[Any], Dict[Any, Any]]:
+        """
+        Classify records for upsert operations.
+
+        Args:
+            objs: List of model instances
+            update_conflicts: Whether this is an upsert operation
+            unique_fields: Fields to check for conflicts
+
+        Returns:
+            Tuple of (existing_record_ids, existing_pks_map)
+        """
+        if not (update_conflicts and unique_fields):
+            return set(), {}
+
+        query_model = None
+        if self.mti_handler.is_mti_model():
+            query_model = self.mti_handler.find_model_with_unique_fields(unique_fields)
+            logger.info("MTI model detected: querying %s for unique fields %s", query_model.__name__, unique_fields)
+
+        existing_ids, existing_pks = self.record_classifier.classify_for_upsert(objs, unique_fields, query_model=query_model)
+
+        logger.info("Upsert classification: %d existing, %d new records", len(existing_ids), len(objs) - len(existing_ids))
+
+        return existing_ids, existing_pks
+
+    def _is_upsert_operation(self, result_objects: List[Model]) -> bool:
+        """Check if the operation was an upsert (with update_conflicts=True)."""
+        if not result_objects:
+            return False
+        return hasattr(result_objects[0], "_bulk_hooks_upsert_metadata")
+
+    def _dispatch_upsert_after_hooks(self, result_objects: List[Model], models_in_chain: List[type]) -> None:
+        """
+        Dispatch after hooks for upsert operations, splitting by create/update.
+
+        This matches Salesforce behavior where created records fire after_create
+        and updated records fire after_update hooks.
+
+        Args:
+            result_objects: List of objects returned from the operation
+            models_in_chain: List of model classes in the MTI inheritance chain
+        """
+        created, updated = self._classify_upsert_results(result_objects)
+
+        logger.info("Upsert after hooks: %d created, %d updated", len(created), len(updated))
+
+        if created:
+            create_changeset = build_changeset_for_create(self.model_cls, created)
+            create_changeset.operation_meta["relationships_preloaded"] = True
+            self._dispatch_hooks_for_models(models_in_chain, create_changeset, "after_create", bypass_hooks=False)
+
+        if updated:
+            old_records_map = self.analyzer.fetch_old_records_map(updated)
+            update_changeset = build_changeset_for_update(self.model_cls, updated, {}, old_records_map=old_records_map)
+            update_changeset.operation_meta["relationships_preloaded"] = True
+            self._dispatch_hooks_for_models(models_in_chain, update_changeset, "after_update", bypass_hooks=False)
+
+        self._cleanup_upsert_metadata(result_objects)
+
+    def _classify_upsert_results(self, result_objects: List[Model]) -> Tuple[List[Model], List[Model]]:
+        """
+        Classify upsert results into created and updated objects.
+
+        Returns:
+            Tuple of (created_objects, updated_objects)
+        """
+        created_objects = []
+        updated_objects = []
+        objects_needing_timestamp_check = []
+
+        # First pass: collect objects with metadata
+        for obj in result_objects:
+            if hasattr(obj, "_bulk_hooks_was_created"):
+                if obj._bulk_hooks_was_created:
+                    created_objects.append(obj)
+                else:
+                    updated_objects.append(obj)
+            else:
+                objects_needing_timestamp_check.append(obj)
+
+        # Second pass: bulk check timestamps for objects without metadata
+        if objects_needing_timestamp_check:
+            created, updated = self._classify_by_timestamps(objects_needing_timestamp_check)
+            created_objects.extend(created)
+            updated_objects.extend(updated)
+
+        return created_objects, updated_objects
+
+    def _classify_by_timestamps(self, objects: List[Model]) -> Tuple[List[Model], List[Model]]:
+        """
+        Classify objects as created or updated based on timestamp comparison.
+
+        Returns:
+            Tuple of (created_objects, updated_objects)
+        """
+        created = []
+        updated = []
+
+        # Group by model class to handle MTI scenarios
+        objects_by_model = {}
+        for obj in objects:
+            model_cls = obj.__class__
+            objects_by_model.setdefault(model_cls, []).append(obj)
+
+        # Process each model class
+        for model_cls, objs in objects_by_model.items():
+            if not (hasattr(model_cls, "created_at") and hasattr(model_cls, "updated_at")):
+                # No timestamp fields, default to created
+                created.extend(objs)
+                continue
+
+            # Bulk fetch timestamps
+            pks = extract_pks(objs)
+            if not pks:
+                created.extend(objs)
+                continue
+
+            timestamp_map = {
+                record["pk"]: (record["created_at"], record["updated_at"])
+                for record in model_cls.objects.filter(pk__in=pks).values("pk", "created_at", "updated_at")
+            }
+
+            # Classify based on timestamp difference
+            for obj in objs:
+                if obj.pk not in timestamp_map:
+                    created.append(obj)
+                    continue
+
+                created_at, updated_at = timestamp_map[obj.pk]
+                if not (created_at and updated_at):
+                    created.append(obj)
+                    continue
+
+                time_diff = abs((updated_at - created_at).total_seconds())
+                if time_diff <= self.UPSERT_TIMESTAMP_THRESHOLD_SECONDS:
+                    created.append(obj)
+                else:
+                    updated.append(obj)
+
+        return created, updated
+
+    def _cleanup_upsert_metadata(self, result_objects: List[Model]) -> None:
+        """Clean up temporary metadata added during upsert operations."""
+        for obj in result_objects:
+            for attr in ("_bulk_hooks_was_created", "_bulk_hooks_upsert_metadata"):
+                if hasattr(obj, attr):
+                    delattr(obj, attr)
+
+    # ==================== INSTANCE STATE TRACKING ====================
+
+    def _snapshot_instance_state(self, instances: List[Model]) -> Dict[Any, Dict[str, Any]]:
+        """
+        Create a snapshot of current instance field values.
+
+        Args:
+            instances: List of model instances
+
+        Returns:
+            Dict mapping pk -> {field_name: value}
+        """
+        snapshot = {}
+
+        for instance in instances:
+            if instance.pk is None:
+                continue
+
+            field_values = {}
+            for field in self.model_cls._meta.get_fields():
+                # Skip non-concrete fields
+                if field.many_to_many or field.one_to_many:
+                    continue
+
+                try:
+                    field_values[field.name] = getattr(instance, field.name)
+                except (AttributeError, FieldDoesNotExist):
+                    field_values[field.name] = None
+
+            snapshot[instance.pk] = field_values
+
+        return snapshot
+
+    def _detect_modifications(
+        self,
+        instances: List[Model],
+        pre_hook_state: Dict[Any, Dict[str, Any]],
+    ) -> Set[str]:
+        """
+        Detect which fields were modified by comparing to snapshot.
+
+        Args:
+            instances: List of model instances
+            pre_hook_state: Previous state snapshot
+
+        Returns:
+            Set of field names that were modified
+        """
+        modified_fields = set()
+
+        for instance in instances:
+            if instance.pk not in pre_hook_state:
+                continue
+
+            old_values = pre_hook_state[instance.pk]
+
+            for field_name, old_value in old_values.items():
+                try:
+                    current_value = getattr(instance, field_name)
+                except (AttributeError, FieldDoesNotExist):
+                    current_value = None
+
+                if current_value != old_value:
+                    modified_fields.add(field_name)
+
+        return modified_fields
+
+    def _persist_hook_modifications(self, instances: List[Model], modified_fields: Set[str]) -> None:
+        """
+        Persist modifications made by hooks using bulk_update.
+
+        Args:
+            instances: List of modified instances
+            modified_fields: Set of field names that were modified
+        """
+        logger.info("Hooks modified %d field(s): %s", len(modified_fields), ", ".join(sorted(modified_fields)))
+        logger.info("Auto-persisting modifications via bulk_update")
+
+        # Use Django's bulk_update directly (not our hook version)
+        fresh_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
+        QuerySet.bulk_update(fresh_qs, instances, list(modified_fields))
+
+    # ==================== RELATIONSHIP PRELOADING ====================
+
+    def _fetch_instances_with_relationships(
+        self,
+        queryset: QuerySet,
+        relationships: Set[str],
+    ) -> List[Model]:
+        """
+        Fetch instances with relationships preloaded.
+
+        Args:
+            queryset: QuerySet to fetch from
+            relationships: Set of relationship names to preload
+
+        Returns:
+            List of model instances with relationships loaded
+        """
+        if relationships:
+            logger.info("Fetching instances with select_related(%s)", list(relationships))
+            queryset = queryset.select_related(*relationships)
+        else:
+            logger.info("Fetching instances without select_related")
+
+        return list(queryset)
+
+    def _preload_condition_relationships_for_operation(
+        self,
+        changeset: ChangeSet,
+        models_in_chain: List[type],
+    ) -> None:
+        """
+        Preload relationships needed by hook conditions for this operation.
+
+        This prevents N+1 queries by loading all necessary relationships upfront.
+
+        Args:
+            changeset: The changeset for this operation
+            models_in_chain: List of model classes in inheritance chain
+        """
+        relationships = self._extract_condition_relationships_for_operation(changeset, models_in_chain)
+
+        if relationships:
+            logger.info("Bulk preloading %d condition relationships for %s hooks", len(relationships), changeset.model_cls.__name__)
+            self.dispatcher._preload_condition_relationships(changeset, relationships)
+            changeset.operation_meta["relationships_preloaded"] = True
+        else:
+            logger.info("No condition relationships to preload for %s hooks", changeset.model_cls.__name__)
+
+    def _extract_condition_relationships_for_operation(
+        self,
+        changeset: ChangeSet,
+        models_in_chain: List[type],
+    ) -> Set[str]:
+        """
+        Extract relationships needed by hook conditions for this operation.
+
+        Args:
+            changeset: The changeset for this operation
+            models_in_chain: List of model classes in inheritance chain
+
+        Returns:
+            Set of relationship field names to preload
+        """
+        relationships = set()
+        event_prefix = changeset.operation_type
+        events_to_check = [f"validate_{event_prefix}", f"before_{event_prefix}", f"after_{event_prefix}"]
+
+        for model_cls in models_in_chain:
+            for event in events_to_check:
+                hooks = self.dispatcher.registry.get_hooks(model_cls, event)
+
+                for handler_cls, method_name, condition, priority in hooks:
+                    if condition:
+                        condition_rels = self.dispatcher._extract_condition_relationships(condition, model_cls)
+                        relationships.update(condition_rels)
+
+        return relationships
+
+    def _extract_hook_relationships(self) -> Set[str]:
+        """
+        Extract all relationship paths that hooks might access.
+
+        This includes both condition relationships and @select_related decorators
+        for the model and its MTI parents. Prevents N+1 queries during bulk operations.
+
+        Returns:
+            Set of relationship field names to preload with select_related
+        """
+        relationships = set()
+        models_to_check = self.inheritance_chain
+        events_to_check = ["before_update", "after_update", "validate_update"]
+
+        for model_cls in models_to_check:
+            logger.info("Checking hooks for model %s", model_cls.__name__)
+
+            for event in events_to_check:
+                hooks = self.dispatcher.registry.get_hooks(model_cls, event)
+                logger.info("Found %d hooks for %s.%s", len(hooks), model_cls.__name__, event)
+
+                for handler_cls, method_name, condition, priority in hooks:
+                    # Extract from conditions
+                    if condition:
+                        condition_rels = self.dispatcher._extract_condition_relationships(condition, model_cls)
+                        if condition_rels:
+                            logger.info("Condition relationships for %s.%s: %s", model_cls.__name__, method_name, condition_rels)
+                            relationships.update(condition_rels)
+
+                    # Extract from @select_related decorators
+                    try:
+                        method = getattr(handler_cls, method_name, None)
+                        if method:
+                            select_related_fields = getattr(method, "_select_related_fields", None)
+                            if select_related_fields and hasattr(select_related_fields, "__iter__"):
+                                logger.info(
+                                    "@select_related fields on %s.%s: %s", handler_cls.__name__, method_name, list(select_related_fields)
+                                )
+                                relationships.update(select_related_fields)
+                    except Exception as e:
+                        logger.warning("Failed to extract @select_related from %s.%s: %s", handler_cls.__name__, method_name, e)
+
+        # Also preload all forward FK relationships on the model (aggressive approach)
+        try:
+            for field in self.model_cls._meta.get_fields():
+                if field.is_relation and not field.many_to_many and not field.one_to_many:
+                    relationships.add(field.name)
+                    logger.info("AUTO: Adding FK relationship field %s", field.name)
+        except Exception as e:
+            logger.warning("Failed to extract all relationship fields: %s", e)
+
+        logger.info("Total extracted relationships for %s: %s", self.model_cls.__name__, list(relationships))
+
+        return relationships
+
+    # ==================== HELPER METHODS ====================
+
+    def _build_update_changeset(
+        self,
+        objs: List[Model],
+        fields: List[str],
+        old_records_map: Dict[Any, Model],
+    ) -> ChangeSet:
+        """
+        Build a changeset for bulk update operations.
+
+        Args:
+            objs: List of model instances to update
+            fields: List of field names to update
+            old_records_map: Map of pk -> old record
+
+        Returns:
+            ChangeSet for the update operation
+        """
+        changes = [
+            RecordChange(
+                new_record=obj,
+                old_record=old_records_map.get(obj.pk),
+                changed_fields=fields,
+            )
+            for obj in objs
+        ]
+
+        return ChangeSet(self.model_cls, changes, "update", {"fields": fields})