@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/core/apple-projection-domain-services.mjs

@@ -1,5 +1,10 @@
 import { randomUUID } from "node:crypto";
+import { exploreProfileCatalog, profileExplorationInput } from "../profile/profile-exploration.mjs";
+import { createListenerProfileInput, savedListenerChoices } from "../profile/listener-profile-build.mjs";
 import { lyricSeedsFromProfile } from "./lyric-profile.mjs";
+import { cachedAvoidGate, createAvoidGate, listeningVersion } from "./listener-avoids.mjs";
+import { recordListenerChoice } from "../profile/listener-corrections.mjs";
+import { normalizedTrackTitle } from "./track-title.mjs";
 import { collectionCoverage } from "../profile/music-providers.mjs";
 import { lstat } from "node:fs/promises";
 import path from "node:path";
@@ -408,6 +413,11 @@ function safeHistoryCount(value) {
   return value;
 }
 
+// A pick leaves out minutes or skips that its plays never recorded.
+function optionalHistoryCount(context, key) {
+  return context[key] === undefined ? {} : { [key]: safeHistoryCount(context[key]) };
+}
+
 function safeHistoryExternalRefs(value) {
   if (value === undefined) return [];
   if (!Array.isArray(value)) {
@@ -487,10 +497,13 @@ function safeHistoryTrack(raw) {
   if (hasRediscovery) {
     const rediscovery = raw.rediscovery;
     const engagedPlayCount = safeHistoryCount(rediscovery.engaged_play_count);
-    const explicitSkips = safeHistoryCount(rediscovery.explicit_skips);
-    const listeningMinutes = safeHistoryCount(rediscovery.listening_minutes);
+    const explicitSkips = optionalHistoryCount(rediscovery, "explicit_skips");
+    const listeningMinutes = optionalHistoryCount(rediscovery, "listening_minutes");
     const quietDays = safeHistoryCount(rediscovery.quiet_days);
-    if (engagedPlayCount > playCount || explicitSkips > playCount) {
+    if (
+      engagedPlayCount > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount
+    ) {
       fail("history_candidate_invalid", "A listening-history candidate is invalid.");
     }
     const rediscoverySignal = cleanText(
@@ -512,7 +525,9 @@ function safeHistoryTrack(raw) {
     const peakFields = [
       rediscovery.peak_year,
       rediscovery.peak_year_play_count,
-      rediscovery.peak_year_listening_minutes,
+      ...(rediscovery.peak_year_listening_minutes === undefined
+        ? []
+        : [rediscovery.peak_year_listening_minutes]),
     ];
     if (peakFields.some((value) => value !== undefined)) {
       if (
@@ -524,9 +539,9 @@ function safeHistoryTrack(raw) {
       }
     }
     track.rediscovery = {
-      listening_minutes: listeningMinutes,
+      ...listeningMinutes,
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       first_played_at: firstPlayedAt,
       last_played_at: lastPlayedAt,
       quiet_days: quietDays,
@@ -535,8 +550,7 @@ function safeHistoryTrack(raw) {
         ? {
             peak_year: rediscovery.peak_year,
             peak_year_play_count: rediscovery.peak_year_play_count,
-            peak_year_listening_minutes:
-              rediscovery.peak_year_listening_minutes,
+            ...optionalHistoryCount(rediscovery, "peak_year_listening_minutes"),
           }
         : {}),
       evidence_id: rediscovery.evidence_id.toLowerCase(),
@@ -546,9 +560,10 @@ function safeHistoryTrack(raw) {
     const engagedPlayCount = safeHistoryCount(
       historicalReturn.engaged_play_count,
     );
-    const explicitSkips = safeHistoryCount(historicalReturn.explicit_skips);
-    const listeningMinutes = safeHistoryCount(
-      historicalReturn.listening_minutes,
+    const explicitSkips = optionalHistoryCount(historicalReturn, "explicit_skips");
+    const listeningMinutes = optionalHistoryCount(
+      historicalReturn,
+      "listening_minutes",
     );
     const returnCount = safeHistoryCount(historicalReturn.return_count);
     const longestGapDays = safeHistoryCount(
@@ -577,7 +592,7 @@ function safeHistoryTrack(raw) {
       latestReturnGapDays < 1 ||
       latestReturnGapDays > longestGapDays ||
       engagedPlayCount > playCount ||
-      explicitSkips > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount ||
       Date.parse(firstPlayedAt) > Date.parse(latestReturnAt) ||
       Date.parse(latestReturnAt) > Date.parse(lastPlayedAt) ||
       !rediscoverySignals.has(historicalReturnSignal) ||
@@ -586,9 +601,9 @@ function safeHistoryTrack(raw) {
       fail("history_candidate_invalid", "A listening-history candidate is invalid.");
     }
     track.historical_return = {
-      listening_minutes: listeningMinutes,
+      ...listeningMinutes,
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       first_played_at: firstPlayedAt,
       last_played_at: lastPlayedAt,
       return_count: returnCount,
@@ -605,12 +620,14 @@ function safeHistoryTrack(raw) {
     const yearEngagedPlayCount = safeHistoryCount(
       capsule.year_engaged_play_count,
     );
-    const yearListeningMinutes = safeHistoryCount(
-      capsule.year_listening_minutes,
+    const yearListeningMinutes = optionalHistoryCount(
+      capsule,
+      "year_listening_minutes",
     );
-    const yearExplicitSkips = safeHistoryCount(capsule.year_explicit_skips);
-    const lifetimeListeningMinutes = safeHistoryCount(
-      capsule.lifetime_listening_minutes,
+    const yearExplicitSkips = optionalHistoryCount(capsule, "year_explicit_skips");
+    const lifetimeListeningMinutes = optionalHistoryCount(
+      capsule,
+      "lifetime_listening_minutes",
     );
     const representativeSignal = cleanText(
       capsule.representative_signal,
@@ -622,8 +639,9 @@ function safeHistoryTrack(raw) {
       year > 9999 ||
       yearPlayCount > playCount ||
       yearEngagedPlayCount > yearPlayCount ||
-      yearExplicitSkips > yearPlayCount ||
-      yearListeningMinutes > lifetimeListeningMinutes ||
+      (yearExplicitSkips.year_explicit_skips ?? 0) > yearPlayCount ||
+      (yearListeningMinutes.year_listening_minutes ?? 0) >
+        (lifetimeListeningMinutes.lifetime_listening_minutes ?? Infinity) ||
       !rediscoverySignals.has(representativeSignal) ||
       !isUuid(capsule.evidence_id)
     ) {
@@ -633,16 +651,16 @@ function safeHistoryTrack(raw) {
       year,
       year_play_count: yearPlayCount,
       year_engaged_play_count: yearEngagedPlayCount,
-      year_listening_minutes: yearListeningMinutes,
-      year_explicit_skips: yearExplicitSkips,
-      lifetime_listening_minutes: lifetimeListeningMinutes,
+      ...yearListeningMinutes,
+      ...yearExplicitSkips,
+      ...lifetimeListeningMinutes,
       representative_signal: representativeSignal,
       evidence_id: capsule.evidence_id.toLowerCase(),
     };
   } else {
     const context = raw.back_to_back;
     const engagedPlayCount = safeHistoryCount(context.engaged_play_count);
-    const explicitSkips = safeHistoryCount(context.explicit_skips);
+    const explicitSkips = optionalHistoryCount(context, "explicit_skips");
     const burstCount = safeHistoryCount(context.burst_count);
     const maximumConsecutivePlays = safeHistoryCount(
       context.maximum_consecutive_plays,
@@ -664,7 +682,7 @@ function safeHistoryTrack(raw) {
       playsInBursts < burstCount * 2 ||
       playsInBursts > playCount ||
       engagedPlayCount > playCount ||
-      explicitSkips > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount ||
       !backToBackSignals.has(sequenceSignal) ||
       !isUuid(context.evidence_id)
     ) {
@@ -672,7 +690,7 @@ function safeHistoryTrack(raw) {
     }
     track.back_to_back = {
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       burst_count: burstCount,
       maximum_consecutive_plays: maximumConsecutivePlays,
       plays_in_bursts: playsInBursts,
@@ -797,9 +815,10 @@ function normalizedArtistNames(value) {
     .filter(Boolean);
 }
 
+// A remaster or live take of a song counts as the song (src/core/track-title.mjs).
 export function exactTitleArtistMatch(left, right) {
-  const leftTitle = normalizeText(left.title);
-  const rightTitle = normalizeText(right.title);
+  const leftTitle = normalizedTrackTitle(left.title);
+  const rightTitle = normalizedTrackTitle(right.title);
   const leftArtists = normalizedArtistNames(left.artist_credit);
   const rightArtists = new Set(normalizedArtistNames(right.artist_credit));
   return (
@@ -868,13 +887,14 @@ export function safeExternalSource(raw) {
     fail("external_candidate_invalid", "External catalog source metadata is invalid.");
   }
   if (raw.provider === "apple_music") {
-    if (raw.catalog !== "itunes_search_api" || raw.storefront !== "US") {
+    // The storefront follows the listener's account or region, as a two-letter country code.
+    if (raw.catalog !== "itunes_search_api" || typeof raw.storefront !== "string" || !/^[A-Z]{2}$/u.test(raw.storefront)) {
       fail("external_candidate_invalid", "External catalog source metadata is invalid.");
     }
     return {
       provider: "apple_music",
       catalog: "itunes_search_api",
-      storefront: "US",
+      storefront: raw.storefront,
       retrieved_at: raw.retrieved_at,
       coverage: cleanText(raw.coverage, 500, "external_candidate_invalid"),
     };
@@ -970,26 +990,20 @@ function preferenceSignalLabel(observation = {}) {
   return labels.join(", ") || "explicit provider preference signal";
 }
 
-function listenerAssertionAvoids(
+const avoidGates = new WeakMap();
+
+export function listenerAssertionAvoids(
   listening,
   entityType,
   label,
   artistCredit = "",
 ) {
   const avoids = listening?.listener_assertions?.avoids ?? [];
-  const normalizedLabel = normalizeText(label ?? "");
-  const normalizedArtist = normalizeText(artistCredit ?? "");
-  return avoids.some((avoid) => {
-    if (avoid.entity_type === "artist") {
-      const avoidedArtist = normalizeText(avoid.label ?? "");
-      return entityType === "artist"
-        ? avoidedArtist === normalizedLabel
-        : avoidedArtist === normalizedArtist;
-    }
-    return entityType === "track" &&
-      normalizeText(avoid.label ?? "") === normalizedLabel &&
-      normalizeText(avoid.artist_credit ?? "") === normalizedArtist;
-  });
+  let gate = avoidGates.get(avoids);
+  if (!gate) avoidGates.set(avoids, gate = createAvoidGate(avoids));
+  return entityType === "artist"
+    ? gate.avoidsArtist(label)
+    : gate.avoidsTrack({ title: label, artist_credit: artistCredit });
 }
 
 function normalizeAppleCorrectionLabels(listening, projection) {
@@ -1195,6 +1209,10 @@ export class AppleProjectionDomainServices {
   #listeningHistoryStore;
   #subjectId;
   #candidateSets = new Map();
+  #profileBuildInput;
+  #avoids = {};
+  #status = {};
+  #ownsStores = true;
 
   constructor({ projection, listeningHistoryStore = null, subjectId = null }) {
     if (!projection) throw new TypeError("A trusted Apple projection is required");
@@ -1206,6 +1224,19 @@ export class AppleProjectionDomainServices {
     this.#subjectId = subjectId?.toLowerCase() ?? null;
   }
 
+  // Each conversation that runs beside another gets a fork: the same projection and history
+  // with its own candidate sets, so one conversation's prompt never clears another's. Only
+  // the original closes them.
+  fork() {
+    const fork = new AppleProjectionDomainServices({
+      projection: this.#projection,
+      listeningHistoryStore: this.#listeningHistoryStore,
+      subjectId: this.#subjectId,
+    });
+    fork.#ownsStores = false;
+    return fork;
+  }
+
   status() {
     return {
       state: "ready",
@@ -1216,7 +1247,17 @@ export class AppleProjectionDomainServices {
     };
   }
 
+  // Every model request reads the status, so it is kept until the library or the listening data changes.
   profileStatus() {
+    const version = typeof this.#projection.logicalDigest === "function"
+      ? `${this.#projection.logicalDigest()}:${listeningVersion(this.#listeningHistoryStore)}` : undefined;
+    if (version === undefined || this.#status.version !== version) {
+      this.#status = { version, value: this.#readProfileStatus() };
+    }
+    return structuredClone(this.#status.value);
+  }
+
+  #readProfileStatus() {
     const summary = this.#projection.getProfileSummary({ maxItems: 1 });
     const listening = this.#listeningHistoryStore?.profileSummary({
       subjectId: this.#subjectId,
@@ -1246,6 +1287,51 @@ export class AppleProjectionDomainServices {
     };
   }
 
+  listeningCoverage() {
+    return this.#listeningHistoryStore?.listeningCoverage?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
+  recentAttention() {
+    return this.#listeningHistoryStore?.recentAttention?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
+  // Moondog's suggestions ledger and the declared mix (src/profile/moondog-suggestions.mjs).
+  recordMoondogSuggestions(entries) {
+    return this.#listeningHistoryStore?.recordMoondogSuggestions?.({ entries }) ?? null;
+  }
+
+  moondogSuggestionHistory(tracks) {
+    return this.#listeningHistoryStore?.moondogSuggestionHistory?.({ subjectId: this.#subjectId, tracks }) ?? null;
+  }
+
+  // A song the dated plays do not place but the Apple library has played counts as known: three
+  // or more library plays as familiar, fewer as heard. Library counts carry no dates.
+  listeningMix(tracks) {
+    const slots = this.#listeningHistoryStore?.listeningMix?.({ subjectId: this.#subjectId, tracks }) ??
+      tracks.map(() => "unknown");
+    return slots.map((slot, index) => {
+      if (!["new", "known_artist", "unknown"].includes(slot)) return slot;
+      const plays = this.#libraryPlayCount(tracks[index]);
+      return plays >= 3 ? "familiar" : plays > 0 ? "heard" : slot;
+    });
+  }
+
+  #libraryPlayCount(track) {
+    const wanted = { title: track?.title, artist_credit: track?.artist_credit ?? (Array.isArray(track?.artists) ? track.artists.join(", ") : "") };
+    if (typeof wanted.title !== "string" || !wanted.title.trim()) return 0;
+    try {
+      const results = this.#projection.searchLibrary({
+        // Without its version suffix, so a remaster finds the library's copy.
+        query: Array.from(normalizedTrackTitle(wanted.title)).slice(0, 256).join(""), limit: 25, offset: 0,
+        filters: { artists: [], genres: [], familiarity: [], preferenceSignals: [] },
+      });
+      return Math.max(0, ...results.tracks.map(safeTrack).filter((candidate) => exactTitleArtistMatch(wanted, candidate))
+        .map((candidate) => candidate.observation_summary.familiarity.play_count ?? 0));
+    } catch {
+      return 0; // Without the library, the dated plays alone place the song.
+    }
+  }
+
   rediscoveryReady() {
     return (
       this.#listeningHistoryStore !== null &&
@@ -1726,7 +1812,43 @@ export class AppleProjectionDomainServices {
     };
   }
 
-  registerExternalCandidateSet({ tracks, source } = {}) {
+  // Every play path asks for each candidate, so the gate is kept until the data changes.
+  filterDiscoveryTracks(tracks) {
+    const store = this.#listeningHistoryStore;
+    const version = store?.profileDataVersion
+      ? `${this.#projection.logicalDigest?.() ?? ""}:${listeningVersion(store)}` : undefined;
+    const gate = cachedAvoidGate(this.#avoids, version, () => {
+      const avoids = store?.activeAvoidances?.({ subjectId: this.#subjectId }) ??
+        store?.profileSummary?.({ subjectId: this.#subjectId })?.listener_assertions?.avoids ?? [];
+      return normalizeAppleCorrectionLabels({ listener_assertions: { avoids } }, this.#projection)
+        .listener_assertions.avoids;
+    });
+    return tracks.filter((track) => !gate.avoidsTrack(track));
+  }
+
+  // Choices live with the listening history, so a library alone cannot save them.
+  listenerChoicesReady() {
+    return this.#listeningHistoryStore !== null;
+  }
+
+  recordListenerChoice(choice) {
+    if (!this.#listeningHistoryStore) throw new Error("Choices can be saved once listening history is imported.");
+    return recordListenerChoice(this.#listeningHistoryStore, { ...choice, subjectId: this.#subjectId });
+  }
+
+  // The choices in force, cheap enough to read when there is no saved reading.
+  listenerChoices() {
+    const store = this.#listeningHistoryStore;
+    if (typeof store?.countActiveListenerCorrections !== "function") return null;
+    return savedListenerChoices(store.listListenerCorrections({ subjectId: this.#subjectId, limit: 30 }),
+      store.countActiveListenerCorrections({ subjectId: this.#subjectId }));
+  }
+
+  isKnownDiscoveryTrack(track) {
+    return (this.#listeningHistoryStore?.listenedTracks?.({ subjectId: this.#subjectId }) ?? []).some(heard => exactTitleArtistMatch(track, heard));
+  }
+
+  registerExternalCandidateSet({ tracks, source, excludeKnown = true } = {}) {
     if (
       !Array.isArray(tracks) ||
       tracks.length < 1 ||
@@ -1747,7 +1869,8 @@ export class AppleProjectionDomainServices {
     }
     const accepted = [];
     let excludedLibraryMatches = 0;
-    for (const track of prepared) {
+    const allowed = this.filterDiscoveryTracks(prepared);
+    for (const track of allowed) {
       const query = Array.from(track.title).slice(0, 256).join("");
       const libraryResults = this.#projection.searchLibrary({
         query,
@@ -1763,14 +1886,14 @@ export class AppleProjectionDomainServices {
       const libraryMatch = libraryResults.tracks
         .map(safeTrack)
         .some((candidate) => exactTitleArtistMatch(track, candidate));
-      if (libraryMatch) {
+      if (excludeKnown && libraryMatch) {
         excludedLibraryMatches += 1;
         continue;
       }
       accepted.push({
         ...track,
         knownness: {
-          imported_library: "not_found_by_exact_title_artist",
+          imported_library: libraryMatch ? "found_by_exact_title_artist" : "not_found_by_exact_title_artist",
           listening_history: "not_checked",
         },
       });
@@ -1780,6 +1903,7 @@ export class AppleProjectionDomainServices {
         candidate_set_id: null,
         candidate_scope: "external_catalog",
         result_count: 0,
+        excluded_avoided_matches: prepared.length - allowed.length,
         excluded_library_matches: excludedLibraryMatches,
         expires_on: "prompt_end",
         source: trustedSource,
@@ -1797,6 +1921,7 @@ export class AppleProjectionDomainServices {
       candidate_set_id: candidateSetId,
       candidate_scope: "external_catalog",
       result_count: accepted.length,
+      excluded_avoided_matches: prepared.length - allowed.length,
       excluded_library_matches: excludedLibraryMatches,
       expires_on: "prompt_end",
       source: trustedSource,
@@ -1893,6 +2018,59 @@ export class AppleProjectionDomainServices {
     };
   }
 
+  #appleProfileCatalog(knownAvoids) {
+    if (typeof this.#projection.getProfileCatalog !== "function") return null;
+    const { listener_assertions: { avoids } } = normalizeAppleCorrectionLabels({
+      listener_assertions: {
+        avoids: knownAvoids ?? this.#listeningHistoryStore?.activeAvoidances?.({ subjectId: this.#subjectId }) ?? [],
+      },
+    }, this.#projection);
+    return this.#projection.getProfileCatalog({ excludePreference: (track) =>
+      listenerAssertionAvoids({ listener_assertions: { avoids } }, "track", track.label, track.artist_credit) });
+  }
+
+  profileExplorationReady() {
+    return typeof this.#projection.getProfileCatalog === "function";
+  }
+
+  async exploreProfile(argumentsValue) {
+    const input = profileExplorationInput(argumentsValue);
+    const listening = this.#listeningHistoryStore?.profileCatalog({ subjectId: this.#subjectId });
+    return exploreProfileCatalog({
+      listening,
+      apple: this.#appleProfileCatalog(listening?.sections.listener_avoids), input,
+    });
+  }
+
+  profileBuildReady() {
+    return typeof this.#listeningHistoryStore?.listenerProfileStorage === "function" &&
+      typeof this.#projection.logicalDigest === "function";
+  }
+
+  getListenerProfileStore() {
+    return this.#listeningHistoryStore.listenerProfileStorage({ subjectId: this.#subjectId });
+  }
+
+  getProfileBuildContext() {
+    const appleDigest = this.#projection.logicalDigest();
+    const version = `${appleDigest}:${listeningVersion(this.#listeningHistoryStore)}`;
+    if (this.#profileBuildInput?.version !== version) {
+      const listening = this.#listeningHistoryStore.profileCatalog({ subjectId: this.#subjectId });
+      const normalized = normalizeAppleCorrectionLabels({ listener_assertions: {
+        preferences: listening.sections.listener_preferences, avoids: listening.sections.listener_avoids,
+      } }, this.#projection).listener_assertions;
+      listening.sections.listener_preferences = normalized.preferences;
+      listening.sections.listener_avoids = normalized.avoids;
+      this.#profileBuildInput = { version, input: createListenerProfileInput({
+        subjectId: this.#subjectId,
+        evidenceRevision: [appleDigest,
+          this.#listeningHistoryStore.profileEvidenceRevision({ subjectId: this.#subjectId })],
+        listening, apple: this.#appleProfileCatalog(listening.sections.listener_avoids),
+      }) };
+    }
+    return { store: this.getListenerProfileStore(), input: this.#profileBuildInput.input };
+  }
+
   async getProfileSummary(argumentsValue) {
     const input = modelArguments(argumentsValue, new Set(["maxItems"]));
     const bounded = boundedLimit(
@@ -1990,13 +2168,16 @@ export class AppleProjectionDomainServices {
         play_count: item.play_count,
         evidence_id: item.evidence_id,
       })) ?? [];
-    const appleArtistFacets = facetItems(
+    const appleCatalog = this.#appleProfileCatalog();
+    const appleArtistFacets = (appleCatalog
+      ? appleCatalog.sections.apple_artists.filter((item) => item.preferred_tracks > 0)
+      : facetItems(
       preferenceItems,
       (item) => item.artist_credit,
       bounded,
-    ).filter(
+    )).filter(
       (item) => !listenerAssertionAvoids(listening, "artist", item.name),
-    );
+    ).slice(0, bounded);
     const spotifyArtistFacets = [
       ...(listening?.curated_preferences.followed_artists ?? []),
       ...(listening?.listening_behavior.enduring_artists ?? []),
@@ -2009,7 +2190,9 @@ export class AppleProjectionDomainServices {
         name: item.name,
         evidence_id: item.evidence_id,
       }));
-    const appleGenreFacets = facetItems(
+    const appleGenreFacets = appleCatalog
+      ? appleCatalog.sections.apple_genres.filter((item) => item.preferred_tracks > 0).slice(0, bounded)
+      : facetItems(
       preferenceItems,
       (item) => item.labels?.provider_genre,
       bounded,
@@ -2109,6 +2292,17 @@ export class AppleProjectionDomainServices {
     if (!isUuid(cleanedId)) {
       fail("invalid_evidence_id", "Profile evidence ID is invalid.");
     }
+    const catalog = this.#appleProfileCatalog();
+    const facet = [...(catalog?.sections.apple_artists ?? []), ...(catalog?.sections.apple_genres ?? [])]
+      .find((item) => item.evidence_id === cleanedId);
+    if (facet) return {
+      evidence_id: facet.evidence_id,
+      claim: { dimension: "taste.library_facet", value: facet.name, direction: "supports" },
+      basis_summary: `${facet.preferred_tracks} tracks with positive provider preferences among ${facet.library_tracks} library tracks, after active Avoids. ${facet.play_count} aggregate plays across ${facet.tracks_with_play_count} tracks with known counts.`,
+      derivation: { kind: "rule", name: "whole-apple-library-facet", version: "1" },
+      confidence: 0.9,
+      interpretation_limit: "A full-library metadata aggregation. Play counts show familiarity; provider preferences are snapshot states, and genre names do not describe measured audio.",
+    };
     const raw = this.#projection.explainProfileEvidence({
       evidenceId: cleanedId,
     });
@@ -2258,6 +2452,11 @@ export class AppleProjectionDomainServices {
         "The playlist track count does not match the explicit user intent.",
       );
     }
+    const external = selections.map((selection) => trustedTracks.get(selection.trackRefId))
+      .filter((track) => track.candidate_scope === "external_catalog");
+    if (this.filterDiscoveryTracks(external).length !== external.length) {
+      fail("discovery_track_avoided", "An external discovery is currently marked Avoid. Choose another track.");
+    }
     const tracks = selections.map((selection, index) => {
       const track = trustedTracks.get(selection.trackRefId);
       const result = {
@@ -2315,6 +2514,7 @@ export class AppleProjectionDomainServices {
 
   close() {
     this.resetCandidateSets();
+    if (!this.#ownsStores) return;
     try {
       this.#projection.close();
     } finally {