# Specification: High-Integrity Cache & Database Synchronization

## 1. Overview
Implement a robust, multi-tier synchronization layer between the primary PostgreSQL database and the Redis caching layer. The system must ensure data integrity through versioning and provide tiered security for sensitive data while maintaining high availability during intermittent failures. **Crucially, all data access must be 'Cache-First,' prioritizing the Redis layer to minimize direct database load.**

## 2. Functional Requirements
- **Cache-First Data Access (Read-Aside Pattern)**:
    - All data read requests MUST attempt to fetch from Redis first.
    - If the data is missing (Cache Miss), the system must fetch from PostgreSQL, update Redis, and then return the result.
    - Tiered security must be applied during the cache lookup (e.g., decryption for sensitive data).
- **Atomic Synchronous Sync (Write-Through Pattern)**:
    - Primary write operations to PostgreSQL must trigger a corresponding update to Redis within the same logical transaction block where possible.
- **Versioned Data Integrity**:
    - Each data entity must include a `version_id` or `updated_at_ns` (nanoseconds).
    - Cache updates MUST be ignored if the current cache version is newer than the incoming update.
- **Degraded Mode with Retry**:
    - If Redis is unavailable, data access MUST fallback directly to PostgreSQL without error.
    - Write failures to Redis must be logged to a PostgreSQL `sync_retry_queue` table for background replay.
- **Tiered Security**:
    - **Tier 1 (Catalog/Non-Sensitive)**: Standard Redis storage.
    - **Tier 2 (Orders/Sensitive)**: Encrypted values in Redis (AES-256).
    - **Tier 3 (PII/Critical)**: No raw PII in Redis; only non-reversible hashes or encrypted references.
- **Idempotent Retries**: All sync operations must be idempotent to prevent duplicate processing.

## 3. Non-Functional Requirements
- **Latency Target**: < 50ms overhead for synchronous sync operations.
- **Reliability**: 100% eventual consistency through the retry mechanism.
- **Security**: Mandatory use of `redactPii` for all sync-related logs.
- **Observability**: Real-time monitoring of the `sync_retry_queue` size.

## 4. Acceptance Criteria
- [ ] Read requests fetch from Redis when data is present (Cache Hit).
- [ ] Read requests fetch from PostgreSQL and update Redis when data is missing (Cache Miss).
- [ ] Successful write to DB triggers immediate Cache update for all tiers.
- [ ] Redis downtime does not block DB writes but populates the `sync_retry_queue`.
- [ ] Stale cache updates (older version/timestamp) are rejected by the sync layer.
- [ ] PII is never stored in plaintext in the Cache layer.
- [ ] 100% test coverage using real PostgreSQL and Redis instances (Anti-Mocking).

## 5. Implementation Constraints (No Ambiguity)
Implementers MUST provide line numbers and code snippets for all proposed changes. No speculative inference allowed.

## 6. Out of Scope
- Full-text search synchronization.
- Multi-region Redis replication.