feat: simplify IRIS connection architecture (Feature 051)

Simplify IRIS database connection management from 6 complex components to
1-2 simple modules with production-ready features.

## Changes

**Core Implementation:**
- New `iris_vector_rag/common/iris_connection.py` - Unified connection module
  - Single function: `get_iris_connection()` with module-level caching
  - Automatic edition detection (Community vs Enterprise)
  - Thread-safe operations with threading.Lock
  - Preserves UV compatibility fix (Issue #5)

- New `iris_vector_rag/common/exceptions.py` - Custom exceptions
  - ValidationError for parameter validation (fail-fast)
  - ConnectionLimitError for edition-aware connection limiting

**Connection Pooling (User Story 3):**
- `IRISConnectionPool` class for high-concurrency scenarios
  - Edition-aware defaults (Community=1, Enterprise=20)
  - Thread-safe acquire/release with queue.Queue
  - Context manager protocol support
  - Timeout handling for pool exhaustion

**Backward Compatibility:**
- Added deprecation warnings to 3 legacy modules:
  - `iris_vector_rag/common/connection_manager.py`
  - `iris_vector_rag/common/iris_connection_manager.py`
  - `iris_vector_rag/testing/connection_pool.py`
- All warnings include migration guidance to new API

**Testing:**
- 12 contract tests (100% passing)
- 18 integration tests (properly skipped without IRIS)
- ZERO breaking changes to existing functionality

**Code Quality:**
- PEP 8 compliant (black formatting)
- Organized imports (isort)
- Zero critical flake8 issues

## Migration

Old:
```python
from iris_vector_rag.common import IRISConnectionManager
manager = IRISConnectionManager()
conn = manager.get_connection()
```

New:
```python
from iris_vector_rag.common import get_iris_connection
conn = get_iris_connection()
```

See specs/051-simplify-iris-connection/quickstart.md for details.

## Testing

```bash
# Contract tests
SKIP_IRIS_CONTAINER=1 pytest tests/contract/test_iris_connection_contract.py -v
# Result: 12 passed, 4 skipped in 0.23s

# Integration tests (require IRIS database)
SKIP_IRIS_CONTAINER=0 pytest tests/integration/test_iris_connection_integration.py -v
```

Closes #051

Author: tom-dyar

iris_vector_rag/common/connection_manager.py

@@ -1,26 +1,47 @@
 """
 Centralized connection manager for RAG pipelines
 Handles JDBC, ODBC, and future dbapi connections with a unified interface
+
+DEPRECATED: This module is deprecated as of Feature 051 (Simplify IRIS Connection).
+Use iris_vector_rag.common.get_iris_connection() instead for simple connections,
+or iris_vector_rag.common.IRISConnectionPool() for pooling.
+See specs/051-simplify-iris-connection/quickstart.md for migration guide.
 """
 
 import logging
 import os
+import warnings
 from contextlib import contextmanager
 from typing import Any, List, Optional
 
 logger = logging.getLogger(__name__)
 
 
 class ConnectionManager:
-    """Manages database connections for RAG pipelines"""
+    """
+    Manages database connections for RAG pipelines
+
+    DEPRECATED: Use get_iris_connection() or IRISConnectionPool instead.
+    """
 
     def __init__(self, connection_type: str = "odbc"):
         """
         Initialize connection manager
 
         Args:
             connection_type: Either "jdbc", "odbc", or "dbapi" (default: "odbc" for stability)
+
+        DEPRECATED: This class is deprecated. Use get_iris_connection() instead:
+            from iris_vector_rag.common import get_iris_connection
+            conn = get_iris_connection()
         """
+        warnings.warn(
+            "ConnectionManager is deprecated as of Feature 051. "
+            "Use get_iris_connection() for simple connections or IRISConnectionPool for pooling. "
+            "See specs/051-simplify-iris-connection/quickstart.md for migration guide.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.connection_type = connection_type.lower()
         self._connection = None
         self._cursor = None
@@ -37,7 +58,9 @@ def connect(self):
 
         if self.connection_type == "jdbc":
             try:
-                from iris_vector_rag.common.iris_connection_manager import get_iris_jdbc_connection
+                from iris_vector_rag.common.iris_connection_manager import (
+                    get_iris_jdbc_connection,
+                )
 
                 self._connection = get_iris_jdbc_connection()
                 logger.info("Established JDBC connection")
@@ -48,7 +71,9 @@ def connect(self):
 
         elif self.connection_type == "dbapi":
             try:
-                from iris_vector_rag.common.iris_dbapi_connector import get_iris_dbapi_connection
+                from iris_vector_rag.common.iris_dbapi_connector import (
+                    get_iris_dbapi_connection,
+                )
 
                 self._connection = get_iris_dbapi_connection()
                 if not self._connection:  # If get_iris_dbapi_connection returns None

iris_vector_rag/common/exceptions.py

@@ -0,0 +1,75 @@
+"""
+Custom exceptions for IRIS connection management.
+
+This module defines the exception hierarchy for the unified IRIS connection module,
+providing clear, actionable error messages for connection failures.
+"""
+
+
+class ValidationError(ValueError):
+    """
+    Raised when connection parameters fail validation before connection attempt.
+
+    This exception is raised during parameter validation (before any connection
+    attempt), providing immediate feedback on invalid configuration.
+
+    Attributes:
+        parameter_name: Name of the parameter that failed validation
+        invalid_value: The value that was rejected
+        valid_range: Description of acceptable values
+        message: Full error message with actionable guidance
+
+    Example:
+        >>> raise ValidationError(
+        ...     parameter_name="port",
+        ...     invalid_value=99999,
+        ...     valid_range="1-65535",
+        ...     message="Invalid port 99999: must be between 1-65535"
+        ... )
+    """
+
+    def __init__(
+        self, parameter_name: str, invalid_value, valid_range: str, message: str
+    ):
+        self.parameter_name = parameter_name
+        self.invalid_value = invalid_value
+        self.valid_range = valid_range
+        super().__init__(message)
+
+
+class ConnectionLimitError(RuntimeError):
+    """
+    Raised when IRIS Community Edition connection limit is reached.
+
+    This exception is raised when attempting to create more connections than
+    allowed by the detected IRIS edition (typically 1 for Community Edition).
+
+    Attributes:
+        current_limit: Maximum connections allowed for detected edition
+        suggested_actions: List of actionable suggestions for resolving the issue
+        message: Full error message with context and suggestions
+
+    Example:
+        >>> raise ConnectionLimitError(
+        ...     current_limit=1,
+        ...     suggested_actions=[
+        ...         "Use connection queuing with IRISConnectionPool",
+        ...         "Run tests serially with pytest -n 0",
+        ...         "Set IRIS_BACKEND_MODE=community explicitly"
+        ...     ],
+        ...     message="IRIS Community Edition connection limit (1) reached. Consider: ..."
+        ... )
+    """
+
+    def __init__(self, current_limit: int, suggested_actions: list[str], message: str):
+        self.current_limit = current_limit
+        self.suggested_actions = suggested_actions
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Format error message with suggested actions."""
+        base_message = super().__str__()
+        if self.suggested_actions:
+            actions = "\n  - ".join(self.suggested_actions)
+            return f"{base_message}\n\nSuggested actions:\n  - {actions}"
+        return base_message