omnibase_infra 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

omnibase_infra/runtime/models/__init__.py

@@ -56,6 +56,7 @@ Exports:
     ModelBindingConfigCacheStats: Cache statistics for BindingConfigResolver
     ModelBindingConfigResolverConfig: Configuration for BindingConfigResolver
     ModelConfigCacheEntry: Internal cache entry for BindingConfigResolver
+    ModelSecurityConfig: Security configuration for handler namespace allowlisting
 """
 
 # Re-export from omnibase_core for convenience
@@ -81,6 +82,9 @@ from omnibase_infra.runtime.models.model_config_ref import ModelConfigRef
 from omnibase_infra.runtime.models.model_config_ref_parse_result import (
     ModelConfigRefParseResult,
 )
+from omnibase_infra.runtime.models.model_contract_load_result import (
+    ModelContractLoadResult,
+)
 from omnibase_infra.runtime.models.model_domain_plugin_config import (
     ModelDomainPluginConfig,
 )
@@ -128,6 +132,9 @@ from omnibase_infra.runtime.models.model_protocol_registration_config import (
 )
 from omnibase_infra.runtime.models.model_retry_policy import ModelRetryPolicy
 from omnibase_infra.runtime.models.model_runtime_config import ModelRuntimeConfig
+from omnibase_infra.runtime.models.model_runtime_contract_config import (
+    ModelRuntimeContractConfig,
+)
 from omnibase_infra.runtime.models.model_runtime_scheduler_config import (
     ModelRuntimeSchedulerConfig,
 )
@@ -148,6 +155,7 @@ from omnibase_infra.runtime.models.model_secret_source_spec import (
     ModelSecretSourceSpec,
     SecretSourceType,
 )
+from omnibase_infra.runtime.models.model_security_config import ModelSecurityConfig
 from omnibase_infra.runtime.models.model_shutdown_batch_result import (
     ModelShutdownBatchResult,
 )
@@ -213,4 +221,9 @@ __all__: list[str] = [
     "ModelTransitionNotificationOutboxMetrics",
     "ModelTransitionNotificationPublisherMetrics",
     "SecretSourceType",
+    # Contract loading models (OMN-1519)
+    "ModelContractLoadResult",
+    "ModelRuntimeContractConfig",
+    # Security configuration (OMN-1519)
+    "ModelSecurityConfig",
 ]

omnibase_infra/runtime/models/model_contract_load_result.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract load result model for tracking individual contract loading.
+
+This module provides the ModelContractLoadResult class for representing
+the outcome of loading a single contract.yaml file, including any subcontracts
+(handler_routing, operation_bindings) that were loaded from it.
+
+Part of OMN-1519: Runtime contract config loader.
+
+Design Pattern:
+    ModelContractLoadResult captures both successful and failed contract
+    loading attempts, allowing the runtime to continue loading other
+    contracts even if one fails. Errors are collected rather than raised
+    immediately.
+
+Thread Safety:
+    ModelContractLoadResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from pathlib import Path
+    >>> from omnibase_infra.runtime.models import ModelContractLoadResult
+    >>>
+    >>> # Successful load
+    >>> result = ModelContractLoadResult.succeeded(
+    ...     contract_path=Path("nodes/auth/contract.yaml"),
+    ...     handler_routing=routing_subcontract,
+    ...     operation_bindings=bindings_subcontract,
+    ... )
+    >>> result.success
+    True
+    >>>
+    >>> # Failed load
+    >>> result = ModelContractLoadResult.failed(
+    ...     contract_path=Path("nodes/broken/contract.yaml"),
+    ...     error="Invalid YAML syntax",
+    ... )
+    >>> result.success
+    False
+
+.. versionadded:: 0.2.8
+    Created as part of OMN-1519.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.bindings import ModelOperationBindingsSubcontract
+from omnibase_infra.models.routing import ModelRoutingSubcontract
+
+
+class ModelContractLoadResult(BaseModel):
+    """Result of loading a single contract.yaml file.
+
+    Captures the outcome of loading a contract, including any subcontracts
+    that were successfully loaded or any errors that occurred.
+
+    Attributes:
+        contract_path: Path to the contract.yaml file that was loaded.
+        success: True if the contract was loaded successfully.
+        error: Error message if loading failed, empty string otherwise.
+        handler_routing: Loaded handler routing subcontract, or None if not present.
+        operation_bindings: Loaded operation bindings subcontract, or None if not present.
+        correlation_id: Correlation ID for tracing this load operation.
+
+    Example:
+        >>> result = ModelContractLoadResult.succeeded(
+        ...     contract_path=Path("nodes/auth/contract.yaml"),
+        ...     handler_routing=routing,
+        ...     operation_bindings=bindings,
+        ... )
+        >>> result.success
+        True
+        >>> result.handler_routing is not None
+        True
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,
+    )
+
+    contract_path: Path = Field(
+        ...,
+        description="Path to the contract.yaml file that was loaded.",
+    )
+    success: bool = Field(
+        ...,
+        description="True if the contract was loaded successfully.",
+    )
+    error: str = Field(
+        default="",
+        description="Error message if loading failed, empty string otherwise.",
+    )
+    handler_routing: ModelRoutingSubcontract | None = Field(
+        default=None,
+        description="Loaded handler routing subcontract, or None if not present.",
+    )
+    operation_bindings: ModelOperationBindingsSubcontract | None = Field(
+        default=None,
+        description="Loaded operation bindings subcontract, or None if not present.",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for tracing this load operation.",
+    )
+
+    @property
+    def has_error(self) -> bool:
+        """Check if an error message exists.
+
+        Returns:
+            True if error is non-empty, False otherwise.
+        """
+        return bool(self.error)
+
+    @property
+    def has_handler_routing(self) -> bool:
+        """Check if handler routing was loaded.
+
+        Returns:
+            True if handler_routing is not None.
+        """
+        return self.handler_routing is not None
+
+    @property
+    def has_operation_bindings(self) -> bool:
+        """Check if operation bindings were loaded.
+
+        Returns:
+            True if operation_bindings is not None.
+        """
+        return self.operation_bindings is not None
+
+    @classmethod
+    def succeeded(
+        cls,
+        contract_path: Path,
+        handler_routing: ModelRoutingSubcontract | None = None,
+        operation_bindings: ModelOperationBindingsSubcontract | None = None,
+        correlation_id: UUID | None = None,
+    ) -> ModelContractLoadResult:
+        """Create a successful contract load result.
+
+        Args:
+            contract_path: Path to the contract.yaml file.
+            handler_routing: Loaded handler routing subcontract, if present.
+            operation_bindings: Loaded operation bindings subcontract, if present.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelContractLoadResult indicating success.
+        """
+        return cls(
+            contract_path=contract_path,
+            success=True,
+            error="",
+            handler_routing=handler_routing,
+            operation_bindings=operation_bindings,
+            correlation_id=correlation_id,
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        contract_path: Path,
+        error: str,
+        correlation_id: UUID | None = None,
+    ) -> ModelContractLoadResult:
+        """Create a failed contract load result.
+
+        Args:
+            contract_path: Path to the contract.yaml file.
+            error: Description of the error that occurred.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelContractLoadResult indicating failure with error details.
+        """
+        return cls(
+            contract_path=contract_path,
+            success=False,
+            error=error,
+            handler_routing=None,
+            operation_bindings=None,
+            correlation_id=correlation_id,
+        )
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``success`` is True.
+
+        Returns:
+            True if contract was loaded successfully, False otherwise.
+        """
+        return self.success
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation.
+
+        Returns:
+            String describing the load result.
+        """
+        if self.success:
+            parts = []
+            if self.has_handler_routing:
+                parts.append("handler_routing")
+            if self.has_operation_bindings:
+                parts.append("operation_bindings")
+            loaded = ", ".join(parts) if parts else "no subcontracts"
+            return f"ModelContractLoadResult({self.contract_path}: {loaded})"
+        return f"ModelContractLoadResult({self.contract_path}: FAILED - {self.error})"
+
+
+__all__ = ["ModelContractLoadResult"]

omnibase_infra/runtime/models/model_runtime_contract_config.py

@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Runtime contract configuration model for consolidated contract loading.
+
+This module provides the ModelRuntimeContractConfig class for representing
+the consolidated result of loading all contract.yaml files at startup.
+
+Part of OMN-1519: Runtime contract config loader.
+
+Design Pattern:
+    ModelRuntimeContractConfig aggregates results from loading multiple
+    contract.yaml files, providing a single source of truth for all
+    handler routing and operation bindings configuration.
+
+Thread Safety:
+    ModelRuntimeContractConfig is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelRuntimeContractConfig
+    >>>
+    >>> config = ModelRuntimeContractConfig(
+    ...     contract_results=[result1, result2],
+    ...     total_contracts_found=5,
+    ...     total_contracts_loaded=4,
+    ...     total_errors=1,
+    ... )
+    >>> config.success_rate
+    0.8
+
+.. versionadded:: 0.2.8
+    Created as part of OMN-1519.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+from omnibase_infra.models.bindings import ModelOperationBindingsSubcontract
+from omnibase_infra.models.routing import ModelRoutingSubcontract
+from omnibase_infra.runtime.models.model_contract_load_result import (
+    ModelContractLoadResult,
+)
+
+
+class ModelRuntimeContractConfig(BaseModel):
+    """Consolidated runtime contract configuration from all loaded contracts.
+
+    Aggregates the results of loading multiple contract.yaml files,
+    providing access to all handler routing and operation bindings
+    configuration loaded at startup.
+
+    Attributes:
+        contract_results: List of individual contract load results.
+        total_contracts_found: Number of contract.yaml files discovered.
+        total_contracts_loaded: Number of contracts successfully loaded.
+        total_errors: Number of contracts that failed to load.
+        correlation_id: Correlation ID for tracing this load session.
+
+    Example:
+        >>> config = ModelRuntimeContractConfig(
+        ...     contract_results=[result1, result2],
+        ...     total_contracts_found=2,
+        ...     total_contracts_loaded=2,
+        ...     total_errors=0,
+        ... )
+        >>> config.all_successful
+        True
+        >>> len(config.handler_routing_configs)
+        2
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    contract_results: list[ModelContractLoadResult] = Field(
+        default_factory=list,
+        description="List of individual contract load results.",
+    )
+    total_contracts_found: int = Field(
+        default=0,
+        ge=0,
+        description="Number of contract.yaml files discovered.",
+    )
+    total_contracts_loaded: int = Field(
+        default=0,
+        ge=0,
+        description="Number of contracts successfully loaded.",
+    )
+    total_errors: int = Field(
+        default=0,
+        ge=0,
+        description="Number of contracts that failed to load.",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Correlation ID for tracing this load session.",
+    )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def all_successful(self) -> bool:
+        """Check if all contracts were loaded successfully.
+
+        Returns:
+            True if total_errors is 0 and at least one contract was found.
+        """
+        return self.total_errors == 0 and self.total_contracts_found > 0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def success_rate(self) -> float:
+        """Calculate the success rate of contract loading.
+
+        Returns:
+            Ratio of successfully loaded contracts to total found (0.0-1.0).
+            Returns 1.0 if no contracts were found.
+        """
+        if self.total_contracts_found == 0:
+            return 1.0
+        return self.total_contracts_loaded / self.total_contracts_found
+
+    @property
+    def successful_results(self) -> list[ModelContractLoadResult]:
+        """Get all successful contract load results.
+
+        Returns:
+            List of ModelContractLoadResult where success is True.
+        """
+        return [r for r in self.contract_results if r.success]
+
+    @property
+    def failed_results(self) -> list[ModelContractLoadResult]:
+        """Get all failed contract load results.
+
+        Returns:
+            List of ModelContractLoadResult where success is False.
+        """
+        return [r for r in self.contract_results if not r.success]
+
+    @property
+    def handler_routing_configs(self) -> dict[Path, ModelRoutingSubcontract]:
+        """Get all loaded handler routing configurations.
+
+        Returns:
+            Mapping of contract path to handler routing subcontract.
+        """
+        return {
+            r.contract_path: r.handler_routing
+            for r in self.contract_results
+            if r.handler_routing is not None
+        }
+
+    @property
+    def operation_bindings_configs(
+        self,
+    ) -> dict[Path, ModelOperationBindingsSubcontract]:
+        """Get all loaded operation bindings configurations.
+
+        Returns:
+            Mapping of contract path to operation bindings subcontract.
+        """
+        return {
+            r.contract_path: r.operation_bindings
+            for r in self.contract_results
+            if r.operation_bindings is not None
+        }
+
+    @property
+    def error_messages(self) -> dict[Path, str]:
+        """Get all error messages from failed loads.
+
+        Returns:
+            Mapping of contract path to error message.
+        """
+        return {r.contract_path: r.error for r in self.contract_results if r.error}
+
+    def get_routing_for_contract(
+        self, contract_path: Path
+    ) -> ModelRoutingSubcontract | None:
+        """Get handler routing for a specific contract.
+
+        Args:
+            contract_path: Path to the contract.yaml file.
+
+        Returns:
+            ModelRoutingSubcontract if found, None otherwise.
+        """
+        for result in self.contract_results:
+            if result.contract_path == contract_path:
+                return result.handler_routing
+        return None
+
+    def get_bindings_for_contract(
+        self, contract_path: Path
+    ) -> ModelOperationBindingsSubcontract | None:
+        """Get operation bindings for a specific contract.
+
+        Args:
+            contract_path: Path to the contract.yaml file.
+
+        Returns:
+            ModelOperationBindingsSubcontract if found, None otherwise.
+        """
+        for result in self.contract_results:
+            if result.contract_path == contract_path:
+                return result.operation_bindings
+        return None
+
+    def __bool__(self) -> bool:
+        """Allow using config in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when all contracts were loaded successfully.
+
+        Note:
+            **Edge case - no contracts found**: Returns ``False`` when
+            ``total_contracts_found == 0``, even if ``total_errors == 0``.
+            This is intentional: an empty result (no contracts discovered)
+            should trigger explicit handling by the caller rather than
+            silently proceeding as if everything succeeded.
+
+        Example:
+            >>> # Empty config with no errors still returns False
+            >>> config = ModelRuntimeContractConfig()
+            >>> bool(config)
+            False
+            >>> config.total_errors
+            0
+            >>> config.total_contracts_found
+            0
+            >>>
+            >>> # Only returns True when contracts are found AND no errors
+            >>> config_with_contracts = ModelRuntimeContractConfig(
+            ...     total_contracts_found=1,
+            ...     total_contracts_loaded=1,
+            ... )
+            >>> bool(config_with_contracts)
+            True
+
+        Returns:
+            True if all contracts loaded successfully (requires at least one
+            contract found and zero errors), False otherwise.
+        """
+        return self.all_successful
+
+    def __str__(self) -> str:
+        """Return a human-readable summary.
+
+        Returns:
+            String summarizing the load results.
+        """
+        return (
+            f"ModelRuntimeContractConfig("
+            f"found={self.total_contracts_found}, "
+            f"loaded={self.total_contracts_loaded}, "
+            f"errors={self.total_errors}, "
+            f"success_rate={self.success_rate:.1%})"
+        )
+
+
+__all__ = ["ModelRuntimeContractConfig"]

omnibase_infra/runtime/models/model_runtime_scheduler_config.py

@@ -28,7 +28,7 @@ Environment Variables:
             Example: "runtime-scheduler-prod-1"
 
         ONEX_RUNTIME_SCHEDULER_TICK_TOPIC: Kafka topic for publishing ticks
-            Default: "runtime.tick.v1"
+            Default: SUFFIX_RUNTIME_TICK from omnibase_infra.topics
             Example: "prod.runtime.tick.v1"
 
     Restart-Safety Settings:
@@ -106,6 +106,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+from omnibase_infra.topics import SUFFIX_RUNTIME_TICK
 
 logger = logging.getLogger(__name__)
 
@@ -167,7 +168,7 @@ class ModelRuntimeSchedulerConfig(BaseModel):
         max_length=255,
     )
     tick_topic: str = Field(
-        default="runtime.tick.v1",
+        default=SUFFIX_RUNTIME_TICK,
         description="Kafka topic for publishing tick events",
         min_length=1,
         max_length=255,
@@ -604,7 +605,7 @@ class ModelRuntimeSchedulerConfig(BaseModel):
         base_config = cls(
             tick_interval_ms=1000,
             scheduler_id="runtime-scheduler-default",
-            tick_topic="runtime.tick.v1",
+            tick_topic=SUFFIX_RUNTIME_TICK,
             persist_sequence_number=True,
             sequence_number_key="runtime_scheduler_sequence",
             max_tick_jitter_ms=100,

omnibase_infra/runtime/models/model_security_config.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security Configuration Model for Runtime Handler Loading.
+
+This module provides the Pydantic model for configuring trusted handler namespaces.
+The model allows operators to extend the trusted namespace list via configuration
+file while maintaining secure defaults.
+
+Security Model:
+    - Default: Only omnibase_core. and omnibase_infra. are trusted
+    - Third-party: Requires allow_third_party_handlers=True AND
+      explicit listing in allowed_handler_namespaces
+    - Config file is auditable/reviewable (unlike env vars)
+
+Example:
+    >>> from omnibase_infra.runtime.models import ModelSecurityConfig
+    >>> config = ModelSecurityConfig()  # Secure defaults
+    >>> config.get_effective_namespaces()
+    ('omnibase_core.', 'omnibase_infra.')
+
+    >>> # Enable third-party handlers
+    >>> config = ModelSecurityConfig(
+    ...     allow_third_party_handlers=True,
+    ...     allowed_handler_namespaces=(
+    ...         "omnibase_core.",
+    ...         "omnibase_infra.",
+    ...         "mycompany.handlers.",
+    ...     ),
+    ... )
+    >>> config.get_effective_namespaces()
+    ('omnibase_core.', 'omnibase_infra.', 'mycompany.handlers.')
+
+.. versionadded:: 0.2.8
+    Created as part of OMN-1519 security hardening.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.constants_security import TRUSTED_HANDLER_NAMESPACE_PREFIXES
+
+
+class ModelSecurityConfig(BaseModel):
+    """Security configuration for runtime handler loading.
+
+    This model allows operators to extend the trusted namespace list
+    via configuration file. The defaults are secure - third-party
+    namespaces require explicit opt-in.
+
+    Security Model:
+        - Default: Only omnibase_core. and omnibase_infra. are trusted
+        - Third-party: Requires allow_third_party_handlers=True AND
+          explicit listing in allowed_handler_namespaces
+        - Config file is auditable/reviewable (unlike env vars)
+
+    Attributes:
+        allow_third_party_handlers: Enable loading handlers from third-party
+            namespaces. When False, only TRUSTED_HANDLER_NAMESPACE_PREFIXES
+            are allowed regardless of allowed_handler_namespaces setting.
+        allowed_handler_namespaces: Allowed namespace prefixes for handler
+            loading. Only effective when allow_third_party_handlers=True.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    allow_third_party_handlers: bool = Field(
+        default=False,
+        description="Enable loading handlers from third-party namespaces. "
+        "When False, only TRUSTED_HANDLER_NAMESPACE_PREFIXES are allowed.",
+    )
+
+    allowed_handler_namespaces: tuple[str, ...] = Field(
+        default=TRUSTED_HANDLER_NAMESPACE_PREFIXES,
+        description="Allowed namespace prefixes for handler loading. "
+        "Only effective when allow_third_party_handlers=True.",
+    )
+
+    def get_effective_namespaces(self) -> tuple[str, ...]:
+        """Get the effective namespace allowlist based on configuration.
+
+        Returns:
+            Tuple of allowed namespace prefixes. If third-party handlers
+            are disabled, returns only the trusted defaults regardless
+            of the allowed_handler_namespaces setting.
+
+        Example:
+            >>> config = ModelSecurityConfig()
+            >>> config.get_effective_namespaces()
+            ('omnibase_core.', 'omnibase_infra.')
+
+            >>> config = ModelSecurityConfig(
+            ...     allow_third_party_handlers=True,
+            ...     allowed_handler_namespaces=("custom.namespace.",),
+            ... )
+            >>> config.get_effective_namespaces()
+            ('custom.namespace.',)
+        """
+        if not self.allow_third_party_handlers:
+            return TRUSTED_HANDLER_NAMESPACE_PREFIXES
+        return self.allowed_handler_namespaces
+
+
+__all__: list[str] = ["ModelSecurityConfig"]