@audiofool/moondog 0.2.0-beta.2 → 0.2.0-beta.3

package/src/core/moondog-application.mjs

@@ -2,6 +2,9 @@ import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
 import { compactListenerProfile, readListenerProfile } from "../profile/listener-profile-build.mjs";
+import { mixCounts, songKeys } from "../profile/moondog-suggestions.mjs";
+import { ARTIST_CREDIT_SEPARATORS } from "./listener-avoids.mjs";
+import { textNamesSong } from "./track-title.mjs";
 
 import {
   readAppleMusicSourceStatus,
@@ -35,7 +38,7 @@ const spotifyPlaybackCapabilities = new Set([
 const neteaseCapabilities = new Set(["netease.search", "netease.play", "netease.control", "netease.now_playing"]);
 
 // What the model sees of a retained Spotify item: no provider identifiers.
-function modelSpotifyItem({ uri: _uri, album_uri: _albumUri, ...item }) {
+function modelSpotifyItem({ uri: _uri, album_uri: _albumUri, isrc: _isrc, ...item }) {
   return structuredClone(item);
 }
 
@@ -53,6 +56,23 @@ function spotifyResolutionError(code, message) {
   return error;
 }
 
+// A ledger entry's artists: its own list, or its credit whole and split into its artists.
+const creditedArtists = (track) => Array.isArray(track.artists) && track.artists.length ? track.artists
+  : typeof track.artistCredit === "string" ? [track.artistCredit, ...track.artistCredit.split(ARTIST_CREDIT_SEPARATORS)] : [];
+
+// The trusted songs of a pending plan that are still in it.
+const keptTrusted = (draft, kept) => {
+  const refs = new Set(kept.map((track) => track.track_ref_id));
+  return draft.trustedTracks.filter((track) => refs.has(track.track_ref_id));
+};
+
+// The plan songs an Avoid left out of a play, queue or save, by name.
+const skippedAvoided = (avoided) => avoided.length ? { skipped_avoided: avoided, skipped_avoided_count: avoided.length } : {};
+
+// A play the listener's Avoid blocks: nothing is sent, and the model can say why.
+const listenerAvoidError = () => spotifyResolutionError("listener_avoid_blocked",
+  "Nothing was sent. The listener asked to keep this artist or song out of what Moondog plays. Tell them so; they can lift it by asking.");
+
 // Only the host's current user message can grant a quick edit. Model tool
 // arguments and Spotify metadata never supply authorization. Exact ordinary
 // commands and quoted names work; ambiguity uses the existing preview path.
@@ -319,10 +339,15 @@ export class MoondogApplication {
   }
 
   async getListenerProfile(input) {
-    if (!this.profileBuildReady()) return { state: "missing", total_claims: 0, claims: [], next_offset: null };
+    const getChoices = () => this.domainServices?.listenerChoices?.() ?? null;
+    if (!this.profileBuildReady()) {
+      const choices = getChoices();
+      return { state: "missing", total_claims: 0, claims: [], next_offset: null, ...(choices ? { listener_choices: choices } : {}) };
+    }
     return readListenerProfile({
       store: this.domainServices.getListenerProfileStore(),
       getInput: () => this.getProfileBuildContext().input,
+      getChoices,
     }, input);
   }
 
@@ -498,14 +523,29 @@ export class MoondogApplication {
     return this.neteasePlayer;
   }
 
-  searchNetease({ query, limit, intent } = {}) {
-    return this.requireNetease().search({ query, limit, intent });
+  async searchNetease({ query, limit, intent } = {}) {
+    const songs = await this.requireNetease().search({ query, limit, intent });
+    return Array.isArray(songs) ? this.#withSuggestedBefore(songs, song => ({ service: "netease",
+      providerTrackId: song.id ? `netease:${song.id}` : null, title: song.title, artists: song.artists })) : songs;
   }
 
   async playNetease({ items, mode, intent } = {}) {
     const player = this.requireNetease();
+    this.requireListenerAvoids();
     if (mode !== "queue") await this.quietOtherPlayers("netease");
-    return player.play({ items, mode, intent });
+    // A found song lists its artists; a song asked for by name has only the name it was asked by.
+    const receipt = await player.play({ items, mode, intent, allow: (song) => this.avoidAllows(Array.isArray(song.artists)
+      ? { title: song.title, artist_credit: song.artists.join(", "), artists: song.artists } : song) });
+    if (["playing", "queued"].includes(receipt?.mode)) {
+      const songs = receipt.songs ?? [];
+      const slots = this.#mixSlots(songs.map((song) => ({ title: song.title, artists: song.artists })));
+      this.#noteSuggestions("netease", songs.map((song, index) => ({ action: receipt.mode === "queued" ? "netease.queue" : "netease.play",
+        providerTrackId: song.id ? `netease:${song.id}` : null, title: song.title, artists: song.artists, mixSlot: slots[index] })));
+      // One song needs no mix line.
+      const mix = songs.length > 1 ? mixCounts(slots) : null;
+      if (mix) return { ...receipt, mix };
+    }
+    return receipt;
   }
 
   async controlNetease({ action, positionSeconds } = {}) {
@@ -642,29 +682,45 @@ export class MoondogApplication {
       throw new Error("Give either up to six songs or one album.");
     }
     let found;
+    let avoided = 0;
     if (album) {
       const result = await this.musicCatalog.findAlbumPreviews({ title: album.title, artist: album.artist });
-      found = { kind: "album", album: result.album, played: result.tracks ?? [], not_found: result.state === "resolved" ? [] : [album] };
+      const songs = result.tracks ?? [];
+      const played = songs.filter((track) => this.avoidAllows(track));
+      avoided = songs.length - played.length;
+      found = { kind: "album", album: result.album, played, not_found: result.state === "resolved" ? [] : [album] };
     } else {
       const played = [];
       const notFound = [];
       const leftOut = [];
       for (const wanted of tracks.slice(0, 6)) {
         if (byExcluded(wanted.artist)) { leftOut.push(wanted); continue; }
+        if (!this.avoidAllows({ title: wanted.title, artist_credit: wanted.artist })) { avoided += 1; continue; }
         const result = await this.musicCatalog.findPreview({ title: wanted.title, artist: wanted.artist });
         if (result.state !== "resolved") notFound.push(wanted);
         else if (byExcluded(result.track.artist_credit)) leftOut.push(wanted);
+        else if (!this.avoidAllows(result.track)) avoided += 1;
         else played.push(result.track);
       }
       found = { kind: "tracks", played, not_found: notFound, left_out: leftOut };
     }
+    if (avoided) found.skipped_avoided_count = avoided;
     if (found.played.length) {
       await this.quietOtherPlayers("apple_music");
       await this.musicPreviewPlayer.play(structuredClone(found.played), found.album ? { album: structuredClone(found.album) } : {});
     }
     // The desktop window plays whole songs where the listener's Apple Music allows it; a terminal plays previews.
     const whole = this.musicPreviewPlayer.wholeSongs?.() === true;
-    return { state: found.played.length ? "resolved" : "not_found", ...found, whole_songs: whole };
+    const slots = this.#mixSlots(found.played.map((track) => ({ title: track.title, artist_credit: track.artist_credit })));
+    // An album the listener named is theirs, every song of it.
+    const albumArtists = [found.album?.artist_credit, album?.artist].filter((name) => typeof name === "string");
+    if (!(found.album && (this.#listenerNamed(found.album.title, albumArtists) || this.#listenerNamed(album.title, albumArtists)))) {
+      this.#noteSuggestions("apple_music", found.played.map((track, index) => ({ action: whole ? "apple_music.play" : "apple_music.preview",
+        providerTrackId: track.catalog_id ? `apple_music:${track.catalog_id}` : null, isrc: track.isrc, title: track.title,
+        artistCredit: track.artist_credit, mixSlot: slots[index] })));
+    }
+    const mix = found.played.length > 1 ? mixCounts(slots) : null;
+    return { state: found.played.length ? "resolved" : "not_found", ...found, ...(mix ? { mix } : {}), whole_songs: whole };
   }
 
   musicDiscoveryReady() {
@@ -737,7 +793,7 @@ export class MoondogApplication {
       ...(stored ? { stored_plays: stored } : {}),
       ...(spotify ? { spotify_top_artists_4_weeks: {
         read_at: spotify.read_at, artists: spotify.artists,
-        basis: "Spotify's affinity ranking over about four weeks, on every device; not play counts.",
+        basis: "Spotify's affinity ranking over about four weeks, on every device; not play counts. It also counts songs Moondog played or queued, which stored_plays.moondog_started_plays counts apart.",
       } } : {}),
     };
   }
@@ -1500,6 +1556,7 @@ export class MoondogApplication {
           typeof item.album_uri === "string" && /^spotify:album:[A-Za-z0-9]{1,128}$/u.test(item.album_uri) ? item.album_uri :
             this.spotifyKnownItems.get(result.item_ref_id)?.album_uri;
         if (albumUri) result.album_uri = albumUri;
+        if (typeof item.isrc === "string" && /^[A-Z]{2}[A-Z0-9]{3}[0-9]{7}$/iu.test(item.isrc)) result.isrc = item.isrc.toUpperCase();
         this.spotifyRefsByUri.set(item.uri, result.item_ref_id);
         // The newest read of an item wins; the oldest items leave first past the bound.
         this.spotifyKnownItems.delete(result.item_ref_id);
@@ -1569,7 +1626,7 @@ export class MoondogApplication {
     return albumUri ? { contextUri: albumUri, offsetUri: uri } : { uris: [uri] };
   }
 
-  #resumeSpotifySelection(parameters, { signal } = {}) {
+  #resumeSpotifySelection(parameters, { signal, played = null } = {}) {
     const transaction = this.pendingPlaylistPromptTransaction;
     // An album started at one song plays that song: it counts as the same selection as
     // the song alone, and its target names the song, not the album.
@@ -1587,10 +1644,20 @@ export class MoondogApplication {
       return Promise.resolve({ ...receipt, already: true });
     }
     const items = (songs ?? (context ? [context] : [])).map(uri => this.spotifyHostReadItems().find(item => item.uri === uri)).filter(Boolean).map(item => structuredClone(item));
+    if (!items.every(item => this.#spotifyItemAllowed(item))) throw listenerAvoidError();
     const attempt = parameters.uris || parameters.contextUri ? { parameters: structuredClone(parameters), items,
       observedAt: this.spotifyContextClock(), turn: this.spotifyContextTurn, epoch: this.spotifyContextEpoch, outcome: "unconfirmed" } : null;
     if (attempt) this.spotifyPlaybackAttempt = attempt;
     const targets = items.map(item => ({ title: item.name ?? "Spotify item", artist_credit: item.artists.join(", ") }));
+    // The songs this selection starts. An album started whole or at one song goes on playing,
+    // so it goes in the ledger by its release. A playlist or an artist names no song until it plays.
+    const album = parameters.contextUri?.startsWith("spotify:album:")
+      ? parameters.offsetUri ? items.find(item => item.uri === parameters.offsetUri && item.type === "track" && item.album)
+        : items.find(item => item.uri === parameters.contextUri && item.type === "album")
+      : null;
+    played ??= [...(songs ?? []).flatMap(uri => items.filter(item => item.uri === uri && item.type === "track").slice(0, 1)
+      .map(item => ({ providerTrackId: uri, isrc: item.isrc, title: item.name, artists: item.artists }))),
+    ...(album ? [{ action: "play.album", release: album.type === "album" ? album.name : album.album, artists: album.artists }] : [])];
     const explicitDevice = parameters.deviceId !== undefined;
     return this.requireSpotifyService().resume(parameters, { signal,
       preferredDeviceId: this.spotifyPreferredPlaybackDevice,
@@ -1604,6 +1671,7 @@ export class MoondogApplication {
       },
     }).then(receipt => {
       const result = { ...receipt, ...(targets.length ? { targets } : {}) };
+      if (receipt.state === "accepted") this.#noteSuggestions("spotify", played.map(track => ({ action: "play", ...track })));
       if (key && transaction && receipt.state === "accepted") {
         transaction.lastAcceptedPlaybackSelection = key;
         transaction.lastAcceptedPlaybackReceipt = { ...structuredClone(result), deviceId: attempt?.parameters.deviceId };
@@ -1710,9 +1778,56 @@ export class MoondogApplication {
   }
 
   spotifyDiscoveryAllowed(item) {
-    if (!this.domainServices?.filterDiscoveryTracks && this.domainServicesError && !["projection_not_built", "projection_subject_unavailable"].includes(this.domainServicesError)) throw spotifyResolutionError("spotify_discovery_preferences_unavailable", "The listener's preferences could not be loaded. Restore the profile before personalized queueing.");
-    const credits = [...new Set([item.artists.join(", "), ...item.artists])];
-    return credits.every(artist_credit => this.domainServices?.filterDiscoveryTracks?.([{ title: item.name, artist_credit }]).length !== 0);
+    return this.avoidAllows({ title: item.name, artist_credit: item.artists.join(", "), artists: item.artists });
+  }
+
+  // A song by its title and artists, an album or an artist by its artists. A playlist, a show or an
+  // episode names no artist the listener avoids.
+  #spotifyItemAllowed(item) {
+    const artists = Array.isArray(item?.artists) ? item.artists : [];
+    if (item?.type === "track") return this.spotifyDiscoveryAllowed({ name: item.name, artists });
+    if (item?.type === "album") return this.avoidAllows({ artist_credit: artists.join(", "), artists });
+    if (item?.type === "artist") return this.avoidAllows({ artist_credit: item.name, artists: [item.name] });
+    return true;
+  }
+
+  // A pending plan's songs, checked again when it plays, queues or is saved, and read as the
+  // candidate gate read them: a history candidate names its first credited artist whole, so
+  // "Earth, Wind & Fire" stays one artist. A song avoided since the plan is left out and named
+  // in the receipt; only a plan with nothing left is refused.
+  #withoutAvoidedPlanTracks(tracks) {
+    const avoided = tracks.filter((track) => {
+      if (!track) return false;
+      const artists = Array.isArray(track.artists) ? track.artists
+        : track.candidate_scope === "private_history" ? [track.artist_credit] : null;
+      return !this.avoidAllows({ title: track.title, artist_credit: track.artist_credit, ...(artists ? { artists } : {}) });
+    });
+    if (avoided.length && avoided.length === tracks.length) throw listenerAvoidError();
+    return { kept: tracks.filter((track) => !avoided.includes(track)),
+      avoided: avoided.map((track) => ({ title: track.title, artist_credit: track.artist_credit })) };
+  }
+
+  // Avoids that exist but could not be loaded stop every play path, rather than letting them through.
+  requireListenerAvoids() {
+    if (!this.domainServices?.filterDiscoveryTracks && this.domainServicesError && !["projection_not_built", "projection_subject_unavailable"].includes(this.domainServicesError)) throw spotifyResolutionError("listener_avoids_unavailable", "The listener's Avoids could not be loaded, so nothing was played. Restore the profile first.");
+  }
+
+  // The listener's Avoids, checked the same way on every play path: { title, artist_credit, artists }.
+  avoidAllows(track) {
+    this.requireListenerAvoids();
+    return this.domainServices?.filterDiscoveryTracks?.([track]).length !== 0;
+  }
+
+  // A Like, an Avoid or its retraction that the listener stated, saved as the profile command
+  // saves it, so the profile, the Avoid check and the saved reading all see it at once.
+  recordTasteChoice({ entityType, label, artistCredit, stance } = {}) {
+    if (!this.tasteChoicesReady()) throw new Error("Choices can be saved once listening history is imported.");
+    return this.domainServices.recordListenerChoice({ entityType, label, artistCredit, stance });
+  }
+
+  tasteChoicesReady() {
+    return typeof this.domainServices?.recordListenerChoice === "function" &&
+      this.domainServices.listenerChoicesReady?.() !== false;
   }
 
   consumeSpotifyDiscoveryQueries(count) {
@@ -1761,7 +1876,8 @@ export class MoondogApplication {
       truncated ||= result.truncated === true || result.has_more === true;
     }
     const items = this.spotifyReadSelections.get("discovery") ?? [];
-    return { provider: "spotify", items: items.map(modelSpotifyItem),
+    return { provider: "spotify", items: this.#withSuggestedBefore(items, item => ({ providerTrackId: item.uri, isrc: item.isrc, title: item.name, artists: item.artists }))
+      .map(modelSpotifyItem),
       queries_used: used + queries.length, queries_remaining: 6 - used - queries.length,
       state: items.length ? "verified_candidates" : failures.length ? "unavailable" : "no_matches",
       failures, skipped_avoided_count: skippedAvoids, skipped_known_count: skippedKnown, truncated,
@@ -1803,11 +1919,11 @@ export class MoondogApplication {
       throw error;
     }
     const seenUris = this.#observedQueueUris(observed, player);
-    const tracks = items.map(item => ({ track_ref_id: item.item_ref_id, title: item.name, artist_credit: item.artists.join(", "), artists: item.artists }));
+    const tracks = items.map(item => ({ track_ref_id: item.item_ref_id, title: item.name, artist_credit: item.artists.join(", "), artists: item.artists, ...(item.isrc ? { isrc: item.isrc } : {}) }));
     const resolved = new Map(items.map(item => [item.item_ref_id, item.uri]));
     this.transientSpotifyContext = true;
     const filters = { filterDiscoveryTracks: tracks => tracks.filter(track => this.spotifyDiscoveryAllowed({ name: track.title, artists: track.artists })) };
-    const receipt = await this.#queueSpotifyTracks(tracks, resolved, { signal, deviceId, seenUris, limit: requested, domainServices: filters,
+    const receipt = await this.#queueSpotifyTracks(tracks, resolved, { signal, deviceId, seenUris, limit: requested, domainServices: filters, ledgerAction: "queue.batch",
       knownTrack: intent?.excludeKnown ? track => this.domainServices?.isKnownDiscoveryTrack?.(track) === true : null });
     if (!receipt.queued.length && !receipt.stopped) transaction.queueBatchAttempted = false;
     const result = { ...receipt, action: "queue.batch", requested, queued_count: receipt.queued.length,
@@ -1833,6 +1949,57 @@ export class MoondogApplication {
     return seen;
   }
 
+  // What Moondog itself started goes in the listening history's ledger, written from accepted
+  // host receipts only, so its picks never come back as the listener's own plays. A ledger
+  // that cannot be written never undoes the playback. On every path, song by song, a song or
+  // album the listener named in this turn or the two before it is their own choice and stays
+  // out of the ledger, and the songs Moondog added around it stay Moondog's.
+  #noteSuggestions(service, tracks) {
+    tracks = this.#withoutListenerNamed(tracks);
+    if (!tracks.length || typeof this.domainServices?.recordMoondogSuggestions !== "function") return;
+    const requestedAt = new Date(this.spotifyContextClock()).toISOString();
+    const entries = tracks.slice(0, 50);
+    const slots = entries.some((track) => track.mixSlot === undefined)
+      ? this.#mixSlots(entries.map((track) => ({ title: track.title, artists: track.artists, artist_credit: track.artistCredit })))
+      : [];
+    try {
+      this.domainServices.recordMoondogSuggestions(entries.map((track, index) => ({ service, requestedAt, mixSlot: slots[index], ...track })));
+    } catch { /* The music still plays; only its origin goes unrecorded. */ }
+  }
+
+  // An album row goes with the song it started at: named song or named album, it is the listener's.
+  #withoutListenerNamed(tracks) {
+    const named = (track) => this.#listenerNamed(track.title ?? track.release, creditedArtists(track));
+    const songs = tracks.filter((track) => track.title);
+    if (songs.some(named)) return songs.filter((track) => !named(track));
+    return tracks.filter((track) => track.title || !named(track));
+  }
+
+  // Named means one message names the title with one of its artists, or quotes the title.
+  #listenerNamed(title, artists) {
+    return typeof title === "string" &&
+      (this.pendingPlaylistPromptTransaction?.listenerTexts ?? []).some((text) => textNamesSong(text, title, artists));
+  }
+
+  // Which candidates Moondog suggested in earlier sessions, so the model can vary its picks.
+  #withSuggestedBefore(items, track) {
+    let history = null;
+    try {
+      history = items.length ? this.domainServices?.moondogSuggestionHistory?.(items.map(track)) : null;
+    } catch { /* Without the ledger, candidates carry no history. */ }
+    return items.map((item, index) => history?.[index] ? { ...item, suggested_before: history[index] } : item);
+  }
+
+  // Where each song sits in the listener's own plays; unknown without a history.
+  #mixSlots(tracks) {
+    try {
+      const slots = tracks.length ? this.domainServices?.listeningMix?.(tracks) : null;
+      return Array.isArray(slots) && slots.length === tracks.length ? slots : tracks.map(() => "unknown");
+    } catch {
+      return tracks.map(() => "unknown");
+    }
+  }
+
   // Spotify's own queue is the truth. An accepted write can take a moment to
   // appear, so look twice before calling an entry unconfirmed.
   async #verifyQueued(uris, { signal } = {}) {
@@ -1893,7 +2060,8 @@ export class MoondogApplication {
     if (queueCancellationRequested(this.pendingPlaylistPromptTransaction?.userText)) throw spotifyResolutionError("spotify_queue_cancelled", "The listener asked to stop queueing. No write was sent.");
     if (this.pendingPlaylistPromptTransaction?.queueIntent && this.spotifyQueueRequest) this.spotifyQueueRequest.attempted = true;
     const item = this.spotifyHostReadItems().find(item => item.uri === uri);
-    const track = { track_ref_id: "single", title: item?.name ?? "the selected track", artist_credit: item?.artists?.join(", ") ?? "" };
+    if (item && !this.#spotifyItemAllowed(item)) throw listenerAvoidError();
+    const track = { track_ref_id: "single", title: item?.name ?? "the selected track", artist_credit: item?.artists?.join(", ") ?? "", artists: item?.artists ?? [], ...(item?.isrc ? { isrc: item.isrc } : {}) };
     // One entry takes the same path as a batch: one device decision, start
     // playback when nothing is playing, and a check of Spotify's real queue.
     const receipt = await this.#queueSpotifyTracks([track], new Map([["single", uri]]), { signal, deviceId: input.deviceId, rethrow: true });
@@ -1949,7 +2117,7 @@ export class MoondogApplication {
     const resolvedByRef = new Map((resolution.resolutions ?? [])
       .filter((entry) => entry.status === "resolved" && /^spotify:track:[A-Za-z0-9]{1,128}$/u.test(entry.spotify?.uri ?? ""))
       .map((entry) => [entry.track_ref_id, entry.spotify.uri]));
-    const receipt = await this.#queueSpotifyTracks(tracks, resolvedByRef, { signal, seenUris, limit: count, domainServices });
+    const receipt = await this.#queueSpotifyTracks(tracks, resolvedByRef, { signal, seenUris, limit: count, domainServices, ledgerAction: "queue.similar" });
     this.recordPromptDiscoverySource(registered.source);
     const result = { ...receipt, action: "queue.similar", requested: count, queued_count: receipt.queued.length,
       shortfall: count - receipt.queued.length, seed_artist: seedArtist, queue_observation_truncated: observed.truncated === true };
@@ -2731,7 +2899,8 @@ export class MoondogApplication {
     const details = spotifyPlaylistDetails({ name, description });
     this.requireSpotifyWriteScopes(["playlist-modify-private"]);
     const uris = this.requireSpotifyTrackUris(trackRefs);
-    return this.writeSpotifyPlaylist(details, uris, { signal });
+    const planned = new Map((this.pendingSpotifyPlaylist?.plan?.tracks ?? []).map((track) => [track.track_ref_id, track]));
+    return this.writeSpotifyPlaylist(details, uris, { signal, tracks: trackRefs.map((ref) => planned.get(ref) ?? null) });
   }
 
   pendingSpotifyPlaylistStatus() {
@@ -2786,8 +2955,9 @@ export class MoondogApplication {
     this.requireSpotifyScopes(["user-read-private"]);
     this.requireSpotifyWriteScopes(["playlist-modify-private"]);
     const draft = this.pendingSpotifyPlaylist;
+    const { kept, avoided } = this.#withoutAvoidedPlanTracks(draft.plan.tracks);
     const result = await this.requireSpotifyResolver().resolve(
-      draft.trustedTracks,
+      keptTrusted(draft, kept),
       { signal },
     );
     signal?.throwIfAborted();
@@ -2800,7 +2970,7 @@ export class MoondogApplication {
         );
       }
     }
-    const uris = draft.plan.tracks.map((track) =>
+    const uris = kept.map((track) =>
       resolvedByRef.get(track.track_ref_id),
     );
     if (uris.some((uri) => typeof uri !== "string")) {
@@ -2809,7 +2979,7 @@ export class MoondogApplication {
         "The pending playlist could not be fully resolved on Spotify, so no playlist was created.",
       );
     }
-    return this.writeSpotifyPlaylist(details, uris, { signal });
+    return this.writeSpotifyPlaylist(details, uris, { signal, tracks: kept, avoided });
   }
 
   async spotifyPlayPendingPlan({ deviceId } = {}, { signal } = {}) {
@@ -2824,14 +2994,15 @@ export class MoondogApplication {
     }
     this.requireSpotifyScopes(["user-read-private"]);
     const draft = this.pendingSpotifyPlaylist;
-    const result = await this.requireSpotifyResolver().resolve(draft.trustedTracks, { signal });
+    const { kept, avoided } = this.#withoutAvoidedPlanTracks(draft.plan.tracks);
+    const result = await this.requireSpotifyResolver().resolve(keptTrusted(draft, kept), { signal });
     signal?.throwIfAborted();
     const resolvedByRef = new Map(
       (result.resolutions ?? [])
         .filter((resolution) => resolution.status === "resolved" && resolution.spotify?.uri)
         .map((resolution) => [resolution.track_ref_id, resolution.spotify.uri]),
     );
-    const uris = draft.plan.tracks.map((track) => resolvedByRef.get(track.track_ref_id));
+    const uris = kept.map((track) => resolvedByRef.get(track.track_ref_id));
     if (uris.some((uri) => typeof uri !== "string")) {
       throw spotifyResolutionError(
         "spotify_pending_playback_unresolved",
@@ -2841,8 +3012,10 @@ export class MoondogApplication {
     const receipt = await this.#resumeSpotifySelection({
       uris,
       ...(deviceId ? { deviceId } : {}),
-    }, { signal });
-    return { ...receipt, track_count: uris.length };
+    }, { signal, played: kept.map((track, index) => ({
+      providerTrackId: uris[index], title: track.title, artistCredit: track.artist_credit,
+    })) });
+    return { ...receipt, track_count: uris.length, ...skippedAvoided(avoided) };
   }
 
   async spotifyQueuePendingPlan({ deviceId } = {}, { signal } = {}) {
@@ -2856,8 +3029,9 @@ export class MoondogApplication {
     }
     this.requireSpotifyScopes(["user-read-private"]);
     const draft = this.pendingSpotifyPlaylist;
+    const { kept, avoided } = this.#withoutAvoidedPlanTracks(draft.plan.tracks);
     const result = await this.requireSpotifyResolver().resolve(
-      draft.trustedTracks,
+      keptTrusted(draft, kept),
       { signal },
     );
     signal?.throwIfAborted();
@@ -2867,15 +3041,19 @@ export class MoondogApplication {
         resolvedByRef.set(resolution.track_ref_id, resolution.spotify.uri);
       }
     }
-    const receipt = await this.#queueSpotifyTracks(draft.plan.tracks, resolvedByRef, { signal, deviceId });
+    const receipt = await this.#queueSpotifyTracks(kept, resolvedByRef, { signal, deviceId, ledgerAction: "queue.plan" });
     if (receipt.state === "no_candidates") {
       throw spotifyResolutionError("spotify_pending_queue_unmatched", "None of the pending tracks matched a Spotify track, so nothing was queued.");
     }
-    return receipt;
+    return avoided.length ? { ...receipt, skipped_avoided: avoided, skipped_avoided_count: receipt.skipped_avoided_count + avoided.length } : receipt;
   }
 
-  async #queueSpotifyTracks(tracks, resolvedByRef, { signal, deviceId, seenUris = null, limit = tracks.length, domainServices = null, knownTrack = null, rethrow = false } = {}) {
+  async #queueSpotifyTracks(tracks, resolvedByRef, { signal, deviceId, seenUris = null, limit = tracks.length, domainServices = null, knownTrack = null, rethrow = false, ledgerAction = "queue.add" } = {}) {
     const label = (track) => ({ title: track.title, artist_credit: track.artist_credit });
+    // A remaster or a second copy of the same song is a duplicate too, not only the same URI.
+    const seenSongs = new Set();
+    const sameSong = (track) => [...songKeys(track), track.isrc ? `isrc:${track.isrc}` : null].filter(Boolean);
+    const accepted = [];
     const queued = [];
     const unmatched = [];
     let skippedDuplicates = 0;
@@ -2891,13 +3069,14 @@ export class MoondogApplication {
     let outcomeUnknown = false;
     let target = null;
     let started = null;
+    let startedUri = null;
     const acceptedUris = [];
     for (const [index, track] of tracks.entries()) {
       if (queued.length >= limit) break;
       if (signal?.aborted) { stopped = label(track); stopIndex = index; break; }
       const uri = resolvedByRef.get(track.track_ref_id);
       if (typeof uri !== "string") { unmatched.push(label(track)); continue; }
-      if (seenUris?.has(uri)) { skippedDuplicates++; continue; }
+      if (seenUris?.has(uri) || sameSong(track).some(key => seenSongs.has(key))) { skippedDuplicates++; continue; }
       if (this.recentUncertainQueueUris.has(uri)) { skippedUncertain++; continue; }
       let dispatching = false;
       try {
@@ -2911,6 +3090,7 @@ export class MoondogApplication {
           dispatching = true;
           const receipt = await service.resume({ uris: [uri], ...device }, { signal });
           started = label(track);
+          startedUri = uri;
           target = { ...target, active: true, ...(receipt?.device ? { device: receipt.device } : {}) };
         };
         if (target.active === false) await start();
@@ -2930,6 +3110,8 @@ export class MoondogApplication {
         }
         acceptedUris.push(uri);
         queued.push(label(track));
+        accepted.push({ track, uri });
+        for (const key of sameSong(track)) seenSongs.add(key);
         if (this.pendingPlaylistPromptTransaction) this.pendingPlaylistPromptTransaction.queueWriteCount = (this.pendingPlaylistPromptTransaction.queueWriteCount ?? 0) + 1;
         seenUris?.add(uri);
         if (seenUris) {
@@ -2958,9 +3140,16 @@ export class MoondogApplication {
     if (queued.length === 0 && !outcomeUnknown) signal?.throwIfAborted();
     const state = stopped ? (queued.length ? "partial" : outcomeUnknown ? "unknown" : "failed")
       : queued.length ? "accepted" : "no_candidates";
+    // Each song is placed in the listener's own history before it lands in the ledger.
+    const slots = this.#mixSlots(accepted.map(({ track }) => track));
+    this.#noteSuggestions("spotify", accepted.map(({ track, uri }, index) => ({
+      action: uri === startedUri ? "play" : ledgerAction, providerTrackId: uri, isrc: track.isrc,
+      title: track.title, artists: track.artists, artistCredit: track.artist_credit, mixSlot: slots[index],
+    })));
+    const mix = mixCounts(slots);
     const verification = acceptedUris.length && !signal?.aborted ? await this.#verifyQueued(acceptedUris, { signal }) : null;
     return { provider: "spotify", ok: !["unknown", "failed"].includes(state), effect: "write_external", action: "playback.queue.add",
-      state, queued, unmatched, not_added: stopIndex >= 0 ? tracks.slice(stopIndex + 1, stopIndex + Math.max(1, limit - queued.length)).map(label) : [],
+      state, queued, ...(mix ? { mix } : {}), unmatched, not_added: stopIndex >= 0 ? tracks.slice(stopIndex + 1, stopIndex + Math.max(1, limit - queued.length)).map(label) : [],
       ...(target?.device ? { device: target.device } : {}), ...(started ? { started_playback: started } : {}),
       ...(verification ? { verification } : {}),
       ...(stopIndex >= 0 ? { not_added_count: Math.min(tracks.length - stopIndex - 1, Math.max(0, limit - queued.length - 1)) } : {}),
@@ -2972,9 +3161,14 @@ export class MoondogApplication {
       ...(signal?.aborted ? { cancelled: true } : {}) };
   }
 
-  async writeSpotifyPlaylist(details, uris, { signal } = {}) {
+  async writeSpotifyPlaylist(details, uris, { signal, tracks = [], avoided: leftOut = [] } = {}) {
     signal?.throwIfAborted();
     this.requireSpotifyPlaylistCreationFlow();
+    const { kept, avoided } = this.#withoutAvoidedPlanTracks(tracks);
+    if (avoided.length) {
+      uris = uris.filter((_uri, index) => kept.includes(tracks[index]));
+      tracks = kept;
+    }
     if (this.pendingPlaylistPromptTransaction) this.pendingPlaylistPromptTransaction.playlistWriteAttempted = true;
     this.invalidateSpotifyQuickEditContext();
     try {
@@ -2982,12 +3176,14 @@ export class MoondogApplication {
         ...details,
         uris,
       }, { signal });
+      this.#noteSuggestions("spotify", tracks.flatMap((track, index) => track ? [{ action: "playlist.write",
+        providerTrackId: uris[index], title: track.title, artistCredit: track.artist_credit }] : []));
       if (this.pendingPlaylistPromptTransaction) {
         this.pendingPlaylistPromptTransaction.externalized = true;
       }
       this.pendingSpotifyPlaylist = null;
       this.pendingPlaylistRevisionCandidateSet = null;
-      return receipt;
+      return { ...receipt, ...skippedAvoided([...leftOut, ...avoided]) };
     } catch (error) {
       if (error?.outcomeUnknown === true || ["playlist_created_without_tracks", "playlist_created_tracks_unknown"].includes(error?.code)) {
         if (this.pendingPlaylistPromptTransaction) {
@@ -3080,6 +3276,7 @@ export class MoondogApplication {
         musicSimilarityReady: this.musicSimilarityReady(),
         ...this.webLookupOptions(),
       musicPreviewReady: this.musicPreviewReady(),
+      tasteChoicesReady: this.tasteChoicesReady(),
       }).map(capability => capability.state === "enabled" && this.#playbackServiceExcludes(capability.id)
         ? { ...capability, state: "blocked", blocked_by: capability.id === "listening.now" ? "no_readable_player" : capability.id === "music_app.control" ? "no_music_app" : capability.id === "playback.service" ? "no_playback_service"
           : neteaseCapabilities.has(capability.id) ? "netease_not_ready" : "playback_service_not_spotify" } : capability),
@@ -3114,6 +3311,7 @@ export class MoondogApplication {
       musicSimilarityReady: this.musicSimilarityReady(),
       ...this.webLookupOptions(),
       musicPreviewReady: this.musicPreviewReady(),
+      tasteChoicesReady: this.tasteChoicesReady(),
     }).filter(descriptor => !this.#playbackServiceExcludes(descriptor.capability_id));
   }
 
@@ -3324,6 +3522,9 @@ export class MoondogApplication {
     if (transaction) transaction.playlistPlanAttempted = true;
     this.invalidateSpotifyQuickEditContext();
     const plan = await this.requirePlaylistServices().buildPlaylistPlan(input);
+    // The host declares the blend from the listener's own plays; the model never writes it.
+    const mix = Array.isArray(plan?.tracks) ? mixCounts(this.#mixSlots(plan.tracks)) : null;
+    if (mix) plan.mix = mix;
     const validatedPlaylistTrackRefs = Array.isArray(plan?.tracks)
       ? plan.tracks.map((track) => track.track_ref_id)
       : null;
@@ -3401,7 +3602,8 @@ export class MoondogApplication {
     };
   }
 
-  beginPrompt({ text } = {}) {
+  // recentTexts are the listener's messages of the turns before this one, newest last.
+  beginPrompt({ text, recentTexts = [] } = {}) {
     if (this.pendingPlaylistPromptTransaction) {
       throw new Error("A Moondog prompt state transaction is already active.");
     }
@@ -3413,6 +3615,8 @@ export class MoondogApplication {
     if (queueIntent) this.spotifyQueueRequest = { ...(queueIntent.clarification_only ? previousQueue : {}), ...queueIntent, observedAt: this.spotifyContextClock(), turn: this.spotifyContextTurn, epoch: this.spotifyContextEpoch };
     this.pendingPlaylistPromptTransaction = {
       userText: text,
+      // What the listener said in this turn and the two before it: a song named there is theirs.
+      listenerTexts: [...(Array.isArray(recentTexts) ? recentTexts : []).slice(-2), text].filter((value) => typeof value === "string"),
       queueIntent,
       removalConfirmationRequested: /^Confirm removal of (?:playlist|track|album|episode|show) .+ from my library[.!。！]?$/u.test(text?.trim() ?? ""),
       pendingSpotifyRemoval: structuredClone(this.pendingSpotifyRemoval),

package/src/core/spotify-listening-intent.mjs

@@ -69,10 +69,13 @@ export function queueCancellationRequested(text) {
     /^(?:キャンセル|やめて|止めて|中止)(?:して)?(?:ください)?[。！!]?$|(?:キュー|再生待ち)[^。！？]{0,20}(?:入れないで|追加しないで|やめて)|追加しないで/u.test(value);
 }
 
-/** The listener asked for music they have not heard, in any supported language. */
+/**
+ * The listener asked for music they have not heard, in any supported language. "Not heard" counts
+ * only when it ends there or says yet, before or ever: "haven't heard in a while" asks to come back.
+ */
 export function unheardRequested(text) {
   return typeof text === "string" &&
-    /没听过|从未听|不要听过|\bunheard\b|\bnever heard\b|outside.*library|曲库之外|nunca he (?:escuchado|o[ií]do)|que no (?:he|haya) (?:escuchado|o[ií]do)|sin escuchar|nuevas para m[ií]|nunca ouvi|que eu (?:ainda )?n[aã]o (?:ouvi|conhe[cç]o)|novas pra mim|novas para mim|聴いたことのない|聞いたことのない|知らない曲|未聴/iu.test(text);
+    /没听过|从未听|不要听过|\bunheard\b|\bnever (?:heard|listened to)\b|\b(?:haven't|have not|'ve not|not)\s+(?:yet\s+|ever\s+)?(?:heard|listened to)(?:\s+(?:yet|before|of|ever|please)\b|\s*(?:$|[,.;!?，。；！？]))|\bnew (?:to|for) me\b|\bunfamiliar\b|outside.*library|曲库之外|nunca he (?:escuchado|o[ií]do)|que no (?:he|haya) (?:escuchado|o[ií]do)|sin escuchar|nuevas para m[ií]|nunca ouvi|que eu (?:ainda )?n[aã]o (?:ouvi|conhe[cç]o)|novas pra mim|novas para mim|聴いたことのない|聞いたことのない|知らない曲|未聴/iu.test(text.replace(/[\u2018\u2019]/gu, "'"));
 }
 
 function queueRefinement(value, previous) {