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

omnibase_infra/validation/__init__.py

@@ -160,6 +160,14 @@ from omnibase_infra.validation.validator_chain_propagation import (
     validate_message_chain,
 )
 
+# Declarative node validation for ONEX architecture (OMN-1725)
+from omnibase_infra.validation.validator_declarative_node import (
+    ValidatorDeclarativeNode,
+    validate_declarative_node_in_file,
+    validate_declarative_nodes,
+    validate_declarative_nodes_ci,
+)
+
 # AST-based execution shape validation for CI gate (OMN-958)
 # NOTE: EXECUTION_SHAPE_RULES is defined ONLY in validator_execution_shape.py
 # (the canonical single source of truth). This import re-exports it for public API
@@ -255,6 +263,7 @@ __all__: list[str] = [
     "ModelModuleImportResult",  # Module import result (from omnibase_core)
     # Validators
     "AnyTypeDetector",  # Any type AST detector (OMN-1276)
+    "ValidatorDeclarativeNode",  # Declarative node validator (OMN-1725)
     "ChainPropagationValidator",  # Chain propagation validator (OMN-951)
     "CircularImportValidator",  # Circular import validator
     "ContractLinter",  # Contract linter (PR #57)
@@ -285,6 +294,9 @@ __all__: list[str] = [
     "validate_any_types_in_file",  # Any type file validation (OMN-1276)
     "validate_architecture",  # Re-export from omnibase_core
     "validate_contracts",  # Re-export from omnibase_core
+    "validate_declarative_node_in_file",  # Declarative node file validation (OMN-1725)
+    "validate_declarative_nodes",  # Declarative node validation (OMN-1725)
+    "validate_declarative_nodes_ci",  # Declarative node CI validation (OMN-1725)
     "validate_execution_shapes",  # Execution shape validation
     "validate_execution_shapes_ci",  # CI shape validation
     "validate_handler_registration",  # Handler registration validation (OMN-1098)

omnibase_infra/validation/contracts/declarative_node.validation.yaml

@@ -0,0 +1,143 @@
+contract_kind: validation_subcontract
+validation:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  validator_id: declarative_node
+  validator_name: ONEX Declarative Node Validator
+  validator_description: |
+    Validates node.py files follow the ONEX declarative pattern where all behavior
+    is defined in contract.yaml rather than custom Python logic.
+
+    This validator performs static AST analysis to detect imperative patterns:
+    - Custom methods beyond __init__ (behavior should be in contract)
+    - @property decorators (state should be in models)
+    - Custom logic in __init__ beyond super().__init__(container)
+    - Instance variable assignments (state belongs in container/models)
+    - Class-level variable assignments (configuration belongs in contract)
+
+    Declarative nodes extend base classes from omnibase_core.nodes and delegate
+    all behavior to handler routing defined in contract.yaml.
+
+    Part of ONEX architecture: Declarative nodes, contract-driven behavior.
+  target_patterns:
+    - "**/node.py"
+    - "node.py"
+  exclude_patterns:
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/venv/**"
+    - "**/.venv/**"
+    - "**/__pycache__/**"
+    - "**/archived/**"
+    - "**/tests/**"
+    - "**/*_test.py"
+    - "**/test_*.py"
+    - "**/conftest.py"
+  rules:
+    - rule_id: DECL-001
+      name: no_custom_methods
+      description: |
+        Node classes must not have custom methods (except __init__).
+        All behavior should be defined in contract.yaml via handler_routing.
+        Custom methods indicate imperative logic that belongs in handlers.
+      severity: error
+      enabled: true
+      parameters:
+        allowed_methods:
+          - "__init__"
+        base_class_patterns:
+          - "^Node.*Effect$"
+          - "^Node.*Compute$"
+          - "^Node.*Reducer$"
+          - "^Node.*Orchestrator$"
+          - "^NodeEffect$"
+          - "^NodeCompute$"
+          - "^NodeReducer$"
+          - "^NodeOrchestrator$"
+    - rule_id: DECL-002
+      name: no_custom_properties
+      description: |
+        Node classes must not have @property decorators.
+        State access should be through container injection or models.
+        Properties indicate node-level state that should be in the container.
+      severity: error
+      enabled: true
+      parameters:
+        forbidden_decorators:
+          - "property"
+          - "cached_property"
+    - rule_id: DECL-003
+      name: no_init_custom_logic
+      description: |
+        __init__ must only call super().__init__(container).
+        No additional logic, assignments, or method calls allowed.
+        All initialization should happen through container dependency injection.
+      severity: error
+      enabled: true
+      parameters:
+        required_pattern: "super().__init__(container)"
+        max_statements: 1
+        allowed_statements:
+          - "super().__init__"
+    - rule_id: DECL-004
+      name: no_instance_variables
+      description: |
+        Node classes must not create instance variables (self.x = ...).
+        State should be managed through the container, not node-level attributes.
+        Instance variables indicate imperative state management.
+      severity: error
+      enabled: true
+      parameters:
+        allow_in_init: false
+        forbidden_patterns:
+          - "^self\\.[a-z_][a-z0-9_]*\\s*="
+    - rule_id: DECL-005
+      name: no_class_variables
+      description: |
+        Node classes must not have class-level variable assignments.
+        Configuration should be in contract.yaml, not hardcoded in Python.
+        Class variables indicate configuration that belongs in contracts.
+      severity: error
+      enabled: true
+      parameters:
+        allowed_class_attributes:
+          - "__slots__"
+          - "__doc__"
+        forbidden_patterns:
+          - "^[A-Z_][A-Z0-9_]*\\s*="
+          - "^[a-z_][a-z0-9_]*\\s*="
+    - rule_id: DECL-006
+      name: syntax_error
+      description: |
+        File has Python syntax error and cannot be validated.
+        Fix the syntax error before validation can proceed.
+      severity: error
+      enabled: true
+    - rule_id: DECL-007
+      name: no_node_class
+      description: |
+        File is named node.py but does not contain a Node class.
+        Either add a Node class or rename the file.
+      severity: warning
+      enabled: true
+  # ============================================================================
+  # LINE-BASED SUPPRESSION
+  # ============================================================================
+  # Use ONEX_EXCLUDE to exempt imperative nodes that are intentionally non-declarative.
+  # Place the comment on the line before or same line as the class definition.
+  #
+  # Usage example:
+  #   # ONEX_EXCLUDE: declarative_node - legacy node with embedded logic (OMN-XXXX)
+  #   class MyLegacyNode(NodeEffect):
+  #       def custom_method(self): ...
+  # ============================================================================
+  suppression_comments:
+    - "# ONEX_EXCLUDE: declarative_node"
+    - "# ONEX_EXCLUDE: declarative"
+  severity_default: error
+  fail_on_error: true
+  fail_on_warning: false
+  max_violations: 0
+  parallel_execution: true

omnibase_infra/validation/infra_validators.py

@@ -446,7 +446,10 @@ INFRA_NODES_PATH = "src/omnibase_infra/nodes/"
 # - 115 (2026-01-29): OMN-1653 contract registry reducer (+2 unions)
 #                     ContractRegistryEvent: 4-type union for event routing
 #                     contract_yaml: dict | str for flexible YAML handling
-INFRA_MAX_UNIONS = 115
+# - 117 (2026-02-01): OMN-1783 PostgresRepositoryRuntime (+2 unions)
+#                     call() return type: list[dict] | dict | None
+#                     _execute_with_timeout() return type: list[dict] | dict | None
+INFRA_MAX_UNIONS = 117
 
 # Maximum allowed architecture violations in infrastructure code.
 # Set to 0 (strict enforcement) to ensure one-model-per-file principle is always followed.

omnibase_infra/validation/validation_exemptions.yaml

@@ -132,6 +132,24 @@ pattern_exemptions:
       - CLAUDE.md (Accepted Pattern Exceptions - EventBusKafka Complexity)
     ticket: OMN-1305
   # ==========================================================================
+  # PostgresRepositoryRuntime Exemptions (OMN-1783)
+  # ==========================================================================
+  # Contract-driven database runtime with cohesive methods for query execution.
+  # All methods serve the same purpose: executing repository contract operations.
+  # Public: call(), contract (property), config (property)
+  # Private: _create_error_context, _get_operation, _validate_operation_allowed,
+  #          _validate_arg_count, _build_sql, _inject_order_by, _inject_limit,
+  #          _execute_with_timeout, _get_primary_table, _fingerprint_sql
+  - file_pattern: 'postgres_repository_runtime\.py'
+    class_pattern: "Class 'PostgresRepositoryRuntime'"
+    violation_pattern: 'has \d+ methods'
+    reason: >
+      Cohesive runtime class with single responsibility: executing repository contract operations. Methods are logically grouped: validation (3), SQL building (3), execution (1), and helpers (3). Breaking into smaller classes would reduce cohesion and complicate the simple contract-driven execution flow.
+
+    documentation:
+      - OMN-1783 PR description
+    ticket: OMN-1783
+  # ==========================================================================
   # Protocol Plugin Architecture Exemptions
   # ==========================================================================
   # The 'execute' method name is a standard plugin architecture pattern.
@@ -982,6 +1000,23 @@ pattern_exemptions:
     documentation:
       - CLAUDE.md (Circuit Breaker Pattern section)
     ticket: OMN-1004
+  # ==========================================================================
+  # MixinAsyncCircuitBreaker - _init_circuit_breaker parameter count (OMN-1743)
+  # ==========================================================================
+  # Circuit breaker initialization requires multiple configuration parameters
+  # for proper resilience behavior: threshold, reset_timeout, service_name,
+  # transport_type, and half_open_successes. These are standard circuit breaker
+  # configuration parameters that belong together for proper initialization.
+  - file_pattern: 'mixin_async_circuit_breaker\.py'
+    method_pattern: "Function '_init_circuit_breaker'"
+    violation_pattern: 'has \d+ parameters'
+    reason: >
+      Circuit breaker initialization requires cohesive configuration parameters: threshold (failures before open), reset_timeout (seconds before half-open), service_name (for error context), transport_type (for error codes), and half_open_successes (for close validation). These parameters define the complete circuit breaker behavior and cannot be split without losing cohesion. Alternative is ModelCircuitBreakerConfig but direct parameters preferred for mixin flexibility.
+
+    documentation:
+      - docs/patterns/circuit_breaker_implementation.md
+      - CLAUDE.md (Circuit Breaker Pattern section)
+    ticket: OMN-1743
   # ModelOperationContext - operation_name is an operation identifier string
   - file_pattern: 'model_operation_context\.py'
     violation_pattern: "Field 'operation_name' might reference an entity"
@@ -1919,6 +1954,82 @@ pattern_exemptions:
     documentation:
       - CLAUDE.md (Contract-Driven - node_name conventions)
     ticket: OMN-1653
+  # ==========================================================================
+  # ModelDeclarativeNodeViolation Field Exemptions (OMN-1725)
+  # ==========================================================================
+  # node_class_name and method_name are descriptive strings providing context
+  # about where a violation occurred, not entity references requiring ID + display_name.
+  - file_pattern: 'model_declarative_node_violation\.py'
+    violation_pattern: "Field 'node_class_name' might reference an entity"
+    reason: >
+      node_class_name is a descriptive string showing which node class contains the violation (e.g., "NodeRegistrationOrchestrator"). It provides human-readable context for error messages and CI output, not an entity reference requiring ID + display_name pattern.
+
+    documentation:
+      - CLAUDE.md (Declarative Nodes)
+    ticket: OMN-1725
+  - file_pattern: 'model_declarative_node_violation\.py'
+    violation_pattern: "Field 'method_name' might reference an entity"
+    reason: >
+      method_name is a descriptive string showing which method/property triggered the violation (e.g., "compute", "__bool__"). It provides human-readable context for debugging and does not require ID + display_name pattern.
+
+    documentation:
+      - CLAUDE.md (Declarative Nodes)
+    ticket: OMN-1725
+  # ==========================================================================
+  # Observability Consumer Model Exemptions (OMN-1743)
+  # ==========================================================================
+  # These models consume EXTERNAL Kafka events from omniclaude producers.
+  # The field types are dictated by the producer schema, not our internal design.
+  # Using entity references (_id + _name) or enums would break compatibility
+  # with the existing event producers.
+  - file_pattern: 'services/observability/agent_actions/models/model_agent_action\.py'
+    violation_pattern: "Field 'agent_name' might reference an entity"
+    reason: >
+      External observability event payload. The agent_name field comes from Kafka events produced by omniclaude. Using ID + display_name pattern would break compatibility with existing producers.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
+  - file_pattern: 'services/observability/agent_actions/models/model_agent_action\.py'
+    violation_pattern: "Field 'action_name' might reference an entity"
+    reason: >
+      External observability event payload. The action_name field comes from Kafka events produced by omniclaude. Using ID + display_name pattern would break compatibility with existing producers.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
+  - file_pattern: 'services/observability/agent_actions/models/model_execution_log\.py'
+    violation_pattern: "Field 'agent_name' might reference an entity"
+    reason: >
+      External observability event payload. The agent_name field comes from Kafka events produced by omniclaude. Using ID + display_name pattern would break compatibility with existing producers.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
+  - file_pattern: 'services/observability/agent_actions/models/model_execution_log\.py'
+    violation_pattern: "Field 'status' should use Enum"
+    reason: >
+      External observability event payload. The status field values (started, running, completed, failed) are defined by omniclaude producer. Converting to enum would break compatibility.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
+  - file_pattern: 'services/observability/agent_actions/models/model_envelope\.py'
+    violation_pattern: "Field 'producer_id' should use UUID"
+    reason: >
+      External service identifier string (e.g., 'omniclaude', 'archon-intelligence'). It is NOT an internal entity UUID but a producer service name.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
+  - file_pattern: 'services/observability/agent_actions/models/model_performance_metric\.py'
+    violation_pattern: "Field 'metric_name' might reference an entity"
+    reason: >
+      External observability event payload. The metric_name field comes from Kafka events produced by omniclaude. Using ID + display_name pattern would break compatibility.
+
+    documentation:
+      - docs/plans/OMN-1743-migration-plan.md
+    ticket: OMN-1743
 # Architecture validator exemptions
 # These handle one-model-per-file violations for domain-grouped protocols
 architecture_exemptions: