fix: isolate model imports from dependency runtime

examples/ex_01_flext_result_helpers.py

@@ -86,10 +86,10 @@ def side_effects_and_folds(self) -> None:
         self.audit_check("map_or.success_default", ok_value.map_or(0))
         self.audit_check("map_or.failure_default", fail_value.map_or(0))
         self.audit_check(
-            "map_or.success_func", ok_value.map_or("none", lambda n: f"n={n}")
+            "map_or.success_func", ok_value.map_or("none", "n={}".format)
         )
         self.audit_check(
-            "map_or.failure_func", fail_value.map_or("none", lambda n: f"n={n}")
+            "map_or.failure_func", fail_value.map_or("none", "n={}".format)
         )
         self.audit_check(
             "fold.success",

src/flext_core/_handlers_parts/flexthandlers_part_07.py

@@ -80,7 +80,11 @@ def scan_class(
                 for name in dir(target_class)
                 if hasattr(method := getattr(target_class, name, None), c.HANDLER_ATTR)
             ]
-            return sorted(handlers, key=lambda x: x[1].priority, reverse=True)
+
+            def priority(item: tuple[str, p.DecoratorConfig]) -> int:
+                return item[1].priority
+
+            return sorted(handlers, key=priority, reverse=True)
 
         @staticmethod
         def scan_module(
@@ -135,7 +139,13 @@ def narrowed_func(
 
                 setattr(narrowed_func, c.HANDLER_ATTR, settings)
                 handlers.append((name, narrowed_func, settings))
-            return sorted(handlers, key=lambda x: (-x[2].priority, x[0]))
+
+            def priority_and_name(
+                item: tuple[str, Callable[..., t.Scalar | None], p.DecoratorConfig],
+            ) -> tuple[int, str]:
+                return -item[2].priority, item[0]
+
+            return sorted(handlers, key=priority_and_name)
 
 
 __all__: list[str] = ["FlextHandlers"]

src/flext_core/_lazy_parts/flextlazy_part_02.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import sys
+from functools import partial
 from types import ModuleType
 from typing import TYPE_CHECKING, cast
 
@@ -207,8 +208,11 @@ def install(
             names = tuple(dict.fromkeys((*normalized, *all_exports)))
 
         module_globals["_LAZY_IMPORTS"] = normalized
-        module_globals["__getattr__"] = lambda name: self.get(
-            name, normalized, module_globals, module_name
+        module_globals["__getattr__"] = partial(
+            self.get,
+            lazy_imports=normalized,
+            module_globals=module_globals,
+            module_name=module_name,
         )
         module_globals["__dir__"] = lambda: list(names)
         if publish_all:

src/flext_core/_models/_base_parts/flextmodelsbase_part_02.py

@@ -105,7 +105,7 @@
                 title="Attributes",
                 examples=[{"source": "api", "priority": "high"}],
             ),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(default_factory=lambda: MappingProxyType(dict[str, t.JsonValue]()))
         metadata_value: Annotated[
             t.Scalar | None,
             mp.Field(default=None, description="Scalar metadata value."),

src/flext_core/_models/_context/__scope_parts/flextmodelscontextscope_part_01.py

@@ -65,7 +65,7 @@
             mp.Field(
                 description="Additional metric counters and timing values grouped by metric key."
             ),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(default_factory=lambda: MappingProxyType(dict[str, t.JsonValue]()))
 
 
 __all__: list[str] = ["FlextModelsContextScope"]

src/flext_core/_models/_context/__scope_parts/flextmodelscontextscope_part_02.py

@@ -34,10 +34,16 @@
         hooks: Annotated[
             t.ContextHookMap,
             mp.Field(
-                default_factory=lambda: MappingProxyType({}),
+                default_factory=lambda: MappingProxyType(
+                    dict[str, t.SequenceOf[t.ContextHookCallable]]()
+                ),
                 description="Lifecycle hooks keyed by event name",
             ),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(
+            default_factory=lambda: MappingProxyType(
+                dict[str, t.SequenceOf[t.ContextHookCallable]]()
+            )
+        )
         statistics: Annotated[
             FlextModelsContextScopePart01.ContextStatistics,
             mp.Field(
@@ -63,10 +69,21 @@
                 str, contextvars.ContextVar[FlextModelsContainers.ConfigMap | None]
             ],
             mp.Field(
-                default_factory=lambda: MappingProxyType({}),
+                default_factory=lambda: MappingProxyType(
+                    dict[
+                        str,
+                        contextvars.ContextVar[FlextModelsContainers.ConfigMap | None],
+                    ]()
+                ),
                 description="ContextVar registry keyed by scope name",
             ),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(
+            default_factory=lambda: MappingProxyType(
+                dict[
+                    str, contextvars.ContextVar[FlextModelsContainers.ConfigMap | None]
+                ]()
+            )
+        )
 
         @classmethod
         def create_default(

src/flext_core/_models/_context/_export.py

@@ -30,7 +30,7 @@
         data: Annotated[
             t.MappingKV[str, t.JsonPayload],
             Field(
-                default_factory=lambda: MappingProxyType({}),
+                default_factory=lambda: MappingProxyType(dict[str, t.JsonPayload]()),
                 description="All context data from all scopes",
             ),
         ]
@@ -52,7 +52,7 @@
                 )
             ),
             Field(
-                default_factory=lambda: MappingProxyType({}),
+                default_factory=lambda: MappingProxyType(dict[str, t.JsonValue]()),
                 description="Usage statistics (operation counts, timing info)",
             ),
         ]

src/flext_core/_models/cqrs.py

@@ -130,7 +130,7 @@
                 title="Query Filters",
                 examples=[{"status": "active", "tenant": "acme"}],
             ),
-        ] = Field(default_factory=lambda: MappingProxyType({}))
+        ] = Field(default_factory=lambda: MappingProxyType(dict[str, t.Scalar]()))
         pagination: Annotated[
             _CqrsPagination,
             Field(
@@ -238,11 +238,11 @@
         ] = Field(default_factory=lambda: _u().generate_prefixed_id("evt"))
         data: Annotated[
             t.MappingKV[str, t.Scalar], Field(description="Event payload data")
-        ] = Field(default_factory=lambda: MappingProxyType({}))
+        ] = Field(default_factory=lambda: MappingProxyType(dict[str, t.Scalar]()))
         metadata: Annotated[
             t.MappingKV[str, t.Scalar],
             Field(description="Event metadata (timestamps, correlation IDs, etc.)"),
-        ] = Field(default_factory=lambda: MappingProxyType({}))
+        ] = Field(default_factory=lambda: MappingProxyType(dict[str, t.Scalar]()))
 
     type FlextMessage = t.MessageUnion[Command, Query, Event]
 

src/flext_core/_models/errors.py

@@ -28,7 +28,7 @@
         exception_counts: Annotated[
             t.IntMapping,
             mp.Field(description="Per-exception occurrence totals keyed by type name."),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(default_factory=lambda: MappingProxyType(dict[str, int]()))
         exception_counts_summary: Annotated[
             str,
             mp.Field(description="Human-readable summary for logs and diagnostics."),
@@ -61,7 +61,7 @@
         exception_counts: Annotated[
             t.IntMapping,
             mp.Field(description="Recorded counts keyed by exception type name."),
-        ] = mp.Field(default_factory=lambda: MappingProxyType({}))
+        ] = mp.Field(default_factory=lambda: MappingProxyType(dict[str, int]()))
 
         @up.computed_field
         @property

src/flext_core/_models/pydantic.py

@@ -18,7 +18,7 @@
 from pathlib import Path
 from re import Pattern
 from types import EllipsisType
-from typing import dataclass_transform
+from typing import Literal, dataclass_transform
 
 from pydantic import (
     AfterValidator,
@@ -36,7 +36,7 @@
     JsonValue,
     PlainSerializer,
     PlainValidator,
-    PrivateAttr,
+    PrivateAttr as PydanticPrivateAttr,
     RootModel as PydanticRootModel,
     SkipValidation,
     TypeAdapter as PydanticTypeAdapter,
@@ -82,6 +82,17 @@
     return field_factory(default, **kwargs)
 
 
+def _private_attr[PrivateT](
+    default: PrivateT | PydanticUndefinedType = PydanticUndefined,
+    *,
+    default_factory: Callable[..., PrivateT] | None = None,
+    init: Literal[False] = False,
+) -> PrivateT:
+    """Typed FLEXT facade for ``pydantic.PrivateAttr``."""
+    private_attr_factory: Callable[..., PrivateT] = PydanticPrivateAttr
+    return private_attr_factory(default, default_factory=default_factory, init=init)
+
+
 class FlextModelsPydantic:
     """Public base model classes from pydantic v2.
 
@@ -94,19 +105,22 @@
     """
 
     @dataclass_transform(
-        kw_only_default=True, field_specifiers=(_field, Field, PrivateAttr)
+        kw_only_default=True,
+        field_specifiers=(_field, Field, PydanticPrivateAttr, _private_attr),
     )
     class BaseModel(PydanticBaseModel):
         """Canonical BaseModel exported through the FLEXT models facade."""
 
     @dataclass_transform(
-        kw_only_default=True, field_specifiers=(_field, Field, PrivateAttr)
+        kw_only_default=True,
+        field_specifiers=(_field, Field, PydanticPrivateAttr, _private_attr),
     )
     class BaseSettings(PydanticBaseSettings):
         """Canonical BaseSettings exported through the FLEXT models facade."""
 
     @dataclass_transform(
-        kw_only_default=True, field_specifiers=(_field, Field, PrivateAttr)
+        kw_only_default=True,
+        field_specifiers=(_field, Field, PydanticPrivateAttr, _private_attr),
     )
     class RootModel[RootValueT](PydanticRootModel[RootValueT]):
         """Canonical RootModel exported through the FLEXT models facade."""
@@ -116,10 +130,7 @@
     SettingsConfigDict = _PydanticSettingsConfigDict
 
     Field = staticmethod(_field)
-    # NOTE (multi-agent): mro-ecfu — staticmethod wrap matches Field above and
-    # u.PrivateAttr (_utilities/pydantic.py): pyright cannot model an unwrapped
-    # function class attribute called through the facade (mixins.py:59 error).
-    PrivateAttr = staticmethod(PrivateAttr)
+    PrivateAttr = staticmethod(_private_attr)
     SkipValidation = SkipValidation
     # Same unwrapped-class-attribute problem as PrivateAttr above: pyright
     # binds the bare decorator through the facade and infers the facade type

src/flext_core/_runtime/__init__.py

@@ -6,7 +6,32 @@
 
 from __future__ import annotations
 
-from ._container import FlextRuntimeContainer
-from ._dependency import FlextRuntimeDependencyIntegration
+from types import MappingProxyType
+from typing import TYPE_CHECKING
 
-__all__: list[str] = ["FlextRuntimeContainer", "FlextRuntimeDependencyIntegration"]
+from flext_core.lazy import build_lazy_import_map, install_lazy_exports
+
+if TYPE_CHECKING:
+    from ._container import FlextRuntimeContainer
+    from ._dependency import FlextRuntimeDependencyIntegration
+
+__all__: tuple[str, ...] = (
+    "FlextRuntimeContainer",
+    "FlextRuntimeDependencyIntegration",
+)
+
+install_lazy_exports(
+    __name__,
+    globals(),
+    MappingProxyType(
+        build_lazy_import_map(
+            MappingProxyType({
+                "._container": ("FlextRuntimeContainer",),
+                "._dependency": ("FlextRuntimeDependencyIntegration",),
+            }),
+            alias_groups=MappingProxyType({}),
+            sort_keys=False,
+        )
+    ),
+    public_exports=__all__,
+)

src/flext_core/_utilities/_parser_targets_parts/parser_targets_part_01.py

@@ -49,25 +49,19 @@ def _parse_try_direct[T](
         if isinstance(value, target):
             return value
         target_name = target.__name__ if hasattr(target, "__name__") else "type"
-        parsed_direct: T = (
-            FlextUtilitiesModel
-            .validate_value(target, value)
-            .fold(
-                lambda error: FlextUtilitiesParserTargets._parse_with_default(
-                    default,
-                    default_factory,
-                    c.ERR_PARSER_CANNOT_PARSE_TO_TARGET.format(
-                        field_prefix=fp,
-                        source_type=value.__class__.__name__,
-                        target_name=target_name,
-                        error=error,
-                    ),
-                ),
-                lambda validated: validated,
-            )
-            .unwrap()
-        )
-        return parsed_direct
+        validation = FlextUtilitiesModel.validate_value(target, value)
+        if validation.success:
+            return validation.value
+        return FlextUtilitiesParserTargets._parse_with_default(
+            default,
+            default_factory,
+            c.ERR_PARSER_CANNOT_PARSE_TO_TARGET.format(
+                field_prefix=fp,
+                source_type=value.__class__.__name__,
+                target_name=target_name,
+                error=validation.error,
+            ),
+        ).unwrap()
 
     @staticmethod
     @r.safe

src/flext_core/_utilities/collection.py

@@ -17,10 +17,10 @@
     FlextConstants as c,
     FlextProtocols as p,
     FlextResult as r,
-    FlextRuntime,
     FlextTypes as t,
 )
 from flext_core._models.containers import FlextModelsContainers as mc
+from flext_core._runtime._metadata import FlextRuntimeMetadata
 
 from .collection_iter import FlextUtilitiesCollectionIter
 from .collection_merge import FlextUtilitiesCollectionMerge
@@ -44,7 +44,7 @@ def normalize_domain_event_data(
         for key, item in raw_source.items():
             if item is None:
                 continue
-            normalized[key] = FlextRuntime.normalize_to_metadata(item)
+            normalized[key] = FlextRuntimeMetadata.normalize_to_metadata(item)
         return normalized
 
     @staticmethod

src/flext_core/_utilities/collection_merge.py

@@ -10,13 +10,9 @@
 from collections.abc import Callable, Mapping
 from typing import ClassVar, TypeGuard
 
-from flext_core import (
-    FlextProtocols as p,
-    FlextResult as r,
-    FlextRuntime,
-    FlextTypes as t,
-)
+from flext_core import FlextProtocols as p, FlextResult as r, FlextTypes as t
 from flext_core._constants.cqrs import FlextConstantsCqrs as _c_cqrs
+from flext_core._runtime._metadata import FlextRuntimeMetadata
 from flext_core._utilities.guards_type_core import FlextUtilitiesGuardsTypeCore
 
 
@@ -40,7 +36,10 @@ def _merge_deep_single_key(
         if FlextUtilitiesCollectionMerge._is_json_mapping(
             current_val
         ) and FlextUtilitiesCollectionMerge._is_json_mapping(value):
-            result[key] = FlextRuntime.normalize_to_metadata({**current_val, **value})
+            result[key] = FlextRuntimeMetadata.normalize_to_metadata({
+                **current_val,
+                **value,
+            })
             return r[bool].ok(True)
         result[key] = value
         return r[bool].ok(True)
@@ -87,7 +86,10 @@ def _merge_append(
             if FlextUtilitiesCollectionMerge._is_json_list(
                 current_val
             ) and FlextUtilitiesCollectionMerge._is_json_list(value):
-                result[key] = FlextRuntime.normalize_to_metadata([*current_val, *value])
+                result[key] = FlextRuntimeMetadata.normalize_to_metadata([
+                    *current_val,
+                    *value,
+                ])
                 continue
             result[key] = value
         return r[t.JsonMapping].ok(result)