feat: implement Firestore event and error storage (Issue #2)

[prosdev]

Summary

Implements persistent storage for events and errors using Google Cloud Firestore with batch operations, retry logic, and stream-based isolation.

Closes #2

Implementation Details

FirestoreEventStore

• Storage structure: Subcollections per stream ()
• Batching: Automatic chunking into 500-doc batches (Firestore limit)
• Retry logic: Exponential backoff for transient errors (DeadlineExceeded, ServiceUnavailable, InternalServerError)
• Async wrapper: Uses asyncio.to_thread() to wrap sync Firestore client
• Methods: store(), store_batch(), read(stream, limit)

FirestoreErrorStore (Dead Letter Queue)

• Storage structure: Flat errors/ collection
• Captures: Raw payload, error message, timestamp, metadata
• Methods: store_error(), query_errors(limit)

Testing

• Unit tests: 20 tests with mocked Firestore client (100% coverage)
• Integration tests: 3 tests with Docker Compose Firestore emulator
  • End-to-end write/read (100 events)
  • Stream isolation (mobile vs web)
  • Error store persistence

Docker Compose

• Added docker-compose.yml with Firestore emulator
• Tests skip gracefully when emulator not running
• Updated README with Docker usage instructions

Commits

1. Setup + serialization helpers - FirestoreEventStore base, path construction, serialization
2. Write path + retry logic - store(), store_batch() with tenacity retries
3. Read path + deserialization - read(), _dict_to_event() with type routing
4. Error store (DLQ) - FirestoreErrorStore for failed events
5. Integration tests + Docker - Docker Compose + 3 integration tests
6. Documentation - Updated tasks.md acceptance criteria

Testing

# Unit tests (fast, no Docker)
uv run pytest

# Integration tests (requires Docker)
docker compose up -d
export FIRESTORE_EMULATOR_HOST=localhost:8080
uv run pytest -m integration
docker compose down

Files Changed

• src/eventkit/stores/firestore.py (new, 240 lines)
• tests/unit/stores/test_firestore.py (new, 270 lines)
• tests/integration/test_firestore_integration.py (new, 140 lines)
• docker-compose.yml (new)
• pytest.ini (updated with integration marker)
• README.md (updated with Docker instructions)
• pyproject.toml (added tenacity dependency)
• src/eventkit/schema/events.py (added stream field)
• specs/core-pipeline/tasks.md (marked Task 4 complete)

Dependencies Added

• tenacity>=8.2.0 - Retry logic with exponential backoff

Acceptance Criteria (All Met)

• FirestoreEventStore implements EventStore Protocol
• Batch writes (max 500 docs per batch)
• Document ID: {stream}/{timestamp}_{uuid}
• Retry logic for transient errors
• FirestoreErrorStore implements ErrorStore Protocol
• Unit tests with mocked Firestore client
• Integration tests with Firestore emulator