omnibase_infra 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

omnibase_infra/runtime/__init__.py

@@ -90,13 +90,22 @@ from omnibase_infra.runtime.service_kernel import load_runtime_config
 from omnibase_infra.runtime.service_kernel import main as kernel_main
 from omnibase_infra.runtime.service_message_dispatch_engine import MessageDispatchEngine
 from omnibase_infra.runtime.models import (
+    ModelProjectorNotificationConfig,
     ModelRuntimeSchedulerConfig,
     ModelRuntimeSchedulerMetrics,
     ModelRuntimeTick,
+    ModelStateTransitionNotification,
+    ModelTransitionNotificationPublisherMetrics,
 )
 from omnibase_infra.runtime.registry_policy import RegistryPolicy
 from omnibase_infra.runtime.protocol_policy import ProtocolPolicy
-from omnibase_infra.runtime.protocols import ProtocolRuntimeScheduler
+from omnibase_infra.runtime.protocols import (
+    ProtocolRuntimeScheduler,
+    ProtocolTransitionNotificationPublisher,
+)
+from omnibase_infra.runtime.mixins import (
+    ProtocolProjectorNotificationContext,
+)
 from omnibase_infra.runtime.registry import (
     MessageTypeRegistryError,
     ModelDomainConstraint,
@@ -145,6 +154,28 @@ from omnibase_infra.runtime.handler_plugin_loader import (
     MAX_CONTRACT_SIZE,
 )
 
+# Handler bootstrap source (OMN-1087)
+from omnibase_infra.runtime.handler_bootstrap_source import (
+    HandlerBootstrapSource,
+    SOURCE_TYPE_BOOTSTRAP,
+)
+
+# Handler identity helper (OMN-1095)
+from omnibase_infra.runtime.handler_identity import (
+    HANDLER_IDENTITY_PREFIX,
+    handler_identity,
+)
+
+# Handler source resolver (OMN-1095)
+from omnibase_infra.runtime.handler_source_resolver import HandlerSourceResolver
+
+# Handler contract config loader
+from omnibase_infra.runtime.handler_contract_config_loader import (
+    MAX_CONTRACT_SIZE_BYTES,
+    extract_handler_config,
+    load_handler_contract_config,
+)
+
 # Binding config resolver (OMN-765)
 from omnibase_infra.runtime.binding_config_resolver import BindingConfigResolver
 from omnibase_infra.runtime.protocol_handler_plugin_loader import (
@@ -181,6 +212,29 @@ from omnibase_infra.runtime.security_metadata_validator import (
     validate_handler_security,
 )
 
+# Transition notification publisher and outbox (OMN-1139)
+from omnibase_infra.runtime.constants_notification import FROM_STATE_INITIAL
+from omnibase_infra.runtime.transition_notification_publisher import (
+    TransitionNotificationPublisher,
+)
+from omnibase_infra.runtime.transition_notification_outbox import (
+    TransitionNotificationOutbox,
+)
+
+# Registry contract source (OMN-1100)
+from omnibase_infra.runtime.registry_contract_source import (
+    DEFAULT_CONSUL_HOST,
+    DEFAULT_CONSUL_PORT,
+    DEFAULT_CONTRACT_PREFIX,
+    RegistryContractSource,
+    adelete_contract_from_consul,
+    alist_contracts_in_consul,
+    astore_contract_in_consul,
+    delete_contract_from_consul,
+    list_contracts_in_consul,
+    store_contract_in_consul,
+)
+
 # Chain-aware dispatch (OMN-951) - must be imported LAST to avoid circular import
 from omnibase_infra.runtime.chain_aware_dispatch import (
     ChainAwareDispatcher,
@@ -214,9 +268,12 @@ __all__: list[str] = [
     "MessageTypeRegistryError",
     "ModelDomainConstraint",
     "ModelMessageTypeEntry",
+    "ModelProjectorNotificationConfig",
     "ModelRuntimeSchedulerConfig",
     "ModelRuntimeSchedulerMetrics",
     "ModelRuntimeTick",
+    "ModelStateTransitionNotification",
+    "ModelTransitionNotificationPublisherMetrics",
     "ProtocolMessageDispatcher",
     "ProtocolMessageTypeRegistry",
     # Registry classes
@@ -230,8 +287,14 @@ __all__: list[str] = [
     "RegistryDispatcher",
     # Runtime scheduler (OMN-953)
     "ProtocolRuntimeScheduler",
+    # Transition notification (OMN-1139)
+    "ProtocolTransitionNotificationPublisher",
+    # Projector notification context protocol (OMN-1139)
+    "ProtocolProjectorNotificationContext",
     # Error class
     "RegistryError",
+    # Notification constants (OMN-1139)
+    "FROM_STATE_INITIAL",
     # Runtime host
     "RuntimeHostProcess",
     "RuntimeScheduler",
@@ -277,6 +340,18 @@ __all__: list[str] = [
     "HandlerPluginLoader",
     "MAX_CONTRACT_SIZE",
     "ProtocolHandlerPluginLoader",
+    # Handler bootstrap source (OMN-1087)
+    "HandlerBootstrapSource",
+    "SOURCE_TYPE_BOOTSTRAP",
+    # Handler identity helper (OMN-1095)
+    "HANDLER_IDENTITY_PREFIX",
+    "handler_identity",
+    # Handler source resolver (OMN-1095)
+    "HandlerSourceResolver",
+    # Handler contract config loader
+    "MAX_CONTRACT_SIZE_BYTES",
+    "extract_handler_config",
+    "load_handler_contract_config",
     # Binding config resolver (OMN-765)
     "BindingConfigResolver",
     # Handler discovery protocol and implementation (OMN-1133)
@@ -293,4 +368,18 @@ __all__: list[str] = [
     # Security metadata validator (OMN-1137)
     "SecurityMetadataValidator",
     "validate_handler_security",
+    # Transition notification publisher and outbox (OMN-1139)
+    "TransitionNotificationOutbox",
+    "TransitionNotificationPublisher",
+    # Registry contract source (OMN-1100)
+    "DEFAULT_CONSUL_HOST",
+    "DEFAULT_CONSUL_PORT",
+    "DEFAULT_CONTRACT_PREFIX",
+    "RegistryContractSource",
+    "adelete_contract_from_consul",
+    "alist_contracts_in_consul",
+    "astore_contract_in_consul",
+    "delete_contract_from_consul",
+    "list_contracts_in_consul",
+    "store_contract_in_consul",
 ]

omnibase_infra/runtime/binding_config_resolver.py

@@ -56,10 +56,12 @@ Example:
         # Bootstrap container and register config
         container = ModelONEXContainer()
         config = ModelBindingConfigResolverConfig(env_prefix="HANDLER")
+        from omnibase_core.enums import EnumInjectionScope
+
         await container.service_registry.register_instance(
             interface=ModelBindingConfigResolverConfig,
             instance=config,
-            scope="global",
+            scope=EnumInjectionScope.GLOBAL,
         )
 
         # Create resolver with container injection
@@ -235,14 +237,15 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
 
     Example:
         >>> # Container setup (async context required)
+        >>> from omnibase_core.enums import EnumInjectionScope
         >>> container = ModelONEXContainer()
         >>> config = ModelBindingConfigResolverConfig(env_prefix="HANDLER")
         >>> await container.service_registry.register_instance(
         ...     interface=ModelBindingConfigResolverConfig,
         ...     instance=config,
-        ...     scope="global",
+        ...     scope=EnumInjectionScope.GLOBAL,
         ... )
-        >>> resolver = BindingConfigResolver(container)
+        >>> resolver = await BindingConfigResolver.create(container)
         >>> binding = resolver.resolve(
         ...     handler_type="db",
         ...     inline_config={"pool_size": 10}
@@ -252,6 +255,9 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
     def __init__(
         self,
         container: ModelONEXContainer,
+        *,
+        _config: ModelBindingConfigResolverConfig | None = None,
+        _secret_resolver: SecretResolver | None = None,
     ) -> None:
         """Initialize BindingConfigResolver with container-based dependency injection.
 
@@ -259,52 +265,37 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
         Config is resolved from container's service registry, and SecretResolver
         is resolved as an optional dependency.
 
+        Note:
+            Prefer using the async factory method ``create()`` for initialization,
+            which properly resolves dependencies from the container's service registry.
+            Direct ``__init__`` usage requires pre-resolved config and secret_resolver.
+
         Args:
             container: ONEX container for dependency resolution.
+            _config: Pre-resolved config (used by create() factory). If None, raises error.
+            _secret_resolver: Pre-resolved secret resolver (optional, used by create() factory).
 
         Raises:
-            ProtocolConfigurationError: If ModelBindingConfigResolverConfig is not registered
-                in the container's service registry.
+            ProtocolConfigurationError: If _config is not provided (use create() instead).
         """
         self._container = container
 
-        # Resolve config from container's service registry
-        try:
-            self._config: ModelBindingConfigResolverConfig = (
-                container.service_registry.resolve_service(
-                    ModelBindingConfigResolverConfig
-                )
-            )
-        except (LookupError, KeyError, TypeError, AttributeError) as e:
-            # LookupError/KeyError: service not registered
-            # TypeError: invalid interface specification
-            # AttributeError: container/registry missing expected methods
+        # Validate that config was provided (either via create() or directly)
+        if _config is None:
             context = ModelInfraErrorContext.with_correlation(
                 transport_type=EnumInfraTransportType.RUNTIME,
                 operation="init",
                 target_name="binding_config_resolver",
             )
             raise ProtocolConfigurationError(
-                "Failed to resolve ModelBindingConfigResolverConfig from container. "
-                "Ensure config is registered via container.service_registry.register_instance().",
+                "BindingConfigResolver requires config to be provided. "
+                "Use the async factory method BindingConfigResolver.create(container) "
+                "for proper initialization with dependency resolution.",
                 context=context,
-            ) from e
-
-        # Resolve SecretResolver from container (optional dependency)
-        # This replaces the config.secret_resolver pattern
-        self._secret_resolver: SecretResolver | None = None
-        try:
-            from omnibase_infra.runtime.secret_resolver import SecretResolver
-
-            self._secret_resolver = container.service_registry.resolve_service(
-                SecretResolver
             )
-        except (ImportError, KeyError, AttributeError):
-            # SecretResolver is optional - if not registered, vault: schemes won't work
-            # ImportError: SecretResolver module not available
-            # KeyError: SecretResolver not registered in service registry
-            # AttributeError: service_registry missing resolve_service method (test mocks)
-            pass
+
+        self._config: ModelBindingConfigResolverConfig = _config
+        self._secret_resolver: SecretResolver | None = _secret_resolver
 
         # Use OrderedDict for LRU eviction support - entries are moved to end on access
         self._cache: OrderedDict[str, ModelConfigCacheEntry] = OrderedDict()
@@ -357,6 +348,80 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
         self._async_key_locks: dict[str, asyncio.Lock] = {}
         self._async_key_lock_timestamps: dict[str, float] = {}
 
+    @classmethod
+    async def create(
+        cls,
+        container: ModelONEXContainer,
+    ) -> BindingConfigResolver:
+        """Async factory method for creating BindingConfigResolver with proper DI.
+
+        This is the preferred method for creating BindingConfigResolver instances.
+        It properly resolves dependencies from the container's async service registry.
+
+        Args:
+            container: ONEX container for dependency resolution.
+
+        Returns:
+            Fully initialized BindingConfigResolver instance.
+
+        Raises:
+            ProtocolConfigurationError: If ModelBindingConfigResolverConfig is not registered
+                in the container's service registry.
+
+        Example:
+            >>> from omnibase_core.enums import EnumInjectionScope
+            >>> container = ModelONEXContainer()
+            >>> config = ModelBindingConfigResolverConfig(env_prefix="HANDLER")
+            >>> await container.service_registry.register_instance(
+            ...     interface=ModelBindingConfigResolverConfig,
+            ...     instance=config,
+            ...     scope=EnumInjectionScope.GLOBAL,
+            ... )
+            >>> resolver = await BindingConfigResolver.create(container)
+        """
+        # Resolve config from container's service registry
+        try:
+            config: ModelBindingConfigResolverConfig = (
+                await container.service_registry.resolve_service(
+                    ModelBindingConfigResolverConfig
+                )
+            )
+        except (LookupError, KeyError, TypeError, AttributeError) as e:
+            # LookupError/KeyError: service not registered
+            # TypeError: invalid interface specification
+            # AttributeError: container/registry missing expected methods
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="create",
+                target_name="binding_config_resolver",
+            )
+            raise ProtocolConfigurationError(
+                "Failed to resolve ModelBindingConfigResolverConfig from container. "
+                "Ensure config is registered via container.service_registry.register_instance().",
+                context=context,
+            ) from e
+
+        # Resolve SecretResolver from container (optional dependency)
+        secret_resolver: SecretResolver | None = None
+        try:
+            from omnibase_infra.runtime.secret_resolver import SecretResolver
+
+            secret_resolver = await container.service_registry.resolve_service(
+                SecretResolver
+            )
+        except (ImportError, KeyError, AttributeError):
+            # SecretResolver is optional - if not registered, vault: schemes won't work
+            # ImportError: SecretResolver module not available
+            # KeyError: SecretResolver not registered in service registry
+            # AttributeError: service_registry missing resolve_service method (test mocks)
+            pass
+
+        return cls(
+            container,
+            _config=config,
+            _secret_resolver=secret_resolver,
+        )
+
     # === Primary API (Sync) ===
 
     def resolve(
@@ -533,7 +598,7 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
             result = await self._resolve_config_async(
                 handler_type=handler_type,
                 config_ref=config_ref,
-                inline_config=inline_config,
+                inline_config=inline_config,  # type: ignore[arg-type]
                 correlation_id=correlation_id,
             )
 
@@ -917,7 +982,7 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
     def _describe_source(
         self,
         config_ref: str | None,
-        inline_config: dict[str, object] | None,
+        inline_config: dict[str, JsonType] | None,
     ) -> str:
         """Create a description of the configuration source for debugging.
 
@@ -945,7 +1010,7 @@ class BindingConfigResolver:  # ONEX_EXCLUDE: method_count - follows SecretResol
         self,
         handler_type: str,
         config_ref: str | None,
-        inline_config: dict[str, object] | None,
+        inline_config: dict[str, JsonType] | None,
         correlation_id: UUID,
     ) -> ModelBindingConfig:
         """Resolve configuration from sources synchronously.

omnibase_infra/runtime/constants_notification.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Notification Constants Module.
+
+Provides constants for notification publishing, particularly for state
+transition notifications used by projectors and orchestrators.
+
+Sentinel Values
+---------------
+- **FROM_STATE_INITIAL**: Sentinel value used when publishing a state transition
+  notification for a NEW entity (one that didn't exist before the projection).
+  This is used instead of an empty string to provide clear semantic meaning.
+
+Usage:
+    >>> from omnibase_infra.runtime.constants_notification import FROM_STATE_INITIAL
+    >>>
+    >>> # In notification publishing code:
+    >>> effective_from_state = from_state if from_state is not None else FROM_STATE_INITIAL
+    >>>
+    >>> # In notification consumers:
+    >>> if notification.from_state == FROM_STATE_INITIAL:
+    ...     # This is a new entity, not a state transition from existing state
+    ...     handle_new_entity(notification)
+
+Why Not Empty String?
+    Using an empty string ("") for new entities is semantically ambiguous:
+    - An empty string could be confused with an actual empty state value
+    - It doesn't clearly communicate "this entity was just created"
+    - Consumers cannot distinguish between "no previous state" and "empty state"
+
+    The "__INITIAL__" sentinel provides:
+    - Clear semantic meaning (obviously not a real FSM state name)
+    - Easy detection in consumer code
+    - Explicit intent communication
+
+Related:
+    - ModelStateTransitionNotification: The notification model that uses this value
+    - MixinProjectorNotificationPublishing: The mixin that sets this value
+    - TransitionNotificationPublisher: The publisher that emits these notifications
+
+Related Tickets:
+    - OMN-1139: Integrate TransitionNotificationPublisher with ProjectorShell
+
+.. versionadded:: 0.8.0
+    Created as part of OMN-1139 notification integration.
+"""
+
+from typing import Final
+
+# Sentinel value for from_state when publishing notifications for NEW entities.
+# This indicates the entity was just created and has no previous state.
+# Consumers can check: if notification.from_state == FROM_STATE_INITIAL
+FROM_STATE_INITIAL: Final[str] = "__INITIAL__"
+"""Sentinel value indicating a new entity with no previous state.
+
+This value is used as the ``from_state`` field in ModelStateTransitionNotification
+when publishing a notification for a newly created entity. It replaces the
+semantically ambiguous empty string ("") with a clear, distinguishable marker.
+
+Example:
+    >>> notification = ModelStateTransitionNotification(
+    ...     aggregate_type="registration",
+    ...     aggregate_id=uuid4(),
+    ...     from_state=FROM_STATE_INITIAL,  # New entity
+    ...     to_state="pending",
+    ...     # ... other fields
+    ... )
+
+Note:
+    The double underscore prefix/suffix convention (``__INITIAL__``) follows
+    Python's pattern for special/dunder values, making it obviously not a
+    real FSM state name that would be used in domain logic.
+"""
+
+__all__: list[str] = ["FROM_STATE_INITIAL"]

omnibase_infra/runtime/contract_handler_discovery.py

@@ -437,7 +437,12 @@ class ContractHandlerDiscovery:
                 if hasattr(e, "model") and hasattr(e.model, "context"):
                     context_dict = e.model.context
                     if isinstance(context_dict, dict):
-                        error_code = context_dict.get("loader_error", error_code)
+                        loader_error = context_dict.get("loader_error")
+                        error_code = (
+                            str(loader_error)
+                            if loader_error is not None
+                            else error_code
+                        )
 
                 errors.append(
                     ModelDiscoveryError(