muzick/docs/architecture/02-invariants-and-risks.md

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.