name: validation

rules:
  - Validate inputs early and raise ValueError or domain-specific exceptions (ProviderError) for invalid contract inputs.
  - Tests should assert that invalid inputs raise the expected exceptions.
  - Use explicit checks for types and shapes on public APIs (e.g., ensure text is str before embedding).

examples:
  - path: ai_provider.py
    excerpt: |
      ```python
      if not isinstance(text, str):
          raise ProviderError("text must be a string")
      ```
    note: explicit type validation before network call

  - path: pipeline/ai_provider_wrapper.py
    excerpt: |
      ```python
      if not texts:
          return []
      if motion_ids is None:
          motion_ids = [None for _ in texts]
      ```
    note: defensive handling of empty inputs

anti_patterns:
  - Bad: Allowing invalid values to propagate into heavy computation (e.g., non-string into embedding pipeline).
    remediation: Fail fast with a typed exception and add unit tests to cover validations.