omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/registration/events/model_node_registration_initiated.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Initiated Event Model.
+
+This module provides ModelNodeRegistrationInitiated for the ONEX 2-way
+registration pattern. Emitted by the Registration Orchestrator when it
+receives a NodeIntrospected event to represent the start of a registration
+attempt.
+
+IMPORTANT: Timestamp fields (emitted_at) have NO default_factory (no datetime.now()).
+This is intentional per ONEX architecture - orchestrators use injected `now` parameter
+from RuntimeTick or dispatch context. This ensures:
+    - Deterministic testing (fixed time in tests)
+    - Consistent ordering (no clock skew between nodes)
+    - Explicit time injection (no hidden time dependencies)
+
+See Also:
+    - docs/design/ONEX_RUNTIME_REGISTRATION_TICKET_PLAN.md (C1 section)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeRegistrationInitiated(BaseModel):
+    """Event model for registration initiation by the orchestrator.
+
+    Emitted when the orchestrator receives a NodeIntrospected event and
+    begins processing a registration attempt. This event represents the
+    start of the registration workflow without implying command-driven
+    semantics.
+
+    This is the first decision event in the registration workflow, linking
+    the NodeIntrospected trigger to subsequent orchestrator decisions.
+
+    Attributes:
+        entity_id: The entity identifier (equals node_id for registration domain).
+            Used as partition key for ordering guarantees.
+        node_id: Unique identifier of the node being registered.
+        correlation_id: Correlation ID for distributed tracing across the workflow.
+        causation_id: Message ID of the triggering NodeIntrospected event.
+        emitted_at: Timestamp when the orchestrator emitted this event (UTC).
+        registration_attempt_id: Unique identifier for this registration attempt.
+            Enables tracking multiple registration attempts for the same node.
+
+    Time Injection:
+        The `emitted_at` field must be explicitly provided by the handler
+        using its injected `now` parameter. Do NOT use datetime.now() directly.
+        This ensures deterministic testing and consistent ordering across nodes.
+
+    Example:
+        >>> from datetime import UTC, datetime
+        >>> from uuid import uuid4
+        >>> event = ModelNodeRegistrationInitiated(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ...     registration_attempt_id=uuid4(),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Entity and node identification
+    entity_id: UUID = Field(
+        ...,
+        description="Entity identifier (equals node_id for registration domain)",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="Unique identifier of the node being registered",
+    )
+
+    # Tracing and causation
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="Message ID of the triggering NodeIntrospected event",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="Timestamp when the orchestrator emitted this event (UTC)",
+    )
+
+    # Registration-specific
+    registration_attempt_id: UUID = Field(
+        ...,
+        description="Unique identifier for this registration attempt",
+    )
+
+
+__all__ = ["ModelNodeRegistrationInitiated"]

omnibase_infra/models/registration/events/model_node_registration_rejected.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Rejected Event Model.
+
+This module provides ModelNodeRegistrationRejected for the ONEX 2-way
+registration pattern. Emitted by the Registration Orchestrator when it
+rejects a node's registration request.
+
+See Also:
+    - docs/design/ONEX_RUNTIME_REGISTRATION_TICKET_PLAN.md (C1 section)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeRegistrationRejected(BaseModel):
+    """Event model for registration rejection by the orchestrator.
+
+    Emitted when the orchestrator decides to reject a node's registration.
+    This is a terminal state for the registration attempt - the node must
+    re-introspect to attempt registration again.
+
+    Common rejection reasons include:
+    - Node version incompatibility
+    - Capability requirements not met
+    - Rate limiting exceeded
+    - Duplicate registration attempt
+    - Policy violation
+
+    Attributes:
+        entity_id: The entity identifier (equals node_id for registration domain).
+            Used as partition key for ordering guarantees.
+        node_id: Unique identifier of the node being rejected.
+        correlation_id: Correlation ID for distributed tracing across the workflow.
+        causation_id: Message ID of the event that triggered this decision.
+        emitted_at: Timestamp when the orchestrator emitted this event (UTC).
+        rejection_reason: Human-readable explanation for the rejection.
+            Should be safe to expose to the node (no internal details).
+
+    Time Injection:
+        The `emitted_at` field must be explicitly provided by the handler
+        using its injected `now` parameter. Do NOT use datetime.now() directly.
+        This ensures deterministic testing and consistent ordering across nodes.
+
+    Example:
+        >>> from datetime import UTC, datetime
+        >>> from uuid import uuid4
+        >>> event = ModelNodeRegistrationRejected(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ...     rejection_reason="Node version 0.9.0 is below minimum required 1.0.0",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Entity and node identification
+    entity_id: UUID = Field(
+        ...,
+        description="Entity identifier (equals node_id for registration domain)",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="Unique identifier of the node being rejected",
+    )
+
+    # Tracing and causation
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="Message ID of the event that triggered this decision",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="Timestamp when the orchestrator emitted this event (UTC)",
+    )
+
+    # Rejection-specific
+    rejection_reason: str = Field(
+        ...,
+        min_length=1,
+        max_length=1024,
+        description="Human-readable explanation for the rejection",
+    )
+
+
+__all__ = ["ModelNodeRegistrationRejected"]

omnibase_infra/models/registration/model_introspection_metrics.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Introspection performance metrics model.
+
+This module provides ModelIntrospectionMetrics for capturing timing and
+performance information during node introspection operations.
+
+.. versionadded:: 0.6.0
+    Created as part of OMN-1002 Union Reduction Phase 2 to replace the
+    union pattern ``dict[str, float | bool | int | list[str]]`` with a
+    strongly-typed Pydantic model.
+
+Example:
+    >>> metrics = ModelIntrospectionMetrics(
+    ...     get_capabilities_ms=12.5,
+    ...     total_introspection_ms=45.0,
+    ...     method_count=15,
+    ... )
+    >>> metrics.threshold_exceeded
+    False
+    >>> metrics.to_dict()
+    {'get_capabilities_ms': 12.5, ...}
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelIntrospectionMetrics(BaseModel):
+    """Performance metrics for introspection operations.
+
+    This Pydantic model captures timing information for introspection operations,
+    enabling performance monitoring and alerting when operations exceed
+    the <50ms target threshold.
+
+    .. versionadded:: 0.6.0
+        Created to replace union-typed dict return from dataclass.to_dict().
+
+    Attributes:
+        get_capabilities_ms: Time taken by get_capabilities() in milliseconds.
+        discover_capabilities_ms: Time taken by _discover_capabilities() in ms.
+        get_endpoints_ms: Time taken by get_endpoints() in milliseconds.
+        get_current_state_ms: Time taken by get_current_state() in milliseconds.
+        total_introspection_ms: Total time for get_introspection_data() in ms.
+        cache_hit: Whether the result was served from cache.
+        method_count: Number of methods discovered during reflection.
+        threshold_exceeded: Whether any operation exceeded performance thresholds.
+        slow_operations: List of operation names that exceeded their thresholds.
+
+    Example:
+        >>> from omnibase_infra.models.registration import ModelIntrospectionMetrics
+        >>> metrics = ModelIntrospectionMetrics(
+        ...     get_capabilities_ms=12.5,
+        ...     discover_capabilities_ms=8.0,
+        ...     get_endpoints_ms=2.0,
+        ...     get_current_state_ms=1.0,
+        ...     total_introspection_ms=25.0,
+        ...     cache_hit=False,
+        ...     method_count=15,
+        ...     threshold_exceeded=False,
+        ...     slow_operations=[],
+        ... )
+        >>> metrics.total_introspection_ms
+        25.0
+        >>> metrics.cache_hit
+        False
+
+        # Convert to dictionary for logging/serialization
+        >>> metrics_dict = metrics.to_dict()
+        >>> metrics_dict["method_count"]
+        15
+
+        # Create from existing dataclass
+        >>> from dataclasses import dataclass, field
+        >>> @dataclass
+        ... class LegacyMetrics:
+        ...     get_capabilities_ms: float = 0.0
+        ...     discover_capabilities_ms: float = 0.0
+        ...     get_endpoints_ms: float = 0.0
+        ...     get_current_state_ms: float = 0.0
+        ...     total_introspection_ms: float = 0.0
+        ...     cache_hit: bool = False
+        ...     method_count: int = 0
+        ...     threshold_exceeded: bool = False
+        ...     slow_operations: list[str] = field(default_factory=list)
+        >>> legacy = LegacyMetrics(total_introspection_ms=30.0)
+        >>> model = ModelIntrospectionMetrics.from_dataclass(legacy)
+        >>> model.total_introspection_ms
+        30.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Timing fields (all in milliseconds)
+    get_capabilities_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Time taken by get_capabilities() in milliseconds",
+    )
+    discover_capabilities_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Time taken by _discover_capabilities() in milliseconds",
+    )
+    get_endpoints_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Time taken by get_endpoints() in milliseconds",
+    )
+    get_current_state_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Time taken by get_current_state() in milliseconds",
+    )
+    total_introspection_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Total time for get_introspection_data() in milliseconds",
+    )
+
+    # Status fields
+    cache_hit: bool = Field(
+        default=False,
+        description="Whether the result was served from cache",
+    )
+    method_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of methods discovered during reflection",
+    )
+    threshold_exceeded: bool = Field(
+        default=False,
+        description="Whether any operation exceeded performance thresholds",
+    )
+
+    # Operations that exceeded thresholds
+    slow_operations: list[str] = Field(
+        default_factory=list,
+        description="List of operation names that exceeded their thresholds",
+    )
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert metrics to dictionary for logging/serialization.
+
+        This method provides a dictionary output for JSON serialization
+        and logging purposes. Uses ``object`` as the value type to avoid
+        union complexity while maintaining type safety.
+
+        For strongly-typed access to individual fields, use the model
+        attributes directly (e.g., ``metrics.total_introspection_ms``).
+
+        .. versionadded:: 0.6.0
+
+        Returns:
+            Dictionary with all metric fields. Uses ``object`` value type
+            for simplicity; actual values are floats, bools, ints, or lists.
+
+        Example:
+            >>> metrics = ModelIntrospectionMetrics(
+            ...     total_introspection_ms=25.0,
+            ...     method_count=15,
+            ... )
+            >>> d = metrics.to_dict()
+            >>> d["total_introspection_ms"]
+            25.0
+            >>> d["method_count"]
+            15
+        """
+        return {
+            "get_capabilities_ms": self.get_capabilities_ms,
+            "discover_capabilities_ms": self.discover_capabilities_ms,
+            "get_endpoints_ms": self.get_endpoints_ms,
+            "get_current_state_ms": self.get_current_state_ms,
+            "total_introspection_ms": self.total_introspection_ms,
+            "cache_hit": self.cache_hit,
+            "method_count": self.method_count,
+            "threshold_exceeded": self.threshold_exceeded,
+            "slow_operations": list(self.slow_operations),
+        }
+
+    @classmethod
+    def from_dataclass(cls, metrics: object) -> ModelIntrospectionMetrics:
+        """Create ModelIntrospectionMetrics from a dataclass instance.
+
+        This factory method converts existing IntrospectionPerformanceMetrics
+        dataclass instances to the new Pydantic model, enabling gradual
+        migration without breaking existing code.
+
+        .. versionadded:: 0.6.0
+
+        Args:
+            metrics: A dataclass instance with compatible fields. Expected to have
+                the following attributes: get_capabilities_ms, discover_capabilities_ms,
+                get_endpoints_ms, get_current_state_ms, total_introspection_ms,
+                cache_hit, method_count, threshold_exceeded, slow_operations.
+
+        Returns:
+            A new ModelIntrospectionMetrics instance with values copied from
+            the input dataclass.
+
+        Raises:
+            pydantic.ValidationError: If any attribute has an incompatible type.
+
+        Note:
+            Missing attributes fall back to sensible defaults (0.0 / 0 / False / []),
+            making this factory tolerant of partially-populated legacy dataclasses.
+
+        Example:
+            >>> from dataclasses import dataclass, field
+            >>> @dataclass
+            ... class IntrospectionPerformanceMetrics:
+            ...     get_capabilities_ms: float = 0.0
+            ...     discover_capabilities_ms: float = 0.0
+            ...     get_endpoints_ms: float = 0.0
+            ...     get_current_state_ms: float = 0.0
+            ...     total_introspection_ms: float = 0.0
+            ...     cache_hit: bool = False
+            ...     method_count: int = 0
+            ...     threshold_exceeded: bool = False
+            ...     slow_operations: list[str] = field(default_factory=list)
+            >>> dc = IntrospectionPerformanceMetrics(
+            ...     total_introspection_ms=42.0,
+            ...     cache_hit=True,
+            ... )
+            >>> model = ModelIntrospectionMetrics.from_dataclass(dc)
+            >>> model.total_introspection_ms
+            42.0
+            >>> model.cache_hit
+            True
+        """
+        # Extract slow_operations with defensive copy to avoid mutation
+        slow_ops = getattr(metrics, "slow_operations", [])
+        slow_ops_copy = list(slow_ops) if slow_ops else []
+
+        return cls(
+            get_capabilities_ms=getattr(metrics, "get_capabilities_ms", 0.0),
+            discover_capabilities_ms=getattr(metrics, "discover_capabilities_ms", 0.0),
+            get_endpoints_ms=getattr(metrics, "get_endpoints_ms", 0.0),
+            get_current_state_ms=getattr(metrics, "get_current_state_ms", 0.0),
+            total_introspection_ms=getattr(metrics, "total_introspection_ms", 0.0),
+            cache_hit=getattr(metrics, "cache_hit", False),
+            method_count=getattr(metrics, "method_count", 0),
+            threshold_exceeded=getattr(metrics, "threshold_exceeded", False),
+            slow_operations=slow_ops_copy,
+        )
+
+
+__all__ = ["ModelIntrospectionMetrics"]

omnibase_infra/models/registration/model_node_capabilities.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Capabilities Model.
+
+This module provides ModelNodeCapabilities for strongly-typed node capabilities
+in the ONEX 2-way registration pattern.
+
+Note:
+    This model does NOT use MixinDictLikeAccessors because it requires custom
+    logic to differentiate between known model fields (model_fields) and custom
+    capabilities stored in model_extra. The mixin's simple hasattr/getattr pattern
+    would not correctly handle this distinction.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelNodeCapabilities(BaseModel):
+    """Strongly-typed node capabilities model.
+
+    Uses explicit capability fields instead of generic dictionaries.
+    Uses extra="allow" to support custom capabilities while
+    providing type safety for known fields.
+
+    Known capability fields are typed explicitly. Additional custom
+    capabilities can be added via the extra="allow" config, and they
+    will be stored as model extra fields accessible via model_extra.
+
+    Attributes:
+        postgres: Whether node has PostgreSQL capability.
+        read: Whether node has read capability.
+        write: Whether node has write capability.
+        database: Whether node has generic database capability.
+        processing: Whether node has processing capability.
+        batch_size: Optional batch size limit.
+        max_batch: Optional maximum batch size.
+        supported_types: List of supported data types.
+        routing: Whether node has routing capability.
+        config: Nested configuration dictionary (JSON-serializable values only).
+        transactions: Whether node supports transactions.
+        feature: Generic feature flag.
+
+    Example:
+        >>> caps = ModelNodeCapabilities(
+        ...     postgres=True,
+        ...     read=True,
+        ...     write=True,
+        ... )
+        >>> caps.postgres
+        True
+
+        >>> # Custom capabilities via extra="allow"
+        >>> caps = ModelNodeCapabilities(
+        ...     custom_capability=True,  # type: ignore[call-arg]
+        ...     another_field="value",  # type: ignore[call-arg]
+        ... )
+        >>> caps.model_extra["custom_capability"]
+        True
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Accept additional fields not explicitly defined
+        frozen=False,  # Allow updates (ModelNodeRegistration is mutable)
+        from_attributes=True,
+    )
+
+    # Database capabilities
+    postgres: bool = Field(default=False, description="PostgreSQL capability")
+    read: bool = Field(default=False, description="Read capability")
+    write: bool = Field(default=False, description="Write capability")
+    database: bool = Field(default=False, description="Generic database capability")
+    transactions: bool = Field(default=False, description="Transaction support")
+
+    # Processing capabilities
+    processing: bool = Field(default=False, description="Processing capability")
+    batch_size: int | None = Field(default=None, description="Batch size limit")
+    max_batch: int | None = Field(default=None, description="Maximum batch size")
+    supported_types: list[str] = Field(
+        default_factory=list, description="Supported data types"
+    )
+
+    # Network capabilities
+    routing: bool = Field(default=False, description="Routing capability")
+
+    # Generic feature flag (used in tests)
+    feature: bool = Field(default=False, description="Generic feature flag")
+
+    # Configuration (nested) - uses JsonType for JSON-serializable values.
+    # Supports primitives (str, int, float, bool, None), lists, and nested dicts.
+    config: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Nested configuration (JSON-serializable values)",
+    )
+
+    def __getitem__(self, key: str) -> object:
+        """Enable dict-like access to capabilities.
+
+        Args:
+            key: The capability name to retrieve.
+
+        Returns:
+            The capability value (from known field or model_extra).
+
+        Raises:
+            KeyError: If key is not found in known fields or model_extra.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True, custom=42)
+            >>> caps["postgres"]
+            True
+            >>> caps["custom"]  # Custom capability from model_extra
+            42
+        """
+        if key in type(self).model_fields:
+            return getattr(self, key)
+        extra = self.model_extra or {}
+        if key in extra:
+            return extra[key]
+        raise KeyError(key)
+
+    def __contains__(self, key: object) -> bool:
+        """Enable membership testing for capabilities.
+
+        Returns True if key is a known field OR exists in model_extra.
+
+        Args:
+            key: The capability name to check.
+
+        Returns:
+            True if the key exists as a known field or in model_extra.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True, custom=42)
+            >>> "postgres" in caps
+            True
+            >>> "custom" in caps  # Custom capability in model_extra
+            True
+            >>> "unknown" in caps
+            False
+        """
+        if not isinstance(key, str):
+            return False
+
+        # Check known fields first (access via class to avoid deprecation)
+        if key in type(self).model_fields:
+            return True
+
+        # Check model_extra for custom capabilities
+        return bool(self.model_extra and key in self.model_extra)
+
+    def get(self, key: str, default: object = None) -> object:
+        """Safely get a capability value with optional default.
+
+        Args:
+            key: The capability name to retrieve.
+            default: Value to return if key is not found (defaults to None).
+
+        Returns:
+            The capability value if found, otherwise the default value.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True)
+            >>> caps.get("postgres")
+            True
+            >>> caps.get("unknown", False)
+            False
+            >>> caps.get("unknown")  # Returns None by default
+        """
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+
+__all__ = [
+    "ModelNodeCapabilities",
+]