omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/registration/model_node_registration_record.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Record for PostgreSQL Intent.
+
+This module provides ModelNodeRegistrationRecord, a frozen record model
+suitable for use with ModelPostgresUpsertRegistrationIntent.
+
+Architecture:
+    This model extends ModelRegistrationRecordBase from omnibase_core to ensure
+    protocol compliance and consistent serialization behavior. It captures the
+    minimal set of fields needed for node registration persistence.
+
+    Unlike ModelNodeRegistration (which is mutable and has complex validation),
+    this record is:
+    - Immutable (frozen=True)
+    - Minimal (only essential fields)
+    - Compliant with ProtocolRegistrationRecord
+
+    Strong Typing:
+    This model uses strongly-typed models for capabilities and metadata:
+    - capabilities: ModelNodeCapabilities - typed capability flags
+    - metadata: ModelNodeMetadata - typed deployment metadata
+
+    These models replace the legacy dict[str, Any] pattern to comply with
+    the ONEX "no Any types" rule. Both models use extra="allow" to support
+    custom fields while maintaining type safety for known fields.
+
+Thread Safety:
+    ModelNodeRegistrationRecord is immutable after creation, making it
+    thread-safe for concurrent read access.
+
+Related:
+    - ModelNodeRegistration: Full mutable registration model
+    - ModelPostgresUpsertRegistrationIntent: Intent that uses this record
+    - ModelNodeCapabilities: Strongly-typed capabilities model
+    - ModelNodeMetadata: Strongly-typed metadata model
+    - OMN-889: Infrastructure MVP
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import Field, field_validator
+
+from omnibase_core.enums.enum_node_kind import EnumNodeKind
+from omnibase_core.models.intents import ModelRegistrationRecordBase
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+from omnibase_infra.models.registration.model_node_metadata import ModelNodeMetadata
+
+
+class ModelNodeRegistrationRecord(ModelRegistrationRecordBase):
+    """Frozen record for node registration in PostgreSQL.
+
+    This is a minimal, immutable record designed for use with
+    ModelPostgresUpsertRegistrationIntent. It captures the essential
+    fields needed for node registration without complex validation.
+
+    The record is serialized by the Effect layer when persisting to PostgreSQL.
+    The to_persistence_dict() method (inherited from ModelRegistrationRecordBase)
+    handles JSON-compatible serialization.
+
+    Strong Typing:
+        Uses ModelNodeCapabilities and ModelNodeMetadata instead of dict[str, Any]
+        to comply with ONEX "no Any types" rule. Both models use extra="allow"
+        to support custom fields while providing type safety for known fields.
+
+    Attributes:
+        node_id: Unique node identifier (UUID).
+        node_type: ONEX node type (effect, compute, reducer, orchestrator).
+        node_version: Semantic version of the node.
+        capabilities: Strongly-typed node capabilities (ModelNodeCapabilities).
+        endpoints: Exposed endpoints as name -> URL mapping.
+        metadata: Strongly-typed node metadata (ModelNodeMetadata).
+        health_endpoint: Optional URL for health check endpoint.
+        registered_at: Timestamp when node was first registered.
+        updated_at: Timestamp of last update.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> from omnibase_core.enums.enum_node_kind import EnumNodeKind
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> from omnibase_infra.models.registration import (
+        ...     ModelNodeCapabilities,
+        ...     ModelNodeMetadata,
+        ... )
+        >>> now = datetime.now(UTC)
+        >>> record = ModelNodeRegistrationRecord(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=0, patch=0),
+        ...     capabilities=ModelNodeCapabilities(postgres=True),
+        ...     endpoints={"health": "http://localhost:8080/health"},
+        ...     metadata=ModelNodeMetadata(environment="production"),
+        ...     health_endpoint="http://localhost:8080/health",
+        ...     registered_at=now,
+        ...     updated_at=now,
+        ... )
+        >>> db_data = record.to_persistence_dict()
+        >>> assert isinstance(db_data["node_id"], str)  # UUID serialized
+    """
+
+    # Identity
+    node_id: UUID = Field(..., description="Unique node identifier")
+    node_type: EnumNodeKind = Field(..., description="ONEX node type")
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node",
+    )
+
+    @field_validator("node_version", mode="before")
+    @classmethod
+    def parse_node_version(cls, v: ModelSemVer | str) -> ModelSemVer:
+        """Parse node_version from string or ModelSemVer.
+
+        Args:
+            v: Either a ModelSemVer instance or a semver string.
+
+        Returns:
+            Validated ModelSemVer instance.
+
+        Raises:
+            ValueError: If the string is not a valid semantic version.
+        """
+        if isinstance(v, str):
+            try:
+                return ModelSemVer.parse(v)
+            except Exception as e:
+                raise ValueError(f"node_version: {e!s}") from e
+        return v
+
+    # Capabilities and endpoints - strongly typed models
+    capabilities: ModelNodeCapabilities = Field(
+        default_factory=ModelNodeCapabilities,
+        description="Strongly-typed node capabilities",
+    )
+    endpoints: dict[str, str] = Field(
+        default_factory=dict, description="Exposed endpoints (name -> URL)"
+    )
+    metadata: ModelNodeMetadata = Field(
+        default_factory=ModelNodeMetadata,
+        description="Strongly-typed node metadata",
+    )
+
+    # Health tracking
+    health_endpoint: str | None = Field(
+        default=None, description="URL for health check endpoint"
+    )
+
+    # Timestamps
+    registered_at: datetime = Field(
+        ..., description="Timestamp when node was first registered"
+    )
+    updated_at: datetime = Field(..., description="Timestamp of last update")
+
+
+__all__ = ["ModelNodeRegistrationRecord"]

omnibase_infra/models/registry/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry Models Module.
+
+This module provides Pydantic models for message type registry functionality
+in the ONEX runtime dispatch infrastructure.
+
+Models:
+    - ModelDomainConstraint: Domain ownership rules and cross-domain constraints
+    - ModelMessageTypeEntry: Registry entry for message type to handler mappings
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - runtime.registry: Registry implementation using these models
+
+.. versionadded:: 0.5.0
+"""
+
+from omnibase_infra.models.registry.model_domain_constraint import (
+    ModelDomainConstraint,
+)
+from omnibase_infra.models.registry.model_message_type_entry import (
+    ModelMessageTypeEntry,
+)
+
+__all__: list[str] = [
+    "ModelDomainConstraint",
+    "ModelMessageTypeEntry",
+]

omnibase_infra/models/registry/model_domain_constraint.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Domain Constraint Model.
+
+Defines domain ownership rules and cross-domain consumption constraints for
+message type routing in the ONEX runtime.
+
+Design Principles:
+    - Domain ownership is derived from topic name (onex.<domain>.*) AND message type
+      registry entry domain field
+    - Domain isolation by default: handlers can only process messages from their domain
+    - Cross-domain consumption requires explicit opt-in via allowed_cross_domains
+    - Clear fail-fast validation at startup time
+
+Topic Domain Extraction:
+    Domain is extracted from the first segment after the namespace prefix:
+    - "onex.registration.events" -> domain = "registration"
+    - "dev.user.events.v1" -> domain = "user"
+    - "prod.order.commands.v2" -> domain = "order"
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - RegistryMessageType: Uses domain constraints for validation
+
+.. versionadded:: 0.5.0
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.validation import ModelValidationOutcome
+
+
+class ModelDomainConstraint(BaseModel):
+    """
+    Domain constraint configuration for message type routing.
+
+    Defines which domains a handler can consume messages from and enforces
+    domain ownership rules. By default, handlers are isolated to their own
+    domain and must explicitly opt-in to cross-domain message consumption.
+
+    Attributes:
+        owning_domain: The domain that owns this handler/message type.
+            Must match the domain extracted from topic for same-domain processing.
+            Example: "registration", "user", "order"
+        allowed_cross_domains: Set of domains this handler can consume from
+            in addition to its own domain. Empty by default (domain isolation).
+            Example: {"user", "order"} allows consuming from user.* and order.* topics
+        allow_all_domains: If True, allows consumption from any domain.
+            Use sparingly - only for truly domain-agnostic handlers.
+            Overrides allowed_cross_domains if True.
+        require_explicit_opt_in: If True, cross-domain consumption raises error
+            unless explicitly allowed. Default True for security.
+
+    Example:
+        >>> # Registration handler only processes registration messages
+        >>> constraint = ModelDomainConstraint(owning_domain="registration")
+        >>> constraint.can_consume_from("registration")
+        True
+        >>> constraint.can_consume_from("user")
+        False
+
+        >>> # Handler with cross-domain access
+        >>> constraint = ModelDomainConstraint(
+        ...     owning_domain="notification",
+        ...     allowed_cross_domains={"user", "order"},
+        ... )
+        >>> constraint.can_consume_from("user")
+        True
+        >>> constraint.can_consume_from("billing")
+        False
+
+    Thread Safety:
+        This model is immutable (frozen=True) and thread-safe for concurrent access.
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    owning_domain: str = Field(
+        ...,
+        description=(
+            "The domain that owns this handler/message type. "
+            "Must match topic domain for same-domain processing."
+        ),
+        min_length=1,
+        max_length=100,
+    )
+
+    allowed_cross_domains: frozenset[str] = Field(
+        default_factory=frozenset,
+        description=(
+            "Domains this handler can consume from in addition to owning_domain. "
+            "Empty by default for domain isolation."
+        ),
+    )
+
+    allow_all_domains: bool = Field(
+        default=False,
+        description=(
+            "If True, allows consumption from any domain. "
+            "Overrides allowed_cross_domains. Use sparingly."
+        ),
+    )
+
+    require_explicit_opt_in: bool = Field(
+        default=True,
+        description=(
+            "If True, cross-domain consumption raises error unless explicitly "
+            "allowed via allowed_cross_domains or allow_all_domains."
+        ),
+    )
+
+    def can_consume_from(self, topic_domain: str) -> bool:
+        """
+        Check if this constraint allows consuming messages from the given domain.
+
+        Args:
+            topic_domain: The domain extracted from the topic being consumed.
+
+        Returns:
+            True if consumption is allowed, False otherwise.
+
+        Example:
+            >>> constraint = ModelDomainConstraint(owning_domain="registration")
+            >>> constraint.can_consume_from("registration")
+            True
+            >>> constraint.can_consume_from("user")
+            False
+
+        .. versionadded:: 0.5.0
+        """
+        # Allow all domains if flag is set
+        if self.allow_all_domains:
+            return True
+
+        # Always allow own domain
+        if topic_domain == self.owning_domain:
+            return True
+
+        # Check explicit cross-domain allowlist
+        if topic_domain in self.allowed_cross_domains:
+            return True
+
+        return False
+
+    def validate_consumption(
+        self,
+        topic_domain: str,
+        message_type: str,
+    ) -> ModelValidationOutcome:
+        """
+        Validate if consumption is allowed and return detailed error if not.
+
+        This method provides detailed validation with error messages suitable
+        for fail-fast behavior at startup time.
+
+        Args:
+            topic_domain: The domain extracted from the topic.
+            message_type: The message type being consumed (for error messages).
+
+        Returns:
+            ModelValidationOutcome with is_valid=True if valid,
+            or is_valid=False with error_message if invalid.
+
+        Example:
+            >>> constraint = ModelDomainConstraint(owning_domain="registration")
+            >>> outcome = constraint.validate_consumption("user", "UserCreated")
+            >>> outcome.is_valid
+            False
+
+        .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Return type changed from tuple[bool, str | None] to ModelValidationOutcome.
+        """
+        if self.can_consume_from(topic_domain):
+            return ModelValidationOutcome.success()
+
+        # Build detailed error message
+        if self.require_explicit_opt_in:
+            allowed = [self.owning_domain]
+            allowed.extend(sorted(self.allowed_cross_domains))
+            return ModelValidationOutcome.failure(
+                f"Domain mismatch: handler in domain '{self.owning_domain}' cannot "
+                f"consume message type '{message_type}' from domain '{topic_domain}'. "
+                f"Allowed domains: {allowed}. "
+                f"To enable cross-domain consumption, add '{topic_domain}' to "
+                f"allowed_cross_domains or set allow_all_domains=True."
+            )
+        else:
+            return ModelValidationOutcome.failure(
+                f"Domain mismatch: handler domain '{self.owning_domain}' does not "
+                f"match topic domain '{topic_domain}' for message type '{message_type}'."
+            )
+
+
+__all__ = ["ModelDomainConstraint"]

omnibase_infra/models/registry/model_message_type_entry.py

@@ -0,0 +1,271 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Message Type Entry Model.
+
+Defines the registry entry for message type to handler mappings in the
+Central Message Type Registry.
+
+Design Principles:
+    - Each entry maps a message type to one or more handler implementations
+    - Topic category constraints define where message types can appear
+    - Domain ownership is tracked for cross-domain validation
+    - Immutable entries for thread-safe concurrent access
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - ModelDomainConstraint: Domain ownership rules
+    - RegistryMessageType: Uses entries for handler resolution
+
+.. versionadded:: 0.5.0
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums import EnumMessageCategory
+from omnibase_infra.models.registry.model_domain_constraint import (
+    ModelDomainConstraint,
+)
+from omnibase_infra.models.validation import ModelValidationOutcome
+
+
+class ModelMessageTypeEntry(BaseModel):
+    """
+    Registry entry mapping a message type to handler(s) with constraints.
+
+    Each entry represents a message type registration in the Central Message Type
+    Registry. It defines which handlers process the message type, what categories
+    are allowed, and domain ownership constraints.
+
+    Attributes:
+        message_type: The fully-qualified message type name.
+            Example: "UserCreated", "CreateOrderCommand", "CheckoutIntent"
+        handler_ids: List of handler IDs that can process this message type.
+            Supports fan-out pattern with multiple handlers per type.
+        allowed_categories: Message categories where this type can appear.
+            Example: [EVENT] for domain events, [COMMAND] for commands.
+        domain_constraint: Domain ownership and cross-domain rules.
+        description: Human-readable description of the message type.
+        enabled: Whether this entry is active. Disabled entries are skipped.
+        registered_at: Timestamp when this entry was registered.
+
+    Fan-Out Support:
+        Multiple handler_ids can be registered for the same message type to enable
+        fan-out processing patterns. Each registered handler will receive the
+        message independently.
+
+    Example:
+        >>> entry = ModelMessageTypeEntry(
+        ...     message_type="UserCreated",
+        ...     handler_ids=["user-event-handler", "audit-logger"],
+        ...     allowed_categories=[EnumMessageCategory.EVENT],
+        ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+        ...     description="User creation event",
+        ... )
+        >>> entry.supports_category(EnumMessageCategory.EVENT)
+        True
+        >>> entry.supports_category(EnumMessageCategory.COMMAND)
+        False
+
+    Thread Safety:
+        This model is immutable (frozen=True) and thread-safe for concurrent access.
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # ---- Message Type Identity ----
+    message_type: str = Field(
+        ...,
+        description="The fully-qualified message type name.",
+        min_length=1,
+        max_length=200,
+    )
+
+    # ---- Handler Mapping ----
+    handler_ids: tuple[str, ...] = Field(
+        ...,
+        description=(
+            "Handler IDs that can process this message type. "
+            "Tuple for immutability and fan-out support."
+        ),
+        min_length=1,
+    )
+
+    # ---- Category Constraints ----
+    allowed_categories: frozenset[EnumMessageCategory] = Field(
+        ...,
+        description=(
+            "Message categories where this type can appear. Frozenset for immutability."
+        ),
+    )
+
+    @field_validator("allowed_categories")
+    @classmethod
+    def validate_allowed_categories_not_empty(
+        cls, value: frozenset[EnumMessageCategory]
+    ) -> frozenset[EnumMessageCategory]:
+        """Validate that allowed_categories contains at least one category.
+
+        A message type with no allowed categories is invalid because it can
+        never be routed - there is no valid topic category where it could appear.
+
+        Args:
+            value: The frozenset of allowed categories.
+
+        Returns:
+            The validated frozenset.
+
+        Raises:
+            ValueError: If the frozenset is empty.
+        """
+        if not value:
+            msg = (
+                "allowed_categories cannot be empty. "
+                "A message type must be allowed in at least one category "
+                "(EVENT, COMMAND, or INTENT) to be routable."
+            )
+            raise ValueError(msg)
+        return value
+
+    # ---- Domain Constraints ----
+    domain_constraint: ModelDomainConstraint = Field(
+        ...,
+        description="Domain ownership and cross-domain consumption rules.",
+    )
+
+    # ---- Metadata ----
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description of the message type.",
+        max_length=500,
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether this entry is active. Disabled entries are skipped.",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    registered_at: datetime = Field(
+        ...,
+        description="Timestamp when this entry was registered (UTC, must be explicitly provided).",
+    )
+
+    def supports_category(self, category: EnumMessageCategory) -> bool:
+        """
+        Check if this message type is allowed in the given category.
+
+        Args:
+            category: The message category to check.
+
+        Returns:
+            True if the message type can appear in this category, False otherwise.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> entry.supports_category(EnumMessageCategory.EVENT)
+            True
+
+        .. versionadded:: 0.5.0
+        """
+        return category in self.allowed_categories
+
+    def validate_category(
+        self,
+        topic_category: EnumMessageCategory,
+    ) -> ModelValidationOutcome:
+        """
+        Validate if the message type can appear in the given topic category.
+
+        Args:
+            topic_category: The category inferred from the topic.
+
+        Returns:
+            ModelValidationOutcome with is_valid=True if valid,
+            or is_valid=False with error_message if invalid.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> outcome = entry.validate_category(EnumMessageCategory.COMMAND)
+            >>> outcome.is_valid
+            False
+
+        .. versionadded:: 0.5.0
+        .. versionchanged:: 0.6.0
+            Return type changed from tuple[bool, str | None] to ModelValidationOutcome.
+        """
+        if self.supports_category(topic_category):
+            return ModelValidationOutcome.success()
+
+        allowed_str = ", ".join(sorted(c.value for c in self.allowed_categories))
+        return ModelValidationOutcome.failure(
+            f"Message type '{self.message_type}' is not allowed in category "
+            f"'{topic_category.value}'. Allowed categories: [{allowed_str}]."
+        )
+
+    def with_additional_handler(self, handler_id: str) -> "ModelMessageTypeEntry":
+        """
+        Create a new entry with an additional handler ID.
+
+        Used for fan-out registration where multiple handlers process
+        the same message type.
+
+        Args:
+            handler_id: The handler ID to add.
+
+        Returns:
+            New ModelMessageTypeEntry with the additional handler.
+
+        Example:
+            >>> entry = ModelMessageTypeEntry(
+            ...     message_type="UserCreated",
+            ...     handler_ids=("handler-1",),
+            ...     allowed_categories=frozenset([EnumMessageCategory.EVENT]),
+            ...     domain_constraint=ModelDomainConstraint(owning_domain="user"),
+            ... )
+            >>> updated = entry.with_additional_handler("handler-2")
+            >>> updated.handler_ids
+            ('handler-1', 'handler-2')
+
+        .. versionadded:: 0.5.0
+        """
+        if handler_id in self.handler_ids:
+            return self
+
+        new_handlers = tuple(list(self.handler_ids) + [handler_id])
+        return self.model_copy(update={"handler_ids": new_handlers})
+
+    def with_enabled(self, enabled: bool) -> "ModelMessageTypeEntry":
+        """
+        Create a new entry with updated enabled status.
+
+        Args:
+            enabled: The new enabled status.
+
+        Returns:
+            New ModelMessageTypeEntry with updated status.
+
+        .. versionadded:: 0.5.0
+        """
+        return self.model_copy(update={"enabled": enabled})
+
+
+__all__ = ["ModelMessageTypeEntry"]

omnibase_infra/models/resilience/__init__.py

@@ -0,0 +1,9 @@
+"""Resilience models for infrastructure fault tolerance."""
+
+from omnibase_infra.models.resilience.model_circuit_breaker_config import (
+    ModelCircuitBreakerConfig,
+)
+
+__all__ = [
+    "ModelCircuitBreakerConfig",
+]