omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_registration_orchestrator/contract.yaml

@@ -0,0 +1,482 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# ONEX Node Contract - Registration Orchestrator Node
+#
+# =============================================================================
+# SUBCONTRACT ARCHITECTURE NOTE (PR #79 Nitpick)
+# =============================================================================
+# As this contract grows in complexity, consider extracting sections into
+# subcontracts. ONEX supports 6 subcontract types from ModelContract:
+#
+#   1. fsm_subcontract        - FSM state machine definitions
+#   2. event_subcontract      - Event type definitions and routing
+#   3. aggregation_subcontract - Aggregation/projection rules
+#   4. state_subcontract      - State management configuration
+#   5. routing_subcontract    - Message routing rules
+#   6. caching_subcontract    - Caching strategy definitions
+#
+# Current candidates for extraction:
+#   - handler_routing section (246 lines) -> routing_subcontract
+#   - consumed_events/published_events    -> event_subcontract
+#   - coordination_rules                  -> state_subcontract
+#
+# Extraction pattern:
+#   1. Create subcontracts/ directory
+#   2. Move section to routing_subcontract.yaml
+#   3. Reference: routing_subcontract: !include subcontracts/routing.yaml
+#
+# This keeps the main contract readable while enabling modular evolution.
+# =============================================================================
+#
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "1.0.0"
+name: "node_registration_orchestrator"
+node_type: "ORCHESTRATOR_GENERIC"
+description: "Registration workflow orchestrator that coordinates node lifecycle by calling reducer for intents and effect for execution."
+# MCP (Model Context Protocol) Configuration
+# Exposes this orchestrator as an AI-invocable tool via MCP server
+mcp:
+  expose: true
+  tool_name: "register_node"
+  description: "Register a new ONEX node with the cluster. Handles Consul service registration and PostgreSQL metadata storage. Returns registration status and assigned service ID."
+  timeout_seconds: 30
+input_model:
+  name: "ModelOrchestratorInput"
+  module: "omnibase_infra.nodes.node_registration_orchestrator.models"
+  description: "Input containing introspection event and workflow configuration."
+output_model:
+  name: "ModelOrchestratorOutput"
+  module: "omnibase_infra.nodes.node_registration_orchestrator.models"
+  description: "Output containing dual registration outcome and workflow status."
+# OMN-973: Time injection context for timeout evaluation
+# Implemented in omnibase_infra#66. The DispatchContextEnforcer injects `now`
+# timestamps from RuntimeTick events into orchestrator dispatch context, enabling
+# deterministic timeout evaluation. This contract declares the time injection
+# configuration that the orchestrator uses for workflow step execution.
+time_injection:
+  enabled: true
+  source: "RuntimeTick"
+  field: "now"
+  description: "Use injected timestamp from RuntimeTick for timeout evaluation"
+# OMN-930: Projection reader integration for state decisions
+# Implemented in omnibase_spi#44. ProtocolProjectionReader is now defined in
+# omnibase_spi.protocols, enabling dependency injection of projection readers.
+# The orchestrator resolves projection_reader as a dependency, and the
+# "read_projection" workflow step can invoke ProjectionReaderRegistration
+# to query current registration state for decision-making.
+projection_reader:
+  protocol: "ProtocolProjectionReader"
+  module: "omnibase_spi.protocols"
+  projections:
+    - name: "node_registration_state"
+      description: "Current registration state for all nodes"
+# Workflow Coordination Configuration
+# ====================================
+# Design Decision: Single Source of Truth for Coordination Settings
+#
+# CONSOLIDATION NOTE (PR #57 Review):
+# Previously, coordination settings could appear at two levels:
+#   1. Top-level workflow_coordination (parallel_execution, timeouts, etc.)
+#   2. Nested coordination_rules within workflow_definition
+#
+# This created ambiguity about which settings took precedence. The resolution:
+# ALL coordination settings are now consolidated ONLY within coordination_rules
+# (nested under workflow_definition). This eliminates duplication and ambiguity.
+#
+# Configuration Hierarchy (Single Source of Truth):
+# ┌─────────────────────────────────────────────────────────────────────────┐
+# │ workflow_coordination                                                    │
+# │   └── workflow_definition                                               │
+# │         ├── workflow_metadata     → Name, version, description          │
+# │         ├── execution_graph       → DAG of nodes with dependencies      │
+# │         └── coordination_rules    → ALL coordination settings:          │
+# │               ├── execution_mode, parallel_execution_allowed            │
+# │               ├── max_parallel_branches                                 │
+# │               ├── failure_recovery_strategy, max_retries                │
+# │               ├── timeout_ms                                            │
+# │               ├── checkpoint_enabled, checkpoint_interval_ms            │
+# │               ├── state_persistence_enabled                             │
+# │               └── rollback_enabled                                      │
+# └─────────────────────────────────────────────────────────────────────────┘
+#
+# IMPORTANT: No coordination settings exist at the workflow_coordination level
+# itself. All such settings MUST be placed in coordination_rules to ensure
+# a single authoritative source for all coordination behavior.
+workflow_coordination:
+  workflow_definition:
+    workflow_metadata:
+      workflow_name: "node_registration_workflow"
+      workflow_version:
+        major: 1
+        minor: 0
+        patch: 0
+      description: "Registers nodes with Consul and PostgreSQL based on introspection events"
+    execution_graph:
+      nodes:
+        - node_id: "receive_introspection"
+          node_type: EFFECT_GENERIC
+          description: "Receive introspection, tick, or ack events"
+          step_config:
+            event_pattern: ["node-introspection.*", "registry-request-introspection.*", "runtime-tick.*", "node-registration-acked.*"]
+        # OMN-930: Reads current registration state via ProtocolProjectionReader.
+        # Uses ProjectionReaderRegistration to query node_registration_state.
+        - node_id: "read_projection"
+          node_type: EFFECT_GENERIC
+          description: "Read current registration state from projection"
+          depends_on: ["receive_introspection"]
+          step_config:
+            protocol: "ProtocolProjectionReader"
+            operation: "read_projection"
+            projection_name: "node_registration_state"
+        # OMN-973: Evaluates timeout using injected `now` from dispatch context.
+        # The DispatchContextEnforcer injects time from RuntimeTick events.
+        - node_id: "evaluate_timeout"
+          node_type: COMPUTE_GENERIC
+          description: "Evaluate timeout based on injected now from RuntimeTick"
+          depends_on: ["read_projection"]
+          step_config:
+            time_injection: true
+            timeout_evaluation: true
+        - node_id: "compute_intents"
+          node_type: REDUCER_GENERIC
+          description: "Compute registration intents from introspection event"
+          depends_on: ["evaluate_timeout"]
+          step_config:
+            reducer_protocol: "ProtocolReducer"
+            output_type: "list[ModelRegistrationIntent]"
+        - node_id: "execute_consul_registration"
+          node_type: EFFECT_GENERIC
+          description: "Execute Consul registration intent"
+          depends_on: ["compute_intents"]
+          step_config:
+            effect_node: "node_registry_effect"
+            intent_filter: "consul.*"
+        - node_id: "execute_postgres_registration"
+          node_type: EFFECT_GENERIC
+          description: "Execute PostgreSQL registration intent"
+          depends_on: ["compute_intents"]
+          step_config:
+            effect_node: "node_registry_effect"
+            intent_filter: "postgres.*"
+        - node_id: "aggregate_results"
+          node_type: COMPUTE_GENERIC
+          description: "Aggregate registration results"
+          depends_on: ["execute_consul_registration", "execute_postgres_registration"]
+          step_config:
+            aggregation_strategy: "all_or_partial"
+        - node_id: "publish_outcome"
+          node_type: EFFECT_GENERIC
+          description: "Publish registration outcome event"
+          depends_on: ["aggregate_results"]
+          step_config:
+            event_type: "NodeRegistrationResultEvent"
+    # ┌─────────────────────────────────────────────────────────────────────────┐
+    # │ COORDINATION RULES (Single Source of Truth - See header comments)        │
+    # ├─────────────────────────────────────────────────────────────────────────┤
+    # │ This section contains ALL coordination settings for the workflow.        │
+    # │ Per PR #57 consolidation, no coordination settings exist elsewhere.      │
+    # │ Settings are grouped by concern:                                         │
+    # │   - Execution mode (parallel vs sequential)                              │
+    # │   - Failure handling and recovery                                        │
+    # │   - Timeouts                                                             │
+    # │   - Checkpointing and state persistence                                  │
+    # │   - Rollback configuration                                               │
+    # └─────────────────────────────────────────────────────────────────────────┘
+    #
+    # Parallel Execution Design:
+    # The workflow uses parallel mode to execute Consul and Postgres registrations
+    # concurrently. Both depend only on compute_intents, so they run in the same
+    # wave. Error handling ensures one failure doesn't block the other's cleanup.
+    # See: omnibase_core.utils.workflow_executor._execute_parallel for wave-based
+    # parallel execution with proper error aggregation.
+    coordination_rules:
+      # Execution mode configuration
+      # PARALLEL: Steps with same dependencies run concurrently (wave-based)
+      # - execute_consul_registration and execute_postgres_registration run in parallel
+      # - Both depend only on compute_intents, so they form a single wave
+      # - Reduces latency for successful registrations
+      execution_mode: parallel
+      parallel_execution_allowed: true
+      max_parallel_branches: 2
+      # ┌─────────────────────────────────────────────────────────────────────┐
+      # │ WORKFLOW STEP RETRIES (coordination_rules.max_retries)              │
+      # ├─────────────────────────────────────────────────────────────────────┤
+      # │ Purpose: Retry an entire workflow step when it fails.               │
+      # │                                                                     │
+      # │ Behavior: If a step (e.g., execute_consul_registration) fails,      │
+      # │ the orchestrator will retry the ENTIRE step up to max_retries       │
+      # │ times before marking the workflow as failed.                        │
+      # │                                                                     │
+      # │ Use Case: Transient failures at the workflow coordination level,    │
+      # │ such as temporary network partitions or resource contention.        │
+      # │                                                                     │
+      # │ DISTINCT FROM: error_handling.retry_policy.max_retries which         │
+      # │ provides error-specific retries with exponential backoff.           │
+      # │                                                                     │
+      # │ Cross-reference: See error_handling.retry_policy section for        │
+      # │ error-level retry configuration.                                    │
+      # └─────────────────────────────────────────────────────────────────────┘
+      failure_recovery_strategy: retry
+      max_retries: 3 # Workflow step retry count (see box above)
+      recovery_enabled: true
+      # Timeout configuration
+      timeout_ms: 30000
+      # Checkpoint and state persistence
+      checkpoint_enabled: true
+      checkpoint_interval_ms: 5000
+      # NOTE: state_persistence_enabled is defined in ModelWorkflowConfig but the
+      # workflow execution layer does NOT read or use this flag yet. Kept true for
+      # forward compatibility. Actual persistence happens via direct projector calls.
+      state_persistence_enabled: true
+      # Rollback configuration
+      rollback_enabled: true
+consumed_events:
+  - topic: "{env}.{namespace}.onex.evt.node-introspection.v1"
+    event_type: "NodeIntrospectionEvent"
+  - topic: "{env}.{namespace}.onex.evt.registry-request-introspection.v1"
+    event_type: "RegistryRequestIntrospectionEvent"
+  - topic: "{env}.{namespace}.onex.internal.runtime-tick.v1"
+    event_type: "RuntimeTick"
+    internal: true
+    description: "Internal tick for timeout evaluation"
+  - topic: "{env}.{namespace}.onex.cmd.node-registration-acked.v1"
+    event_type: "NodeRegistrationAcked"
+    message_category: "COMMAND"
+    description: "Node acknowledges registration acceptance"
+  # OMN-1006: Node heartbeat events for liveness tracking
+  # Heartbeats update last_heartbeat_at and extend liveness_deadline in the
+  # registration projection. The HandlerNodeHeartbeat processes these events.
+  # Note: direct_handler=true indicates this event bypasses the workflow and is
+  # handled by a dedicated handler (HandlerNodeHeartbeat) via handle_heartbeat().
+  - topic: "{env}.{namespace}.onex.evt.node-heartbeat.v1"
+    event_type: "NodeHeartbeatEvent"
+    description: "Periodic heartbeat from active nodes for liveness tracking"
+    direct_handler: true
+# Handler Routing Configuration
+# ==============================
+# Declarative mapping of consumed events to handler implementations.
+# This section defines the event-to-handler routing that the orchestrator
+# performs at runtime. Each handler is stateless and returns EVENTS only.
+#
+# Handler Pattern (from omnibase_infra/nodes/node_registration_orchestrator/handlers/):
+#   async def handle(event, now, correlation_id) -> list[BaseModel]
+#
+# All handlers:
+#   - Receive `now` parameter for deterministic time-based decisions
+#   - Query projection state via ProjectionReaderRegistration (read-only)
+#   - Return a list of event models (never intents or projections)
+#   - Are coroutine-safe for concurrent async calls with different event instances
+handler_routing:
+  # Handler routing is keyed by the model class name of the event payload.
+  # The orchestrator extracts the payload from ModelEventEnvelope and routes
+  # based on isinstance() checks in the order specified below.
+  routing_strategy: "payload_type_match"
+  handlers:
+    # ModelNodeIntrospectionEvent -> HandlerNodeIntrospected
+    # Canonical registration trigger - node announces itself to the cluster.
+    # Queries projection state and emits NodeRegistrationInitiated if:
+    #   - Node is new (no projection exists)
+    #   - Node is in retriable state (LIVENESS_EXPIRED, REJECTED, ACK_TIMED_OUT)
+    - event_model:
+        name: "ModelNodeIntrospectionEvent"
+        module: "omnibase_infra.models.registration.model_node_introspection_event"
+      handler:
+        name: "HandlerNodeIntrospected"
+        module: "omnibase_infra.nodes.node_registration_orchestrator.handlers.handler_node_introspected"
+      output_events:
+        - "ModelNodeRegistrationInitiated"
+      state_decision_matrix:
+        - current_state: null
+          action: "emit_registration_initiated"
+          description: "New node - initiate registration"
+        - current_state: "LIVENESS_EXPIRED"
+          action: "emit_registration_initiated"
+          description: "Re-registration after liveness expiry"
+        - current_state: "REJECTED"
+          action: "emit_registration_initiated"
+          description: "Retry after rejection"
+        - current_state: "ACK_TIMED_OUT"
+          action: "emit_registration_initiated"
+          description: "Retry after ack timeout"
+        - current_state: "PENDING_REGISTRATION"
+          action: "no_op"
+          description: "Already processing"
+        - current_state: "ACCEPTED"
+          action: "no_op"
+          description: "Waiting for ack"
+        - current_state: "AWAITING_ACK"
+          action: "no_op"
+          description: "Waiting for ack"
+        - current_state: "ACK_RECEIVED"
+          action: "no_op"
+          description: "Transitioning to active"
+        - current_state: "ACTIVE"
+          action: "no_op"
+          description: "Already active - use heartbeat"
+    # ModelRuntimeTick -> HandlerRuntimeTick
+    # Periodic timeout detection - evaluates pending registrations for timeouts.
+    # Queries all entities in timeout-eligible states and emits:
+    #   - NodeRegistrationAckTimedOut for expired ack deadlines
+    #   - NodeLivenessExpired for expired liveness deadlines
+    - event_model:
+        name: "ModelRuntimeTick"
+        module: "omnibase_infra.runtime.models.model_runtime_tick"
+      handler:
+        name: "HandlerRuntimeTick"
+        module: "omnibase_infra.nodes.node_registration_orchestrator.handlers.handler_runtime_tick"
+      output_events:
+        - "ModelNodeRegistrationAckTimedOut"
+        - "ModelNodeLivenessExpired"
+      timeout_evaluation:
+        uses_injected_now: true
+        queries_pending_entities: true
+        state_filters:
+          - "AWAITING_ACK"
+          - "ACTIVE"
+    # ModelNodeRegistrationAcked -> HandlerNodeRegistrationAcked
+    # Acknowledgment processing - node confirms it received registration acceptance.
+    # Validates state transition and emits:
+    #   - NodeRegistrationAckReceived for successful acknowledgment
+    #   - NodeBecameActive when transitioning to active state
+    - event_model:
+        name: "ModelNodeRegistrationAcked"
+        module: "omnibase_infra.models.registration.commands.model_node_registration_acked"
+      handler:
+        name: "HandlerNodeRegistrationAcked"
+        module: "omnibase_infra.nodes.node_registration_orchestrator.handlers.handler_node_registration_acked"
+      message_category: "COMMAND"
+      output_events:
+        - "ModelNodeRegistrationAckReceived"
+        - "ModelNodeBecameActive"
+      state_transition:
+        valid_from_states:
+          - "AWAITING_ACK"
+        target_state: "ACTIVE"
+    # ModelNodeHeartbeatEvent -> HandlerNodeHeartbeat
+    # Heartbeat processing - updates liveness tracking for active nodes.
+    - event_model:
+        name: "ModelNodeHeartbeatEvent"
+        module: "omnibase_infra.models.registration.model_node_heartbeat_event"
+      handler:
+        name: "HandlerNodeHeartbeat"
+        module: "omnibase_infra.nodes.node_registration_orchestrator.handlers.handler_node_heartbeat"
+      output_events: []
+      direct_handler: true
+      description: "Updates node liveness tracking via heartbeat"
+  # Handler initialization configuration
+  # All handlers share the same projection reader dependency
+  handler_dependencies:
+    projection_reader:
+      protocol: "ProtocolProjectionReader"
+      implementation: "ProjectionReaderRegistration"
+      module: "omnibase_infra.projectors.projection_reader_registration"
+      shared: true
+      description: "Shared projection reader for all handlers"
+published_events:
+  - topic: "{env}.{namespace}.onex.evt.node-registration-result.v1"
+    event_type: "NodeRegistrationResultEvent"
+  - topic: "{env}.{namespace}.onex.evt.node-registration-initiated.v1"
+    event_type: "NodeRegistrationInitiated"
+  - topic: "{env}.{namespace}.onex.evt.node-registration-accepted.v1"
+    event_type: "NodeRegistrationAccepted"
+  - topic: "{env}.{namespace}.onex.evt.node-registration-rejected.v1"
+    event_type: "NodeRegistrationRejected"
+  - topic: "{env}.{namespace}.onex.evt.node-registration-ack-timed-out.v1"
+    event_type: "NodeRegistrationAckTimedOut"
+  - topic: "{env}.{namespace}.onex.evt.node-registration-ack-received.v1"
+    event_type: "NodeRegistrationAckReceived"
+  - topic: "{env}.{namespace}.onex.evt.node-became-active.v1"
+    event_type: "NodeBecameActive"
+  - topic: "{env}.{namespace}.onex.evt.node-liveness-expired.v1"
+    event_type: "NodeLivenessExpired"
+intent_consumption:
+  subscribed_intents:
+    - "consul.register"
+    - "consul.deregister"
+    - "postgres.upsert_registration"
+  intent_routing_table:
+    "consul.register": "node_registry_effect"
+    "consul.deregister": "node_registry_effect"
+    "postgres.upsert_registration": "node_registry_effect"
+dependencies:
+  - name: "reducer_protocol"
+    type: "protocol"
+    description: "Protocol for calling reducer to get intents."
+  - name: "effect_node"
+    type: "node"
+    module: "omnibase_infra.nodes.node_registry_effect"
+    description: "Effect node for executing intents."
+  # OMN-930: ProtocolProjectionReader is defined in omnibase_spi.protocols.
+  - name: "projection_reader"
+    type: "protocol"
+    module: "omnibase_spi.protocols"
+    description: "Protocol for reading projection state."
+# Error Handling Configuration
+# =============================
+# ┌─────────────────────────────────────────────────────────────────────────────┐
+# │ ERROR-LEVEL RETRIES (error_handling.retry_policy.max_retries)               │
+# ├─────────────────────────────────────────────────────────────────────────────┤
+# │ Purpose: Retry specific error types with exponential backoff.               │
+# │                                                                             │
+# │ Behavior: When a specific error type occurs (e.g., ConnectionError),        │
+# │ retry the failing operation with exponential backoff delays:                │
+# │   - 1st retry: 100ms delay                                                  │
+# │   - 2nd retry: 200ms delay                                                  │
+# │   - 3rd retry: 400ms delay (capped at max_delay_ms)                         │
+# │                                                                             │
+# │ Use Case: Transient infrastructure errors that may resolve quickly,         │
+# │ such as database connection timeouts or temporary service unavailability.   │
+# │                                                                             │
+# │ DISTINCT FROM: coordination_rules.max_retries which retries entire          │
+# │ workflow steps without backoff delays.                                      │
+# │                                                                             │
+# │ Interaction: Both retry mechanisms can be active simultaneously:            │
+# │   1. Error-level retry attempts the operation with backoff                  │
+# │   2. If all error-level retries fail, the step fails                        │
+# │   3. Workflow step retry then retries the entire step                       │
+# │                                                                             │
+# │ Cross-reference: See coordination_rules.max_retries for workflow step       │
+# │ retry configuration.                                                        │
+# └─────────────────────────────────────────────────────────────────────────────┘
+error_handling:
+  retry_policy:
+    max_retries: 3 # Error-level retry count (see box above)
+    initial_delay_ms: 100
+    max_delay_ms: 5000
+    exponential_base: 2
+    retry_on:
+      - "EffectExecutionError"
+      - "ConnectionError"
+      - "TimeoutError"
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout_ms: 60000
+  error_types:
+    - name: "ReducerError"
+      description: "Error from reducer during intent generation"
+      recoverable: true
+      retry_strategy: "none"
+    - name: "EffectExecutionError"
+      description: "Error from effect node during intent execution"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "AggregationError"
+      description: "Error during result aggregation"
+      recoverable: false
+      retry_strategy: "none"
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+metadata:
+  author: "OmniNode Team"
+  created: "2025-12-18"
+  tags:
+    - "orchestrator"
+    - "registration"
+    - "workflow"
+    - "mvp"

omnibase_infra/nodes/node_registration_orchestrator/dispatchers/__init__.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration dispatcher adapters for MessageDispatchEngine integration.
+
+This module provides ProtocolMessageDispatcher adapters that wrap the
+registration orchestrator handlers for integration with MessageDispatchEngine's
+category-based routing.
+
+Available Dispatchers:
+    - DispatcherNodeIntrospected: Handles ModelNodeIntrospectionEvent (EVENT)
+    - DispatcherRuntimeTick: Handles ModelRuntimeTick (EVENT)
+    - DispatcherNodeRegistrationAcked: Handles ModelNodeRegistrationAcked (COMMAND)
+
+Usage:
+    The dispatchers are typically wired via wire_registration_dispatchers()
+    in the domain wiring module (wiring.py), but can also be created directly:
+
+    >>> from omnibase_infra.nodes.node_registration_orchestrator.dispatchers import (
+    ...     DispatcherNodeIntrospected,
+    ... )
+    >>> dispatcher = DispatcherNodeIntrospected(handler_instance)
+    >>> engine.register_dispatcher(dispatcher)
+
+Design:
+    Each dispatcher:
+    - Implements ProtocolMessageDispatcher protocol
+    - Wraps a registration handler (HandlerNode*, HandlerRuntimeTick)
+    - Handles deserialization from ModelEventEnvelope to typed payload
+    - Injects time via dispatch context (ORCHESTRATOR node kind)
+    - Returns ModelDispatchResult with structured success/error info
+
+Related:
+    - OMN-888: Registration Orchestrator
+    - OMN-892: 2-way Registration E2E Integration Test
+    - OMN-934: Message Dispatch Engine
+    - OMN-1346: Registration Code Extraction
+"""
+
+from omnibase_infra.nodes.node_registration_orchestrator.dispatchers.dispatcher_node_introspected import (
+    DispatcherNodeIntrospected,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.dispatchers.dispatcher_node_registration_acked import (
+    DispatcherNodeRegistrationAcked,
+)
+from omnibase_infra.nodes.node_registration_orchestrator.dispatchers.dispatcher_runtime_tick import (
+    DispatcherRuntimeTick,
+)
+
+__all__: list[str] = [
+    "DispatcherNodeIntrospected",
+    "DispatcherNodeRegistrationAcked",
+    "DispatcherRuntimeTick",
+]