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

django_bulk_hooks/operations/coordinator.py

@@ -6,18 +6,38 @@ 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.
@@ -26,11 +46,13 @@ class BulkOperationCoordinator:
     for the QuerySet. It wires up services and coordinates the hook
     lifecycle for each operation type.
 
-    Services are created lazily and cached.
+    Services are created lazily and cached for performance.
     """
 
+    # Constants
+    UPSERT_TIMESTAMP_THRESHOLD_SECONDS = 1.0
 
-    def __init__(self, queryset):
+    def __init__(self, queryset: QuerySet):
         """
         Initialize coordinator for a queryset.
 
@@ -40,77 +62,96 @@ class BulkOperationCoordinator:
         self.queryset = queryset
         self.model_cls = queryset.model
 
-        # Lazy initialization
+        # 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"""
-        if self._analyzer is None:
-            from django_bulk_hooks.operations.analyzer import ModelAnalyzer
+        """Get or create ModelAnalyzer."""
+        from django_bulk_hooks.operations.analyzer import ModelAnalyzer
 
-            self._analyzer = ModelAnalyzer(self.model_cls)
-        return self._analyzer
+        return self._get_or_create_service("analyzer", ModelAnalyzer, self.model_cls)
 
     @property
     def mti_handler(self):
-        """Get or create MTIHandler"""
-        if self._mti_handler is None:
-            from django_bulk_hooks.operations.mti_handler import MTIHandler
+        """Get or create MTIHandler."""
+        from django_bulk_hooks.operations.mti_handler import MTIHandler
 
-            self._mti_handler = MTIHandler(self.model_cls)
-        return self._mti_handler
+        return self._get_or_create_service("mti_handler", MTIHandler, self.model_cls)
 
     @property
     def record_classifier(self):
-        """Get or create RecordClassifier"""
-        if self._record_classifier is None:
-            from django_bulk_hooks.operations.record_classifier import RecordClassifier
+        """Get or create RecordClassifier."""
+        from django_bulk_hooks.operations.record_classifier import RecordClassifier
 
-            self._record_classifier = RecordClassifier(self.model_cls)
-        return self._record_classifier
+        return self._get_or_create_service("record_classifier", RecordClassifier, self.model_cls)
 
     @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,
-                record_classifier=self.record_classifier,
-            )
-        return self._executor
+        """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"""
-        if self._dispatcher is None:
-            from django_bulk_hooks.dispatcher import get_dispatcher
+        """Get or create Dispatcher."""
+        from django_bulk_hooks.dispatcher import get_dispatcher
 
-            self._dispatcher = get_dispatcher()
-        return self._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,
-        batch_size=None,
-        ignore_conflicts=False,
-        update_conflicts=False,
-        update_fields=None,
-        unique_fields=None,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
+        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.
 
@@ -122,7 +163,6 @@ class BulkOperationCoordinator:
             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
@@ -130,22 +170,11 @@ class BulkOperationCoordinator:
         if not objs:
             return objs
 
-        # Validate
         self.analyzer.validate_for_create(objs)
 
-        # For upsert operations, classify records upfront
-        existing_record_ids = set()
-        existing_pks_map = {}
-        if update_conflicts and unique_fields:
-            existing_record_ids, existing_pks_map = self.record_classifier.classify_for_upsert(
-                objs, unique_fields
-            )
-            logger.info(
-                f"Upsert operation: {len(existing_record_ids)} existing, "
-                f"{len(objs) - len(existing_record_ids)} new records"
-            )
+        # Handle upsert classification upfront
+        existing_record_ids, existing_pks_map = self._classify_upsert_records(objs, update_conflicts, unique_fields)
 
-        # Build initial changeset
         changeset = build_changeset_for_create(
             self.model_cls,
             objs,
@@ -156,7 +185,6 @@ class BulkOperationCoordinator:
             unique_fields=unique_fields,
         )
 
-        # Execute with hook lifecycle
         def operation():
             return self.executor.bulk_create(
                 objs,
@@ -174,18 +202,16 @@ class BulkOperationCoordinator:
             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,
-    ):
+        objs: List[Model],
+        fields: List[str],
+        batch_size: Optional[int] = None,
+        bypass_hooks: bool = False,
+    ) -> int:
         """
         Execute bulk update with hooks.
 
@@ -194,7 +220,6 @@ class BulkOperationCoordinator:
             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
@@ -202,27 +227,11 @@ class BulkOperationCoordinator:
         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)
+        changeset = self._build_update_changeset(objs, fields, old_records_map)
 
-        # Build changeset
-        from django_bulk_hooks.changeset import ChangeSet
-        from django_bulk_hooks.changeset import 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)
 
@@ -231,19 +240,20 @@ class BulkOperationCoordinator:
             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,
-    ):
+        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)
@@ -252,171 +262,435 @@ class BulkOperationCoordinator:
         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.
-        
-        Hook Semantics:
-        - BEFORE_UPDATE hooks run after the DB update and CAN modify instances
-        - Modifications are auto-persisted (framework handles complexity)
-        - AFTER_UPDATE hooks run after BEFORE_UPDATE and are read-only
-        - This enables cascade logic and computed fields based on DB values
-        - User expectation: BEFORE_UPDATE hooks can modify data
-        
-        Why this approach works well:
-        - Allows hooks to see Subquery/F() computed values
-        - Enables HasChanged conditions on complex expressions
-        - Maintains SQL performance (Subquery stays in database)
-        - Meets user expectations: BEFORE_UPDATE can modify instances
-        - Clean separation: BEFORE for modifications, AFTER for side effects
-        
-        For true "prevent write" semantics, intercept at a higher level
-        or use bulk_update() directly (which has true before semantics).
-        """
-        from django_bulk_hooks.context import get_bypass_hooks
-
-        # Fast path: no hooks at all
+
+        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)
 
-        # Full hook lifecycle path
-        return self._execute_queryset_update_with_hooks(
-            update_kwargs=update_kwargs,
-            bypass_validation=bypass_validation,
+        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, bypass_validation=False,
-    ):
+        self,
+        update_kwargs: Dict[str, Any],
+    ) -> int:
         """
         Execute queryset update with full hook lifecycle support.
-        
-        This method implements the fetch-update-fetch pattern required
-        to support hooks with queryset.update(). BEFORE_UPDATE hooks can
-        modify instances and modifications are auto-persisted.
-        
+
+        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
-            bypass_validation: Skip validation hooks if True
-            
+
         Returns:
             Number of rows updated
         """
-        # Step 1: Fetch old state (before database update)
-        old_instances = list(self.queryset)
+        # 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
-        # Use stored reference to parent class method - clean and simple
         update_count = QuerySet.update(self.queryset, **update_kwargs)
-
         if update_count == 0:
             return 0
 
-        # Step 3: Fetch new state (after database update)
-        # This captures any Subquery/F() computed values
-        # Use primary keys to fetch updated instances since queryset filters may no longer match
-        pks = [inst.pk for inst in old_instances]
-        new_instances = list(self.model_cls.objects.filter(pk__in=pks))
+        # 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
+        # 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,
         )
-
-        # Mark as queryset update for potential hook inspection
         changeset.operation_meta["is_queryset_update"] = True
         changeset.operation_meta["allows_modifications"] = True
 
-        # Step 5: Get MTI inheritance chain
-        models_in_chain = [self.model_cls]
-        if self.mti_handler.is_mti_model():
-            models_in_chain.extend(self.mti_handler.get_parent_models())
-
-        # Step 6: Run VALIDATE hooks (if not bypassed)
-        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,
-                    "validate_update",
-                    bypass_hooks=False,
-                )
-
-        # Step 7: Run BEFORE_UPDATE hooks with modification tracking
-        modified_fields = self._run_before_update_hooks_with_tracking(
-            new_instances,
-            models_in_chain,
-            changeset,
-        )
+        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 8: Auto-persist BEFORE_UPDATE modifications
+        # Step 7: Auto-persist BEFORE_UPDATE modifications
         if modified_fields:
             self._persist_hook_modifications(new_instances, modified_fields)
 
-        # Step 9: Take snapshot before AFTER_UPDATE hooks
-        pre_after_hook_state = self._snapshot_instance_state(new_instances)
+        # 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 10: Run AFTER_UPDATE hooks (read-only side effects)
-        for model_cls in models_in_chain:
-            model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(
-                model_changeset,
-                "after_update",
-                bypass_hooks=False,
-            )
-
-        # Step 11: Auto-persist AFTER_UPDATE modifications (if any)
-        after_modified_fields = self._detect_modifications(new_instances, pre_after_hook_state)
+        # 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, models_in_chain, changeset):
+    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.
-        
-        This is what users expect - BEFORE_UPDATE hooks can modify instances
-        and those modifications will be automatically persisted. The framework
-        handles the complexity internally.
-        
+
         Returns:
             Set of field names that were modified by hooks
         """
-        # Snapshot current state
         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])
 
-        # Run BEFORE_UPDATE hooks
         for model_cls in models_in_chain:
             model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(
-                model_changeset,
-                "before_update",
-                bypass_hooks=False,
-            )
+            self.dispatcher.dispatch(model_changeset, event_suffix, bypass_hooks=bypass_hooks)
 
-        # Detect modifications
-        return self._detect_modifications(instances, pre_hook_state)
+    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.
 
-    def _snapshot_instance_state(self, instances):
+        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}
         """
@@ -428,29 +702,31 @@ class BulkOperationCoordinator:
 
             field_values = {}
             for field in self.model_cls._meta.get_fields():
-                # Skip relations that aren't concrete fields
+                # Skip non-concrete fields
                 if field.many_to_many or field.one_to_many:
                     continue
 
-                field_name = field.name
                 try:
-                    field_values[field_name] = getattr(instance, field_name)
+                    field_values[field.name] = getattr(instance, field.name)
                 except (AttributeError, FieldDoesNotExist):
-                    # Field not accessible (e.g., deferred field)
-                    field_values[field_name] = None
+                    field_values[field.name] = None
 
             snapshot[instance.pk] = field_values
 
         return snapshot
 
-    def _detect_modifications(self, instances, pre_hook_state):
+    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 from _snapshot_instance_state
-            
+            pre_hook_state: Previous state snapshot
+
         Returns:
             Set of field names that were modified
         """
@@ -468,314 +744,185 @@ class BulkOperationCoordinator:
                 except (AttributeError, FieldDoesNotExist):
                     current_value = None
 
-                # Compare values
                 if current_value != old_value:
                     modified_fields.add(field_name)
 
         return modified_fields
 
-    def _persist_hook_modifications(self, instances, modified_fields):
+    def _persist_hook_modifications(self, instances: List[Model], modified_fields: Set[str]) -> None:
         """
         Persist modifications made by hooks using bulk_update.
-        
-        This creates a "cascade" effect similar to Salesforce workflows.
-        
+
         Args:
             instances: List of modified instances
             modified_fields: Set of field names that were modified
         """
-        logger.info(
-            f"Hooks modified {len(modified_fields)} field(s): "
-            f"{', '.join(sorted(modified_fields))}",
-        )
+        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)
-        # Create a fresh QuerySet to avoid recursion
         fresh_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
         QuerySet.bulk_update(fresh_qs, instances, list(modified_fields))
 
-    @transaction.atomic
-    def delete(self, bypass_hooks=False, bypass_validation=False):
+    # ==================== RELATIONSHIP PRELOADING ====================
+
+    def _fetch_instances_with_relationships(
+        self,
+        queryset: QuerySet,
+        relationships: Set[str],
+    ) -> List[Model]:
         """
-        Execute delete with hooks.
+        Fetch instances with relationships preloaded.
 
         Args:
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
+            queryset: QuerySet to fetch from
+            relationships: Set of relationship names to preload
 
         Returns:
-            Tuple of (count, details dict)
+            List of model instances with relationships loaded
         """
-        # 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():
-            # Use stored reference to parent method - clean and simple
-            return QuerySet.delete(self.queryset)
+        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 self._execute_with_mti_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="delete",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
+        return list(queryset)
 
-    def clean(self, objs, is_create=None):
+    def _preload_condition_relationships_for_operation(
+        self,
+        changeset: ChangeSet,
+        models_in_chain: List[type],
+    ) -> None:
         """
-        Execute validation hooks only (no database operations).
+        Preload relationships needed by hook conditions for this operation.
 
-        This is used by Django's clean() method to hook VALIDATE_* events
-        without performing the actual operation.
+        This prevents N+1 queries by loading all necessary relationships upfront.
 
         Args:
-            objs: List of model instances to validate
-            is_create: True for create, False for update, None to auto-detect
-
-        Returns:
-            None
+            changeset: The changeset for this operation
+            models_in_chain: List of model classes in inheritance chain
         """
-        if not objs:
-            return
-
-        # Auto-detect if is_create not specified
-        if is_create is None:
-            is_create = objs[0].pk is None
+        relationships = self._extract_condition_relationships_for_operation(changeset, models_in_chain)
 
-        # Build changeset based on operation type
-        if is_create:
-            changeset = build_changeset_for_create(self.model_cls, objs)
-            event = "validate_create"
+        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:
-            # 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 ====================
+            logger.info("No condition relationships to preload for %s hooks", changeset.model_cls.__name__)
 
-    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(
+    def _extract_condition_relationships_for_operation(
         self,
-        changeset,
-        operation,
-        event_prefix,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
+        changeset: ChangeSet,
+        models_in_chain: List[type],
+    ) -> Set[str]:
         """
-        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.
-        
+        Extract relationships needed by hook conditions for this operation.
+
         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
-            
+            changeset: The changeset for this operation
+            models_in_chain: List of model classes in inheritance chain
+
         Returns:
-            Result of operation
+            Set of relationship field names to preload
         """
-        if bypass_hooks:
-            return operation()
+        relationships = set()
+        event_prefix = changeset.operation_type
+        events_to_check = [f"validate_{event_prefix}", f"before_{event_prefix}", f"after_{event_prefix}"]
 
-        # 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)
+            for event in events_to_check:
+                hooks = self.dispatcher.registry.get_hooks(model_cls, event)
 
-        # Execute the actual operation
-        result = operation()
+                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)
 
-        # 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":
-            # Check if this was an upsert operation
-            is_upsert = self._is_upsert_operation(result)
-            if is_upsert:
-                # Split hooks for upsert: after_create for created, after_update for updated
-                self._dispatch_upsert_after_hooks(result, models_in_chain)
-            else:
-                # Normal create operation
-                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)
-        else:
-            # Non-create operations (update, delete)
-            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
+        return relationships
 
-    def _get_fk_fields_being_updated(self, update_kwargs):
+    def _extract_hook_relationships(self) -> Set[str]:
         """
-        Get the relationship names for FK fields being updated.
+        Extract all relationship paths that hooks might access.
 
-        This helps @select_related avoid preloading relationships that are
-        being modified, which can cause cache conflicts.
-
-        Args:
-            update_kwargs: Dict of fields being updated
+        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 names (e.g., {'business'}) for FK fields being updated
-        """
-        fk_relationships = set()
-
-        for field_name in update_kwargs.keys():
-            try:
-                field = self.model_cls._meta.get_field(field_name)
-                if (field.is_relation and
-                    not field.many_to_many and
-                    not field.one_to_many and
-                    hasattr(field, "attname") and
-                    field.attname == field_name):
-                    # This is a FK field being updated by its attname (e.g., business_id)
-                    # Add the relationship name (e.g., 'business') to skip list
-                    fk_relationships.add(field.name)
-            except FieldDoesNotExist:
-                # If field lookup fails, skip it
-                continue
+            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)
 
-        return fk_relationships
+        logger.info("Total extracted relationships for %s: %s", self.model_cls.__name__, list(relationships))
 
-    def _is_upsert_operation(self, result_objects):
-        """
-        Check if the operation was an upsert (mixed create/update).
-        
-        Args:
-            result_objects: List of objects returned from the operation
-            
-        Returns:
-            True if this was an upsert operation, False otherwise
-        """
-        if not result_objects:
-            return False
-            
-        # Check if any object has upsert metadata
-        return hasattr(result_objects[0], '_bulk_hooks_upsert_metadata')
+        return relationships
 
-    def _dispatch_upsert_after_hooks(self, result_objects, models_in_chain):
+    # ==================== HELPER METHODS ====================
+
+    def _build_update_changeset(
+        self,
+        objs: List[Model],
+        fields: List[str],
+        old_records_map: Dict[Any, Model],
+    ) -> ChangeSet:
         """
-        Dispatch after hooks for upsert operations, splitting by create/update.
-        
-        This matches Salesforce behavior:
-        - Records that were created fire after_create hooks
-        - Records that were updated fire after_update hooks
-        
+        Build a changeset for bulk update operations.
+
         Args:
-            result_objects: List of objects returned from the operation
-            models_in_chain: List of model classes in the MTI inheritance chain
+            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
         """
-        # Split objects by operation type
-        created_objects = []
-        updated_objects = []
-        
-        for obj in result_objects:
-            was_created = getattr(obj, '_bulk_hooks_was_created', True)
-            if was_created:
-                created_objects.append(obj)
-            else:
-                updated_objects.append(obj)
-        
-        logger.info(
-            f"Upsert after hooks: {len(created_objects)} created, "
-            f"{len(updated_objects)} updated"
-        )
-        
-        # Dispatch after_create hooks for created objects
-        if created_objects:
-            from django_bulk_hooks.helpers import build_changeset_for_create
-            create_changeset = build_changeset_for_create(self.model_cls, created_objects)
-            
-            for model_cls in models_in_chain:
-                model_changeset = self._build_changeset_for_model(create_changeset, model_cls)
-                self.dispatcher.dispatch(model_changeset, "after_create", bypass_hooks=False)
-        
-        # Dispatch after_update hooks for updated objects
-        if updated_objects:
-            # Fetch old records for proper change detection
-            old_records_map = self.analyzer.fetch_old_records_map(updated_objects)
-            
-            from django_bulk_hooks.helpers import build_changeset_for_update
-            update_changeset = build_changeset_for_update(
-                self.model_cls,
-                updated_objects,
-                update_kwargs={},  # Empty since we don't know specific fields
-                old_records_map=old_records_map,
+        changes = [
+            RecordChange(
+                new_record=obj,
+                old_record=old_records_map.get(obj.pk),
+                changed_fields=fields,
             )
-            
-            for model_cls in models_in_chain:
-                model_changeset = self._build_changeset_for_model(update_changeset, model_cls)
-                self.dispatcher.dispatch(model_changeset, "after_update", bypass_hooks=False)
-        
-        # Clean up temporary metadata
-        self._cleanup_upsert_metadata(result_objects)
+            for obj in objs
+        ]
 
-    def _cleanup_upsert_metadata(self, result_objects):
-        """
-        Clean up temporary metadata added during upsert operations.
-        
-        Args:
-            result_objects: List of objects to clean up
-        """
-        for obj in result_objects:
-            if hasattr(obj, '_bulk_hooks_was_created'):
-                delattr(obj, '_bulk_hooks_was_created')
-            if hasattr(obj, '_bulk_hooks_upsert_metadata'):
-                delattr(obj, '_bulk_hooks_upsert_metadata')
+        return ChangeSet(self.model_cls, changes, "update", {"fields": fields})