kami
38 lines
2.6 KiB
Markdown
38 lines
2.6 KiB
Markdown
# 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.
|