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

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",

omnibase_infra/mixins/mixin_node_introspection.py

@@ -154,6 +154,7 @@ Usage:
             config = ModelIntrospectionConfig(
                 node_id=node_config.node_id,
                 node_type=EnumNodeKind.EFFECT,
+                node_name="my_node",
                 event_bus=event_bus,
             )
             self.initialize_introspection(config)
@@ -214,6 +215,7 @@ from omnibase_infra.capabilities import ContractCapabilityExtractor
 from omnibase_infra.constants_topic_patterns import TOPIC_NAME_PATTERN
 from omnibase_infra.enums import EnumInfraTransportType, EnumIntrospectionReason
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+from omnibase_infra.models import ModelNodeIdentity
 from omnibase_infra.models.discovery import (
     ModelDiscoveredCapabilities,
     ModelIntrospectionConfig,
@@ -422,6 +424,7 @@ class MixinNodeIntrospection:
                 config = ModelIntrospectionConfig(
                     node_id=node_id,
                     node_type=EnumNodeKind.EFFECT,
+                    node_name="postgres_adapter",
                     event_bus=adapter_config.event_bus,
                 )
                 self.initialize_introspection(config)
@@ -463,6 +466,9 @@ class MixinNodeIntrospection:
     _introspection_node_type: EnumNodeKind | None
     _introspection_event_bus: ProtocolEventBus | None
     _introspection_version: str
+    _introspection_node_name: str
+    _introspection_env: str
+    _introspection_service: str
     _introspection_start_time: float | None
     _introspection_contract: ModelContractBase | None
 
@@ -590,6 +596,7 @@ class MixinNodeIntrospection:
                     config = ModelIntrospectionConfig(
                         node_id=node_config.node_id,
                         node_type=EnumNodeKind.EFFECT,
+                        node_name="my_node",
                         event_bus=node_config.event_bus,
                         version="1.2.0",
                     )
@@ -601,6 +608,7 @@ class MixinNodeIntrospection:
                     config = ModelIntrospectionConfig(
                         node_id=node_config.node_id,
                         node_type=EnumNodeKind.EFFECT,
+                        node_name="my_effect_node",
                         event_bus=node_config.event_bus,
                         operation_keywords=frozenset({"fetch", "upload", "download"}),
                     )
@@ -638,6 +646,9 @@ class MixinNodeIntrospection:
             )
         self._introspection_event_bus = config.event_bus
         self._introspection_version = config.version
+        self._introspection_node_name = config.node_name
+        self._introspection_env = config.env
+        self._introspection_service = config.service
         self._introspection_cache_ttl = config.cache_ttl
 
         # Capability discovery configuration - frozensets are immutable, no copy needed
@@ -984,38 +995,40 @@ class MixinNodeIntrospection:
     ) -> ModelNodeEventBusConfig | None:
         """Extract and resolve event_bus config from contract.
 
-        Extracts topic suffixes from the contract's event_bus subcontract and
-        resolves them to full environment-qualified topic strings.
+        Extracts topic names from the contract's event_bus subcontract.
+        Topics are realm-agnostic in ONEX - environment/realm is enforced via
+        envelope identity, not topic naming.
 
-        Topic Resolution:
-            Contract topics are suffixes (e.g., "onex.evt.intent-classified.v1").
-            This method prepends the environment prefix to create full topics
-            (e.g., "dev.onex.evt.intent-classified.v1").
+        Topic Format:
+            Topics follow ONEX naming convention:
+            onex.{kind}.{producer}.{event-name}.v{n}
+
+            Example: "onex.evt.intent-classified.v1"
 
         Args:
-            env_prefix: Environment prefix (e.g., "dev", "prod", "staging").
-                Must be a valid identifier without dots or special characters.
+            env_prefix: Environment prefix (retained for compatibility, but no longer
+                used for topic resolution as topics are realm-agnostic).
 
         Returns:
-            Resolved event bus config with full topic strings, or None if:
+            Resolved event bus config with topic strings, or None if:
             - No contract is configured (_introspection_contract is None)
             - Contract has no event_bus subcontract
             - event_bus subcontract has no publish_topics or subscribe_topics
 
         Raises:
-            ValueError: If topic resolution fails due to unresolved placeholders
-                (e.g., "{env}" or "{namespace}" remaining in the resolved topic).
+            ValueError: If topic validation fails due to unresolved placeholders
+                (e.g., "{env}" or "{namespace}" remaining in the topic).
                 This is a fail-fast mechanism to prevent misconfigured topics
                 from being published to the registry.
 
         Example:
             >>> config = self._extract_event_bus_config("dev")
             >>> config.publish_topic_strings
-            ['dev.onex.evt.node-registered.v1']
+            ['onex.evt.node-registered.v1']
 
         See Also:
-            - ModelEventBusSubcontract: Contract model with topic suffixes
-            - ModelNodeEventBusConfig: Registry storage model with full topics
+            - ModelEventBusSubcontract: Contract model with topics
+            - ModelNodeEventBusConfig: Registry storage model
         """
         if self._introspection_contract is None:
             return None
@@ -1037,8 +1050,12 @@ class MixinNodeIntrospection:
             return None
 
         def resolve_topic(suffix: str) -> str:
-            """Resolve topic suffix to full topic with env prefix."""
-            # Full topic format: {env}.{suffix}
+            """Resolve topic suffix to topic name (realm-agnostic).
+
+            Topics are realm-agnostic in ONEX. The environment/realm is enforced via
+            envelope identity, not topic naming. This enables cross-environment event
+            routing when needed while maintaining proper isolation through identity.
+            """
             # Strip whitespace from suffix to handle YAML formatting artifacts
             suffix = suffix.strip()
 
@@ -1065,9 +1082,8 @@ class MixinNodeIntrospection:
                     parameter="topic_suffix",
                 )
 
-            full_topic = f"{env_prefix}.{suffix}"
-
-            return full_topic
+            # Return topic unchanged - topics are realm-agnostic
+            return suffix
 
         def build_entry(suffix: str) -> ModelEventBusTopicEntry:
             """Build topic entry from suffix."""
@@ -2081,9 +2097,15 @@ class MixinNodeIntrospection:
             return False
 
         request_topic = self._request_introspection_topic
+        node_identity = ModelNodeIdentity(
+            env=self._introspection_env,
+            service=self._introspection_service,
+            node_name=self._introspection_node_name,
+            version=self._introspection_version,
+        )
         unsubscribe = await event_bus.subscribe(
             topic=request_topic,
-            group_id=f"introspection-{self._introspection_node_id}",
+            node_identity=node_identity,
             on_message=self._handle_introspection_request,
         )
         self._registry_unsubscribe = unsubscribe

omnibase_infra/mixins/mixin_postgres_error_response.py

@@ -0,0 +1,314 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL Error Response Mixin.
+
+Provides standardized PostgreSQL exception handling for persistence operations
+in NodeContractPersistenceEffect. Extracts the common ~60-line exception
+handling pattern into a reusable mixin.
+
+Architecture:
+    MixinPostgresErrorResponse is designed to be mixed into PostgreSQL
+    persistence classes to provide consistent error handling, sanitization,
+    logging, and ModelBackendResult construction.
+
+    The mixin handles:
+    - TimeoutError/InfraTimeoutError -> TIMEOUT_ERROR code
+    - InfraAuthenticationError -> AUTH_ERROR code
+    - InfraConnectionError -> CONNECTION_ERROR code
+    - RepositoryExecutionError -> operation-specific error code
+    - Generic Exception -> UNKNOWN_ERROR code
+
+Error Sanitization:
+    All error messages are sanitized using utility functions to prevent
+    exposure of sensitive information (credentials, connection strings)
+    in logs and responses.
+
+Logging:
+    - Timeout/Connection errors: logger.warning (retriable)
+    - Auth errors: logger.exception (non-retriable, needs attention)
+    - Repository errors: logger.warning (may be retriable)
+    - Unknown errors: logger.exception (needs investigation)
+
+Usage:
+    >>> class MyPersistence(MixinPostgresErrorResponse):
+    ...     async def handle(self, payload, correlation_id):
+    ...         start_time = time.perf_counter()
+    ...         try:
+    ...             # ... database operation ...
+    ...         except Exception as e:
+    ...             ctx = PostgresErrorContext(
+    ...                 exception=e,
+    ...                 operation="my_operation",
+    ...                 correlation_id=correlation_id,
+    ...                 start_time=start_time,
+    ...                 log_context={"my_field": "value"},
+    ...                 operation_error_code=EnumPostgresErrorCode.UPSERT_ERROR,
+    ...             )
+    ...             return self._build_error_response(ctx)
+
+Related:
+    - NodeContractPersistenceEffect: Parent effect node
+    - EnumPostgresErrorCode: Error code enumeration
+    - ModelBackendResult: Structured result model
+    - OMN-1845: Implementation ticket
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from omnibase_infra.enums import EnumPostgresErrorCode
+from omnibase_infra.errors import (
+    InfraAuthenticationError,
+    InfraConnectionError,
+    InfraTimeoutError,
+    RepositoryExecutionError,
+)
+from omnibase_infra.utils import sanitize_backend_error, sanitize_error_message
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from omnibase_infra.models.model_backend_result import (
+        ModelBackendResult,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PostgresErrorContext:
+    """Context for PostgreSQL error handling.
+
+    Encapsulates all parameters needed for error handling to reduce
+    function parameter count and improve readability.
+
+    Attributes:
+        exception: The exception that was raised during the operation.
+        operation: Name of the operation for logging.
+        correlation_id: Request correlation ID for distributed tracing.
+        start_time: Result of time.perf_counter() captured before operation.
+        log_context: Additional context fields for log messages.
+        operation_error_code: Error code for RepositoryExecutionError.
+    """
+
+    exception: Exception
+    operation: str
+    correlation_id: UUID
+    start_time: float
+    log_context: dict[str, object] = field(default_factory=dict)
+    operation_error_code: EnumPostgresErrorCode | None = None
+
+
+class MixinPostgresErrorResponse:
+    """Mixin providing standardized PostgreSQL exception handling.
+
+    Consolidates the common exception handling pattern used across all
+    PostgreSQL handlers in NodeContractPersistenceEffect. This ensures
+    consistent error classification, sanitization, logging, and result
+    construction.
+
+    The mixin is designed to be used with any class that needs to handle
+    PostgreSQL operation errors and return ModelBackendResult.
+
+    Error Handling Matrix:
+        | Exception Type           | Error Code       | Log Level  | Retriable |
+        |--------------------------|------------------|------------|-----------|
+        | TimeoutError             | TIMEOUT_ERROR    | warning    | Yes       |
+        | InfraTimeoutError        | TIMEOUT_ERROR    | warning    | Yes       |
+        | InfraAuthenticationError | AUTH_ERROR       | exception  | No        |
+        | InfraConnectionError     | CONNECTION_ERROR | warning    | Yes       |
+        | RepositoryExecutionError | (configurable)   | warning    | Maybe     |
+        | Exception (catch-all)    | UNKNOWN_ERROR    | exception  | No        |
+
+    Example:
+        >>> class HandlerPostgresExample(MixinPostgresErrorResponse):
+        ...     async def handle(self, payload, correlation_id):
+        ...         start_time = time.perf_counter()
+        ...         try:
+        ...             async with self._pool.acquire() as conn:
+        ...                 await conn.execute("SELECT 1")
+        ...             duration_ms = (time.perf_counter() - start_time) * 1000
+        ...             return ModelBackendResult(
+        ...                 success=True,
+        ...                 duration_ms=duration_ms,
+        ...                 backend_id="postgres",
+        ...                 correlation_id=correlation_id,
+        ...             )
+        ...         except Exception as e:
+        ...             ctx = PostgresErrorContext(
+        ...                 exception=e,
+        ...                 operation="example_operation",
+        ...                 correlation_id=correlation_id,
+        ...                 start_time=start_time,
+        ...             )
+        ...             return self._build_error_response(ctx)
+
+    See Also:
+        - HandlerPostgresContractUpsert: Example handler using this mixin
+        - HandlerPostgresTopicUpdate: Example handler using this mixin
+        - EnumPostgresErrorCode: Error code classification
+    """
+
+    def _build_error_response(
+        self,
+        ctx: PostgresErrorContext,
+    ) -> ModelBackendResult:
+        """Build ModelBackendResult for PostgreSQL operation exceptions.
+
+        Processes an exception raised during a PostgreSQL operation and
+        returns a properly constructed ModelBackendResult with:
+        - Appropriate error code based on exception type
+        - Sanitized error message (no credentials/PII)
+        - Operation duration in milliseconds
+        - Correlation ID for distributed tracing
+
+        Args:
+            ctx: PostgresErrorContext containing all error handling parameters.
+
+        Returns:
+            ModelBackendResult with:
+                - success: Always False (this is error handling)
+                - error: Sanitized error message safe for logs/responses
+                - error_code: EnumPostgresErrorCode based on exception type
+                - duration_ms: Operation duration in milliseconds
+                - backend_id: Always "postgres"
+                - correlation_id: Passed through for tracing
+
+        Note:
+            This method never raises exceptions. All error paths return
+            a properly constructed ModelBackendResult.
+        """
+        # Extract context fields for readability
+        exception = ctx.exception
+        operation = ctx.operation
+        correlation_id = ctx.correlation_id
+        start_time = ctx.start_time
+        log_context = ctx.log_context
+        operation_error_code = ctx.operation_error_code
+        # Local import to avoid circular import at module load time
+        # (mixins/__init__.py loads before nodes/__init__.py in some paths)
+        from omnibase_infra.models.model_backend_result import (
+            ModelBackendResult as BackendResult,
+        )
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+
+        # Build base log context
+        base_context: dict[str, object] = {
+            "correlation_id": str(correlation_id),
+            "duration_ms": duration_ms,
+        }
+
+        # Merge caller-provided context
+        if log_context:
+            base_context.update(log_context)
+
+        # Handle timeout errors - retriable infrastructure failures
+        if isinstance(exception, (TimeoutError, InfraTimeoutError)):
+            sanitized_error = sanitize_error_message(exception)
+            base_context["error"] = sanitized_error
+
+            logger.warning(
+                f"{operation} timed out",
+                extra=base_context,
+            )
+
+            return BackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.TIMEOUT_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        # Handle authentication errors - non-retriable configuration failures
+        if isinstance(exception, InfraAuthenticationError):
+            sanitized_error = sanitize_error_message(exception)
+            base_context["error"] = sanitized_error
+
+            logger.exception(
+                f"{operation} authentication failed",
+                extra=base_context,
+            )
+
+            return BackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.AUTH_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        # Handle connection errors - retriable infrastructure failures
+        if isinstance(exception, InfraConnectionError):
+            sanitized_error = sanitize_error_message(exception)
+            base_context["error"] = sanitized_error
+
+            logger.warning(
+                f"{operation} connection failed",
+                extra=base_context,
+            )
+
+            return BackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.CONNECTION_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        # Handle repository execution errors - operation-specific failures
+        if isinstance(exception, RepositoryExecutionError):
+            sanitized_error = sanitize_error_message(exception)
+            base_context["error"] = sanitized_error
+
+            logger.warning(
+                f"{operation} execution failed",
+                extra=base_context,
+            )
+
+            # Use operation-specific error code if provided, else fall back to UNKNOWN
+            error_code = operation_error_code or EnumPostgresErrorCode.UNKNOWN_ERROR
+
+            return BackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=error_code,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        # Generic catch-all for unexpected exceptions
+        # This catch-all is required because database adapters may raise
+        # unexpected exceptions beyond typed infrastructure errors (e.g.,
+        # driver errors, encoding errors, connection pool errors, asyncpg-
+        # specific exceptions). All errors must be sanitized to prevent
+        # credential exposure.
+        sanitized_error = sanitize_backend_error("postgres", exception)
+        base_context["error"] = sanitized_error
+        base_context["error_type"] = type(exception).__name__
+
+        logger.exception(
+            f"{operation} failed with unexpected error",
+            extra=base_context,
+        )
+
+        return BackendResult(
+            success=False,
+            error=sanitized_error,
+            error_code=EnumPostgresErrorCode.UNKNOWN_ERROR,
+            duration_ms=duration_ms,
+            backend_id="postgres",
+            correlation_id=correlation_id,
+        )
+
+
+__all__: list[str] = ["MixinPostgresErrorResponse", "PostgresErrorContext"]