omnibase_infra 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

omnibase_infra/__init__.py

@@ -76,7 +76,7 @@ See Also
 - Runtime kernel: omnibase_infra.runtime.service_kernel
 """
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 from . import (
     enums,

omnibase_infra/enums/__init__.py

@@ -36,6 +36,7 @@ Exports:
     EnumNodeOutputType: Node output types for execution shape validation
     EnumNonRetryableErrorCategory: Non-retryable error categories for DLQ
     EnumPolicyType: Policy types for RegistryPolicy plugins
+    EnumPostgresErrorCode: PostgreSQL error codes for contract persistence operations
     EnumRegistrationState: Registration FSM states for two-way registration
     EnumRegistrationStatus: Registration workflow status (IDLE, PENDING, PARTIAL, COMPLETE, FAILED)
     EnumRegistryResponseStatus: Registry operation response status (SUCCESS, PARTIAL, FAILED)
@@ -82,6 +83,7 @@ from omnibase_infra.enums.enum_non_retryable_error_category import (
     EnumNonRetryableErrorCategory,
 )
 from omnibase_infra.enums.enum_policy_type import EnumPolicyType
+from omnibase_infra.enums.enum_postgres_error_code import EnumPostgresErrorCode
 from omnibase_infra.enums.enum_registration_state import EnumRegistrationState
 from omnibase_infra.enums.enum_registration_status import EnumRegistrationStatus
 from omnibase_infra.enums.enum_registry_response_status import (
@@ -123,6 +125,7 @@ __all__: list[str] = [
     "EnumNodeOutputType",
     "EnumNonRetryableErrorCategory",
     "EnumPolicyType",
+    "EnumPostgresErrorCode",
     "EnumRegistrationState",
     "EnumRegistrationStatus",
     "EnumRegistryResponseStatus",

omnibase_infra/enums/enum_consumer_group_purpose.py

@@ -11,6 +11,7 @@ Consumer Group Purpose Categories:
     - REPLAY: Reprocess historical data from earliest offset
     - AUDIT: Compliance and read-only consumption
     - BACKFILL: One-shot bounded consumers for populating derived state
+    - CONTRACT_REGISTRY: Contract lifecycle events (registration, deregistration, heartbeat)
 
 The purpose determines consumer group naming conventions and default
 offset reset policies in the Kafka adapter layer.
@@ -63,6 +64,11 @@ class EnumConsumerGroupPurpose(str, Enum):
             - Naming: {base_group_id}-backfill
             - Pattern: Bounded consumption until caught up
 
+        CONTRACT_REGISTRY: Contract lifecycle events processing.
+            - Default offset reset: latest
+            - Naming: {base_group_id}-contract-registry
+            - Pattern: Continuous consumption of registration, deregistration, heartbeat events
+
     Example:
         >>> purpose = EnumConsumerGroupPurpose.REPLAY
         >>> f"order-processor-{purpose.value}"
@@ -84,6 +90,9 @@ class EnumConsumerGroupPurpose(str, Enum):
     BACKFILL = "backfill"
     """One-shot bounded consumers for populating derived state."""
 
+    CONTRACT_REGISTRY = "contract-registry"
+    """Contract lifecycle events (registration, deregistration, heartbeat)."""
+
     def __str__(self) -> str:
         """Return the string value for serialization."""
         return self.value

omnibase_infra/enums/enum_postgres_error_code.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL Error Code Enumeration.
+
+Defines structured error codes for PostgreSQL persistence operations. These codes
+enable precise error classification, debugging, and programmatic error handling
+for contract registry persistence via NodeContractPersistenceEffect.
+
+Error Code Categories:
+    - Connection errors: Connection, timeout, authentication failures
+    - Operation errors: Specific operation failures (upsert, topic, etc.)
+    - Unknown errors: Catch-all for unclassified failures
+
+Usage:
+    >>> from omnibase_infra.enums import EnumPostgresErrorCode
+    >>> error_code = EnumPostgresErrorCode.CONNECTION_ERROR
+    >>> print(f"Error: {error_code.value}")
+    Error: POSTGRES_CONNECTION_ERROR
+
+    >>> # Check if error is retriable
+    >>> if error_code.is_retriable:
+    ...     print("Will retry operation")
+
+    >>> # Categorize error type
+    >>> if error_code.is_connection_error:
+    ...     print("Connection-level failure")
+
+See Also:
+    - NodeContractPersistenceEffect: Effect node using these error codes
+    - ContractRegistryReducer: Source of intents that may trigger these errors
+    - contract.yaml: Error code definitions in error_handling.error_codes
+"""
+
+from enum import Enum
+
+
+class EnumPostgresErrorCode(str, Enum):
+    """Error codes for PostgreSQL persistence operations.
+
+    These codes provide structured classification for failures during
+    contract registry persistence operations. Each code maps to a specific
+    failure scenario as defined in the contract.yaml error_codes section.
+
+    Connection Errors (retriable):
+        CONNECTION_ERROR: Connection to PostgreSQL server failed.
+            The database server is unreachable or connection was refused.
+            Verify PostgreSQL server is running and network is accessible.
+
+        TIMEOUT_ERROR: PostgreSQL operation exceeded timeout.
+            The operation took longer than the configured timeout threshold.
+            Check database load and query performance.
+
+    Authentication Errors (non-retriable):
+        AUTH_ERROR: Authentication with PostgreSQL server failed.
+            Invalid credentials or insufficient privileges.
+            Verify POSTGRES_USER and POSTGRES_PASSWORD in .env.
+
+    Operation Errors (non-retriable):
+        UPSERT_ERROR: PostgreSQL upsert operation failed.
+            Insert/update of contract record failed due to constraint
+            violation, invalid data, or schema mismatch.
+
+        TOPIC_UPDATE_ERROR: PostgreSQL topic update failed.
+            Failed to update topic routing table. Check JSONB array
+            operations and topic table schema.
+
+        MARK_STALE_ERROR: PostgreSQL mark stale operation failed.
+            Batch staleness marking failed. Check is_stale column
+            and last_seen_at timestamp handling.
+
+        HEARTBEAT_ERROR: PostgreSQL heartbeat update failed.
+            Heartbeat timestamp update failed. Verify contract_id
+            exists and last_seen_at column is writable.
+
+        DEACTIVATE_ERROR: PostgreSQL deactivation failed.
+            Soft delete (is_active=false) failed. Check contract_id
+            validity and is_active column constraints.
+
+        CLEANUP_ERROR: PostgreSQL topic cleanup failed.
+            Failed to remove contract from topic arrays. Check JSONB
+            array manipulation and referential integrity.
+
+    Unknown Errors (non-retriable):
+        UNKNOWN_ERROR: Unknown error during PostgreSQL operation.
+            Catch-all for unclassified PostgreSQL failures.
+            Check logs for underlying exception details.
+    """
+
+    # Connection errors
+    CONNECTION_ERROR = "POSTGRES_CONNECTION_ERROR"
+    TIMEOUT_ERROR = "POSTGRES_TIMEOUT_ERROR"
+    AUTH_ERROR = "POSTGRES_AUTH_ERROR"
+
+    # Operation errors
+    UPSERT_ERROR = "POSTGRES_UPSERT_ERROR"
+    TOPIC_UPDATE_ERROR = "POSTGRES_TOPIC_UPDATE_ERROR"
+    MARK_STALE_ERROR = "POSTGRES_MARK_STALE_ERROR"
+    HEARTBEAT_ERROR = "POSTGRES_HEARTBEAT_ERROR"
+    DEACTIVATE_ERROR = "POSTGRES_DEACTIVATE_ERROR"
+    CLEANUP_ERROR = "POSTGRES_CLEANUP_ERROR"
+
+    # Unknown errors
+    UNKNOWN_ERROR = "POSTGRES_UNKNOWN_ERROR"
+
+    @property
+    def is_retriable(self) -> bool:
+        """Check if this error is retriable.
+
+        Retriable errors indicate transient failures that may succeed
+        on retry, such as connection issues or timeouts. Non-retriable
+        errors indicate permanent failures requiring intervention.
+
+        Returns:
+            True if the error is retriable, False otherwise.
+        """
+        return self in {
+            EnumPostgresErrorCode.CONNECTION_ERROR,
+            EnumPostgresErrorCode.TIMEOUT_ERROR,
+        }
+
+    @property
+    def is_connection_error(self) -> bool:
+        """Check if this is a connection-level error.
+
+        Connection errors indicate infrastructure-level failures
+        rather than operation-specific issues.
+
+        Returns:
+            True if this is a connection-level error.
+        """
+        return self in {
+            EnumPostgresErrorCode.CONNECTION_ERROR,
+            EnumPostgresErrorCode.TIMEOUT_ERROR,
+            EnumPostgresErrorCode.AUTH_ERROR,
+        }
+
+    @property
+    def is_operation_error(self) -> bool:
+        """Check if this is an operation-specific error.
+
+        Operation errors indicate failures in specific database
+        operations rather than infrastructure issues.
+
+        Returns:
+            True if this is an operation-specific error.
+        """
+        return self in {
+            EnumPostgresErrorCode.UPSERT_ERROR,
+            EnumPostgresErrorCode.TOPIC_UPDATE_ERROR,
+            EnumPostgresErrorCode.MARK_STALE_ERROR,
+            EnumPostgresErrorCode.HEARTBEAT_ERROR,
+            EnumPostgresErrorCode.DEACTIVATE_ERROR,
+            EnumPostgresErrorCode.CLEANUP_ERROR,
+        }
+
+    @property
+    def description(self) -> str:
+        """Get human-readable description of the error code.
+
+        Returns:
+            Description string for the error code.
+        """
+        descriptions = {
+            EnumPostgresErrorCode.CONNECTION_ERROR: (
+                "Connection to PostgreSQL server failed"
+            ),
+            EnumPostgresErrorCode.TIMEOUT_ERROR: (
+                "PostgreSQL operation exceeded timeout"
+            ),
+            EnumPostgresErrorCode.AUTH_ERROR: (
+                "Authentication with PostgreSQL server failed"
+            ),
+            EnumPostgresErrorCode.UPSERT_ERROR: "PostgreSQL upsert operation failed",
+            EnumPostgresErrorCode.TOPIC_UPDATE_ERROR: "PostgreSQL topic update failed",
+            EnumPostgresErrorCode.MARK_STALE_ERROR: (
+                "PostgreSQL mark stale operation failed"
+            ),
+            EnumPostgresErrorCode.HEARTBEAT_ERROR: "PostgreSQL heartbeat update failed",
+            EnumPostgresErrorCode.DEACTIVATE_ERROR: "PostgreSQL deactivation failed",
+            EnumPostgresErrorCode.CLEANUP_ERROR: "PostgreSQL topic cleanup failed",
+            EnumPostgresErrorCode.UNKNOWN_ERROR: (
+                "Unknown error during PostgreSQL operation"
+            ),
+        }
+        return descriptions.get(self, "Unknown error")
+
+
+__all__ = ["EnumPostgresErrorCode"]

omnibase_infra/errors/__init__.py

@@ -10,6 +10,7 @@ Exports:
     ModelInfraErrorContext: Configuration model for bundled error context
     RuntimeHostError: Base infrastructure error class
     ProtocolConfigurationError: Protocol configuration validation errors
+    ProtocolDependencyResolutionError: Protocol dependency resolution errors
     SecretResolutionError: Secret/credential resolution errors
     InfraConnectionError: Infrastructure connection errors
     InfraTimeoutError: Infrastructure timeout errors
@@ -115,6 +116,7 @@ from omnibase_infra.errors.error_infra import (
     InfraTimeoutError,
     InfraUnavailableError,
     ProtocolConfigurationError,
+    ProtocolDependencyResolutionError,
     RuntimeHostError,
     SecretResolutionError,
     UnknownHandlerTypeError,
@@ -162,6 +164,8 @@ __all__: list[str] = [
     "ModelTimeoutErrorContext",
     "PolicyRegistryError",
     "ProtocolConfigurationError",
+    # Protocol dependency resolution errors
+    "ProtocolDependencyResolutionError",
     # Repository errors
     "RepositoryContractError",
     "RepositoryError",

omnibase_infra/errors/error_infra.py

@@ -597,6 +597,65 @@ class UnknownHandlerTypeError(RuntimeHostError):
         )
 
 
+class ProtocolDependencyResolutionError(RuntimeHostError):
+    """Raised when protocol dependencies cannot be resolved from container.
+
+    Used when a node's contract.yaml declares protocol dependencies that
+    are not registered in the container's service_registry. This is a
+    fail-fast error that prevents node creation with missing dependencies.
+
+    Example:
+        >>> context = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="resolve_dependencies",
+        ...     target_name="NodeContractPersistenceEffect",
+        ... )
+        >>> raise ProtocolDependencyResolutionError(
+        ...     "Missing required protocols for node",
+        ...     context=context,
+        ...     missing_protocols=["ProtocolPostgresAdapter"],
+        ...     node_name="node_contract_persistence_effect",
+        ... )
+
+    .. versionadded:: 0.x.x
+        Part of OMN-1732 runtime dependency injection.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: ModelInfraErrorContext | None = None,
+        *,
+        missing_protocols: list[str] | None = None,
+        node_name: str | None = None,
+        contract_path: str | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize ProtocolDependencyResolutionError.
+
+        Args:
+            message: Human-readable error message
+            context: Bundled infrastructure context
+            missing_protocols: List of protocol class names that could not be resolved
+            node_name: Name of the node requiring the protocols
+            contract_path: Path to the contract.yaml file (for debugging)
+            **extra_context: Additional context information
+        """
+        if missing_protocols is not None:
+            extra_context["missing_protocols"] = missing_protocols
+        if node_name is not None:
+            extra_context["node_name"] = node_name
+        if contract_path is not None:
+            extra_context["contract_path"] = contract_path
+
+        super().__init__(
+            message=message,
+            error_code=EnumCoreErrorCode.DEPENDENCY_ERROR,
+            context=context,
+            **extra_context,
+        )
+
+
 __all__: list[str] = [
     "EnvelopeValidationError",
     "InfraAuthenticationError",
@@ -604,6 +663,7 @@ __all__: list[str] = [
     "InfraTimeoutError",
     "InfraUnavailableError",
     "ProtocolConfigurationError",
+    "ProtocolDependencyResolutionError",
     "RuntimeHostError",
     "SecretResolutionError",
     "UnknownHandlerTypeError",

omnibase_infra/handlers/__init__.py

@@ -20,6 +20,7 @@ Available Handlers:
 - HandlerGraph: Graph database handler (Memgraph/Neo4j via Bolt protocol)
 - HandlerIntent: Intent storage and query handler wrapping HandlerGraph (demo wiring)
 - HandlerQdrant: Qdrant vector database handler (MVP: create, upsert, search, delete)
+- HandlerSlackWebhook: Slack webhook handler for infrastructure alerting
 
 Response Models:
 - ModelDbQueryPayload: Database query result payload
@@ -45,6 +46,7 @@ from omnibase_infra.handlers.handler_manifest_persistence import (
 )
 from omnibase_infra.handlers.handler_mcp import HandlerMCP
 from omnibase_infra.handlers.handler_qdrant import HandlerQdrant
+from omnibase_infra.handlers.handler_slack_webhook import HandlerSlackWebhook
 from omnibase_infra.handlers.handler_vault import HandlerVault
 from omnibase_infra.handlers.models import (
     ModelConsulHandlerPayload,
@@ -71,6 +73,7 @@ __all__: list[str] = [
     "HandlerManifestPersistence",
     "HandlerMCP",
     "HandlerQdrant",
+    "HandlerSlackWebhook",
     "HandlerVault",
     "ModelConsulHandlerPayload",
     "ModelConsulHandlerResponse",