# Invariants and Risks

This document outlines the critical rules that MUST be respected to maintain system integrity and the identified technical risks.

## 1. System Invariants (The "Never Break" Rules)

### **A. Data Consistency (The "No Ghost Tracks" Rule)**
* **Invariant:** Every `track` record in the database must correspond to a physical file on the disk.
* **Mechanism:** The **Consistency Worker** must run periodically to reconcile the database with the `/mnt/hdd1/media/Music` directory. Any discrepancy must result in the track being marked as `MISSING` in the DB, rather than deleted immediately.

### **B. Session Integrity (The "No Deadlocks" Rule)**
* **Invariant:** An `ACTIVE` recommendation batch must eventually reach a terminal state (`RESOLVED` or `FAILED`).
* **Mechanism:** Every batch must have a `last_interaction_at` timestamp. A background sweep must transition stale `ACTIVE` sessions to `RESOLVED` to allow new sessions to start.

### **C. Filesystem Safety (The "Irreversible Action" Rule)**
* **Invariant:** Hard deletion of a file from the filesystem is the final, irreversible step in the `PENDING_REMOVAL` lifecycle.
* **Mechanism:** A track only enters the `DELETE_FILE` state after it has been `warned` for at least 24 hours and the user has not explicitly triggered a `RESTORE`.

## 2. Known Technical Risks

### **A. The "Similarity Explosion" (Scalability)**
* **Risk:** Precomputing a $O(n^2)$ similarity matrix for large libraries will exhaust database resources.
* **Mitigation:** 
    * Use **Tiered Similarity**: Metadata-based matches (Instant) $\rightarrow$ Audio-feature matches (Asynchronous/On-demand).
    * Limit similarity computation to tracks within the same genre or recent listening window.

### **B. Computational Exhaustion (Resource Management)**
* **Risk:** Heavy audio analysis (Essentia) can starve the API of CPU/RAM.
* **Mitigation:** Audio analysis and metadata enrichment must run in dedicated worker processes (containers) with strict resource limits (cgroups/Docker).

### **C. Metadata Drift**
* **Risk:** External providers (MusicBrainz/Discogs) may provide conflicting or low-quality data.
* **Mitigation:** Implement a priority-based enrichment pipeline and allow manual user overrides via the UI.

### **D. Race Conditions (The "Cleanup Race")**
* **Risk:** A user interacts with a track at the exact moment the Sweep Worker attempts to delete the file.
* **Mitigation:** Use transactional state transitions (e.g., `UPDATE tracks SET state = 'HIDDEN' WHERE id = X AND state = 'PENDING_REMOVAL'`) to ensure an action only happens if the state hasn't changed.