serato-doctor/docs/design/crate-classification.md

Crate Classification

Problem

Static crates are manually maintained track lists. Smart crates are dynamic views generated from rules, so stale-looking entries in them should not be presented as broken manual references or given the same health-score weight.

Architecture

Crates carry a static, smart, or unknown kind. Folder provenance is the primary signal: Serato stores regular .crate files in Subcrates and smart .scrate definitions in SmartCrates. Compatible by key.crate is also treated as smart when encountered in Subcrates, based on the original migration case study.

Smart crate names use ≫≫ to encode hierarchy. The model preserves those segments, so Compatible by key≫≫10A.scrate has a parent of Compatible by key and a display name of 10A. Smart definitions and dynamic .crate containers are counted separately.

The library loader reads both folders. Health analysis reports all references but scores only non-smart references. Unknown crates remain scoreable so incomplete classification cannot silently hide potential problems.

Serato documents the folder distinction in What is in the Serato folder? and explains that smart crates are populated from rules in Crates in Serato DJ.

Edge Cases

• The known Compatible by key dynamic crate in the Subcrates folder.
• Crate fixtures outside a recognized Serato folder.
• Libraries containing both static and smart references to the same track.
• Dynamic references whose current materialized paths appear missing.

Verification

Tests cover all three kinds, both Serato folders, the known dynamic fallback, the synthetic five-static/two-smart library, and exclusion from health scoring.