omnibase_infra 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

omnibase_infra/runtime/models/__init__.py

@@ -47,12 +47,19 @@ Exports:
     ModelSecretResolverMetrics: Resolution metrics for observability
     ModelSecretSourceInfo: Non-sensitive source information for introspection
     ModelRetryPolicy: Retry policy configuration for handler operations
+    ModelTransitionNotificationPublisherMetrics: Metrics for transition notification publisher
+    ModelTransitionNotificationOutboxMetrics: Metrics for transition notification outbox
+    ModelTransitionNotificationOutboxConfig: Configuration for transition notification outbox
+    ModelStateTransitionNotification: State transition notification (re-export from omnibase_core)
+    ModelProjectorNotificationConfig: Configuration for projector notification publishing
     ModelBindingConfig: Configuration for binding a handler to the runtime
     ModelBindingConfigCacheStats: Cache statistics for BindingConfigResolver
     ModelBindingConfigResolverConfig: Configuration for BindingConfigResolver
     ModelConfigCacheEntry: Internal cache entry for BindingConfigResolver
 """
 
+# Re-export from omnibase_core for convenience
+from omnibase_core.models.notifications import ModelStateTransitionNotification
 from omnibase_infra.runtime.enums.enum_config_ref_scheme import EnumConfigRefScheme
 from omnibase_infra.runtime.models.model_batch_lifecycle_result import (
     ModelBatchLifecycleResult,
@@ -110,6 +117,9 @@ from omnibase_infra.runtime.models.model_policy_registration import (
 )
 from omnibase_infra.runtime.models.model_policy_result import ModelPolicyResult
 from omnibase_infra.runtime.models.model_policy_type_filter import ModelPolicyTypeFilter
+from omnibase_infra.runtime.models.model_projector_notification_config import (
+    ModelProjectorNotificationConfig,
+)
 from omnibase_infra.runtime.models.model_projector_plugin_loader_config import (
     ModelProjectorPluginLoaderConfig,
 )
@@ -142,6 +152,15 @@ from omnibase_infra.runtime.models.model_shutdown_batch_result import (
     ModelShutdownBatchResult,
 )
 from omnibase_infra.runtime.models.model_shutdown_config import ModelShutdownConfig
+from omnibase_infra.runtime.models.model_transition_notification_outbox_config import (
+    ModelTransitionNotificationOutboxConfig,
+)
+from omnibase_infra.runtime.models.model_transition_notification_outbox_metrics import (
+    ModelTransitionNotificationOutboxMetrics,
+)
+from omnibase_infra.runtime.models.model_transition_notification_publisher_metrics import (
+    ModelTransitionNotificationPublisherMetrics,
+)
 
 __all__: list[str] = [
     "EnumConfigRefScheme",
@@ -173,6 +192,7 @@ __all__: list[str] = [
     "ModelPolicyRegistration",
     "ModelPolicyResult",
     "ModelPolicyTypeFilter",
+    "ModelProjectorNotificationConfig",
     "ModelProjectorPluginLoaderConfig",
     "ModelProtocolRegistrationConfig",
     "ModelRetryPolicy",
@@ -188,5 +208,9 @@ __all__: list[str] = [
     "ModelSecretSourceSpec",
     "ModelShutdownBatchResult",
     "ModelShutdownConfig",
+    "ModelStateTransitionNotification",
+    "ModelTransitionNotificationOutboxConfig",
+    "ModelTransitionNotificationOutboxMetrics",
+    "ModelTransitionNotificationPublisherMetrics",
     "SecretSourceType",
 ]

omnibase_infra/runtime/models/model_health_check_result.py

@@ -209,10 +209,11 @@ class ModelHealthCheckResult(BaseModel):
                 details=health_response,
             )
         # Non-dict response - treat as details, assume healthy
+        # Convert to string representation for JsonType compatibility
         return cls(
             handler_type=handler_type,
             healthy=True,
-            details={"raw_response": health_response},
+            details={"raw_response": str(health_response)},
         )
 
     def __str__(self) -> str:

omnibase_infra/runtime/models/model_projector_notification_config.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector Notification Configuration Model.
+
+Defines configuration for state transition notification publishing from projectors.
+When configured, the projector will publish notifications to the event bus after
+successful state transitions are committed.
+
+This enables the Observer pattern for orchestrator coordination without tight
+coupling between reducers and workflow coordinators.
+
+Architecture Overview:
+    1. ProjectorShell processes events and persists state changes
+    2. Before commit, the previous state is fetched (if state tracking enabled)
+    3. After successful commit, a notification is published with from_state/to_state
+    4. Orchestrators subscribe to notifications and coordinate downstream workflows
+
+Configuration Fields:
+    - expected_topic: Expected event bus topic for validation/documentation (required).
+        NOTE: The actual publishing topic is determined by TransitionNotificationPublisher.
+        This field accepts "topic" as an alias for backwards compatibility.
+    - state_column: Column name containing the FSM state (required)
+    - aggregate_id_column: Column name containing the aggregate ID (required)
+    - version_column: Column name containing the projection version (optional)
+    - enabled: Whether notifications are enabled (default: True)
+
+Example Usage:
+    >>> from omnibase_infra.runtime.models import ModelProjectorNotificationConfig
+    >>>
+    >>> # Using the preferred field name
+    >>> config = ModelProjectorNotificationConfig(
+    ...     expected_topic="onex.fsm.state.transitions.v1",
+    ...     state_column="current_state",
+    ...     aggregate_id_column="entity_id",
+    ...     version_column="version",
+    ...     enabled=True,
+    ... )
+    >>>
+    >>> # Using the backwards-compatible alias
+    >>> config = ModelProjectorNotificationConfig(
+    ...     topic="onex.fsm.state.transitions.v1",  # alias for expected_topic
+    ...     state_column="current_state",
+    ...     aggregate_id_column="entity_id",
+    ... )
+
+Related Tickets:
+    - OMN-1139: Implement TransitionNotificationPublisher integration with ProjectorShell
+
+Thread Safety:
+    This model is immutable (frozen=True) after creation, making it thread-safe
+    for concurrent read access.
+
+.. versionadded:: 0.8.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelProjectorNotificationConfig(BaseModel):
+    """Configuration for state transition notification publishing.
+
+    When attached to a ProjectorShell via the notification_config parameter,
+    enables automatic publishing of state transition notifications after
+    successful projection commits.
+
+    Attributes:
+        expected_topic: Expected event bus topic for state transition notifications.
+            This field is for documentation and validation purposes only - the actual
+            publishing topic is determined by TransitionNotificationPublisher's
+            configuration. ProjectorShell will log a warning if this value differs
+            from the publisher's configured topic. Example topics:
+            - "onex.fsm.state.transitions.v1"
+            - "registration.state.transitions.v1"
+            Accepts "topic" as an alias for backwards compatibility.
+        state_column: Name of the column that contains the FSM state value.
+            This column must exist in the projection schema and contain string
+            values representing the current state.
+        aggregate_id_column: Name of the column that contains the aggregate ID.
+            This column must exist in the projection schema and typically contains
+            a UUID identifying the aggregate instance.
+        version_column: Optional name of the column that contains the projection
+            version. If specified, the version value will be included in
+            notifications for ordering and idempotency detection.
+        enabled: Whether notification publishing is enabled. Defaults to True.
+            Set to False to disable notifications without removing configuration.
+
+    Example:
+        >>> config = ModelProjectorNotificationConfig(
+        ...     expected_topic="onex.fsm.state.transitions.v1",
+        ...     state_column="current_state",
+        ...     aggregate_id_column="entity_id",
+        ...     version_column="version",
+        ... )
+        >>> config.expected_topic
+        'onex.fsm.state.transitions.v1'
+        >>> config.state_column
+        'current_state'
+        >>> config.enabled
+        True
+
+    Note:
+        The column names specified must match columns defined in the projector's
+        contract schema. The ProjectorShell will validate these column names
+        against the schema at initialization time.
+
+        Important: The expected_topic field does NOT control where notifications
+        are published. The actual topic is determined by TransitionNotificationPublisher.
+        This field exists so ProjectorShell can warn when there's a mismatch between
+        the expected and actual topics, helping catch configuration errors early.
+
+    See Also:
+        - ProjectorShell: Uses this config for notification integration
+        - TransitionNotificationPublisher: Publishes the notifications
+        - ModelStateTransitionNotification: The notification payload model
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+        populate_by_name=True,  # Allow both "expected_topic" and "topic" (alias)
+    )
+
+    expected_topic: str = Field(
+        ...,
+        alias="topic",  # Backwards compatibility
+        min_length=1,
+        max_length=256,
+        pattern=r"^[a-zA-Z][a-zA-Z0-9]*([._-][a-zA-Z0-9]+)*$",
+        description=(
+            "Expected event bus topic for state transition notifications. "
+            "Must start with a letter (a-zA-Z), end with an alphanumeric character, "
+            "and contain only alphanumeric characters with single dots, underscores, "
+            "or hyphens as separators. Consecutive separators (e.g., '..', '--', '__', '.-') "
+            "and trailing separators are not allowed. "
+            "NOTE: This field is for documentation and validation purposes only. "
+            "The actual publishing topic is determined by TransitionNotificationPublisher. "
+            "ProjectorShell will warn if this value differs from the publisher's topic."
+        ),
+    )
+
+    state_column: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        description="Column name containing the FSM state value",
+    )
+
+    aggregate_id_column: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        description="Column name containing the aggregate ID",
+    )
+
+    version_column: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=128,
+        description="Optional column name containing the projection version",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether notification publishing is enabled",
+    )
+
+
+__all__: list[str] = ["ModelProjectorNotificationConfig"]

omnibase_infra/runtime/models/model_transition_notification_outbox_config.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration model for TransitionNotificationOutbox.
+
+This module provides a Pydantic model for configuring the TransitionNotificationOutbox,
+which implements the outbox pattern for guaranteed notification delivery of state
+transition events.
+
+Related:
+    - TransitionNotificationOutbox: The outbox implementation
+    - ModelTransitionNotificationOutboxMetrics: Metrics model for observability
+    - docs/patterns/retry_backoff_compensation_strategy.md: Outbox pattern docs
+
+.. versionadded:: 0.8.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelTransitionNotificationOutboxConfig(BaseModel):
+    """Configuration for TransitionNotificationOutbox.
+
+    This model encapsulates all configuration options for the outbox pattern
+    implementation that ensures at-least-once delivery semantics for state
+    transition notifications.
+
+    The outbox stores notifications in the same database transaction as projections,
+    then processes them asynchronously via a background processor.
+
+    Attributes:
+        outbox_table: PostgreSQL table name for the outbox.
+        batch_size: Maximum notifications to process per batch.
+        poll_interval_seconds: Seconds between polls when idle.
+        query_timeout_seconds: Timeout for database queries.
+        strict_transaction_mode: If True, raises error when store() called
+            outside a transaction context.
+        shutdown_timeout_seconds: Timeout for graceful shutdown.
+        max_retries: Maximum retry attempts before moving to DLQ. None disables DLQ.
+        dlq_topic: Topic name for DLQ (for metrics/logging purposes).
+
+    Example:
+        >>> config = ModelTransitionNotificationOutboxConfig(
+        ...     outbox_table="state_transition_outbox",
+        ...     batch_size=50,
+        ...     poll_interval_seconds=0.5,
+        ...     max_retries=3,
+        ...     dlq_topic="notifications-dlq",
+        ... )
+        >>> outbox = TransitionNotificationOutbox(
+        ...     pool=pool,
+        ...     publisher=publisher,
+        ...     **config.model_dump(),  # Unpack as kwargs
+        ... )
+
+    Related:
+        - TransitionNotificationOutbox: Uses this configuration
+        - ModelTransitionNotificationOutboxMetrics: Runtime metrics
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    outbox_table: str = Field(
+        default="transition_notification_outbox",
+        min_length=1,
+        max_length=63,  # PostgreSQL identifier limit
+        description="PostgreSQL table name for the outbox",
+    )
+    batch_size: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description="Maximum notifications to process per batch",
+    )
+    poll_interval_seconds: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=60.0,
+        description="Seconds between background processor polls when idle",
+    )
+    query_timeout_seconds: float = Field(
+        default=30.0,
+        ge=1.0,
+        le=300.0,
+        description="Timeout in seconds for database queries",
+    )
+    strict_transaction_mode: bool = Field(
+        default=True,
+        description="If True, raises error when store() called outside transaction",
+    )
+    shutdown_timeout_seconds: float = Field(
+        default=10.0,
+        ge=1.0,
+        le=300.0,
+        description="Timeout in seconds for graceful shutdown during stop()",
+    )
+    max_retries: int | None = Field(
+        default=None,
+        ge=1,
+        le=100,
+        description="Maximum retry attempts before moving to DLQ. None disables DLQ",
+    )
+    dlq_topic: str | None = Field(
+        default=None,
+        description="Topic name for DLQ (for metrics/logging purposes)",
+    )
+
+
+__all__: list[str] = [
+    "ModelTransitionNotificationOutboxConfig",
+]

omnibase_infra/runtime/models/model_transition_notification_outbox_metrics.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Transition Notification Outbox Metrics Model.
+
+This module provides a strongly-typed Pydantic model for outbox metrics,
+replacing the untyped dict return from get_metrics().
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelTransitionNotificationOutboxMetrics(BaseModel):
+    """Metrics for transition notification outbox operation.
+
+    This model provides type-safe access to outbox metrics for observability
+    and monitoring purposes.
+
+    Attributes:
+        table_name: The outbox table name.
+        is_running: Whether the background processor is currently running.
+        notifications_stored: Total count of notifications stored in outbox.
+        notifications_processed: Total count of notifications successfully processed.
+        notifications_failed: Total count of notifications that failed processing.
+        notifications_sent_to_dlq: Total count of notifications sent to DLQ after
+            exceeding max retry attempts.
+        dlq_publish_failures: Count of failed DLQ publish attempts.
+        batch_size: Configured batch size for processing.
+        poll_interval_seconds: Configured poll interval in seconds.
+        max_retries: Configured maximum retry attempts before DLQ (None if DLQ disabled).
+        dlq_topic: Configured DLQ topic name (None if DLQ disabled).
+
+    Class Variables:
+        DEFAULT_DLQ_ALERT_THRESHOLD: Recommended threshold for alerting on DLQ
+            unavailability. Non-zero dlq_publish_failures indicate the DLQ is
+            having issues; reaching this threshold suggests operator intervention
+            is needed.
+
+    Observability Helpers:
+        dlq_needs_attention(): Returns True when DLQ publish failures have reached
+            the alert threshold, indicating operator intervention may be needed.
+        pending_dlq_ratio(): Returns the ratio of notifications stuck in DLQ retry
+            state, helping operators understand what fraction of failures are
+            DLQ-related versus normal processing failures.
+    """
+
+    DEFAULT_DLQ_ALERT_THRESHOLD: ClassVar[int] = 3
+    """Recommended threshold for alerting on DLQ unavailability.
+
+    Non-zero dlq_publish_failures indicate the DLQ is having issues. When this
+    threshold is reached, it suggests the DLQ has been unavailable for multiple
+    consecutive attempts and operator intervention is needed to investigate:
+    - Network connectivity to the DLQ broker
+    - DLQ topic existence and permissions
+    - Broker availability and health
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    table_name: str = Field(..., description="The outbox table name")
+    is_running: bool = Field(default=False, description="Whether processor is running")
+    notifications_stored: int = Field(
+        default=0, ge=0, description="Total notifications stored"
+    )
+    notifications_processed: int = Field(
+        default=0, ge=0, description="Total notifications successfully processed"
+    )
+    notifications_failed: int = Field(
+        default=0, ge=0, description="Total notifications that failed processing"
+    )
+    notifications_sent_to_dlq: int = Field(
+        default=0, ge=0, description="Total notifications sent to DLQ"
+    )
+    dlq_publish_failures: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Count of failed DLQ publish attempts. Non-zero values indicate DLQ "
+            "availability issues. Monitor this metric to detect when the DLQ is "
+            "unavailable, which can cause infinite retry loops for notifications "
+            "that have exceeded max_retries."
+        ),
+    )
+    batch_size: int = Field(default=100, ge=1, description="Configured batch size")
+    poll_interval_seconds: float = Field(
+        default=1.0, gt=0, description="Configured poll interval"
+    )
+    max_retries: int | None = Field(
+        default=None, ge=1, description="Max retries before DLQ (None if DLQ disabled)"
+    )
+    dlq_topic: str | None = Field(
+        default=None, description="DLQ topic name (None if DLQ disabled)"
+    )
+
+    def dlq_needs_attention(self) -> bool:
+        """Check if DLQ publish failures have reached the alert threshold.
+
+        This method indicates when the DLQ is experiencing availability issues
+        that may require operator intervention. When True, it suggests:
+
+        - The DLQ has been unavailable for multiple consecutive attempts
+        - Notifications that exceeded max_retries are stuck in retry loops
+        - Operator should investigate DLQ broker connectivity and health
+
+        Returns:
+            False if DLQ is disabled (max_retries is None).
+            True if dlq_publish_failures >= DEFAULT_DLQ_ALERT_THRESHOLD.
+            False otherwise (DLQ is enabled but failures below threshold).
+        """
+        if self.max_retries is None:
+            return False
+        return self.dlq_publish_failures >= self.DEFAULT_DLQ_ALERT_THRESHOLD
+
+    def pending_dlq_ratio(self) -> float:
+        """Calculate the ratio of notifications stuck in DLQ retry state.
+
+        This metric helps operators understand what fraction of failed
+        notifications are DLQ-related versus normal processing failures.
+        A high ratio indicates DLQ availability is the bottleneck.
+
+        Returns:
+            0.0 if DLQ is disabled (max_retries is None).
+            0.0 if no notifications have failed (notifications_failed == 0).
+            Ratio of dlq_publish_failures to notifications_failed otherwise.
+            Formula: dlq_publish_failures / max(1, notifications_failed)
+        """
+        if self.max_retries is None:
+            return 0.0
+        if self.notifications_failed == 0:
+            return 0.0
+        return self.dlq_publish_failures / max(1, self.notifications_failed)
+
+
+__all__: list[str] = ["ModelTransitionNotificationOutboxMetrics"]