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

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

omnibase_infra/mixins/mixin_postgres_op_executor.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shared execution core for PostgreSQL operation handlers.
+
+This mixin centralizes the mechanical aspects of PostgreSQL handler execution:
+- Timing via time.perf_counter()
+- Error classification and sanitization
+- ModelBackendResult construction
+- Structured logging with correlation IDs
+
+By extracting this boilerplate into a reusable mixin, handlers are reduced from
+~200 lines to ~30 lines, eliminating drift risk where error handling patterns
+could diverge across handlers.
+
+Architecture:
+    Handlers inherit from MixinPostgresOpExecutor and call _execute_postgres_op()
+    with their operation-specific logic wrapped in a callable. The mixin handles
+    all timing, error classification, sanitization, and result construction.
+
+Error Classification:
+    - TimeoutError, InfraTimeoutError → POSTGRES_TIMEOUT_ERROR (retriable)
+    - InfraAuthenticationError → POSTGRES_AUTH_ERROR (non-retriable)
+    - InfraConnectionError → POSTGRES_CONNECTION_ERROR (retriable)
+    - RepositoryExecutionError → op_error_code (handler-specified)
+    - Exception → POSTGRES_UNKNOWN_ERROR (non-retriable)
+
+Usage:
+    ```python
+    class HandlerPostgresHeartbeat(MixinPostgresOpExecutor):
+        async def handle(self, payload, correlation_id) -> ModelBackendResult:
+            return await self._execute_postgres_op(
+                op_error_code=EnumPostgresErrorCode.HEARTBEAT_ERROR,
+                correlation_id=correlation_id,
+                log_context={"contract_id": payload.contract_id},
+                fn=lambda: self._do_heartbeat(payload),
+            )
+    ```
+
+Related:
+    - EnumPostgresErrorCode: Error code enumeration with retriability metadata
+    - MixinAsyncCircuitBreaker: Circuit breaker mixin (not integrated here)
+    - OMN-1857: Extraction ticket for this mixin
+
+Note on Circuit Breaker:
+    Per OMN-1857 design decision 1A, the executor should manage circuit breaker
+    internally. However, this initial implementation focuses on the core execution
+    mechanics. Circuit breaker integration will be added as a follow-up once the
+    basic pattern is validated.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from omnibase_infra.enums import EnumPostgresErrorCode
+from omnibase_infra.errors import (
+    InfraAuthenticationError,
+    InfraConnectionError,
+    InfraTimeoutError,
+    RepositoryExecutionError,
+)
+from omnibase_infra.models.model_backend_result import ModelBackendResult
+from omnibase_infra.utils import sanitize_backend_error, sanitize_error_message
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class MixinPostgresOpExecutor:
+    """Shared execution core for PostgreSQL operation handlers.
+
+    Centralizes timing, error handling, sanitization, and result construction
+    for PostgreSQL operations. Handlers inherit this mixin and delegate to
+    _execute_postgres_op() for consistent mechanical behavior.
+
+    This mixin does NOT manage circuit breaker state - that responsibility
+    remains with the handler or a separate MixinAsyncCircuitBreaker composition.
+
+    Example:
+        ```python
+        class HandlerPostgresUpsert(MixinPostgresOpExecutor):
+            def __init__(self, pool: asyncpg.Pool) -> None:
+                self._pool = pool
+
+            async def handle(
+                self, payload: ModelPayloadUpsertContract, correlation_id: UUID
+            ) -> ModelBackendResult:
+                return await self._execute_postgres_op(
+                    op_error_code=EnumPostgresErrorCode.UPSERT_ERROR,
+                    correlation_id=correlation_id,
+                    log_context={
+                        "contract_id": payload.contract_id,
+                        "node_name": payload.node_name,
+                    },
+                    fn=lambda: self._execute_upsert(payload),
+                )
+        ```
+
+    See Also:
+        - EnumPostgresErrorCode: Error codes with is_retriable property
+        - sanitize_error_message: Error sanitization utility
+        - ModelBackendResult: Structured result model
+    """
+
+    async def _execute_postgres_op(
+        self,
+        *,
+        op_error_code: EnumPostgresErrorCode,
+        correlation_id: UUID,
+        log_context: dict[str, object],
+        fn: Callable[[], Awaitable[T]],
+    ) -> ModelBackendResult:
+        """Execute a PostgreSQL operation with timing, error handling, and sanitization.
+
+        This method wraps the actual database operation (fn) with:
+        1. Timing measurement via time.perf_counter()
+        2. Exception classification into appropriate error codes
+        3. Error message sanitization to prevent credential exposure
+        4. Structured logging with correlation ID and context
+        5. ModelBackendResult construction
+
+        Args:
+            op_error_code: Operation-specific error code for non-infrastructure
+                failures (e.g., UPSERT_ERROR, HEARTBEAT_ERROR). Used when the
+                operation fails due to business logic or query issues rather
+                than connection/auth problems.
+            correlation_id: Request correlation ID for distributed tracing.
+            log_context: Additional fields for structured logging (e.g.,
+                contract_id, node_name). Included in all log messages.
+            fn: Async callable that performs the actual database operation.
+                Should return any value on success. The return value is not
+                used - only success/failure matters.
+
+        Returns:
+            ModelBackendResult with:
+                - success: True if fn() completed without exception
+                - error: Sanitized error message (empty string on success)
+                - error_code: Appropriate EnumPostgresErrorCode
+                - duration_ms: Operation duration in milliseconds
+                - backend_id: "postgres"
+                - correlation_id: Passed through for tracing
+
+        Error Classification:
+            | Exception Type              | Error Code              | Retriable |
+            |-----------------------------|-------------------------|-----------|
+            | TimeoutError                | TIMEOUT_ERROR           | Yes       |
+            | InfraTimeoutError           | TIMEOUT_ERROR           | Yes       |
+            | InfraAuthenticationError    | AUTH_ERROR              | No        |
+            | InfraConnectionError        | CONNECTION_ERROR        | Yes       |
+            | RepositoryExecutionError    | op_error_code           | No        |
+            | Exception                   | UNKNOWN_ERROR           | No        |
+
+        Note:
+            This method never raises exceptions. All errors are captured,
+            sanitized, logged, and returned in the result model.
+        """
+        start_time = time.perf_counter()
+        log_extra = {
+            "correlation_id": str(correlation_id),
+            **log_context,
+        }
+
+        try:
+            # Execute the operation
+            await fn()
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.debug(
+                "PostgreSQL operation completed successfully",
+                extra={**log_extra, "duration_ms": duration_ms},
+            )
+
+            return ModelBackendResult(
+                success=True,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except (TimeoutError, InfraTimeoutError) as e:
+            # Timeout - retriable error
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL operation timed out",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.TIMEOUT_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraAuthenticationError as e:
+            # Authentication failure - non-retriable
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.exception(
+                "PostgreSQL authentication failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.AUTH_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except InfraConnectionError as e:
+            # Connection failure - retriable
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL connection failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.CONNECTION_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except RepositoryExecutionError as e:
+            # Query/operation failure - use handler-provided error code
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_error_message(e)
+            logger.warning(
+                "PostgreSQL operation failed",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error": sanitized_error,
+                    "error_code": op_error_code.value,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=op_error_code,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+        except (
+            Exception
+        ) as e:  # ONEX: catch-all for driver errors, encoding errors, pool errors
+            # Unknown error - non-retriable, requires investigation
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            sanitized_error = sanitize_backend_error("postgres", e)
+            logger.exception(
+                "PostgreSQL operation failed with unexpected error",
+                extra={
+                    **log_extra,
+                    "duration_ms": duration_ms,
+                    "error_type": type(e).__name__,
+                    "error": sanitized_error,
+                },
+            )
+            return ModelBackendResult(
+                success=False,
+                error=sanitized_error,
+                error_code=EnumPostgresErrorCode.UNKNOWN_ERROR,
+                duration_ms=duration_ms,
+                backend_id="postgres",
+                correlation_id=correlation_id,
+            )
+
+
+__all__ = ["MixinPostgresOpExecutor"]

omnibase_infra/models/__init__.py

@@ -30,6 +30,7 @@ from omnibase_infra.models.event_bus import (
 from omnibase_infra.models.handlers import ModelHandlerIdentifier
 from omnibase_infra.models.health import ModelHealthCheckResult
 from omnibase_infra.models.logging import ModelLogContext
+from omnibase_infra.models.model_backend_result import ModelBackendResult
 from omnibase_infra.models.model_node_identity import ModelNodeIdentity
 from omnibase_infra.models.model_retry_error_classification import (
     ModelRetryErrorClassification,
@@ -93,6 +94,8 @@ __all__: list[str] = [
     "ModelConsumerRetryConfig",
     "ModelIdempotencyConfig",
     "ModelOffsetPolicyConfig",
+    # Backend result models
+    "ModelBackendResult",
     # Resilience models
     "ModelCircuitBreakerConfig",
     # Validation models

omnibase_infra/{nodes/effects/models → models}/model_backend_result.py

@@ -61,7 +61,9 @@ class ModelBackendResult(BaseModel):
     Attributes:
         success: Whether the backend operation completed successfully.
         error: Sanitized error message if success is False.
-        error_code: Optional error code for programmatic handling.
+        error_code: Error code for programmatic handling. PostgreSQL handlers
+            use EnumPostgresErrorCode enum values which serialize to strings
+            (e.g., "POSTGRES_CONNECTION_ERROR"). Other backends use string codes.
         duration_ms: Time taken for the operation in milliseconds.
         backend_id: Optional identifier for the backend instance.
 
@@ -96,18 +98,30 @@ class ModelBackendResult(BaseModel):
         >>> result.success
         True
 
-    Example (failure case):
+    Example (failure case with PostgreSQL enum):
+        >>> from omnibase_infra.enums import EnumPostgresErrorCode
         >>> result = ModelBackendResult(
         ...     success=False,
         ...     error="Connection refused to database host",
-        ...     error_code="DATABASE_CONNECTION_ERROR",
+        ...     error_code=EnumPostgresErrorCode.CONNECTION_ERROR,
         ...     duration_ms=5000.0,
         ...     backend_id="postgres",
         ... )
         >>> result.success
         False
-        >>> result.error
-        'Connection refused to database host'
+        >>> result.error_code  # Enum serializes to string
+        'POSTGRES_CONNECTION_ERROR'
+
+    Example (failure case with Consul string code):
+        >>> result = ModelBackendResult(
+        ...     success=False,
+        ...     error="Service registration failed",
+        ...     error_code="CONSUL_CONNECTION_ERROR",
+        ...     duration_ms=1500.0,
+        ...     backend_id="consul",
+        ... )
+        >>> result.error_code
+        'CONSUL_CONNECTION_ERROR'
     """
 
     model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
@@ -122,7 +136,9 @@ class ModelBackendResult(BaseModel):
     )
     error_code: str | None = Field(
         default=None,
-        description="Error code for programmatic handling (e.g., DATABASE_CONNECTION_ERROR)",
+        description="Error code for programmatic handling. PostgreSQL handlers use "
+        "EnumPostgresErrorCode enum values (which serialize to strings like "
+        "'POSTGRES_CONNECTION_ERROR'). Other backends use string codes directly.",
     )
     duration_ms: float = Field(
         default=0.0,