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

omnibase_infra/runtime/handler_contract_source.py

@@ -37,6 +37,7 @@ from pydantic import ValidationError
 
 from omnibase_core.models.contracts.model_handler_contract import ModelHandlerContract
 from omnibase_core.models.errors.model_onex_error import ModelOnexError
+from omnibase_core.models.primitives import ModelSemVer
 from omnibase_infra.enums import EnumHandlerErrorType, EnumHandlerSourceType
 from omnibase_infra.models.errors import ModelHandlerValidationError
 from omnibase_infra.models.handlers import (
@@ -46,11 +47,42 @@ from omnibase_infra.models.handlers import (
 )
 from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
+# =============================================================================
+# Module-Level Model Rebuild Pattern (Immediate Execution)
+# =============================================================================
+#
+# This module uses a simple MODULE-LEVEL model_rebuild() call. This differs from
+# HandlerBootstrapSource which uses a deferred, thread-safe pattern.
+#
+# WHY IMMEDIATE (module-load) IS SAFE HERE:
+#   - HandlerContractSource is NOT imported through runtime.__init__.py
+#   - This module is imported explicitly by user code AFTER the runtime is
+#     initialized and all model dependencies are resolved
+#   - Python's import mechanism is inherently thread-safe for module-level code:
+#     the import lock ensures module initialization runs exactly once, even if
+#     multiple threads import the same module simultaneously
+#   - Therefore, no explicit thread-safety mechanism (locks) is needed
+#
+# WHY HANDLERBOOTSTRAPSOURCE NEEDS DEFERRED PATTERN:
+#   - HandlerBootstrapSource is imported during runtime bootstrap (via __init__.py)
+#   - At that point, ModelHandlerValidationError may not be fully resolved
+#   - Additionally, discover_handlers() may be called from multiple threads,
+#     requiring explicit synchronization for the rebuild call
+#
+# PATTERN COMPARISON:
+#   - HandlerContractSource: Immediate + module-level (this file)
+#   - HandlerBootstrapSource: Deferred + thread-safe (see that file for rationale)
+#
+# See Also:
+#   - handler_bootstrap_source.py lines 68-100 for the deferred pattern rationale
+#   - OMN-1087 for the ticket tracking this design decision
+# =============================================================================
+#
 # Rebuild ModelContractDiscoveryResult to resolve the forward reference
 # to ModelHandlerValidationError. This must happen after ModelHandlerValidationError
 # is imported to make the type available for Pydantic validation.
 #
-# Why this pattern is used:
+# Why forward reference resolution is needed:
 #   ModelContractDiscoveryResult has a field typed as list[ModelHandlerValidationError].
 #   ModelHandlerValidationError imports ModelHandlerIdentifier from models.handlers.
 #   If ModelContractDiscoveryResult directly imported ModelHandlerValidationError,
@@ -72,10 +104,212 @@ logger = logging.getLogger(__name__)
 # File pattern for handler contracts
 HANDLER_CONTRACT_FILENAME = "handler_contract.yaml"
 
+
 # Maximum contract file size (10MB) to prevent memory exhaustion
 MAX_CONTRACT_SIZE = 10 * 1024 * 1024
 
 
+# =============================================================================
+# Module-Level Helper Functions
+# =============================================================================
+#
+# These functions are extracted from HandlerContractSource to reduce method count
+# while maintaining the same functionality. They are pure functions that operate
+# on their inputs without requiring instance state.
+# =============================================================================
+
+
+def _sanitize_path_for_logging(path: Path) -> str:
+    """Sanitize a file path for safe inclusion in logs and error messages.
+
+    In production environments, full paths may leak sensitive information
+    about directory structure. This function returns only the filename and
+    parent directory to provide context without exposing full paths.
+
+    Args:
+        path: The full path to sanitize.
+
+    Returns:
+        Sanitized path string showing only parent/filename.
+        For example: "/home/user/code/handlers/handler_contract.yaml"
+        becomes "handlers/handler_contract.yaml".
+    """
+    # Return parent directory name + filename for context
+    # This provides enough info for debugging without full path exposure
+    try:
+        return str(Path(path.parent.name) / path.name)
+    except (ValueError, AttributeError):
+        # Fallback to just filename if parent extraction fails
+        return path.name
+
+
+def _create_parse_error(
+    contract_path: Path,
+    error: yaml.YAMLError,
+) -> ModelHandlerValidationError:
+    """Create a validation error for YAML parse failures.
+
+    Args:
+        contract_path: Path to the failing contract file.
+        error: The YAML parsing error.
+
+    Returns:
+        ModelHandlerValidationError with parse error details.
+    """
+    handler_identity = ModelHandlerIdentifier.from_handler_id(
+        f"unknown@{contract_path.name}"
+    )
+
+    return ModelHandlerValidationError(
+        error_type=EnumHandlerErrorType.CONTRACT_PARSE_ERROR,
+        rule_id="CONTRACT-001",
+        handler_identity=handler_identity,
+        source_type=EnumHandlerSourceType.CONTRACT,
+        message=f"Failed to parse YAML in {_sanitize_path_for_logging(contract_path)}: {error}",
+        remediation_hint="Check YAML syntax and ensure proper indentation",
+        file_path=str(contract_path),
+    )
+
+
+def _create_validation_error(
+    contract_path: Path,
+    error: ValidationError,
+) -> ModelHandlerValidationError:
+    """Create a validation error for contract validation failures.
+
+    Args:
+        contract_path: Path to the failing contract file.
+        error: The Pydantic validation error.
+
+    Returns:
+        ModelHandlerValidationError with validation details.
+    """
+    handler_identity = ModelHandlerIdentifier.from_handler_id(
+        f"unknown@{contract_path.name}"
+    )
+
+    # Extract first error detail for remediation hint
+    error_details = error.errors()
+    if error_details:
+        first_error = error_details[0]
+        field_loc = " -> ".join(str(x) for x in first_error.get("loc", ()))
+        error_msg = str(first_error.get("msg", "validation failed"))
+    else:
+        field_loc = "unknown"
+        error_msg = "validation failed"
+
+    return ModelHandlerValidationError(
+        error_type=EnumHandlerErrorType.CONTRACT_VALIDATION_ERROR,
+        rule_id="CONTRACT-002",
+        handler_identity=handler_identity,
+        source_type=EnumHandlerSourceType.CONTRACT,
+        message=f"Contract validation failed in {_sanitize_path_for_logging(contract_path)}: {error_msg} at {field_loc}",
+        remediation_hint=f"Check the '{field_loc}' field in the contract",
+        file_path=str(contract_path),
+    )
+
+
+def _create_size_limit_error(
+    contract_path: Path,
+    file_size: int,
+) -> ModelHandlerValidationError:
+    """Create a validation error for file size limit violations.
+
+    Args:
+        contract_path: Path to the oversized contract file.
+        file_size: The actual file size in bytes.
+
+    Returns:
+        ModelHandlerValidationError with size limit details.
+    """
+    handler_identity = ModelHandlerIdentifier.from_handler_id(
+        f"unknown@{contract_path.name}"
+    )
+
+    return ModelHandlerValidationError(
+        error_type=EnumHandlerErrorType.CONTRACT_VALIDATION_ERROR,
+        rule_id="CONTRACT-003",
+        handler_identity=handler_identity,
+        source_type=EnumHandlerSourceType.CONTRACT,
+        message=(
+            f"Contract file {_sanitize_path_for_logging(contract_path)} exceeds size limit: "
+            f"{file_size} bytes (max: {MAX_CONTRACT_SIZE} bytes)"
+        ),
+        remediation_hint=(
+            f"Reduce contract file size to under {MAX_CONTRACT_SIZE // (1024 * 1024)}MB. "
+            "Consider splitting into multiple contracts if needed."
+        ),
+        file_path=str(contract_path),
+    )
+
+
+def _create_io_error(
+    contract_path: Path,
+    error: OSError,
+) -> ModelHandlerValidationError:
+    """Create a validation error for I/O failures.
+
+    Args:
+        contract_path: Path to the contract file that failed to read.
+        error: The I/O error encountered.
+
+    Returns:
+        ModelHandlerValidationError with I/O error details.
+    """
+    handler_identity = ModelHandlerIdentifier.from_handler_id(
+        f"unknown@{contract_path.name}"
+    )
+
+    # OSError.strerror may be None for some error types (e.g., custom subclasses),
+    # so use str(error) as a fallback to ensure we always have an error message
+    error_message = error.strerror or str(error)
+
+    return ModelHandlerValidationError(
+        error_type=EnumHandlerErrorType.CONTRACT_PARSE_ERROR,
+        rule_id="CONTRACT-004",
+        handler_identity=handler_identity,
+        source_type=EnumHandlerSourceType.CONTRACT,
+        message=f"Failed to read contract file: {error_message}",
+        remediation_hint="Check file permissions and ensure the file exists",
+        file_path=str(contract_path),
+    )
+
+
+def _create_version_parse_error(
+    contract_path: Path,
+    error_message: str,
+) -> ModelHandlerValidationError:
+    """Create a validation error for version string parse failures.
+
+    Args:
+        contract_path: Path to the contract file with invalid version.
+        error_message: The error message describing the version parse failure.
+
+    Returns:
+        ModelHandlerValidationError with version parse error details.
+    """
+    handler_identity = ModelHandlerIdentifier.from_handler_id(
+        f"unknown@{contract_path.name}"
+    )
+
+    return ModelHandlerValidationError(
+        error_type=EnumHandlerErrorType.CONTRACT_VALIDATION_ERROR,
+        rule_id="CONTRACT-005",
+        handler_identity=handler_identity,
+        source_type=EnumHandlerSourceType.CONTRACT,
+        message=(
+            f"Invalid version string in contract "
+            f"{_sanitize_path_for_logging(contract_path)}: {error_message}"
+        ),
+        remediation_hint=(
+            "Ensure the 'version' field uses semantic versioning format "
+            "(e.g., '1.0.0', '2.1.3-beta.1'). "
+            "Version components must be non-negative integers."
+        ),
+        file_path=str(contract_path),
+    )
+
+
 # =============================================================================
 # HandlerContractSource Implementation
 # =============================================================================
@@ -165,29 +399,6 @@ class HandlerContractSource(ProtocolContractSource):
         """
         return "CONTRACT"
 
-    def _sanitize_path_for_logging(self, path: Path) -> str:
-        """Sanitize a file path for safe inclusion in logs and error messages.
-
-        In production environments, full paths may leak sensitive information
-        about directory structure. This method returns only the filename and
-        parent directory to provide context without exposing full paths.
-
-        Args:
-            path: The full path to sanitize.
-
-        Returns:
-            Sanitized path string showing only parent/filename.
-            For example: "/home/user/code/handlers/handler_contract.yaml"
-            becomes "handlers/handler_contract.yaml".
-        """
-        # Return parent directory name + filename for context
-        # This provides enough info for debugging without full path exposure
-        try:
-            return str(Path(path.parent.name) / path.name)
-        except (ValueError, AttributeError):
-            # Fallback to just filename if parent extraction fails
-            return path.name
-
     async def discover_handlers(
         self,
     ) -> ModelContractDiscoveryResult:
@@ -307,7 +518,7 @@ class HandlerContractSource(ProtocolContractSource):
                         },
                     )
                 except yaml.YAMLError as e:
-                    error = self._create_parse_error(contract_file, e)
+                    error = _create_parse_error(contract_file, e)
                     if not self._graceful_mode:
                         raise ModelOnexError(
                             f"Failed to parse YAML contract at {contract_file}: {e}",
@@ -315,7 +526,7 @@ class HandlerContractSource(ProtocolContractSource):
                         ) from e
                     logger.warning(
                         "Failed to parse YAML contract in %s, continuing in graceful mode",
-                        self._sanitize_path_for_logging(contract_file),
+                        _sanitize_path_for_logging(contract_file),
                         extra={
                             "contract_file": str(contract_file),
                             "error_type": "yaml_parse_error",
@@ -325,7 +536,7 @@ class HandlerContractSource(ProtocolContractSource):
                     )
                     validation_errors.append(error)
                 except ValidationError as e:
-                    error = self._create_validation_error(contract_file, e)
+                    error = _create_validation_error(contract_file, e)
                     if not self._graceful_mode:
                         raise ModelOnexError(
                             f"Contract validation failed at {contract_file}: {e}",
@@ -333,7 +544,7 @@ class HandlerContractSource(ProtocolContractSource):
                         ) from e
                     logger.warning(
                         "Contract validation failed in %s, continuing in graceful mode",
-                        self._sanitize_path_for_logging(contract_file),
+                        _sanitize_path_for_logging(contract_file),
                         extra={
                             "contract_file": str(contract_file),
                             "error_type": "validation_error",
@@ -348,7 +559,9 @@ class HandlerContractSource(ProtocolContractSource):
                     if not self._graceful_mode:
                         raise
 
-                    # Only handle file size limit errors (HANDLER_SOURCE_005) gracefully
+                    # Handle specific error codes gracefully:
+                    # - HANDLER_SOURCE_005: File size limit exceeded
+                    # - HANDLER_SOURCE_007: Invalid version string
                     # Other ModelOnexError types should be re-raised as they may indicate
                     # more serious issues (e.g., configuration errors, programming errors)
                     # Defensive check: error_code should always exist on ModelOnexError,
@@ -362,13 +575,13 @@ class HandlerContractSource(ProtocolContractSource):
                             file_size = contract_file.stat().st_size
                         except OSError:
                             file_size = 0  # File may have been deleted/changed
-                        error = self._create_size_limit_error(
+                        error = _create_size_limit_error(
                             contract_file,
                             file_size,
                         )
                         logger.warning(
                             "Contract file %s exceeds size limit, continuing in graceful mode",
-                            self._sanitize_path_for_logging(contract_file),
+                            _sanitize_path_for_logging(contract_file),
                             extra={
                                 "contract_file": str(contract_file),
                                 "error_type": "size_limit_error",
@@ -378,6 +591,26 @@ class HandlerContractSource(ProtocolContractSource):
                             },
                         )
                         validation_errors.append(error)
+                    elif error_code == "HANDLER_SOURCE_007":
+                        # Invalid version string - extract version from error message
+                        error = _create_version_parse_error(
+                            contract_file,
+                            str(e),
+                        )
+                        logger.warning(
+                            "Contract file %s has invalid version string, "
+                            "continuing in graceful mode",
+                            _sanitize_path_for_logging(contract_file),
+                            extra={
+                                "contract_file": str(contract_file),
+                                "error_type": "version_parse_error",
+                                "error_code": error_code,
+                                "error_message": str(e),
+                                "graceful_mode": self._graceful_mode,
+                                "paths_scanned": len(self._contract_paths),
+                            },
+                        )
+                        validation_errors.append(error)
                     else:
                         # Re-raise unexpected ModelOnexError types even in graceful mode
                         # These may indicate configuration or programming errors
@@ -389,10 +622,10 @@ class HandlerContractSource(ProtocolContractSource):
                             f"Failed to read contract file at {contract_file}: {e}",
                             error_code="HANDLER_SOURCE_006",
                         ) from e
-                    error = self._create_io_error(contract_file, e)
+                    error = _create_io_error(contract_file, e)
                     logger.warning(
                         "Failed to read contract file, continuing in graceful mode: %s",
-                        self._sanitize_path_for_logging(contract_file),
+                        _sanitize_path_for_logging(contract_file),
                         extra={
                             "contract_file": str(contract_file),
                             "error_type": "io_error",
@@ -446,7 +679,8 @@ class HandlerContractSource(ProtocolContractSource):
             ModelHandlerDescriptor created from the contract.
 
         Raises:
-            ModelOnexError: If contract file exceeds MAX_CONTRACT_SIZE (10MB).
+            ModelOnexError: If contract file exceeds MAX_CONTRACT_SIZE (10MB),
+                or if the version string in the contract is invalid.
             yaml.YAMLError: If YAML parsing fails.
             ValidationError: If contract validation fails.
         """
@@ -477,150 +711,38 @@ class HandlerContractSource(ProtocolContractSource):
         # Validate against ModelHandlerContract
         contract = ModelHandlerContract.model_validate(raw_data)
 
+        # TODO [OMN-1420]: Extract handler_class from ModelHandlerContract
+        #
+        # handler_contract.yaml files include a `handler_class` field for dynamic import
+        # (e.g., "omnibase_infra.handlers.handler_consul.HandlerConsul"), but
+        # ModelHandlerContract from omnibase_core does not have this field yet.
+        #
+        # Once ModelHandlerContract is updated to include handler_class, this code
+        # should be changed from:
+        #     handler_class=raw_data.get("handler_class")
+        # to:
+        #     handler_class=contract.handler_class
+        #
+        # For now, extract directly from raw YAML data to support dynamic handler loading.
+        # See: https://linear.app/omninode/issue/OMN-1420
+        handler_class = (
+            raw_data.get("handler_class") if isinstance(raw_data, dict) else None
+        )
+
+        # Use contract_version directly - it's already a ModelSemVer from Pydantic validation
         # Transform to descriptor
         return ModelHandlerDescriptor(
             handler_id=contract.handler_id,
             name=contract.name,
-            version=contract.version,
+            version=contract.contract_version,
             handler_kind=contract.descriptor.handler_kind,
             input_model=contract.input_model,
             output_model=contract.output_model,
             description=contract.description,
+            handler_class=handler_class,
             contract_path=str(contract_path),
         )
 
-    def _create_parse_error(
-        self,
-        contract_path: Path,
-        error: yaml.YAMLError,
-    ) -> ModelHandlerValidationError:
-        """Create a validation error for YAML parse failures.
-
-        Args:
-            contract_path: Path to the failing contract file.
-            error: The YAML parsing error.
-
-        Returns:
-            ModelHandlerValidationError with parse error details.
-        """
-        handler_identity = ModelHandlerIdentifier.from_handler_id(
-            f"unknown@{contract_path.name}"
-        )
-
-        return ModelHandlerValidationError(
-            error_type=EnumHandlerErrorType.CONTRACT_PARSE_ERROR,
-            rule_id="CONTRACT-001",
-            handler_identity=handler_identity,
-            source_type=EnumHandlerSourceType.CONTRACT,
-            message=f"Failed to parse YAML in {self._sanitize_path_for_logging(contract_path)}: {error}",
-            remediation_hint="Check YAML syntax and ensure proper indentation",
-            file_path=str(contract_path),
-        )
-
-    def _create_validation_error(
-        self,
-        contract_path: Path,
-        error: ValidationError,
-    ) -> ModelHandlerValidationError:
-        """Create a validation error for contract validation failures.
-
-        Args:
-            contract_path: Path to the failing contract file.
-            error: The Pydantic validation error.
-
-        Returns:
-            ModelHandlerValidationError with validation details.
-        """
-        handler_identity = ModelHandlerIdentifier.from_handler_id(
-            f"unknown@{contract_path.name}"
-        )
-
-        # Extract first error detail for remediation hint
-        error_details = error.errors()
-        if error_details:
-            first_error = error_details[0]
-            field_loc = " -> ".join(str(x) for x in first_error.get("loc", ()))
-            error_msg = str(first_error.get("msg", "validation failed"))
-        else:
-            field_loc = "unknown"
-            error_msg = "validation failed"
-
-        return ModelHandlerValidationError(
-            error_type=EnumHandlerErrorType.CONTRACT_VALIDATION_ERROR,
-            rule_id="CONTRACT-002",
-            handler_identity=handler_identity,
-            source_type=EnumHandlerSourceType.CONTRACT,
-            message=f"Contract validation failed in {self._sanitize_path_for_logging(contract_path)}: {error_msg} at {field_loc}",
-            remediation_hint=f"Check the '{field_loc}' field in the contract",
-            file_path=str(contract_path),
-        )
-
-    def _create_size_limit_error(
-        self,
-        contract_path: Path,
-        file_size: int,
-    ) -> ModelHandlerValidationError:
-        """Create a validation error for file size limit violations.
-
-        Args:
-            contract_path: Path to the oversized contract file.
-            file_size: The actual file size in bytes.
-
-        Returns:
-            ModelHandlerValidationError with size limit details.
-        """
-        handler_identity = ModelHandlerIdentifier.from_handler_id(
-            f"unknown@{contract_path.name}"
-        )
-
-        return ModelHandlerValidationError(
-            error_type=EnumHandlerErrorType.CONTRACT_VALIDATION_ERROR,
-            rule_id="CONTRACT-003",
-            handler_identity=handler_identity,
-            source_type=EnumHandlerSourceType.CONTRACT,
-            message=(
-                f"Contract file {self._sanitize_path_for_logging(contract_path)} exceeds size limit: "
-                f"{file_size} bytes (max: {MAX_CONTRACT_SIZE} bytes)"
-            ),
-            remediation_hint=(
-                f"Reduce contract file size to under {MAX_CONTRACT_SIZE // (1024 * 1024)}MB. "
-                "Consider splitting into multiple contracts if needed."
-            ),
-            file_path=str(contract_path),
-        )
-
-    def _create_io_error(
-        self,
-        contract_path: Path,
-        error: OSError,
-    ) -> ModelHandlerValidationError:
-        """Create a validation error for I/O failures.
-
-        Args:
-            contract_path: Path to the contract file that failed to read.
-            error: The I/O error encountered.
-
-        Returns:
-            ModelHandlerValidationError with I/O error details.
-        """
-        handler_identity = ModelHandlerIdentifier.from_handler_id(
-            f"unknown@{contract_path.name}"
-        )
-
-        # OSError.strerror may be None for some error types (e.g., custom subclasses),
-        # so use str(error) as a fallback to ensure we always have an error message
-        error_message = error.strerror or str(error)
-
-        return ModelHandlerValidationError(
-            error_type=EnumHandlerErrorType.CONTRACT_PARSE_ERROR,
-            rule_id="CONTRACT-004",
-            handler_identity=handler_identity,
-            source_type=EnumHandlerSourceType.CONTRACT,
-            message=f"Failed to read contract file: {error_message}",
-            remediation_hint="Check file permissions and ensure the file exists",
-            file_path=str(contract_path),
-        )
-
     def _log_discovery_results(
         self,
         discovered_count: int,

omnibase_infra/runtime/handler_plugin_loader.py

@@ -820,7 +820,8 @@ class HandlerPluginLoader(ProtocolHandlerPluginLoader):
                 # Extract error code if available
                 error_code: str | None = None
                 if hasattr(e, "model") and hasattr(e.model, "context"):
-                    error_code = e.model.context.get("loader_error")
+                    loader_error = e.model.context.get("loader_error")
+                    error_code = str(loader_error) if loader_error is not None else None
 
                 failed_handlers.append(
                     ModelFailedPluginLoad(
@@ -1126,7 +1127,8 @@ class HandlerPluginLoader(ProtocolHandlerPluginLoader):
                 # Extract error code if available
                 error_code: str | None = None
                 if hasattr(e, "model") and hasattr(e.model, "context"):
-                    error_code = e.model.context.get("loader_error")
+                    loader_error = e.model.context.get("loader_error")
+                    error_code = str(loader_error) if loader_error is not None else None
 
                 failed_handlers.append(
                     ModelFailedPluginLoad(

omnibase_infra/runtime/mixin_semver_cache.py

@@ -23,7 +23,11 @@ from collections.abc import Callable
 
 from omnibase_core.models.errors import ModelOnexError
 from omnibase_core.models.primitives import ModelSemVer
+from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ProtocolConfigurationError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
 from omnibase_infra.runtime.util_version import normalize_version
 
 
@@ -98,10 +102,15 @@ class MixinSemverCache:
         """
         with cls._semver_cache_lock:
             if cls._semver_cache is not None:
+                context = ModelInfraErrorContext.with_correlation(
+                    transport_type=EnumInfraTransportType.RUNTIME,
+                    operation="configure_semver_cache",
+                )
                 raise ProtocolConfigurationError(
                     "Cannot reconfigure semver cache after first use. "
                     "Set SEMVER_CACHE_SIZE before creating any "
-                    "registry instances, or use _reset_semver_cache() for testing."
+                    "registry instances, or use _reset_semver_cache() for testing.",
+                    context=context,
                 )
             cls.SEMVER_CACHE_SIZE = maxsize
 
@@ -219,14 +228,24 @@ class MixinSemverCache:
                 try:
                     return ModelSemVer.parse(normalized_version)
                 except ModelOnexError as e:
+                    context = ModelInfraErrorContext.with_correlation(
+                        transport_type=EnumInfraTransportType.RUNTIME,
+                        operation="parse_semver",
+                    )
                     raise ProtocolConfigurationError(
                         str(e),
                         version=normalized_version,
+                        context=context,
                     ) from e
                 except ValueError as e:
+                    context = ModelInfraErrorContext.with_correlation(
+                        transport_type=EnumInfraTransportType.RUNTIME,
+                        operation="parse_semver",
+                    )
                     raise ProtocolConfigurationError(
                         str(e),
                         version=normalized_version,
+                        context=context,
                     ) from e
 
             def _parse_semver_impl(version: str) -> ModelSemVer:
@@ -248,9 +267,14 @@ class MixinSemverCache:
                 try:
                     normalized = normalize_version(version)
                 except ValueError as e:
+                    context = ModelInfraErrorContext.with_correlation(
+                        transport_type=EnumInfraTransportType.RUNTIME,
+                        operation="normalize_version",
+                    )
                     raise ProtocolConfigurationError(
                         str(e),
                         version=version,
+                        context=context,
                     ) from e
 
                 # Now call the cached function with the NORMALIZED version

omnibase_infra/runtime/mixins/__init__.py

@@ -6,12 +6,19 @@ This module provides mixins for runtime components such as projectors.
 
 Exports:
     - MixinProjectorSqlOperations: SQL execution methods for projector implementations
+    - MixinProjectorNotificationPublishing: Notification publishing for projector implementations
 """
 
+from omnibase_infra.runtime.mixins.mixin_projector_notification_publishing import (
+    MixinProjectorNotificationPublishing,
+    ProtocolProjectorNotificationContext,
+)
 from omnibase_infra.runtime.mixins.mixin_projector_sql_operations import (
     MixinProjectorSqlOperations,
 )
 
 __all__: list[str] = [
+    "MixinProjectorNotificationPublishing",
     "MixinProjectorSqlOperations",
+    "ProtocolProjectorNotificationContext",
 ]