python_script_runner 1.7.10

# DOMAIN_RULES.md — python_script_runner.rs

## 1. Tier Assignments

| Function / Method | Tier | Reason |
|-------------------|------|--------|
| `PythonExecutor::execute_script()` | 1 | Public API — silent failure hides script execution errors |
| `run_python_script()` | 1 | Public API — silent failure loses script failure information |
| `PythonExecutor::new()` | 2 | Constructor — failure visible via .expect() panic |
| `ScriptPaths::new()` | 2 | Constructor — failure visible via .expect() panic |
| `ScriptPaths::get_script_path()` | 3 | Pure path construction — no IO |

## 2. Logging Strategy

- **Implementation:** Uses tokio async I/O for streaming output
- **Logger name:** N/A — module does not write to audit logs; streams stdout/stderr directly
- **Output routing:** `run_python_script()` forwards stdout/stderr to process stdout/stderr in real time

## 3. Error Classes

| Class | Inherits | Raised when |
|-------|----------|-------------|
| `io::Error` (NotFound) | `std::io::Error` | Script file does not exist at path |
| `io::Error` (Other) | `std::io::Error` | Script exits non-zero after all retry attempts exhausted |
| `io::Error` (NotFound) | `std::io::Error` | Python interpreter not found |
| `io::Error` (InvalidInput) | `std::io::Error` | Script path contains invalid UTF-8 |

No custom error types. `std::io::Error` is sufficient for process-execution errors.

## 4. Retry Policy

| Function | Retries | Max Attempts | Retryable Errors | Delay |
|----------|---------|--------------|------------------|-------|
| `run_python_script()` | Yes | 3 | Non-zero exit status | 3s, fixed |

**Not retryable:**
- Script file not found — fails fast before loop, returns `NotFound` immediately
- Python interpreter not found — will never succeed, no point retrying
- Invalid UTF-8 in path — deterministic failure, no point retrying

**Non-idempotent note:** `run_python_script()`: no retry — non-idempotent. Running the same script twice may produce different side effects (e.g., file writes, network calls). Retry is intended only for transient failures (interpreter warmup, temp file locks), not for scripts that modify state.

## 5. Domain-Specific Test Scenarios

### Path resolution
- PROJECT_DIRECTORY must be loaded from .env via dotenv
- Relative path must be joined to PROJECT_DIRECTORY correctly
- Path with leading slash must still be relative to PROJECT_DIRECTORY

### Script execution
- Missing script must fail fast with NotFound (no retry)
- Script that exits 0 on first attempt must succeed immediately
- Script that exits non-zero must retry up to 3 times
- Final non-zero exit must return error with max retries message

### Output streaming
- stdout must be streamed to process stdout in real time
- stderr must be streamed to process stderr in real time
- Output from all attempts must be visible (not just final attempt)

### Python interpreter detection
- python3 must be preferred over python if both available
- Fallback to python when python3 not available

### Error handling
- Invalid UTF-8 in path must return InvalidInput error
- Empty script path must be handled (not crash)
- Non-existent PROJECT_DIRECTORY must panic with clear message