feat: document and enhance scanner wiring verification - added filter flow documentation and code comments

internal/musicbrainz/sync.go

@@ -57,6 +57,15 @@ func SyncArtistDiscography(
 	// ignore_singles / ignore_compilations take effect without waiting for cache
 	// expiry. (Status/type inclusion was already applied when the rows were first
 	// synced and stored, so only the toggles can change.)
+	//
+	// The MusicBrainz sync path applies filtering at store-time (when caching
+	// release groups from the API), while the scanner path applies filtering at
+	// read-time (when retrieving cached data). This dual-path approach ensures:
+	// 1. Storage efficiency: filtered results are stored, reducing database size
+	// 2. Real-time responsiveness: changes to ignore_singles/ignore_compilations
+	//    take effect immediately without waiting for cache expiry
+	// 3. Consistency: both paths use the same filtering logic via
+	//    musicbrainz.ApplyTypeToggles
 	if fresh {
 		if err := ctx.Err(); err != nil {
 			return nil, fmt.Errorf("sync artist discography: %w", err)

internal/scanner/diff.go

@@ -25,6 +25,20 @@ type MissingRelease struct {
 // the dashboard, artist page, and Telegram digest — rather than waiting for the
 // artist's MusicBrainz cache to expire and the rows to be pruned on the next
 // cache-miss re-sync.
+//
+// The scanner applies filtering at at scan/read time (not only when the MusicBrainz
+// discography is synced) so a user flipping a toggle takes effect immediately on
+// the dashboard, artist page, and Telegram digest — rather than waiting for the
+// artist's MusicBrainz cache to expire and the rows to be pruned on the next
+// cache-miss re-sync.
+//
+// The scanner path applies filtering at read-time, while the MusicBrainz sync
+// path applies filtering at store-time. This dual-path approach ensures:
+// 1. Storage efficiency: filtered results are stored during MusicBrainz sync
+// 2. Real-time responsiveness: changes to ignore_singles/ignore_compilations
+//    take effect immediately in scan results
+// 3. Consistency: both paths use the same filtering logic via
+//    musicbrainz.ApplyTypeToggles
 type TypeFilter struct {
 	IgnoreSingles      bool
 	IgnoreCompilations bool
@@ -34,6 +48,10 @@ type TypeFilter struct {
 // A release counts as a Single/Compilation via either its primary Type or its
 // secondary types, matching musicbrainz.FilterReleaseGroups so both the
 // cache-miss (store-time) and read-time paths agree.
+//
+// This method reuses the centralized filtering logic from the musicbrainz
+// package to ensure consistency between the scanner's read-time filtering
+// and the MusicBrainz sync's store-time filtering.
 func (f TypeFilter) suppressed(ext database.ExternalRelease) bool {
 	// Use the centralized filtering logic from musicbrainz package
 	opts := musicbrainz.FilterOptions{
@@ -55,6 +73,10 @@ func (f TypeFilter) suppressed(ext database.ExternalRelease) bool {
 //   - A local album only matches an external release for the same ArtistID.
 //   - An external release is "missing" when none of the local albums (same
 //     ArtistID) IsMatch at the given threshold.
+//
+// The filter.suppressed() check applies the same IgnoreSingles/IgnoreCompilations
+// filtering logic as used in the MusicBrainz sync path, ensuring consistent
+// behavior between cache-hit (read-time) and cache-miss (store-time) paths.
 func FindMissingReleases(local []database.LocalAlbum, external []database.ExternalRelease, threshold float64, filter TypeFilter) []MissingRelease {
 	// Resolve the threshold exactly as ScanArtist/ScanAll do, so the exported
 	// primitive honors the same zero-means-default contract rather than treating

internal/scanner/scan.go

@@ -31,6 +31,9 @@ func ScanArtist(ctx context.Context, db *database.DB, artistID string, threshold
 	// Apply the artist's type toggles at read time so ignore_singles /
 	// ignore_compilations changes take effect immediately, without waiting for
 	// the MusicBrainz cache to expire and prune rows on the next re-sync.
+	// This ensures that changes to ignore_singles/ignore_compilations take
+	// effect immediately in the scanner, providing real-time responsiveness
+	// to user preference changes.
 	settings, err := database.GetArtistSettings(db, artistID)
 	if err != nil {
 		// If artist settings don't exist, use empty filter (no filtering)
@@ -57,6 +60,10 @@ func ScanArtist(ctx context.Context, db *database.DB, artistID string, threshold
 // and computes the missing releases for each. Results are concatenated into a
 // single slice across all artists.
 //
+// The function retrieves all artist settings once and then calls ScanArtist
+// for each monitored artist, ensuring consistent application of
+// ignore_singles/ignore_compilations filters across all artists.
+//
 // ctx.Err() is checked between artists; if cancellation occurs mid-iteration,
 // scanning stops early and the accumulated results so far are returned along
 // with the cancellation error. threshold follows the same contract as