# Story 6.2: Consolidate Cache Error Classes

## Status: Hold

## Summary

Replace the four cache-specific exception classes (`CacheError`, `CacheMissError`, `CacheOperationError`, `CacheCapacityError`) with a single `CacheError` class. The internal LRU cache does not require fine-grained exception types.

## Motivation

The complexity audit identified 4 cache-specific exceptions (lines 551-640 in `errors.py`) that are excessive for an internal caching implementation:

- `CacheError` — Base class
- `CacheMissError` — Key not found
- `CacheOperationError` — Operation failed
- `CacheCapacityError` — Capacity exceeded

These are used only by the internal `caching/cache.py` module and are not part of the public API. The base `FapilogError` with `category=ErrorCategory.SYSTEM` already provides classification.

Fine-grained exception types are valuable when:

- External code catches specific exceptions for different handling
- Exception type drives recovery strategy

Neither applies here — the cache is internal infrastructure.

## Acceptance Criteria

- [ ] `CacheMissError`, `CacheOperationError`, `CacheCapacityError` removed from `errors.py`
- [ ] `CacheError` retained with clear docstring
- [ ] `caching/cache.py` updated to use only `CacheError` with descriptive messages
- [ ] `caching/fallback.py` updated if it references removed classes
- [ ] All cache-related tests updated and passing
- [ ] No grep hits for removed class names in `src/`

## Technical Approach

1. Update `CacheError` to accept optional `key`, `operation`, and context parameters:

   ```python
   class CacheError(FapilogError):
       """Error during cache operations."""

       def __init__(
           self,
           message: str,
           *,
           key: str | None = None,
           operation: str | None = None,
           cause: Exception | None = None,
       ) -> None:
           super().__init__(
               message,
               category=ErrorCategory.SYSTEM,
               severity=ErrorSeverity.MEDIUM,
               recovery_strategy=ErrorRecoveryStrategy.FALLBACK,
               cause=cause,
           )
           self.cache_key = key
           self.operation = operation
   ```

2. Remove `CacheMissError`, `CacheOperationError`, `CacheCapacityError`

3. Update `caching/cache.py` to raise `CacheError` with appropriate messages:

   - Cache miss: `CacheError(f"Key not found: {key}", key=key, operation="get")`
   - Operation error: `CacheError(f"Operation '{op}' failed for key '{key}'", key=key, operation=op, cause=exc)`

4. Update tests

## Files Changed

- `src/fapilog/core/errors.py` — Remove 3 classes (~70 lines)
- `src/fapilog/caching/cache.py` — Update exception usage
- `src/fapilog/caching/fallback.py` — Update if needed
- `tests/unit/test_cache.py` — Update exception assertions

## Estimated Effort

2-3 hours

## Risk Assessment

**Risk Level: Low**

- Internal API only
- Cache module is self-contained
- Exception handling patterns remain the same
- Easy to verify via tests

## Rollback Plan

Revert the commit; original exception hierarchy can be restored.
