omnibase_infra 0.2.8__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.8"
+__version__ = "0.3.0"
 
 from . import (
     enums,

omnibase_infra/enums/__init__.py

@@ -57,6 +57,9 @@ from omnibase_infra.enums.enum_circuit_state import EnumCircuitState
 from omnibase_infra.enums.enum_confirmation_event_type import EnumConfirmationEventType
 from omnibase_infra.enums.enum_consumer_group_purpose import EnumConsumerGroupPurpose
 from omnibase_infra.enums.enum_contract_type import EnumContractType
+from omnibase_infra.enums.enum_declarative_node_violation import (
+    EnumDeclarativeNodeViolation,
+)
 from omnibase_infra.enums.enum_dedupe_strategy import EnumDedupeStrategy
 from omnibase_infra.enums.enum_dispatch_status import EnumDispatchStatus
 from omnibase_infra.enums.enum_environment import EnumEnvironment
@@ -101,6 +104,7 @@ __all__: list[str] = [
     "EnumConfirmationEventType",
     "EnumConsumerGroupPurpose",
     "EnumContractType",
+    "EnumDeclarativeNodeViolation",
     "EnumDedupeStrategy",
     "EnumDispatchStatus",
     "EnumEnvironment",

omnibase_infra/enums/enum_declarative_node_violation.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Enum for declarative node violation categories.
+
+Defines the specific violation types detected by the declarative node validator.
+Following the ONEX declarative pattern policy:
+- Node classes MUST only extend base classes without custom logic
+- Only __init__ with super().__init__(container) is allowed
+- No custom methods, properties, or instance variables
+"""
+
+from enum import Enum
+
+
+class EnumDeclarativeNodeViolation(str, Enum):
+    """Violation types for declarative node pattern enforcement.
+
+    These violation types correspond to the ONEX declarative node policy:
+    Nodes must be contract-driven with no custom Python logic.
+
+    Attributes:
+        CUSTOM_METHOD: Node class contains custom method (not __init__).
+        CUSTOM_PROPERTY: Node class contains property definition.
+        INIT_CUSTOM_LOGIC: __init__ contains logic beyond super().__init__().
+        INSTANCE_VARIABLE: __init__ creates custom instance variables.
+        CLASS_VARIABLE: Node class defines class-level variables.
+        SYNTAX_ERROR: File has Python syntax error, cannot validate.
+        NO_NODE_CLASS: File named node.py but contains no node class.
+
+    Policy Summary:
+        - ALLOWED: ``class MyNode(NodeEffect): pass``
+        - ALLOWED: ``def __init__(self, container): super().__init__(container)``
+        - BLOCKED: ``def compute(self, data): ...``
+        - BLOCKED: ``@property def my_prop(self): ...``
+        - BLOCKED: ``self._custom_var = value`` in __init__
+    """
+
+    CUSTOM_METHOD = "custom_method"
+    CUSTOM_PROPERTY = "custom_property"
+    INIT_CUSTOM_LOGIC = "init_custom_logic"
+    INSTANCE_VARIABLE = "instance_variable"
+    CLASS_VARIABLE = "class_variable"
+    SYNTAX_ERROR = "syntax_error"
+    NO_NODE_CLASS = "no_node_class"
+
+    @property
+    def is_exemptable(self) -> bool:
+        """Check if this violation type can be exempted.
+
+        Some violations like SYNTAX_ERROR cannot be exempted because
+        they indicate fundamental issues with the source file.
+
+        Returns:
+            True if the violation type can be exempted via decorator or comment.
+        """
+        return self not in {
+            EnumDeclarativeNodeViolation.SYNTAX_ERROR,
+            EnumDeclarativeNodeViolation.NO_NODE_CLASS,
+        }
+
+    @property
+    def suggestion(self) -> str:
+        """Get the suggested fix for this violation type.
+
+        Returns:
+            Human-readable suggestion for fixing the violation.
+        """
+        suggestions = {
+            EnumDeclarativeNodeViolation.CUSTOM_METHOD: (
+                "Move business logic to a Handler class. Node classes must be "
+                "declarative - all behavior should be defined in contract.yaml "
+                "and implemented by handlers."
+            ),
+            EnumDeclarativeNodeViolation.CUSTOM_PROPERTY: (
+                "Remove property from node class. Node classes should not have "
+                "custom properties - use container dependency injection instead."
+            ),
+            EnumDeclarativeNodeViolation.INIT_CUSTOM_LOGIC: (
+                "Remove custom logic from __init__. The __init__ method should "
+                "only call super().__init__(container). All initialization should "
+                "be handled by the base class and contract.yaml."
+            ),
+            EnumDeclarativeNodeViolation.INSTANCE_VARIABLE: (
+                "Remove instance variable assignment from __init__. Node classes "
+                "should not store state - use container injection and handlers."
+            ),
+            EnumDeclarativeNodeViolation.CLASS_VARIABLE: (
+                "Remove class variable from node class. Configuration should be "
+                "in contract.yaml, not Python code."
+            ),
+            EnumDeclarativeNodeViolation.SYNTAX_ERROR: (
+                "Fix the Python syntax error before validation can proceed."
+            ),
+            EnumDeclarativeNodeViolation.NO_NODE_CLASS: (
+                "File is named node.py but does not contain a Node class. "
+                "Either add a Node class or rename the file."
+            ),
+        }
+        return suggestions.get(self, "Make the node class declarative.")
+
+
+__all__ = ["EnumDeclarativeNodeViolation"]

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