@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/core/listener-avoids.mjs

@@ -0,0 +1,101 @@
+// One Avoid check for every play path. Names fold case, accents and spacing, so "Drake " and
+// "Drake" are one artist, and an artist Avoid matches a whole credit or any artist in it.
+
+// Collaboration separators in artist credits. Full-width forms fold to these before splitting,
+// but callers that do not fold text first can still split on them. A word separator needs a
+// space before it, which a separator before it may already have taken.
+export const ARTIST_CREDIT_SEPARATORS =
+  /\s*(?:,|，|;|；|&|＆|\/|、|和|与)\s*|(?<=\s)(?:featuring|feat\.?|ft\.?|with)\s+/iu;
+
+// "x" also joins artists ("Future x Drake"), but it ends some names ("Lil Nas X"). Only this
+// check splits on it, because it also reads each run of artists as one name.
+const separated = new RegExp(`(${ARTIST_CREDIT_SEPARATORS.source}|(?<=\\s)(?:x|×)\\s+)`, "iu");
+
+// Features named in a title: "Song (feat. Drake)", "Song [with Drake]" or "Song feat. Drake".
+const titleFeature =
+  /\s*[（(【[]\s*(?:featuring|feat\.?|ft\.?|with)\s+([^）)】\]]+)[）)】\]]|\s+(?:-\s+)?(?:featuring|feat\.|ft\.)\s+(.+)$/giu;
+
+export function avoidKey(value) {
+  if (typeof value !== "string") return "";
+  // Only Latin, Greek and Cyrillic accents fold: kana voicing marks change the word.
+  return value.normalize("NFKD").replace(/[̀-ͯ]/gu, "")
+    .toLocaleLowerCase("und").replace(/\s+/gu, " ").trim();
+}
+
+// A title without its features, and the artists those features name.
+function titleParts(title) {
+  const featured = [];
+  const core = typeof title === "string"
+    ? title.replace(titleFeature, (_whole, bracketed, trailing) => { featured.push(bracketed ?? trailing); return ""; })
+    : title;
+  return { core: avoidKey(core), featured };
+}
+
+// Every way to read free-text credits as one artist: the whole credit, each credited artist, and
+// each run of them, so a band named "Simon & Garfunkel" stays one name inside a longer credit.
+// A source's own list of artists names each one whole, so its names are not split.
+function creditKeys(credit, artists = [], featured = []) {
+  const listed = (Array.isArray(artists) ? artists : []).map(avoidKey).filter(Boolean);
+  const keys = new Set(listed);
+  if (listed.length) keys.add(avoidKey(credit));
+  for (const name of [...(listed.length ? [] : [credit]), ...featured]) {
+    const pieces = avoidKey(name).split(separated);
+    for (let start = 0; start < pieces.length; start += 2) {
+      for (let end = start; end < pieces.length; end += 2) {
+        const key = pieces.slice(start, end + 1).join("").trim();
+        if (key) keys.add(key);
+      }
+    }
+  }
+  keys.delete("");
+  return keys;
+}
+
+const overlaps = (left, right) => [...left].some((key) => right.has(key));
+
+/**
+ * Builds the check from Avoid records ({ entity_type, label, artist_credit }). A track Avoid
+ * matches its title, without any features, with any of its credited artists.
+ */
+export function createAvoidGate(avoids = []) {
+  const artists = new Set();
+  const tracks = new Map();
+  for (const avoid of Array.isArray(avoids) ? avoids : []) {
+    const label = avoidKey(avoid?.label);
+    if (!label) continue;
+    if (avoid.entity_type === "artist") artists.add(label);
+    else if (avoid.entity_type === "track") {
+      const { core, featured } = titleParts(avoid.label);
+      const title = core || label;
+      tracks.set(title, [...(tracks.get(title) ?? []), creditKeys(avoid.artist_credit, [], featured)]);
+    }
+  }
+  const avoidsArtist = (keys) => overlaps(keys, artists);
+  return {
+    size: artists.size + tracks.size,
+    avoidsArtist: (name, names = []) => avoidsArtist(creditKeys(name, names)),
+    // A track as { title, artist_credit, artists }, where artists is a source's own list.
+    avoidsTrack({ title, artist_credit: credit, artists: names } = {}) {
+      const { core, featured } = titleParts(title);
+      const keys = creditKeys(credit, names, featured);
+      if (avoidsArtist(keys)) return true;
+      return (tracks.get(core || avoidKey(title)) ?? []).some((avoided) =>
+        avoided.size ? overlaps(avoided, keys) : keys.size === 0);
+    },
+  };
+}
+
+// The gate for the store's current data, rebuilt only when that data changes.
+export function cachedAvoidGate(cache, version, readAvoids) {
+  if (version === undefined || cache.version !== version) {
+    cache.version = version;
+    cache.gate = createAvoidGate(readAvoids());
+  }
+  return cache.gate;
+}
+
+// The store's data version without its own ledger writes, which change no projection until
+// their plays arrive (listeningDataVersion in listening-history-store.mjs).
+export function listeningVersion(store) {
+  return store?.listeningDataVersion?.() ?? store?.profileDataVersion?.();
+}

package/src/core/listening-now.mjs

@@ -0,0 +1,108 @@
+// What the listener plays right now, wherever it plays: the Music app on this Mac, Spotify on its
+// active device, or NetEase through ncm-cli, with the playlist, album or queue it plays from.
+// Two players rarely play at once. When they do, one that plays wins over a paused one, then the
+// listener's chosen service, then this order.
+export const LISTENING_ORDER = Object.freeze(["apple_music", "spotify", "netease"]);
+
+export function activeListening(sources, chosen) {
+  const order = [...new Set([chosen, ...LISTENING_ORDER])];
+  const heard = sources.filter((source) => source.song && (source.state === "playing" || source.state === "paused"));
+  return heard.sort((a, b) => (a.state === "playing" ? 0 : 1) - (b.state === "playing" ? 0 : 1) ||
+    order.indexOf(a.service) - order.indexOf(b.service))[0] ?? null;
+}
+
+const songOf = (item) => ({
+  title: item.name ?? item.title ?? "",
+  artists: Array.isArray(item.artists) ? item.artists : [],
+  album: item.album ?? null,
+  duration_ms: Number.isInteger(item.duration_ms) ? item.duration_ms : null,
+  ...(item.track_ref_id ? { track_ref_id: item.track_ref_id } : {}),
+});
+
+// What the Music app plays, as one source. Its playlist's songs come only from a read that asked for them.
+export function musicAppSource(now) {
+  if (!now.song) return { state: now.state, ...(now.reason ? { reason: now.reason } : {}) };
+  const playlist = now.playlist;
+  return {
+    state: now.state,
+    player: "Music app on this Mac",
+    song: songOf(now.song),
+    position_ms: now.position_ms,
+    shuffle: now.shuffle,
+    repeat: now.repeat,
+    from: playlist ? {
+      kind: playlist.library ? "library" : "playlist",
+      name: playlist.name,
+      tracks_total: playlist.tracks_total ?? null,
+      position: playlist.position ?? null,
+      ...(playlist.tracks ? { first_position: playlist.first_position, tracks: playlist.tracks.map(songOf) } : {}),
+    } : null,
+  };
+}
+
+const musicApp = async (application) => musicAppSource(await application.musicApp.nowPlaying({ tracks: true }));
+
+// Spotify reports only the device that plays; reading it costs three or four requests of the quota.
+async function spotify(application, { signal }) {
+  const player = await application.spotifyNowPlaying({ signal });
+  if (player.state !== "available" || !player.item) return { state: "stopped" };
+  const context = player.context ?? null;
+  const [queue, playlist] = await Promise.all([
+    application.spotifyQueueStatus({ signal }).catch((error) => (signal?.aborted ? Promise.reject(error) : null)),
+    context?.type === "playlist"
+      ? application.requireSpotifyService().playingPlaylist({ uri: context.uri }, { signal })
+        .catch((error) => (signal?.aborted ? Promise.reject(error) : { unavailable: String(error?.message ?? error).slice(0, 200) }))
+      : null,
+  ]);
+  const from = context?.type === "playlist"
+    ? { kind: "playlist", name: playlist.name ?? null, tracks_total: playlist.tracks_total ?? null,
+      ...(playlist.tracks ? { first_position: 1, tracks: playlist.tracks.map(songOf) } : {}),
+      ...(playlist.unavailable ? { unavailable: playlist.unavailable } : {}) }
+    : context?.type === "album" ? { kind: "album", name: player.item.album ?? null }
+      : context?.type === "artist" ? { kind: "artist", name: player.item.artists?.[0] ?? null }
+        : context?.type === "collection" ? { kind: "liked_songs", name: "Liked Songs" }
+          : null;
+  return {
+    state: player.is_playing === true ? "playing" : "paused",
+    player: player.device?.name ? `Spotify on ${player.device.name}` : "Spotify",
+    ...(player.device ? { device: { name: player.device.name ?? null, type: player.device.type ?? null } } : {}),
+    song: songOf(player.item),
+    position_ms: player.progress_ms ?? 0,
+    shuffle: player.shuffle_state === true,
+    repeat: player.repeat_state ?? "off",
+    from,
+    next: (queue?.queue ?? []).map(songOf),
+  };
+}
+
+async function netease(application) {
+  const now = await application.neteaseNowPlaying();
+  if (now.state === "stopped" || !now.song) return { state: "stopped" };
+  return {
+    state: now.state,
+    player: "NetEase Music through ncm-cli on this Mac",
+    song: songOf(now.song),
+    position_ms: now.position_ms ?? 0,
+    from: { kind: "moondog_queue", name: null },
+    next: (now.next ?? []).map(songOf),
+  };
+}
+
+/** Every player Moondog can read, the one the listener hears first: { active, sources }. */
+export async function readListeningNow(application, { signal } = {}) {
+  const readers = [
+    application.musicApp?.available ? ["apple_music", () => musicApp(application)] : null,
+    application.spotifyReady() ? ["spotify", () => spotify(application, { signal })] : null,
+    application.neteaseReady() ? ["netease", () => netease(application)] : null,
+  ].filter(Boolean);
+  const sources = await Promise.all(readers.map(async ([service, read]) => {
+    try {
+      return { service, ...(await read()) };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { service, state: "unreadable", reason: String(error?.message ?? error).slice(0, 200) };
+    }
+  }));
+  const active = activeListening(sources, application.playbackService);
+  return { active: active?.service ?? null, sources: active ? [active, ...sources.filter((source) => source !== active)] : sources };
+}

package/src/core/listening-profile-domain-services.mjs

@@ -1,5 +1,9 @@
 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, listeningVersion } from "./listener-avoids.mjs";
+import { recordListenerChoice } from "../profile/listener-corrections.mjs";
 
 import { isUuid } from "./uuid-v5.mjs";
 import { createListeningHistoryProfileProjection } from "../profile/spotify-archive-taste.mjs";
@@ -75,6 +79,11 @@ function safeCount(value, label) {
   return value;
 }
 
+// A pick leaves out minutes or skips that its plays never recorded.
+function optionalCount(context, key, label) {
+  return context[key] === undefined ? {} : { [key]: safeCount(context[key], label) };
+}
+
 function safeTimestamp(value, label) {
   const cleaned = cleanText(value, 64, label);
   const parsed = Date.parse(cleaned);
@@ -86,15 +95,19 @@ function safeTimestamp(value, label) {
 
 function safeExternalRefs(value) {
   if (value === undefined) return [];
-  if (!Array.isArray(value) || value.length > 1) {
+  if (!Array.isArray(value)) {
     throw new TypeError("Listening-history provider identity is invalid");
   }
-  return value.map((reference) => {
+  // Only a Spotify track ID is kept for playback. Last.fm, ListenBrainz and
+  // Spotify account-data identities stay in the store.
+  const references = value.filter((reference) => reference?.system === "spotify");
+  if (references.length > 1) {
+    throw new TypeError("Listening-history provider identity is invalid");
+  }
+  return references.map((reference) => {
     if (
-      !reference ||
       typeof reference !== "object" ||
       Array.isArray(reference) ||
-      reference.system !== "spotify" ||
       reference.entity_type !== "spotify.track" ||
       typeof reference.external_id !== "string" ||
       !SPOTIFY_TRACK_ID.test(reference.external_id)
@@ -188,18 +201,16 @@ function safeHistoryTrack(value) {
       throw new TypeError("Rediscovery signal is invalid");
     }
     track.rediscovery = {
-      listening_minutes: safeCount(
-        context.listening_minutes,
+      ...optionalCount(
+        context,
+        "listening_minutes",
         "Rediscovery listening minutes",
       ),
       engaged_play_count: safeCount(
         context.engaged_play_count,
         "Rediscovery engaged plays",
       ),
-      explicit_skips: safeCount(
-        context.explicit_skips,
-        "Rediscovery skips",
-      ),
+      ...optionalCount(context, "explicit_skips", "Rediscovery skips"),
       first_played_at: safeTimestamp(
         context.first_played_at,
         "Rediscovery first play",
@@ -217,8 +228,9 @@ function safeHistoryTrack(value) {
               context.peak_year_play_count,
               "Rediscovery peak-year plays",
             ),
-            peak_year_listening_minutes: safeCount(
-              context.peak_year_listening_minutes,
+            ...optionalCount(
+              context,
+              "peak_year_listening_minutes",
               "Rediscovery peak-year minutes",
             ),
           }
@@ -260,8 +272,9 @@ function safeHistoryTrack(value) {
       context.engaged_play_count,
       "Historical-return engaged plays",
     );
-    const explicitSkips = safeCount(
-      context.explicit_skips,
+    const explicitSkips = optionalCount(
+      context,
+      "explicit_skips",
       "Historical-return skips",
     );
     if (
@@ -270,7 +283,7 @@ function safeHistoryTrack(value) {
       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) ||
       !historySupportSignals.has(historicalReturnSignal) ||
@@ -279,12 +292,13 @@ function safeHistoryTrack(value) {
       throw new TypeError("Historical-return candidate is invalid");
     }
     track.historical_return = {
-      listening_minutes: safeCount(
-        context.listening_minutes,
+      ...optionalCount(
+        context,
+        "listening_minutes",
         "Historical-return listening minutes",
       ),
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       first_played_at: firstPlayedAt,
       last_played_at: lastPlayedAt,
       return_count: returnCount,
@@ -310,16 +324,15 @@ function safeHistoryTrack(value) {
         context.year_engaged_play_count,
         "Time Machine engaged plays",
       ),
-      year_listening_minutes: safeCount(
-        context.year_listening_minutes,
+      ...optionalCount(
+        context,
+        "year_listening_minutes",
         "Time Machine year minutes",
       ),
-      year_explicit_skips: safeCount(
-        context.year_explicit_skips,
-        "Time Machine year skips",
-      ),
-      lifetime_listening_minutes: safeCount(
-        context.lifetime_listening_minutes,
+      ...optionalCount(context, "year_explicit_skips", "Time Machine year skips"),
+      ...optionalCount(
+        context,
+        "lifetime_listening_minutes",
         "Time Machine lifetime minutes",
       ),
       representative_signal: cleanText(
@@ -335,8 +348,9 @@ function safeHistoryTrack(value) {
       context.engaged_play_count,
       "Back-to-back engaged plays",
     );
-    const explicitSkips = safeCount(
-      context.explicit_skips,
+    const explicitSkips = optionalCount(
+      context,
+      "explicit_skips",
       "Back-to-back skips",
     );
     const burstCount = safeCount(
@@ -363,7 +377,7 @@ function safeHistoryTrack(value) {
       playsInBursts < burstCount * 2 ||
       playsInBursts > playCount ||
       engagedPlayCount > playCount ||
-      explicitSkips > playCount ||
+      (explicitSkips.explicit_skips ?? 0) > playCount ||
       !backToBackSignals.has(sequenceSignal) ||
       !isUuid(context.evidence_id)
     ) {
@@ -371,7 +385,7 @@ function safeHistoryTrack(value) {
     }
     track.back_to_back = {
       engaged_play_count: engagedPlayCount,
-      explicit_skips: explicitSkips,
+      ...explicitSkips,
       burst_count: burstCount,
       maximum_consecutive_plays: maximumConsecutivePlays,
       plays_in_bursts: playsInBursts,
@@ -409,6 +423,10 @@ export class ListeningProfileDomainServices {
   #store;
   #subjectId;
   #candidateSets = new Map();
+  #profileBuildInput;
+  #avoids = {};
+  #status = {};
+  #ownsStore = true;
 
   constructor({ listeningHistoryStore, subjectId } = {}) {
     if (
@@ -426,6 +444,18 @@ export class ListeningProfileDomainServices {
     this.#subjectId = subjectId.toLowerCase();
   }
 
+  // Each conversation that runs beside another gets a fork: the same store with its own
+  // candidate sets, so one conversation's prompt never clears another's. Only the
+  // original closes the store.
+  fork() {
+    const fork = new ListeningProfileDomainServices({
+      listeningHistoryStore: this.#store,
+      subjectId: this.#subjectId,
+    });
+    fork.#ownsStore = false;
+    return fork;
+  }
+
   status() {
     return {
       state: "ready",
@@ -435,7 +465,16 @@ export class ListeningProfileDomainServices {
     };
   }
 
+  // Every model request reads the status, so it is kept until the listening data changes.
   profileStatus() {
+    const version = listeningVersion(this.#store);
+    if (version === undefined || this.#status.version !== version) {
+      this.#status = { version, value: this.#readProfileStatus() };
+    }
+    return structuredClone(this.#status.value);
+  }
+
+  #readProfileStatus() {
     const source = this.#store.subjectDataStatus({
       subjectId: this.#subjectId,
     });
@@ -458,6 +497,27 @@ export class ListeningProfileDomainServices {
     };
   }
 
+  listeningCoverage() {
+    return this.#store.listeningCoverage?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
+  recentAttention() {
+    return this.#store.recentAttention?.({ subjectId: this.#subjectId }) ?? null;
+  }
+
+  // Moondog's suggestions ledger and the declared mix (src/profile/moondog-suggestions.mjs).
+  recordMoondogSuggestions(entries) {
+    return this.#store.recordMoondogSuggestions?.({ entries }) ?? null;
+  }
+
+  moondogSuggestionHistory(tracks) {
+    return this.#store.moondogSuggestionHistory?.({ subjectId: this.#subjectId, tracks }) ?? null;
+  }
+
+  listeningMix(tracks) {
+    return this.#store.listeningMix?.({ subjectId: this.#subjectId, tracks }) ?? null;
+  }
+
   rediscoveryReady() {
     return typeof this.#store.rediscoveryCandidates === "function";
   }
@@ -518,7 +578,30 @@ export class ListeningProfileDomainServices {
     return { candidateSetId, tracks: prepared };
   }
 
-  registerExternalCandidateSet({ tracks, source } = {}) {
+  // Every play path asks for each candidate, so the gate is kept until the data changes.
+  filterDiscoveryTracks(tracks) {
+    const gate = cachedAvoidGate(this.#avoids, listeningVersion(this.#store), () =>
+      this.#store.activeAvoidances?.({ subjectId: this.#subjectId }) ??
+        this.#store.profileSummary({ subjectId: this.#subjectId })?.listener_assertions?.avoids ?? []);
+    return tracks.filter((track) => !gate.avoidsTrack(track));
+  }
+
+  recordListenerChoice(choice) {
+    return recordListenerChoice(this.#store, { ...choice, subjectId: this.#subjectId });
+  }
+
+  // The choices in force, cheap enough to read when there is no saved reading.
+  listenerChoices() {
+    if (typeof this.#store.countActiveListenerCorrections !== "function") return null;
+    return savedListenerChoices(this.#store.listListenerCorrections({ subjectId: this.#subjectId, limit: 30 }),
+      this.#store.countActiveListenerCorrections({ subjectId: this.#subjectId }));
+  }
+
+  isKnownDiscoveryTrack(track) {
+    return (this.#store.listenedTracks?.({ subjectId: this.#subjectId }) ?? []).some(heard => exactTitleArtistMatch(track, heard));
+  }
+
+  registerExternalCandidateSet({ tracks, source, excludeKnown = true } = {}) {
     if (!Array.isArray(tracks) || tracks.length < 1 || tracks.length > HISTORY_MAX_ITEMS) {
       throw new TypeError("External catalog candidates are invalid");
     }
@@ -530,14 +613,16 @@ export class ListeningProfileDomainServices {
     if (new Set(prepared.map((track) => track.track_ref_id)).size !== prepared.length) {
       throw new TypeError("External catalog candidates are duplicated");
     }
-    // Outside suggestions should be new to the listener, so drop anything already played.
+    // Familiarity is useful evidence, not an automatic discovery exclusion.
     const listened = typeof this.#store.listenedTracks === "function"
       ? this.#store.listenedTracks({ subjectId: this.#subjectId })
       : [];
     const accepted = [];
     let excludedHistoryMatches = 0;
-    for (const track of prepared) {
-      if (listened.some((heard) => exactTitleArtistMatch(track, heard))) {
+    const allowed = this.filterDiscoveryTracks(prepared);
+    for (const track of allowed) {
+      const heard = listened.some((heard) => exactTitleArtistMatch(track, heard));
+      if (excludeKnown && heard) {
         excludedHistoryMatches += 1;
         continue;
       }
@@ -545,7 +630,7 @@ export class ListeningProfileDomainServices {
         ...track,
         knownness: {
           imported_library: "not_imported",
-          listening_history: "not_found_by_exact_title_artist",
+          listening_history: heard ? "found_by_exact_title_artist" : "not_found_by_exact_title_artist",
         },
       });
     }
@@ -560,6 +645,7 @@ export class ListeningProfileDomainServices {
       candidate_set_id: registered,
       candidate_scope: "external_catalog",
       result_count: accepted.length,
+      excluded_avoided_matches: prepared.length - allowed.length,
       excluded_library_matches: excludedHistoryMatches,
       expires_on: "prompt_end",
       source: trustedSource,
@@ -584,6 +670,35 @@ export class ListeningProfileDomainServices {
     return createListeningHistoryProfileProjection(listening, { maxItems });
   }
 
+  profileExplorationReady() {
+    return typeof this.#store.profileCatalog === "function";
+  }
+
+  async exploreProfile(argumentsValue) {
+    const input = profileExplorationInput(argumentsValue);
+    return exploreProfileCatalog({ listening: this.#store.profileCatalog({ subjectId: this.#subjectId }), input });
+  }
+
+  profileBuildReady() {
+    return typeof this.#store.listenerProfileStorage === "function";
+  }
+
+  getListenerProfileStore() {
+    return this.#store.listenerProfileStorage({ subjectId: this.#subjectId });
+  }
+
+  getProfileBuildContext() {
+    const version = listeningVersion(this.#store);
+    if (this.#profileBuildInput?.version !== version) {
+      this.#profileBuildInput = { version, input: createListenerProfileInput({
+        subjectId: this.#subjectId,
+        evidenceRevision: this.#store.profileEvidenceRevision({ subjectId: this.#subjectId }),
+        listening: this.#store.profileCatalog({ subjectId: this.#subjectId }),
+      }) };
+    }
+    return { store: this.getListenerProfileStore(), input: this.#profileBuildInput.input };
+  }
+
   async getRediscoveryCandidates(argumentsValue) {
     const input = modelArguments(argumentsValue, new Set(["limit"]));
     const limit = boundedHistoryItems(input.limit);
@@ -896,6 +1011,11 @@ export class ListeningProfileDomainServices {
     ) {
       throw new TypeError("A playlist plan cannot contain duplicate tracks");
     }
+    const external = selected.map(({ track }) => track)
+      .filter((track) => track.candidate_scope === "external_catalog");
+    if (this.filterDiscoveryTracks(external).length !== external.length) {
+      throw new Error("An external discovery is currently marked Avoid. Choose another track.");
+    }
     const tracks = selected.map(({ track, selectionReason }, index) => ({
       position: index + 1,
       track_ref_id: track.track_ref_id,
@@ -972,13 +1092,41 @@ export class ListeningProfileDomainServices {
     ) {
       throw new TypeError("Retained playlist candidates are invalid");
     }
-    const registered = this.#registerHistoryTracks(tracks);
+    if (this.#candidateSets.size >= CANDIDATE_SETS_MAX) {
+      throw new Error("The prompt has reached its candidate set limit");
+    }
+    const prepared = tracks.map((track) =>
+      track?.candidate_scope === "external_catalog"
+        ? {
+            ...safeExternalTrack(track),
+            knownness: {
+              imported_library: "not_imported",
+              listening_history: "not_found_by_exact_title_artist",
+            },
+          }
+        : safeHistoryTrack(track),
+    );
+    if (
+      new Set(prepared.map((track) => track.track_ref_id)).size !==
+      prepared.length
+    ) {
+      throw new TypeError("Retained playlist candidates are duplicated");
+    }
+    const candidateSetId = randomUUID();
+    this.#candidateSets.set(
+      candidateSetId,
+      new Map(
+        prepared.map((track) => [track.track_ref_id, structuredClone(track)]),
+      ),
+    );
+    const scopes = new Set(prepared.map((track) => track.candidate_scope));
     return {
-      candidate_set_id: registered.candidateSetId,
-      candidate_scope: "private_history",
-      result_count: registered.tracks.length,
+      candidate_set_id: candidateSetId,
+      candidate_scope: scopes.size === 1 ? [...scopes][0] : "mixed",
+      result_count: prepared.length,
       expires_on: "prompt_end",
-      tracks: registered.tracks.map(publicHistoryTrack),
+      source: "retained_validated_playlist",
+      tracks: prepared.map(publicHistoryTrack),
     };
   }
 
@@ -1001,7 +1149,7 @@ export class ListeningProfileDomainServices {
 
   close() {
     this.resetCandidateSets();
-    this.#store.close();
+    if (this.#ownsStore) this.#store.close();
   }
 }
 

package/src/core/listening-upkeep.mjs

@@ -0,0 +1,31 @@
+// Spotify keeps only a listener's last 50 plays, about three hours of listening. The
+// room runs its listening upkeep when it opens and every half hour while it runs: it
+// reads recent plays before they fall out, then rebuilds the saved reading when due.
+export const LISTENING_UPKEEP_INTERVAL_MS = 30 * 60_000;
+
+export function startListeningUpkeep({ run, intervalMs = LISTENING_UPKEEP_INTERVAL_MS }) {
+  let running = null;
+  let stopped = false;
+  const tick = async () => {
+    // A rebuild can outlast the half hour; the next tick waits for the one after.
+    if (stopped || running) return;
+    running = new AbortController();
+    try {
+      await run({ signal: running.signal });
+    } catch {
+      // Signed out, offline or rate limited: the next tick tries again, and nothing waits on this one.
+    } finally {
+      running = null;
+    }
+  };
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  tick();
+  return {
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+      running?.abort();
+    },
+  };
+}