omnibase_infra 0.3.1__py3-none-any.whl → 0.3.2__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.3.2"
 
 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/handlers/registration_storage/handler_registration_storage_postgres.py

@@ -50,6 +50,7 @@ import asyncpg
 
 from omnibase_core.container import ModelONEXContainer
 from omnibase_core.enums.enum_node_kind import EnumNodeKind
+from omnibase_core.models.primitives.model_semver import ModelSemVer
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import (
     InfraConnectionError,
@@ -87,6 +88,9 @@ DEFAULT_POOL_SIZE = 10
 DEFAULT_TIMEOUT_SECONDS = 30.0
 
 # SQL statements
+# NOTE: Database column is `registered_at` but model uses `created_at`. The column
+# is aliased in queries for mapping. This aligns with the existing database schema
+# on 192.168.86.200 which uses `registered_at` for the creation timestamp.
 SQL_CREATE_TABLE = """
 CREATE TABLE IF NOT EXISTS node_registrations (
     node_id UUID PRIMARY KEY,
@@ -95,13 +99,13 @@ CREATE TABLE IF NOT EXISTS node_registrations (
     capabilities JSONB NOT NULL DEFAULT '[]',
     endpoints JSONB NOT NULL DEFAULT '{}',
     metadata JSONB NOT NULL DEFAULT '{}',
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    registered_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 """
 
 SQL_UPSERT = """
-INSERT INTO node_registrations (node_id, node_type, node_version, capabilities, endpoints, metadata, created_at, updated_at)
+INSERT INTO node_registrations (node_id, node_type, node_version, capabilities, endpoints, metadata, registered_at, updated_at)
 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
 ON CONFLICT (node_id) DO UPDATE SET
     node_type = EXCLUDED.node_type,
@@ -114,7 +118,7 @@ RETURNING (xmax = 0) AS was_insert;
 """
 
 SQL_QUERY_BASE = """
-SELECT node_id, node_type, node_version, capabilities, endpoints, metadata, created_at, updated_at
+SELECT node_id, node_type, node_version, capabilities, endpoints, metadata, registered_at AS created_at, updated_at
 FROM node_registrations
 """
 
@@ -384,9 +388,9 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
                 result = await asyncio.wait_for(
                     conn.fetchrow(
                         SQL_UPSERT,
-                        record.node_id,
+                        str(record.node_id),  # VARCHAR column requires string
                         record.node_type.value,
-                        record.node_version,
+                        str(record.node_version),  # VARCHAR column requires string
                         capabilities_json,
                         endpoints_json,
                         metadata_json,
@@ -502,7 +506,7 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
             # Filter by node_id if specified (exact match)
             if query.node_id is not None:
                 conditions.append(f"node_id = ${param_idx}")
-                params.append(query.node_id)
+                params.append(str(query.node_id))  # VARCHAR column requires string
                 param_idx += 1
 
             # Filter by node_type if specified
@@ -531,15 +535,15 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
             count_params = params[:-2]  # Exclude limit and offset
 
             async with pool.acquire() as conn:
-                rows, count_result = await asyncio.gather(
-                    asyncio.wait_for(
-                        conn.fetch(sql_query, *params),
-                        timeout=self._timeout_seconds,
-                    ),
-                    asyncio.wait_for(
-                        conn.fetchval(count_query, *count_params),
-                        timeout=self._timeout_seconds,
-                    ),
+                # NOTE: asyncpg connections don't support concurrent operations,
+                # so we run these queries sequentially instead of with asyncio.gather
+                rows = await asyncio.wait_for(
+                    conn.fetch(sql_query, *params),
+                    timeout=self._timeout_seconds,
+                )
+                count_result = await asyncio.wait_for(
+                    conn.fetchval(count_query, *count_params),
+                    timeout=self._timeout_seconds,
                 )
 
             # Reset circuit breaker on success
@@ -555,11 +559,14 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
                 endpoints = json.loads(row["endpoints"]) if row["endpoints"] else {}
                 metadata = json.loads(row["metadata"]) if row["metadata"] else {}
 
+                # Convert database types to model types:
+                # - node_id: VARCHAR -> UUID
+                # - node_version: VARCHAR -> ModelSemVer
                 records.append(
                     ModelRegistrationRecord(
-                        node_id=row["node_id"],
+                        node_id=UUID(row["node_id"]),
                         node_type=EnumNodeKind(row["node_type"]),
-                        node_version=row["node_version"],
+                        node_version=ModelSemVer.parse(row["node_version"]),
                         capabilities=capabilities,
                         endpoints=endpoints,
                         metadata=metadata,
@@ -684,11 +691,11 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
                 result = await asyncio.wait_for(
                     conn.fetchval(
                         SQL_UPDATE,
-                        node_id,
+                        str(node_id),  # VARCHAR column requires string
                         capabilities_json,
                         endpoints_json,
                         metadata_json,
-                        node_version,
+                        str(node_version) if node_version is not None else None,
                     ),
                     timeout=self._timeout_seconds,
                 )
@@ -792,7 +799,9 @@ class HandlerRegistrationStoragePostgres(MixinAsyncCircuitBreaker):
 
             async with pool.acquire() as conn:
                 result = await asyncio.wait_for(
-                    conn.fetchval(SQL_DELETE, node_id),
+                    conn.fetchval(
+                        SQL_DELETE, str(node_id)
+                    ),  # VARCHAR column requires string
                     timeout=self._timeout_seconds,
                 )
 

omnibase_infra/mixins/__init__.py

@@ -7,6 +7,7 @@ Reusable mixin classes providing:
 - Infrastructure error integration
 - Correlation ID propagation
 - Configurable behavior
+- PostgreSQL error response building for effect persistence
 
 Exports (in __all__):
     Mixins:
@@ -14,8 +15,13 @@ Exports (in __all__):
         - MixinDictLikeAccessors: Dictionary-style access helpers
         - MixinEnvelopeExtraction: Event envelope extraction utilities
         - MixinNodeIntrospection: Node capability introspection
+        - MixinPostgresErrorResponse: PostgreSQL exception handling for persistence
+        - MixinPostgresOpExecutor: PostgreSQL operation execution with error handling
         - MixinRetryExecution: Retry logic with exponential backoff
 
+    Dataclasses:
+        - PostgresErrorContext: Context for PostgreSQL error handling
+
     Protocols (co-located with their tightly-coupled mixins):
         - ProtocolCircuitBreakerAware: Interface for circuit breaker capability.
           Co-located here because it is tightly coupled to MixinAsyncCircuitBreaker.
@@ -48,6 +54,11 @@ from omnibase_infra.mixins.mixin_async_circuit_breaker import MixinAsyncCircuitB
 from omnibase_infra.mixins.mixin_dict_like_accessors import MixinDictLikeAccessors
 from omnibase_infra.mixins.mixin_envelope_extraction import MixinEnvelopeExtraction
 from omnibase_infra.mixins.mixin_node_introspection import MixinNodeIntrospection
+from omnibase_infra.mixins.mixin_postgres_error_response import (
+    MixinPostgresErrorResponse,
+    PostgresErrorContext,
+)
+from omnibase_infra.mixins.mixin_postgres_op_executor import MixinPostgresOpExecutor
 from omnibase_infra.mixins.mixin_retry_execution import MixinRetryExecution
 from omnibase_infra.mixins.protocol_circuit_breaker_aware import (
     ProtocolCircuitBreakerAware,
@@ -63,6 +74,9 @@ __all__: list[str] = [
     "MixinDictLikeAccessors",
     "MixinEnvelopeExtraction",
     "MixinNodeIntrospection",
+    "MixinPostgresErrorResponse",
+    "MixinPostgresOpExecutor",
+    "PostgresErrorContext",
     "MixinRetryExecution",
     "ModelCircuitBreakerConfig",
     "ModelRetryErrorClassification",