spacedrive/.tasks/CORE-015-normalized-cache-swift.md

id, title, status, assignee, priority, tags, depends_on

id	title	status	assignee	priority	tags	depends_on
CORE-015	Normalized Client Cache (Swift)	To Do	james	High	client swift cache performance	CORE-012

Description

Implement the normalized client cache for iOS/macOS apps. Provides instant UI updates, offline support, and massive bandwidth savings by normalizing all resources by ID and updating atomically when events arrive.

Implementation Steps

1. Create NormalizedCache actor with two-level structure:
   • Level 1: Entity store (normalized by ID)
   • Level 2: Query index (maps queries to entity IDs)
2. Implement updateEntity<T>() - updates entity and notifies observers
3. Implement query<T>() - caches queries and results
4. Implement deleteEntity() - removes entity and updates indices
5. Implement invalidateQueriesForResource() - bulk operation handling
6. Add LRU eviction (max 10K entities)
7. Add SQLite persistence for offline support
8. Create EventCacheUpdater for event integration

Cache Architecture

┌─────────────────────────────────────────┐
│ Entity Store (Level 1)                  │
│  "file:uuid-1" → File { ... }           │
│  "album:uuid-2" → Album { ... }         │
└─────────────────────────────────────────┘
                ↑
                │ Atomic updates
                │
┌─────────────────────────────────────────┐
│ Query Index (Level 2)                   │
│  "search:photos" → ["file:uuid-1", ...] │
│  "albums.list" → ["album:uuid-2"]       │
└─────────────────────────────────────────┘

Technical Details

• Location: packages/client-swift/Sources/SpacedriveCore/Cache/NormalizedCache.swift
• Actor for thread-safety
• Max entities: 10,000 (configurable)
• TTL: 5 minutes default (query-specific)
• Persistence: SQLite in app cache directory

Acceptance Criteria

• NormalizedCache actor implemented
• Entity store with LRU eviction
• Query index with TTL
• SQLite persistence
• EventCacheUpdater integration
• ObservableObject wrapper for SwiftUI
• Memory stays under 15MB with 10K entities
• Unit tests for cache operations
• Integration tests with events

References

• docs/core/normalized_cache.md - Complete specification