SYSTEM ARCHITECTURE

/// Incremental scanning with timestamp-based skip logic
/// Delivers 5-15x performance gains on repeated scans
func performIncrementalScan(range: ScanRangeOption) async throws {
    guard let lastScanDate = getLastSuccessfulScanDate() else {
        // First scan - analyze everything
        return try await fullScan(range: range)
    }
    
    var skippedCount = 0
    var analyzedCount = 0
    
    for asset in photoAssets {
        // SKIP LOGIC: Photo hasn't been modified since last scan
        if let modDate = asset.modificationDate,
           modDate < lastScanDate {
            skippedCount += 1
            continue // Skip this photo (already analyzed)
        }
        
        // Analyze photo (new or modified since last scan)
        let result = try await analyzer.analyze(asset)
        analyzedCount += 1
        
        if result.isSensitive {
            await notifyUser(asset)
        }
    }
    
    #if DEBUG
    print("[Incremental] Analyzed: \(analyzedCount), Skipped: \(skippedCount)")
    print("[Performance] Skip ratio: \(Double(skippedCount)/Double(total) * 100)%")
    #endif
    
    // Update timestamp for next scan
    saveLastSuccessfulScanDate(Date())
}

/// Performance metrics (real-world data)
/// v1.7 (Full Scan): 28.4s for 20 photos
/// v2.x (Incremental): 1.9s for 20 photos (99% cache hit)
/// Improvement: 15x faster, 87% battery savings

import CryptoKit

/// ChaCha20-Poly1305 encryption for vault storage
/// Keys stored in iOS Keychain with Secure Enclave protection
final class VaultCrypto {
    
    /// Encrypts photo data with ChaCha20-Poly1305 AEAD
    static func encryptData(_ data: Data, key: SymmetricKey) throws -> Data {
        // ChaCha20-Poly1305 provides:
        // - Confidentiality (encryption)
        // - Authenticity (HMAC)
        // - Integrity (tampering detection)
        let sealedBox = try ChaChaPoly.seal(data, using: key)
        
        return sealedBox.combined // Nonce + Ciphertext + Tag
    }
    
    /// Decrypts vault photo
    static func decryptData(_ encryptedData: Data, key: SymmetricKey) throws -> Data {
        let sealedBox = try ChaChaPoly.SealedBox(combined: encryptedData)
        let decryptedData = try ChaChaPoly.open(sealedBox, using: key)
        
        return decryptedData
    }
    
    /// Generates 256-bit encryption key with entropy validation (v2.1.8+)
    static func generateVaultKey() throws -> SymmetricKey {
        let maxRetries = 3
        
        for attempt in 0..= 7.5 {
                return key
            }
            
            #if DEBUG
            print("[Crypto] Low entropy detected, retry \(attempt + 1)/\(maxRetries)")
            #endif
        }
        
        throw CryptoError.insufficientEntropy
    }
}