perf: 7 performance optimizations for hot paths

1. Cache field names set per class in __getattribute__ (O(1) vs O(n))
2. Cache field-by-name dict per class (O(1) vs O(n) linear scan)
3. Cache _normalize_to_base results with lru_cache (immutable type registry)
4. Pre-compute camel_to_snake config field name at class creation time
5. Guard expensive debug logging with logger.isEnabledFor(logging.DEBUG)
6. Hoist lazy imports out of hot loops in extract_all_configs
7. Wire up _mro_resolution_cache in resolve_field_inheritance with
   coordinated invalidation on context push/pop

All caches use immutable class metadata or follow existing invalidation
patterns. Field name caches lazily populate on first access for classes
created outside _create_lazy_dataclass_unified to avoid AttributeError.

Author: trissim

src/objectstate/context_manager.py

@@ -19,6 +19,7 @@
 
 import contextvars
 import dataclasses
+import functools
 import inspect
 import logging
 import threading
@@ -225,16 +226,19 @@ def config_context(obj, mask_with_none: bool = False, use_live_global: bool = Tr
     merged_token = current_temp_global.set(merged_config)
     type_token = context_type_stack.set(new_types)
     layer_token = context_layer_stack.set(new_layers)
-    # PERFORMANCE: Clear extract cache on context push (new merged config)
+    # PERFORMANCE: Clear caches on context push (new merged config)
     clear_extract_all_configs_cache()
+    from objectstate.dual_axis_resolver import clear_mro_resolution_cache
+    clear_mro_resolution_cache()
     try:
         yield
     finally:
         current_temp_global.reset(merged_token)
         context_type_stack.reset(type_token)
         context_layer_stack.reset(layer_token)
-        # PERFORMANCE: Clear extract cache on context pop
+        # PERFORMANCE: Clear caches on context pop
         clear_extract_all_configs_cache()
+        clear_mro_resolution_cache()
 
 
 def get_context_type_stack():
@@ -280,11 +284,15 @@ def get_context_layer_stack() -> Tuple[Tuple[str, Any], ...]:
     return context_layer_stack.get()
 
 
+@functools.lru_cache(maxsize=None)
 def _normalize_type(t):
     """Normalize a type by getting its base type if it's a lazy variant.
 
     This function is defined here to avoid circular imports with lazy_factory.
     The actual get_base_type_for_lazy is imported lazily when needed.
+
+    PERFORMANCE: Results are cached with lru_cache since type->base_type
+    mappings are immutable after class creation.
     """
     try:
         from objectstate.lazy_factory import get_base_type_for_lazy
@@ -648,14 +656,15 @@ def build_context_stack(
 
     obj_type_name = obj_type.__name__
 
-    # Build ancestor list for logging - support both old and new format
-    if ancestor_objects_with_scopes:
-        ancestor_types = [type(o).__name__ for _, o in ancestor_objects_with_scopes]
-    elif ancestor_objects:
-        ancestor_types = [type(o).__name__ for o in ancestor_objects]
-    else:
-        ancestor_types = []
-    logger.debug(f"🔧 build_context_stack: obj={obj_type_name}, ancestors={ancestor_types}")
+    # PERFORMANCE: Only build ancestor list for logging when DEBUG is enabled
+    if logger.isEnabledFor(logging.DEBUG):
+        if ancestor_objects_with_scopes:
+            ancestor_types = [type(o).__name__ for _, o in ancestor_objects_with_scopes]
+        elif ancestor_objects:
+            ancestor_types = [type(o).__name__ for o in ancestor_objects]
+        else:
+            ancestor_types = []
+        logger.debug(f"🔧 build_context_stack: obj={obj_type_name}, ancestors={ancestor_types}")
 
     # 1. Global context layer (least specific)
     # ALWAYS use LIVE thread-local for global config - it's the SINGLE SOURCE OF TRUTH
@@ -1093,6 +1102,8 @@ def extract_all_configs(context_obj) -> Dict[str, Any]:
 
     # Type-driven extraction: Use dataclass field annotations to find config fields
     if is_dataclass(type(context_obj)):
+        # PERFORMANCE: Hoist import out of the per-field loop
+        from objectstate.lazy_factory import get_base_type_for_lazy
         for field_info in fields(type(context_obj)):
             field_type = field_info.type
             field_name = field_info.name
@@ -1107,7 +1118,6 @@ def extract_all_configs(context_obj) -> Dict[str, Any]:
                     if field_value is not None:
                         # CRITICAL: Use base type for lazy configs so MRO matching works
                         # LazyWellFilterConfig should be stored as WellFilterConfig
-                        from objectstate.lazy_factory import get_base_type_for_lazy
                         instance_type = type(field_value)
                         base_type = get_base_type_for_lazy(instance_type) or instance_type
                         configs[base_type.__name__] = field_value
@@ -1122,7 +1132,8 @@ def extract_all_configs(context_obj) -> Dict[str, Any]:
 
     # Cache result
     _extract_all_configs_cache[obj_id] = configs
-    logger.debug(f"Extracted {len(configs)} configs: {list(configs.keys())}")
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(f"Extracted {len(configs)} configs: {list(configs.keys())}")
     return configs
 
 

src/objectstate/dual_axis_resolver.py

@@ -8,6 +8,7 @@
 """
 
 import logging
+import functools
 from typing import Any, Dict, Optional, Tuple
 from dataclasses import is_dataclass
 
@@ -66,11 +67,16 @@ def invalidate_mro_cache_for_field(changed_type: type, field_name: str) -> None:
         del _mro_resolution_cache[key]
 
 
+@functools.lru_cache(maxsize=None)
 def _normalize_to_base(t: type) -> type:
     """Normalize lazy type to its base type for comparison.
 
     LazyWellFilterConfig -> WellFilterConfig
     WellFilterConfig -> WellFilterConfig
+
+    PERFORMANCE: Results are cached with lru_cache since type->base_type
+    mappings are immutable after class creation. Import is hoisted to
+    avoid per-call import overhead.
     """
     from objectstate.lazy_factory import get_base_type_for_lazy
     return get_base_type_for_lazy(t) or t
@@ -129,6 +135,16 @@ def resolve_field_inheritance(
     # This works for both LazyDataclass types AND concrete dataclasses with None fields.
     obj_base = _normalize_to_base(obj_type)
 
+    # PERFORMANCE: Check MRO resolution cache before doing the full walk.
+    # Cache key uses (obj_type, field_name, config_identity) where config_identity
+    # captures which config instances are active. Cache is cleared on context push/pop.
+    _cache_key = (obj_type, field_name, tuple((k, id(v)) for k, v in available_configs.items()))
+    _cached = _mro_resolution_cache.get(_cache_key, _CACHE_SENTINEL)
+    if _cached is not _CACHE_SENTINEL:
+        return _cached
+
+    _debug = logger.isEnabledFor(logging.DEBUG)
+
     if needs_resolution:
         for config_key, config_instance in available_configs.items():
             # Normalize both sides: LazyWellFilterConfig matches WellFilterConfig
@@ -137,18 +153,20 @@ def resolve_field_inheritance(
                 try:
                     field_value = object.__getattribute__(config_instance, field_name)
                     if field_value is not None:
-                        if field_name == 'well_filter':
-                            logger.debug(f"🔍 CONCRETE VALUE: {obj_type.__name__}.{field_name} = {field_value}")
-                        if field_name == 'num_workers':
-                            logger.debug(f"🔍 SAME-TYPE MATCH: {obj_type.__name__}.{field_name} = {field_value!r} (type={type(field_value).__name__}) FROM config_key={config_key}, config_type={type(config_instance).__name__}")
+                        if _debug:
+                            if field_name == 'well_filter':
+                                logger.debug(f"🔍 CONCRETE VALUE: {obj_type.__name__}.{field_name} = {field_value}")
+                            if field_name == 'num_workers':
+                                logger.debug(f"🔍 SAME-TYPE MATCH: {obj_type.__name__}.{field_name} = {field_value!r} (type={type(field_value).__name__}) FROM config_key={config_key}, config_type={type(config_instance).__name__}")
+                        _mro_resolution_cache[_cache_key] = field_value
                         return field_value
                 except AttributeError:
                     continue
 
     # Step 2: MRO-based inheritance - traverse MRO from most to least specific
     # Skip the first entry (self type) since we already checked it above (for lazy) or want to skip it (for concrete)
     # This finds PARENT class configs with concrete values (sibling inheritance)
-    if field_name in ['output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode']:
+    if _debug and field_name in ('output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode'):
         logger.debug(f"🔍 MRO-INHERITANCE: Resolving {obj_type.__name__}.{field_name}")
         logger.debug(f"🔍 MRO-INHERITANCE: MRO = {[cls.__name__ for cls in obj_type.__mro__]}")
 
@@ -164,24 +182,28 @@ def resolve_field_inheritance(
             if instance_base == mro_base:
                 try:
                     value = object.__getattribute__(config_instance, field_name)
-                    if field_name in ['output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode']:
-                        logger.debug(f"🔍 MRO-INHERITANCE: {mro_class.__name__}.{field_name} = {value}")
-                    if field_name == 'num_workers':
-                        logger.debug(f"🔍 MRO-INHERITANCE: {mro_class.__name__}.{field_name} = {value!r} (type={type(value).__name__})")
-                    if value is not None:
-                        if field_name in ['output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode']:
-                            logger.debug(f"🔍 MRO-INHERITANCE: FOUND {mro_class.__name__}.{field_name}: {value} (returning)")
+                    if _debug:
+                        if field_name in ('output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode'):
+                            logger.debug(f"🔍 MRO-INHERITANCE: {mro_class.__name__}.{field_name} = {value}")
                         if field_name == 'num_workers':
-                            logger.debug(f"🔍 MRO-INHERITANCE: RETURNING {mro_class.__name__}.{field_name} = {value!r}")
+                            logger.debug(f"🔍 MRO-INHERITANCE: {mro_class.__name__}.{field_name} = {value!r} (type={type(value).__name__})")
+                    if value is not None:
+                        if _debug:
+                            if field_name in ('output_dir_suffix', 'sub_dir', 'well_filter', 'well_filter_mode'):
+                                logger.debug(f"🔍 MRO-INHERITANCE: FOUND {mro_class.__name__}.{field_name}: {value} (returning)")
+                            if field_name == 'num_workers':
+                                logger.debug(f"🔍 MRO-INHERITANCE: RETURNING {mro_class.__name__}.{field_name} = {value!r}")
+                        _mro_resolution_cache[_cache_key] = value
                         return value
                 except AttributeError:
                     continue
 
     # No Step 3: If MRO walk finds nothing, return None.
     # "If we wanted static class defaults, it wouldn't have been overridden to None"
     # For LazyDataclass, class defaults are all None anyway (via rebuild_with_none_defaults).
-    if field_name in ['output_dir_suffix', 'sub_dir', 'well_filter']:
+    if _debug and field_name in ('output_dir_suffix', 'sub_dir', 'well_filter'):
         logger.debug(f"🔍 NO-RESOLUTION: {obj_type.__name__}.{field_name} = None")
+    _mro_resolution_cache[_cache_key] = None
     return None
 
 
@@ -248,7 +270,9 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
     # - MRO inheritance only applies when NO concrete value exists in the hierarchy
     #   for the specific config type being resolved
 
-    if field_name == 'well_filter':
+    _debug = logger.isEnabledFor(logging.DEBUG)
+
+    if _debug and field_name == 'well_filter':
         logger.debug(f"🔍 resolve_with_provenance: container={container_base.__name__}, field={field_name}, layers={len(layers)}")
         logger.debug(f"🔍 resolve_with_provenance: mro_types={[t.__name__ for t in mro_types]}")
 
@@ -271,21 +295,21 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
     # This gives hierarchy precedence: inner/child scopes override outer/parent scopes
     # REVERSED ORDER: Walk from inner to outer so more specific scopes override general scopes
     for scope_id, layer_configs in reversed(all_layer_configs):
-        if field_name == 'well_filter':
+        if _debug and field_name == 'well_filter':
             logger.debug(f"🔍   Phase 1 - Layer scope={scope_id!r}, checking same-type only (inner to outer)")
 
         for config_instance in layer_configs.values():
             instance_base = _normalize_to_base(type(config_instance))
-            if field_name in ('well_filter', 'enabled') and instance_base == container_base:
+            if _debug and field_name in ('well_filter', 'enabled') and instance_base == container_base:
                 logger.debug(f"🔍     FOUND same-type config: {instance_base.__name__} @ scope={scope_id}")
             if instance_base == container_base:  # Same-type only, no MRO
                 try:
                     value = object.__getattribute__(config_instance, field_name)
-                    if field_name in ('well_filter', 'enabled'):
+                    if _debug and field_name in ('well_filter', 'enabled'):
                         logger.debug(f"🔍     {container_base.__name__}.{field_name} @ scope={scope_id} = {value!r} (from object.__getattribute__)")
                     if value is not None:
                         # Found concrete value in hierarchy - return immediately
-                        if field_name in ('well_filter', 'enabled'):
+                        if _debug and field_name in ('well_filter', 'enabled'):
                             logger.debug(f"🔍     FOUND concrete value in hierarchy at scope={scope_id!r}, returning {value!r}")
                         return value, scope_id, container_base
                     # Don't set fallback here - let Phase 2 walk MRO to find
@@ -304,7 +328,7 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
     #
     # Therefore: for each MRO type (most→least specific), scan scopes (inner→outer)
     # looking for the first non-None value.
-    if field_name == 'well_filter':
+    if _debug and field_name == 'well_filter':
         logger.debug(f"🔍   Phase 2 - MRO fallback, walking layers inner to outer")
 
     # Track where the "highest-precedence" field exists even if None, so callers
@@ -330,7 +354,7 @@ def resolve_with_provenance(container_type: type, field_name: str) -> Tuple[Any,
                 except AttributeError:
                     continue
 
-                if field_name == 'well_filter':
+                if _debug and field_name == 'well_filter':
                     logger.debug(f"🔍     MRO: {mro_type.__name__}.{field_name} @ {scope_id!r} = {value!r}")
 
                 if value is not None:

src/objectstate/lazy_factory.py

@@ -477,7 +477,22 @@ def __getattribute__(self: Any, name: str) -> Any:
             """
             # Stage 1: Get instance value
             value = object.__getattribute__(self, name)
-            if value is not None or name not in {f.name for f in fields(self.__class__)}:
+            # Fast path: non-None values never need resolution
+            if value is not None:
+                return value
+            # PERFORMANCE: Use pre-computed frozenset (O(1) lookup) instead of
+            # rebuilding {f.name for f in fields(self.__class__)} (O(n)) on every access.
+            # Use object.__getattribute__ for __class__ to avoid recursion.
+            # Lazily populate if not yet set (e.g. class created outside _create_lazy_dataclass_unified).
+            _cls = object.__getattribute__(self, '__class__')
+            try:
+                _fns = _cls._field_names_set
+            except AttributeError:
+                _ft = fields(_cls)
+                _fns = frozenset(f.name for f in _ft)
+                _cls._field_names_set = _fns
+                _cls._fields_by_name = {f.name: f for f in _ft}
+            if name not in _fns:
                 return value
 
             # Stage 2: Simple field path lookup in current scope's merged global
@@ -510,7 +525,13 @@ def __getattribute__(self: Any, name: str) -> Any:
                     return resolved_value
 
                 # For nested dataclass fields, return lazy instance
-                field_obj = next((f for f in fields(self.__class__) if f.name == name), None)
+                # PERFORMANCE: O(1) dict lookup instead of O(n) linear scan
+                _fbm = getattr(self.__class__, '_fields_by_name', None)
+                if _fbm is None:
+                    _ft = fields(self.__class__)
+                    _fbm = {f.name: f for f in _ft}
+                    self.__class__._fields_by_name = _fbm
+                field_obj = _fbm.get(name)
                 if field_obj and is_dataclass(field_obj.type):
                     return field_obj.type()
 
@@ -535,7 +556,13 @@ def __getattribute__(self: Any, name: str) -> Any:
                     return mro_value
 
                 # Also check inherited default metadata
-                field_obj = next((f for f in fields(self.__class__) if f.name == name), None)
+                # PERFORMANCE: O(1) dict lookup instead of O(n) linear scan
+                _fbm = getattr(self.__class__, '_fields_by_name', None)
+                if _fbm is None:
+                    _ft = fields(self.__class__)
+                    _fbm = {f.name: f for f in _ft}
+                    self.__class__._fields_by_name = _fbm
+                field_obj = _fbm.get(name)
                 if field_obj and '_inherited_default' in field_obj.metadata:
                     inherited = field_obj.metadata['_inherited_default']
                     if inherited is not MISSING:
@@ -719,20 +746,32 @@ def _create_lazy_dataclass_unified(
             frozen=base_is_frozen  # Match base class frozen status
         )
 
+        # PERFORMANCE: Pre-compute class-level metadata ONCE at class creation time
+        # instead of recomputing on every instance construction or attribute access.
+        import re
+        _s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', base_class.__name__)
+        _config_field_name = re.sub('([a-z0-9])([A-Z])', r'\1_\2', _s1).lower()
+        lazy_class._config_field_name_cls = _config_field_name
+        lazy_class._global_config_type_cls = global_config_type
+
+        # PERFORMANCE: Cache field names set and field-by-name dict per class.
+        # These are derived from dataclasses.fields() which is immutable after class creation.
+        # Avoids O(n) set creation on every __getattribute__ call and O(n) linear scan
+        # on every field lookup.
+        from dataclasses import fields as _dc_fields
+        _field_tuple = _dc_fields(lazy_class)
+        lazy_class._field_names_set = frozenset(f.name for f in _field_tuple)
+        lazy_class._fields_by_name = {f.name: f for f in _field_tuple}
+
         # Add constructor parameter tracking to detect user-set fields
         original_init = lazy_class.__init__
         def __init_with_tracking__(self, **kwargs):
             # Track which fields were explicitly passed to constructor
             object.__setattr__(self, '_explicitly_set_fields', set(kwargs.keys()))
-            # Store the global config type for inheritance resolution
+            # Store the global config type for inheritance resolution (read from class attr)
             object.__setattr__(self, '_global_config_type', global_config_type)
-            # Store the config field name for simple field path lookup
-            import re
-            def _camel_to_snake_local(name: str) -> str:
-                s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
-                return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
-            config_field_name = _camel_to_snake_local(base_class.__name__)
-            object.__setattr__(self, '_config_field_name', config_field_name)
+            # Store the config field name (read from pre-computed class attr)
+            object.__setattr__(self, '_config_field_name', type(self)._config_field_name_cls)
             original_init(self, **kwargs)
 
         lazy_class.__init__ = __init_with_tracking__