omnibase_infra 0.2.9__py3-none-any.whl → 0.3.0__py3-none-any.whl

omnibase_infra/__init__.py

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

omnibase_infra/errors/__init__.py

@@ -23,6 +23,11 @@ Exports:
     ChainPropagationError: Correlation/causation chain validation errors
     ArchitectureViolationError: Architecture validation errors (blocks startup)
     BindingResolutionError: Binding resolution errors (declarative operation bindings)
+    RepositoryError: Base error for repository operations
+    RepositoryContractError: Contract-level errors (bad op_name, missing params)
+    RepositoryValidationError: Validation errors (type mismatch, constraints)
+    RepositoryExecutionError: Execution errors (asyncpg, connection issues)
+    RepositoryTimeoutError: Query timeout exceeded
 
 Correlation ID Assignment:
     All infrastructure errors support correlation_id for distributed tracing.
@@ -117,6 +122,13 @@ from omnibase_infra.errors.error_infra import (
 from omnibase_infra.errors.error_message_type_registry import MessageTypeRegistryError
 from omnibase_infra.errors.error_policy_registry import PolicyRegistryError
 from omnibase_infra.errors.error_vault import InfraVaultError
+from omnibase_infra.errors.repository import (
+    RepositoryContractError,
+    RepositoryError,
+    RepositoryExecutionError,
+    RepositoryTimeoutError,
+    RepositoryValidationError,
+)
 from omnibase_infra.models.errors.model_infra_error_context import (
     ModelInfraErrorContext,
 )
@@ -150,6 +162,12 @@ __all__: list[str] = [
     "ModelTimeoutErrorContext",
     "PolicyRegistryError",
     "ProtocolConfigurationError",
+    # Repository errors
+    "RepositoryContractError",
+    "RepositoryError",
+    "RepositoryExecutionError",
+    "RepositoryTimeoutError",
+    "RepositoryValidationError",
     # Error classes
     "RuntimeHostError",
     "SecretResolutionError",

omnibase_infra/errors/repository/__init__.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Repository Error Classes Module.
+
+This module provides error classes specific to repository operations,
+enabling typed exception handling for the PostgresRepositoryRuntime.
+
+Error Hierarchy:
+    RuntimeHostError (from omnibase_infra.errors)
+    └── RepositoryError (base repository error)
+        ├── RepositoryContractError (contract-level errors)
+        ├── RepositoryValidationError (validation errors)
+        ├── RepositoryExecutionError (execution errors)
+        └── RepositoryTimeoutError (query timeout errors)
+
+Exports:
+    RepositoryError: Base error for all repository operations
+    RepositoryContractError: Bad op_name, missing params, forbidden op
+    RepositoryValidationError: Param type mismatch, constraint violation
+    RepositoryExecutionError: asyncpg errors, connection issues
+    RepositoryTimeoutError: Query timeout exceeded
+
+Common Fields (all exceptions):
+    op_name: str | None - Operation name from repository contract
+    table: str | None - Target table for the operation
+    retriable: bool - Whether the operation can be retried
+    sql_fingerprint: str | None - SQL fingerprint for query tracking
+
+Example Usage::
+
+    from omnibase_infra.errors.repository import (
+        RepositoryContractError,
+        RepositoryExecutionError,
+        RepositoryTimeoutError,
+        RepositoryValidationError,
+    )
+    from omnibase_infra.models.errors import ModelInfraErrorContext
+    from omnibase_infra.enums import EnumInfraTransportType
+
+    # Contract error - unknown operation
+    context = ModelInfraErrorContext.with_correlation(
+        transport_type=EnumInfraTransportType.DATABASE,
+        operation="execute_operation",
+    )
+    raise RepositoryContractError(
+        "Unknown operation 'invalid_op'",
+        op_name="invalid_op",
+        table="users",
+        context=context,
+    )
+
+    # Check retriability in error handling
+    try:
+        result = await runtime.execute("find_all", {})
+    except RepositoryError as e:
+        if e.retriable:
+            # Can retry with backoff
+            pass
+        else:
+            # Non-retriable, propagate
+            raise
+"""
+
+from omnibase_infra.errors.repository.errors_repository import (
+    RepositoryContractError,
+    RepositoryError,
+    RepositoryExecutionError,
+    RepositoryTimeoutError,
+    RepositoryValidationError,
+)
+
+__all__ = [
+    "RepositoryContractError",
+    "RepositoryError",
+    "RepositoryExecutionError",
+    "RepositoryTimeoutError",
+    "RepositoryValidationError",
+]

omnibase_infra/errors/repository/errors_repository.py

@@ -0,0 +1,424 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Repository Error Classes for PostgresRepositoryRuntime.
+
+This module defines error classes specific to repository operations,
+providing granular error handling for contract-driven database access.
+
+Error Hierarchy:
+    RuntimeHostError (from error_infra)
+    └── RepositoryError (base repository error)
+        ├── RepositoryContractError (contract-level errors)
+        ├── RepositoryValidationError (validation errors)
+        ├── RepositoryExecutionError (execution errors)
+        └── RepositoryTimeoutError (query timeout errors)
+
+All errors:
+    - Extend RuntimeHostError for infrastructure consistency
+    - Include repository-specific fields: op_name, table, retriable
+    - Support optional sql_fingerprint for query tracking
+    - Use EnumCoreErrorCode for error classification
+    - Support correlation IDs for distributed tracing
+
+Retriability Guidelines:
+    - RepositoryContractError: NOT retriable (contract/configuration issue)
+    - RepositoryValidationError: NOT retriable (data validation issue)
+    - RepositoryExecutionError: Generally retriable (transient failures)
+    - RepositoryTimeoutError: Retriable (timeout may be transient)
+
+Example::
+
+    from omnibase_infra.errors.repository import (
+        RepositoryContractError,
+        RepositoryExecutionError,
+        RepositoryTimeoutError,
+        RepositoryValidationError,
+    )
+    from omnibase_infra.models.errors import ModelInfraErrorContext
+    from omnibase_infra.enums import EnumInfraTransportType
+
+    # Contract error - unknown operation
+    context = ModelInfraErrorContext.with_correlation(
+        transport_type=EnumInfraTransportType.DATABASE,
+        operation="execute_operation",
+    )
+    raise RepositoryContractError(
+        "Unknown operation 'invalid_op' not defined in contract",
+        op_name="invalid_op",
+        table="users",
+        context=context,
+    )
+
+    # Execution error with SQL fingerprint
+    raise RepositoryExecutionError(
+        "Connection pool exhausted",
+        op_name="find_by_id",
+        table="users",
+        sql_fingerprint="SELECT * FROM users WHERE id = $1",
+        context=context,
+    ) from e
+"""
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_infra.errors.error_infra import RuntimeHostError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class RepositoryError(RuntimeHostError):
+    """Base error class for all repository operations.
+
+    Provides common structured fields for repository-specific errors:
+        - op_name: The operation name from the repository contract
+        - table: The target table for the operation
+        - retriable: Whether the operation can be retried
+        - sql_fingerprint: Optional SQL fingerprint for query tracking
+
+    Subclasses set default retriability based on error category:
+        - Contract errors: NOT retriable
+        - Validation errors: NOT retriable
+        - Execution errors: Generally retriable
+        - Timeout errors: Retriable
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_operation",
+        ... )
+        >>> raise RepositoryError(
+        ...     "Repository operation failed",
+        ...     op_name="find_by_id",
+        ...     table="users",
+        ...     context=context,
+        ... )
+    """
+
+    # Default retriability for base class (conservative: not retriable)
+    _default_retriable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        op_name: str | None = None,
+        table: str | None = None,
+        retriable: bool | None = None,
+        sql_fingerprint: str | None = None,
+        error_code: EnumCoreErrorCode | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize RepositoryError with repository-specific fields.
+
+        Args:
+            message: Human-readable error message
+            op_name: Operation name from the repository contract
+            table: Target table for the operation
+            retriable: Whether the operation can be retried. If None, uses
+                class default (_default_retriable)
+            sql_fingerprint: SQL fingerprint for query tracking (sanitized)
+            error_code: Error code (defaults to DATABASE_OPERATION_ERROR)
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        # Add repository-specific fields to extra_context
+        if op_name is not None:
+            extra_context["op_name"] = op_name
+        if table is not None:
+            extra_context["table"] = table
+        if sql_fingerprint is not None:
+            extra_context["sql_fingerprint"] = sql_fingerprint
+
+        # Resolve retriability: explicit > class default
+        resolved_retriable = (
+            retriable if retriable is not None else self._default_retriable
+        )
+        extra_context["retriable"] = resolved_retriable
+
+        # Store as instance attributes for programmatic access
+        self.op_name = op_name
+        self.table = table
+        self.retriable = resolved_retriable
+        self.sql_fingerprint = sql_fingerprint
+
+        super().__init__(
+            message=message,
+            error_code=error_code or EnumCoreErrorCode.DATABASE_OPERATION_ERROR,
+            context=context,
+            **extra_context,
+        )
+
+
+class RepositoryContractError(RepositoryError):
+    """Raised for contract-level errors in repository operations.
+
+    Used when:
+        - Operation name (op_name) is not defined in the contract
+        - Required parameters are missing for the operation
+        - Operation is explicitly forbidden in the contract
+        - Contract schema validation fails
+
+    Contract errors are NOT retriable - they indicate a configuration
+    or programming error that requires code or contract changes to fix.
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_operation",
+        ... )
+        >>> raise RepositoryContractError(
+        ...     "Operation 'drop_table' is forbidden in contract",
+        ...     op_name="drop_table",
+        ...     table="users",
+        ...     context=context,
+        ... )
+    """
+
+    _default_retriable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        op_name: str | None = None,
+        table: str | None = None,
+        retriable: bool | None = None,
+        sql_fingerprint: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize RepositoryContractError.
+
+        Args:
+            message: Human-readable error message
+            op_name: Operation name that caused the contract error
+            table: Target table (if applicable)
+            retriable: Override default (False). Contract errors are
+                generally NOT retriable.
+            sql_fingerprint: SQL fingerprint (if applicable)
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        super().__init__(
+            message=message,
+            op_name=op_name,
+            table=table,
+            retriable=retriable,
+            sql_fingerprint=sql_fingerprint,
+            error_code=EnumCoreErrorCode.INVALID_CONFIGURATION,
+            context=context,
+            **extra_context,
+        )
+
+
+class RepositoryValidationError(RepositoryError):
+    """Raised for validation errors in repository operations.
+
+    Used when:
+        - Parameter type mismatches (e.g., string passed for int column)
+        - Constraint violations (e.g., null for non-nullable column)
+        - Value out of allowed range
+        - Invalid data format
+
+    Validation errors are NOT retriable - they indicate invalid input
+    data that must be corrected before retrying.
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_operation",
+        ... )
+        >>> raise RepositoryValidationError(
+        ...     "Parameter 'user_id' expected int, got str",
+        ...     op_name="find_by_id",
+        ...     table="users",
+        ...     context=context,
+        ...     param_name="user_id",
+        ...     expected_type="int",
+        ...     actual_type="str",
+        ... )
+    """
+
+    _default_retriable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        op_name: str | None = None,
+        table: str | None = None,
+        retriable: bool | None = None,
+        sql_fingerprint: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize RepositoryValidationError.
+
+        Args:
+            message: Human-readable error message
+            op_name: Operation name that triggered validation
+            table: Target table (if applicable)
+            retriable: Override default (False). Validation errors are
+                generally NOT retriable.
+            sql_fingerprint: SQL fingerprint (if applicable)
+            context: Bundled infrastructure context
+            **extra_context: Additional context (param_name, expected_type, etc.)
+        """
+        super().__init__(
+            message=message,
+            op_name=op_name,
+            table=table,
+            retriable=retriable,
+            sql_fingerprint=sql_fingerprint,
+            error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+            context=context,
+            **extra_context,
+        )
+
+
+class RepositoryExecutionError(RepositoryError):
+    """Raised for execution errors in repository operations.
+
+    Used when:
+        - asyncpg errors during query execution
+        - Connection pool exhaustion
+        - Database connection lost mid-operation
+        - Deadlock detected
+        - Serialization failures
+
+    Execution errors are generally retriable - they often indicate
+    transient failures that may succeed on retry with backoff.
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_operation",
+        ... )
+        >>> try:
+        ...     result = await pool.execute(sql, *params)
+        ... except asyncpg.PostgresError as e:
+        ...     raise RepositoryExecutionError(
+        ...         f"Query execution failed: {e}",
+        ...         op_name="create_user",
+        ...         table="users",
+        ...         sql_fingerprint="INSERT INTO users (...) VALUES (...)",
+        ...         context=context,
+        ...     ) from e
+    """
+
+    _default_retriable: bool = True
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        op_name: str | None = None,
+        table: str | None = None,
+        retriable: bool | None = None,
+        sql_fingerprint: str | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize RepositoryExecutionError.
+
+        Args:
+            message: Human-readable error message
+            op_name: Operation name that failed during execution
+            table: Target table (if applicable)
+            retriable: Override default (True). Set False for non-retriable
+                execution errors (e.g., constraint violations from DB).
+            sql_fingerprint: SQL fingerprint for query tracking
+            context: Bundled infrastructure context
+            **extra_context: Additional context (asyncpg error details, etc.)
+        """
+        super().__init__(
+            message=message,
+            op_name=op_name,
+            table=table,
+            retriable=retriable,
+            sql_fingerprint=sql_fingerprint,
+            error_code=EnumCoreErrorCode.DATABASE_OPERATION_ERROR,
+            context=context,
+            **extra_context,
+        )
+
+
+class RepositoryTimeoutError(RepositoryError):
+    """Raised when a repository query exceeds its timeout.
+
+    Used when:
+        - Query exceeds statement_timeout
+        - Connection acquisition times out
+        - Transaction times out
+
+    Timeout errors are retriable - the same query may succeed
+    under different load conditions or with adjusted timeouts.
+
+    Example:
+        >>> context = ModelInfraErrorContext.with_correlation(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_operation",
+        ... )
+        >>> raise RepositoryTimeoutError(
+        ...     "Query exceeded 30s timeout",
+        ...     op_name="complex_report",
+        ...     table="analytics",
+        ...     timeout_seconds=30.0,
+        ...     sql_fingerprint="SELECT ... FROM analytics ...",
+        ...     context=context,
+        ... )
+    """
+
+    _default_retriable: bool = True
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        op_name: str | None = None,
+        table: str | None = None,
+        retriable: bool | None = None,
+        sql_fingerprint: str | None = None,
+        timeout_seconds: float | None = None,
+        context: ModelInfraErrorContext | None = None,
+        **extra_context: object,
+    ) -> None:
+        """Initialize RepositoryTimeoutError.
+
+        Args:
+            message: Human-readable error message
+            op_name: Operation name that timed out
+            table: Target table (if applicable)
+            retriable: Override default (True). Timeout errors are
+                generally retriable.
+            sql_fingerprint: SQL fingerprint for query tracking
+            timeout_seconds: The timeout value that was exceeded
+            context: Bundled infrastructure context
+            **extra_context: Additional context information
+        """
+        if timeout_seconds is not None:
+            extra_context["timeout_seconds"] = timeout_seconds
+
+        # Store for programmatic access
+        self.timeout_seconds = timeout_seconds
+
+        super().__init__(
+            message=message,
+            op_name=op_name,
+            table=table,
+            retriable=retriable,
+            sql_fingerprint=sql_fingerprint,
+            error_code=EnumCoreErrorCode.TIMEOUT_ERROR,
+            context=context,
+            **extra_context,
+        )
+
+
+__all__ = [
+    "RepositoryContractError",
+    "RepositoryError",
+    "RepositoryExecutionError",
+    "RepositoryTimeoutError",
+    "RepositoryValidationError",
+]

omnibase_infra/nodes/contract_registry_reducer/reducer.py

@@ -702,13 +702,18 @@ class ContractRegistryReducer:
                     # We store it as-is; the Effect layer handles resolution.
                     topic_suffix = consumed.get("topic")
                     if topic_suffix and isinstance(topic_suffix, str):
+                        # Validate event_type is string (may be missing or wrong type in malformed YAML)
+                        event_type_raw = consumed.get("event_type")
+                        event_type = (
+                            event_type_raw if isinstance(event_type_raw, str) else None
+                        )
                         payload = ModelPayloadUpdateTopic(
                             correlation_id=correlation_id,
                             topic_suffix=topic_suffix,
                             direction="subscribe",
                             contract_id=contract_id,
                             node_name=event.node_name,
-                            event_type=consumed.get("event_type"),
+                            event_type=event_type,
                             last_seen_at=event.timestamp,
                         )
                         intents.append(
@@ -728,13 +733,18 @@ class ContractRegistryReducer:
                     # Effect layer handles resolution (see docstring above).
                     topic_suffix = published.get("topic")
                     if topic_suffix and isinstance(topic_suffix, str):
+                        # Validate event_type is string (may be missing or wrong type in malformed YAML)
+                        event_type_raw = published.get("event_type")
+                        event_type = (
+                            event_type_raw if isinstance(event_type_raw, str) else None
+                        )
                         payload = ModelPayloadUpdateTopic(
                             correlation_id=correlation_id,
                             topic_suffix=topic_suffix,
                             direction="publish",
                             contract_id=contract_id,
                             node_name=event.node_name,
-                            event_type=published.get("event_type"),
+                            event_type=event_type,
                             last_seen_at=event.timestamp,
                         )
                         intents.append(

omnibase_infra/runtime/db/__init__.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database runtime module for omnibase_infra.
+
+This module provides the PostgresRepositoryRuntime and associated models for
+database operations with safety constraints and deterministic query behavior.
+
+Components:
+    - PostgresRepositoryRuntime: Generic Postgres runtime for contract execution
+    - ModelRepositoryRuntimeConfig: Configuration for runtime behavior
+    - ModelDbRepositoryContract: Repository contract specification
+    - ModelDbOperation: Database operation specification
+    - ModelDbReturn: Return type specification
+
+The db module enables safe, configurable database operations with:
+    - Contract-driven operations (all ops defined in ModelDbRepositoryContract)
+    - Operation allowlisting (select, insert, update, upsert)
+    - Row limits for multi-row selects
+    - Query timeouts with asyncio.wait_for()
+    - Deterministic ORDER BY injection
+    - Metrics emission
+
+Example:
+    >>> import asyncpg
+    >>> from omnibase_infra.runtime.db import (
+    ...     PostgresRepositoryRuntime,
+    ...     ModelDbRepositoryContract,
+    ...     ModelDbOperation,
+    ...     ModelDbReturn,
+    ...     ModelRepositoryRuntimeConfig,
+    ... )
+    >>>
+    >>> # Define contract
+    >>> contract = ModelDbRepositoryContract(
+    ...     name="users",
+    ...     database_ref="primary",
+    ...     ops={
+    ...         "find_by_id": ModelDbOperation(
+    ...             mode="select",
+    ...             sql="SELECT * FROM users WHERE id = $1",
+    ...             params=["user_id"],
+    ...             returns=ModelDbReturn(many=False),
+    ...         ),
+    ...     },
+    ... )
+    >>>
+    >>> # Create runtime with pool
+    >>> pool = await asyncpg.create_pool(...)
+    >>> runtime = PostgresRepositoryRuntime(pool, contract)
+    >>>
+    >>> # Execute operation
+    >>> user = await runtime.call("find_by_id", 123)
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.runtime.db.models import (
+    ModelDbOperation,
+    ModelDbRepositoryContract,
+    ModelDbReturn,
+    ModelRepositoryRuntimeConfig,
+)
+from omnibase_infra.runtime.db.postgres_repository_runtime import (
+    PostgresRepositoryRuntime,
+)
+
+__all__: list[str] = [
+    "ModelDbOperation",
+    "ModelDbRepositoryContract",
+    "ModelDbReturn",
+    "ModelRepositoryRuntimeConfig",
+    "PostgresRepositoryRuntime",
+]