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

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">Moondog</h1>
 
-<p align="center">Source candidate 0.2.0-beta.2</p>
+<p align="center">Source candidate 0.2.0-beta.3</p>
 
 <p align="center"><strong>A listening room that shows its work.</strong></p>
 
@@ -131,7 +131,7 @@ Playing a song a lot does not, on its own, establish how much it matters to you.
 | --- | --- |
 | Find a song or artist | Type to filter, then open it. |
 | See why it is there | Read what you played, what that cannot prove, and what you told Moondog, each on its own. |
-| Make a choice | Choose **I like this** (Like) or **Keep it out** (Avoid), and the profile updates in place. |
+| Make a choice | Choose **I like this** (Like) or **Keep it out** (Avoid), and the profile updates in place. You can also say it to the agent, for example “never play this again”. |
 | Change your mind | Choose **Undo my choice**, and the original listening history never changes. |
 | Find more like this | Start an editable request for three songs, from the track you picked. |
 
@@ -155,6 +155,8 @@ It also sees what you already play: the song and playlist in the Music app on a
 macOS asks once before Moondog may read the Music app.
 For example, “Pon doce de salsa clásica a la cola” asks it to add up to twelve verified songs directly; your history guides the choice without limiting it to your library.
 What it reads about the wider music world stays separate from what it knows about you.
+Under a queue or a set of songs, one line names the mix: how many you know well, how many come back after a while, and how many are new to you.
+Songs Moondog chose for you do not count as your own taste.
 
 | Optional connection | What it adds |
 | --- | --- |
@@ -199,6 +201,7 @@ Your profile, and anything Moondog remembers, carry over.
 - [Private Tasteprint](docs/PRIVATE_TASTEPRINT.md): what the evidence can support, and what a report reveals about you.
 - [Product charter](docs/PRODUCT_CHARTER.md) and [public roadmap](docs/ROADMAP.md): where Moondog is headed, and what it will not do.
 - [Voice](docs/VOICE.md): how Moondog talks, and where Pink Floyd shows up.
+- [The listening loop](docs/LISTENING_LOOP.md): how the agent keeps your choices, your recent listening, and its own picks apart.
 - [Runtime architecture](docs/ADR_0001_AGENT_RUNTIME_AND_CLI.md) and [data contracts](contracts/README.md): how the pieces fit together.
 - [Contribution guide](CONTRIBUTING.md): local setup, checks, and how private data is kept out.
 - [Release status](docs/PUBLIC_RELEASE_READINESS.md): what is published, and what the checks cover.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiofool/moondog",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.3",
   "type": "module",
   "description": "Local-first personal AI music agent.",
   "license": "Apache-2.0",

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

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { exploreProfileCatalog, profileExplorationInput } from "../profile/profile-exploration.mjs";
-import { createListenerProfileInput } from "../profile/listener-profile-build.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";
@@ -812,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 (
@@ -883,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"),
     };
@@ -985,6 +990,8 @@ function preferenceSignalLabel(observation = {}) {
   return labels.join(", ") || "explicit provider preference signal";
 }
 
+const avoidGates = new WeakMap();
+
 export function listenerAssertionAvoids(
   listening,
   entityType,
@@ -992,19 +999,11 @@ export function listenerAssertionAvoids(
   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) {
@@ -1211,6 +1210,8 @@ export class AppleProjectionDomainServices {
   #subjectId;
   #candidateSets = new Map();
   #profileBuildInput;
+  #avoids = {};
+  #status = {};
   #ownsStores = true;
 
   constructor({ projection, listeningHistoryStore = null, subjectId = null }) {
@@ -1246,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,
@@ -1284,6 +1295,43 @@ export class AppleProjectionDomainServices {
     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 &&
@@ -1764,16 +1812,36 @@ export class AppleProjectionDomainServices {
     };
   }
 
+  // Every play path asks for each candidate, so the gate is kept until the data changes.
   filterDiscoveryTracks(tracks) {
     const store = this.#listeningHistoryStore;
-    const avoids = store?.activeAvoidances?.({ subjectId: this.#subjectId }) ??
-      store?.profileSummary?.({ subjectId: this.#subjectId })?.listener_assertions?.avoids ?? [];
-    const listening = normalizeAppleCorrectionLabels(
-      { listener_assertions: { avoids } }, this.#projection,
-    );
-    return tracks.filter((track) => !listenerAssertionAvoids(
-      listening, "track", track.title, track.artist_credit,
-    ));
+    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) {
@@ -1985,7 +2053,7 @@ export class AppleProjectionDomainServices {
 
   getProfileBuildContext() {
     const appleDigest = this.#projection.logicalDigest();
-    const version = `${appleDigest}:${this.#listeningHistoryStore.profileDataVersion()}`;
+    const version = `${appleDigest}:${listeningVersion(this.#listeningHistoryStore)}`;
     if (this.#profileBuildInput?.version !== version) {
       const listening = this.#listeningHistoryStore.profileCatalog({ subjectId: this.#subjectId });
       const normalized = normalizeAppleCorrectionLabels({ listener_assertions: {

package/src/core/capability-catalog.mjs

@@ -341,6 +341,12 @@ const catalog = [
       label: N_("Forget something"),
     },
   },
+  {
+    id: "taste.choice", version: "1", state: "enabled", effect: "write_local",
+    description: "Save a lasting Like or Avoid for an artist or song, or undo one, when the listener states it in their own words.",
+    requires_taste_choices: true,
+    agent_tool: { name: "moondog_taste_choice", label: N_("Save your choice") },
+  },
   {
     id: "spotify.history.import",
     version: "1",
@@ -629,7 +635,11 @@ function withRuntimeAvailability(
   profileExplorationReady,
   profileBuildReady,
   musicPreviewReady,
+  tasteChoicesReady,
 ) {
+  if (capability.requires_taste_choices && !tasteChoicesReady) {
+    return { ...capability, state: "blocked", blocked_by: "taste_choices_not_ready" };
+  }
   if (capability.requires_profile_build && !profileBuildReady) {
     return { ...capability, state: "blocked", blocked_by: "profile_build_not_ready" };
   }
@@ -758,6 +768,7 @@ export function listCapabilities({
   profileExplorationReady = false,
   profileBuildReady = false,
   musicPreviewReady = false,
+  tasteChoicesReady = false,
 } = {}) {
   return structuredClone(
     catalog.map((capability) =>
@@ -779,6 +790,7 @@ export function listCapabilities({
         profileExplorationReady,
         profileBuildReady,
         musicPreviewReady,
+        tasteChoicesReady,
       ),
     ),
   );

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-profile-domain-services.mjs

@@ -1,14 +1,15 @@
 import { randomUUID } from "node:crypto";
 import { exploreProfileCatalog, profileExplorationInput } from "../profile/profile-exploration.mjs";
-import { createListenerProfileInput } from "../profile/listener-profile-build.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";
 import {
   assertExternalPlanDiversity,
   exactTitleArtistMatch,
-  listenerAssertionAvoids,
   safeExternalSource,
   safeExternalTrack,
 } from "./apple-projection-domain-services.mjs";
@@ -423,6 +424,8 @@ export class ListeningProfileDomainServices {
   #subjectId;
   #candidateSets = new Map();
   #profileBuildInput;
+  #avoids = {};
+  #status = {};
   #ownsStore = true;
 
   constructor({ listeningHistoryStore, subjectId } = {}) {
@@ -462,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,
     });
@@ -493,6 +505,19 @@ export class ListeningProfileDomainServices {
     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";
   }
@@ -553,12 +578,23 @@ export class ListeningProfileDomainServices {
     return { candidateSetId, tracks: prepared };
   }
 
+  // Every play path asks for each candidate, so the gate is kept until the data changes.
   filterDiscoveryTracks(tracks) {
-    const avoids = this.#store.activeAvoidances?.({ subjectId: this.#subjectId }) ??
-      this.#store.profileSummary({ subjectId: this.#subjectId })?.listener_assertions?.avoids ?? [];
-    return tracks.filter((track) => !listenerAssertionAvoids(
-      { listener_assertions: { avoids } }, "track", track.title, track.artist_credit,
-    ));
+    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) {
@@ -652,7 +688,7 @@ export class ListeningProfileDomainServices {
   }
 
   getProfileBuildContext() {
-    const version = this.#store.profileDataVersion();
+    const version = listeningVersion(this.#store);
     if (this.#profileBuildInput?.version !== version) {
       this.#profileBuildInput = { version, input: createListenerProfileInput({
         subjectId: this.#subjectId,