omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/registration/commands/model_node_registration_acked.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Acknowledged Command Model.
+
+This module provides ModelNodeRegistrationAcked, a command sent by nodes
+to acknowledge their registration in the ONEX 2-way registration pattern.
+
+Command vs Event Distinction:
+    - COMMANDS are imperative requests from external sources
+    - EVENTS are facts about things that have happened
+    - NodeRegistrationAcked is a COMMAND because it's the node requesting
+      acknowledgment of its registration (imperative)
+    - NodeRegistrationAckReceived is the EVENT emitted when the orchestrator
+      processes this command successfully (fact)
+
+Related Tickets:
+    - OMN-888 (C1): Registration Orchestrator
+    - OMN-889 (D1): Registration Reducer
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeRegistrationAcked(BaseModel):
+    """Command: Node acknowledges its registration.
+
+    This is a COMMAND, not an event. Commands are imperative requests
+    from external sources (the node itself in this case) that orchestrators
+    process to make decisions and emit events.
+
+    The orchestrator receives this command and, if valid:
+    1. Emits NodeRegistrationAckReceived event
+    2. Emits NodeBecameActive event (if transitioning to active state)
+
+    Validity Conditions:
+        - Node must be in AWAITING_ACK state (queried from projection)
+        - If node is already ACTIVE, this is a duplicate ack (no-op)
+        - If node is in terminal state, this ack is too late (rejected)
+
+    Attributes:
+        command_id: Unique identifier for this command instance.
+        node_id: The UUID of the node sending the acknowledgment.
+        correlation_id: Correlation ID for distributed tracing, linking
+            this command to the original registration flow.
+        timestamp: When the node sent the acknowledgment.
+
+    Time Injection:
+        The `timestamp` field must be explicitly provided by the caller
+        using an 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
+        >>> ack = ModelNodeRegistrationAcked(
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     timestamp=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ... )
+        >>> assert ack.command_id is not None
+        >>> assert ack.timestamp.tzinfo is not None
+
+    See Also:
+        - ModelNodeRegistrationAckReceived: Event emitted when ack is processed
+        - ModelNodeBecameActive: Event emitted when node becomes active
+        - HandlerNodeRegistrationAcked: Handler that processes this command
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Command identification
+    command_id: UUID = Field(
+        default_factory=uuid4,
+        description="Unique identifier for this command instance.",
+    )
+
+    # Node identification
+    node_id: UUID = Field(
+        ...,
+        description="The UUID of the node sending the acknowledgment.",
+    )
+
+    # Tracing
+    correlation_id: UUID = Field(
+        ...,
+        description=(
+            "Correlation ID for distributed tracing, linking this command "
+            "to the original registration flow."
+        ),
+    )
+
+    # Timestamp - MUST be explicitly injected (no default_factory for testability)
+    timestamp: datetime = Field(
+        ...,
+        description="When the node sent the acknowledgment.",
+    )
+
+
+__all__: list[str] = ["ModelNodeRegistrationAcked"]

omnibase_infra/models/registration/events/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration decision events for C1 Registration Orchestrator.
+
+This module provides event models emitted by the Registration Orchestrator
+during the ONEX 2-way registration workflow. These events represent
+orchestrator decisions and are consumed by the Registration Reducer.
+
+Event Flow:
+    NodeIntrospected (input) -> Orchestrator -> Decision Events (output)
+
+Decision Events:
+    - ModelNodeRegistrationInitiated: Registration attempt started
+    - ModelNodeRegistrationAccepted: Registration accepted by orchestrator
+    - ModelNodeRegistrationRejected: Registration rejected by orchestrator
+    - ModelNodeRegistrationAckTimedOut: Ack deadline passed without acknowledgment
+    - ModelNodeRegistrationAckReceived: Node acknowledged registration
+    - ModelNodeBecameActive: Node transitioned to active state
+    - ModelNodeLivenessExpired: Liveness deadline passed without heartbeat
+
+See Also:
+    - docs/design/ONEX_RUNTIME_REGISTRATION_TICKET_PLAN.md (C1 section)
+    - DESIGN_TWO_WAY_REGISTRATION_ARCHITECTURE.md
+"""
+
+from omnibase_infra.models.registration.events.model_node_became_active import (
+    ModelNodeBecameActive,
+)
+from omnibase_infra.models.registration.events.model_node_liveness_expired import (
+    ModelNodeLivenessExpired,
+)
+from omnibase_infra.models.registration.events.model_node_registration_accepted import (
+    ModelNodeRegistrationAccepted,
+)
+from omnibase_infra.models.registration.events.model_node_registration_ack_received import (
+    ModelNodeRegistrationAckReceived,
+)
+from omnibase_infra.models.registration.events.model_node_registration_ack_timed_out import (
+    ModelNodeRegistrationAckTimedOut,
+)
+from omnibase_infra.models.registration.events.model_node_registration_initiated import (
+    ModelNodeRegistrationInitiated,
+)
+from omnibase_infra.models.registration.events.model_node_registration_rejected import (
+    ModelNodeRegistrationRejected,
+)
+
+__all__ = [
+    "ModelNodeBecameActive",
+    "ModelNodeLivenessExpired",
+    "ModelNodeRegistrationAccepted",
+    "ModelNodeRegistrationAckReceived",
+    "ModelNodeRegistrationAckTimedOut",
+    "ModelNodeRegistrationInitiated",
+    "ModelNodeRegistrationRejected",
+]

omnibase_infra/models/registration/events/model_node_became_active.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Became Active Event Model.
+
+This module provides ModelNodeBecameActive for the ONEX 2-way registration
+pattern. Emitted by the Registration Orchestrator when a node transitions
+to the active state.
+
+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
+
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+
+
+class ModelNodeBecameActive(BaseModel):
+    """Event model for node activation.
+
+    Emitted when the orchestrator transitions a node to the active state.
+    This typically occurs after the node has successfully acknowledged
+    registration and is ready to participate in the cluster.
+
+    The capabilities field captures the node's advertised capabilities
+    at the time of activation, enabling routing and discovery 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 activated node.
+        correlation_id: Correlation ID for distributed tracing across the workflow.
+        causation_id: Message ID of the event that triggered activation.
+        emitted_at: Timestamp when the orchestrator emitted this event (UTC).
+        capabilities: The node's capabilities at activation time.
+            Used for routing and service discovery decisions.
+
+    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
+        >>> from omnibase_infra.models.registration import ModelNodeCapabilities
+        >>> event = ModelNodeBecameActive(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ...     capabilities=ModelNodeCapabilities(postgres=True, read=True),
+        ... )
+    """
+
+    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 activated node",
+    )
+
+    # 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 activation",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="Timestamp when the orchestrator emitted this event (UTC)",
+    )
+
+    # Activation-specific
+    capabilities: ModelNodeCapabilities = Field(
+        ...,
+        description="The node's capabilities at activation time",
+    )
+
+
+__all__ = ["ModelNodeBecameActive"]

omnibase_infra/models/registration/events/model_node_liveness_expired.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Liveness Expired Event Model.
+
+This module provides the event model emitted when an active node fails to
+send heartbeats within the configured liveness deadline.
+
+Related Tickets:
+    - OMN-888 (C1): Registration Orchestrator
+    - OMN-932 (C2): Durable Timeout Handling
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeLivenessExpired(BaseModel):
+    """Event emitted when an active node's liveness deadline has passed.
+
+    This event is produced by the registration orchestrator during RuntimeTick
+    processing when it detects that an ACTIVE node has exceeded its
+    liveness_deadline without sending a heartbeat.
+
+    Event Semantics (per C2 Durable Timeout Handling):
+        - Emitted once per entity per timeout occurrence
+        - Uses emission markers in projection for deduplication
+        - Links to triggering tick via causation_id
+        - Survives orchestrator restarts (deadline stored in projection)
+
+    FSM Impact:
+        This event triggers the FSM transition:
+        ACTIVE -> LIVENESS_EXPIRED (terminal state)
+
+    Attributes:
+        entity_id: The registration entity identifier (same as node_id)
+        node_id: The node UUID that failed liveness check
+        correlation_id: Correlation ID for distributed tracing
+        causation_id: UUID of the RuntimeTick that triggered this event
+        emitted_at: When the liveness expiry was detected (from tick.now)
+        last_heartbeat_at: The timestamp of the last received heartbeat
+
+    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 datetime, UTC, timedelta
+        >>> from uuid import uuid4
+        >>> # Use explicit timestamps (time injection pattern) - not datetime.now()
+        >>> now = datetime(2025, 1, 15, 12, 10, 0, tzinfo=UTC)
+        >>> event = ModelNodeLivenessExpired(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=now,
+        ...     last_heartbeat_at=now - timedelta(minutes=10),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Entity identification
+    entity_id: UUID = Field(
+        ...,
+        description="The registration entity identifier (same as node_id)",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="The node UUID that failed liveness check",
+    )
+
+    # Tracing
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="UUID of the RuntimeTick that triggered this liveness expired event",
+    )
+
+    # Timing - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="When the liveness expiry was detected (from RuntimeTick.now)",
+    )
+    last_heartbeat_at: datetime | None = Field(
+        ...,
+        description="The timestamp of the last received heartbeat (None if never received)",
+    )
+
+
+__all__: list[str] = ["ModelNodeLivenessExpired"]

omnibase_infra/models/registration/events/model_node_registration_accepted.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Accepted Event Model.
+
+This module provides ModelNodeRegistrationAccepted for the ONEX 2-way
+registration pattern. Emitted by the Registration Orchestrator when it
+accepts 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 ModelNodeRegistrationAccepted(BaseModel):
+    """Event model for registration acceptance by the orchestrator.
+
+    Emitted when the orchestrator decides to accept a node's registration.
+    The node must acknowledge this acceptance within the ack_deadline to
+    complete the registration handshake.
+
+    This event triggers the reducer to emit intents for persisting the
+    registration to Consul and PostgreSQL.
+
+    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 event that triggered this decision.
+        emitted_at: Timestamp when the orchestrator emitted this event (UTC).
+        ack_deadline: Deadline by which the node must acknowledge registration.
+            If not acknowledged by this time, NodeRegistrationAckTimedOut is emitted.
+
+    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, timedelta
+        >>> from uuid import uuid4
+        >>> event = ModelNodeRegistrationAccepted(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ...     ack_deadline=datetime(2025, 1, 15, 12, 0, 30, tzinfo=UTC),
+        ... )
+    """
+
+    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 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)",
+    )
+
+    # Registration-specific
+    ack_deadline: datetime = Field(
+        ...,
+        description="Deadline by which the node must acknowledge registration (UTC)",
+    )
+
+
+__all__ = ["ModelNodeRegistrationAccepted"]

omnibase_infra/models/registration/events/model_node_registration_ack_received.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Ack Received Event Model.
+
+This module provides ModelNodeRegistrationAckReceived for the ONEX 2-way
+registration pattern. Emitted by the Registration Orchestrator when it
+receives acknowledgment from the node within the ack_deadline.
+
+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 ModelNodeRegistrationAckReceived(BaseModel):
+    """Event model for registration acknowledgment received.
+
+    Emitted when the orchestrator processes a NodeRegistrationAcked command
+    from the node within the ack_deadline. This completes the handshake and
+    starts the liveness monitoring phase.
+
+    After this event, the node enters a monitored state where it must send
+    heartbeats before the liveness_deadline expires.
+
+    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 that acknowledged registration.
+        correlation_id: Correlation ID for distributed tracing across the workflow.
+        causation_id: Message ID of the NodeRegistrationAcked command.
+        emitted_at: Timestamp when the orchestrator emitted this event (UTC).
+        liveness_deadline: Deadline for the next heartbeat from the node.
+            If no heartbeat is received by this time, NodeLivenessExpired is emitted.
+
+    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, timedelta
+        >>> from uuid import uuid4
+        >>> event = ModelNodeRegistrationAckReceived(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ...     liveness_deadline=datetime(2025, 1, 15, 12, 1, 0, tzinfo=UTC),
+        ... )
+    """
+
+    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 that acknowledged registration",
+    )
+
+    # Tracing and causation
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="Message ID of the NodeRegistrationAcked command",
+    )
+
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="Timestamp when the orchestrator emitted this event (UTC)",
+    )
+
+    # Liveness-specific
+    liveness_deadline: datetime = Field(
+        ...,
+        description="Deadline for the next heartbeat from the node (UTC)",
+    )
+
+
+__all__ = ["ModelNodeRegistrationAckReceived"]

omnibase_infra/models/registration/events/model_node_registration_ack_timed_out.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Registration Ack Timeout Event Model.
+
+This module provides the event model emitted when a node fails to acknowledge
+its registration within the configured deadline.
+
+Related Tickets:
+    - OMN-888 (C1): Registration Orchestrator
+    - OMN-932 (C2): Durable Timeout Handling
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumRegistrationState
+
+
+class ModelNodeRegistrationAckTimedOut(BaseModel):
+    """Event emitted when a node's registration ack deadline has passed.
+
+    This event is produced by the registration orchestrator during RuntimeTick
+    processing when it detects that a node in ACCEPTED or AWAITING_ACK state
+    has exceeded its ack_deadline.
+
+    Event Semantics (per C2 Durable Timeout Handling):
+        - Emitted once per entity per timeout occurrence
+        - Uses emission markers in projection for deduplication
+        - Links to triggering tick via causation_id
+        - Survives orchestrator restarts (deadline stored in projection)
+
+    FSM Impact:
+        This event triggers the FSM transition:
+        AWAITING_ACK -> ACK_TIMED_OUT
+
+    Attributes:
+        entity_id: The registration entity identifier (same as node_id)
+        node_id: The node UUID that failed to acknowledge
+        correlation_id: Correlation ID for distributed tracing
+        causation_id: UUID of the RuntimeTick that triggered this event
+        emitted_at: When the timeout was detected (from tick.now)
+        deadline_at: The original ack deadline that was exceeded
+        previous_state: State before timeout (ACCEPTED or AWAITING_ACK), optional
+
+    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 datetime, UTC, timedelta
+        >>> from uuid import uuid4
+        >>> # Use explicit timestamps (time injection pattern) - not datetime.now()
+        >>> now = datetime(2025, 1, 15, 12, 5, 0, tzinfo=UTC)
+        >>> event = ModelNodeRegistrationAckTimedOut(
+        ...     entity_id=uuid4(),
+        ...     node_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     causation_id=uuid4(),
+        ...     emitted_at=now,
+        ...     deadline_at=now - timedelta(minutes=5),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Entity identification
+    entity_id: UUID = Field(
+        ...,
+        description="The registration entity identifier (same as node_id)",
+    )
+    node_id: UUID = Field(
+        ...,
+        description="The node UUID that failed to acknowledge registration",
+    )
+
+    # Tracing
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    causation_id: UUID = Field(
+        ...,
+        description="UUID of the RuntimeTick that triggered this timeout event",
+    )
+
+    # Timing - MUST be explicitly injected (no default_factory for testability)
+    emitted_at: datetime = Field(
+        ...,
+        description="When the timeout was detected (from RuntimeTick.now)",
+    )
+    deadline_at: datetime = Field(
+        ...,
+        description="The original ack deadline that was exceeded",
+    )
+
+    # State context (optional - provides additional context for FSM processing)
+    previous_state: EnumRegistrationState | None = Field(
+        default=None,
+        description="State before timeout (ACCEPTED or AWAITING_ACK)",
+    )
+
+
+__all__: list[str] = ["ModelNodeRegistrationAckTimedOut"]