@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/profile/local-music-data.mjs

@@ -673,7 +673,7 @@ async function checkpointSqlite(filePath) {
   } catch (error) {
     fail(
       "local_music_data_busy",
-      "Local music data is busy. Close Moondog Studio and other Moondog processes before reset.",
+      "Local music data is busy. Close other Moondog windows and processes before reset.",
       { cause: error },
     );
   } finally {

package/src/profile/moondog-suggestions.mjs

@@ -0,0 +1,184 @@
+import { normalizedArtistName, trackMatchKey } from "../core/track-title.mjs";
+
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+
+// A stored play is one Moondog started when it is the same recording as a suggestion (the same
+// Spotify track or ISRC) or the same song by title and primary artist, and it lands from 60
+// seconds before the request to six hours after it: long enough for a queued batch to play out,
+// short enough that a later return is the listener's own. A play's time is when it ended, so one
+// that ended before the request was the listener's; the 60 seconds only absorb clock skew. A
+// matching play after the window is the listener's choice and marks the suggestion adopted. The
+// match runs whenever the profile is read, so a later history import is matched the same way.
+export const SUGGESTION_WINDOW = Object.freeze({ beforeMs: 60_000, afterMs: 6 * HOUR_MS });
+
+export const SUGGESTION_SERVICES = Object.freeze(["spotify", "netease", "apple_music"]);
+
+// One artist's name can hold a separator ("AC/DC", "Simon & Garfunkel", "Tyler, The Creator"),
+// so a bare credit is tried whole, then by its comma parts, then by every part.
+function creditSplits(credit) {
+  const whole = String(credit ?? "").trim();
+  const split = (pattern) => whole.split(pattern).map((name) => name.trim()).filter(Boolean);
+  return [[whole].filter(Boolean), split(/[,;]/u), split(/\s*(?:,|&|;|\/|\bfeat\.?|\bfeaturing\b)\s*/iu)];
+}
+
+const creditNames = (credit) => [...new Set(creditSplits(credit).flat())];
+
+// The names a track may be stored under: its first artist, or each reading of a bare credit's first one.
+function primaryArtists(track) {
+  if (Array.isArray(track?.artists) && typeof track.artists[0] === "string") return [track.artists[0]];
+  if (Array.isArray(track?.artist_credits)) return track.artist_credits[0]?.name ? [track.artist_credits[0].name] : [];
+  return [...new Set(creditSplits(track?.artist_credit).map((names) => names[0]).filter(Boolean))];
+}
+
+/** One song by its primary artist, the same for every version of it; a bare credit can give more than one. */
+export function songKeys(track) {
+  return [...new Set(primaryArtists(track).map((artist) => trackMatchKey(track?.title, artist)).filter(Boolean))];
+}
+
+const releaseKey = (track) => trackMatchKey(typeof track?.release === "string" ? track.release : track?.release?.title,
+  primaryArtists(track)[0]);
+
+/** The ways a stored track can match a suggestion: its Spotify track, its ISRC, its song, its album. */
+export function playedTrackIdentities(track) {
+  const identities = [];
+  for (const ref of Array.isArray(track?.external_refs) ? track.external_refs : []) {
+    if (ref?.system === "spotify" && ref.entity_type === "spotify.track" && typeof ref.external_id === "string") {
+      identities.push(`spotify:track:${ref.external_id}`);
+    }
+  }
+  if (typeof track?.isrc === "string") identities.push(`isrc:${track.isrc.toUpperCase()}`);
+  for (const key of songKeys(track)) identities.push(`key:${key}`);
+  const release = releaseKey(track);
+  if (release) identities.push(`release:${release}`);
+  return identities;
+}
+
+export function suggestionIdentities(suggestion) {
+  return [...new Set([
+    suggestion.provider_track_id,
+    suggestion.isrc ? `isrc:${suggestion.isrc}` : null,
+    suggestion.track_key ? `key:${suggestion.track_key}` : null,
+    ...(suggestion.track_key ? songKeys({ title: suggestion.title, artist_credit: suggestion.artist_credit }).map((key) => `key:${key}`) : []),
+    suggestion.release_key ? `release:${suggestion.release_key}` : null,
+    // An album row keeps its release title, so its key is rebuilt too, as a song's is.
+    suggestion.release_key && releaseKey({ release: suggestion.title, artist_credit: suggestion.artist_credit })
+      ? `release:${releaseKey({ release: suggestion.title, artist_credit: suggestion.artist_credit })}` : null,
+  ].filter(Boolean))];
+}
+
+/**
+ * The ledger entry for one accepted host write, or null when it names no song. An album Moondog
+ * started names its release instead, so every song of it that plays matches.
+ */
+export function suggestionEntry({ service, action, providerTrackId = null, isrc = null, title, release = null, artists, artistCredit, mixSlot = null, requestedAt }) {
+  const credit = typeof artistCredit === "string" && artistCredit.trim() ? artistCredit.trim()
+    : Array.isArray(artists) ? artists.filter((name) => typeof name === "string").join(", ") : "";
+  const named = { title, release, artists, artist_credit: credit };
+  const key = title ? songKeys(named)[0] ?? null : null;
+  const album = !title && typeof release === "string" ? releaseKey(named) : null;
+  if (!SUGGESTION_SERVICES.includes(service) || !(key || album)) return null;
+  return {
+    service, action,
+    provider_track_id: typeof providerTrackId === "string" && providerTrackId ? providerTrackId : null,
+    isrc: typeof isrc === "string" && /^[A-Z]{2}[A-Z0-9]{3}[0-9]{7}$/iu.test(isrc) ? isrc.toUpperCase() : null,
+    track_key: key,
+    release_key: album,
+    title: Array.from(String(title || release).trim()).slice(0, 512).join(""),
+    artist_credit: Array.from(credit).slice(0, 512).join(""),
+    requested_at: requestedAt,
+    mix_slot: key && MIX_SLOTS.includes(mixSlot) ? mixSlot : null,
+  };
+}
+
+/**
+ * Marks each stored play Moondog started with its suggestion, and returns the suggestions the
+ * listener later played again on their own. Events are never rewritten.
+ */
+export function markMoondogStartedPlays(eventRows, suggestions) {
+  const adopted = new Set();
+  if (!suggestions.length) return { rows: eventRows, adopted };
+  const byIdentity = new Map();
+  for (const suggestion of suggestions) {
+    const entry = { ...suggestion, requestedMs: Date.parse(suggestion.requested_at) };
+    for (const identity of suggestionIdentities(suggestion)) {
+      byIdentity.set(identity, [...(byIdentity.get(identity) ?? []), entry]);
+    }
+  }
+  // Plays repeat a much smaller set of tracks, so a stored track (one revision of a track_refs
+  // row) is matched once, and only plays of a matched track read their time.
+  const byTrack = new Map();
+  const trackMatches = (track) => {
+    const key = typeof track?.track_ref_id === "string" && Number.isInteger(track.revision)
+      ? `${track.track_ref_id}\0${track.revision}` : null;
+    let matches = key === null ? undefined : byTrack.get(key);
+    if (!matches) {
+      matches = [...new Set(playedTrackIdentities(track).flatMap((identity) => byIdentity.get(identity) ?? []))];
+      if (key !== null) byTrack.set(key, matches);
+    }
+    return matches;
+  };
+  const rows = eventRows.map((row) => {
+    if (row.event?.extensions?.["spotify.incognito_mode"] === true) return row;
+    const matches = trackMatches(row.track);
+    if (!matches.length) return row;
+    const playedMs = Date.parse(row.event?.occurred_at);
+    if (!Number.isFinite(playedMs)) return row;
+    const started = matches.find((entry) =>
+      playedMs >= entry.requestedMs - SUGGESTION_WINDOW.beforeMs && playedMs <= entry.requestedMs + SUGGESTION_WINDOW.afterMs);
+    if (started) return { ...row, moondog_suggestion_id: started.suggestion_id };
+    for (const entry of matches) if (playedMs > entry.requestedMs + SUGGESTION_WINDOW.afterMs) adopted.add(entry.suggestion_id);
+    return row;
+  });
+  return { rows, adopted };
+}
+
+// The declared mix: where each song sits in the listener's own plays, Moondog's plays left out.
+// At least 3 plays is a song they know: familiar when one falls within 365 days of their latest
+// play, otherwise returning (then none falls in the last 180 days either). One or two plays, or
+// only plays Moondog started, is a song they have heard. With none, it is new from an artist
+// they play, or new to them.
+export const MIX_SLOTS = Object.freeze(["familiar", "returning", "heard", "known_artist", "new"]);
+
+/** What the listener's own plays say about songs and artists, or null with no plays at all. */
+export function listeningFamiliarity(catalog, referenceDate) {
+  const referenceMs = Date.parse(referenceDate ?? "");
+  if (!Number.isFinite(referenceMs) || !catalog?.history_tracks?.length) return null;
+  const tracks = new Map();
+  for (const row of catalog.history_tracks) {
+    const key = trackMatchKey(row.label, row.artist_credit);
+    if (!key) continue;
+    const known = tracks.get(key) ?? { plays: 0, lastMs: 0 };
+    known.plays += row.play_count ?? 0;
+    known.lastMs = Math.max(known.lastMs, Date.parse(row.last_played_at) || 0);
+    tracks.set(key, known);
+  }
+  const artists = new Set((catalog.history_artists ?? []).map((row) => normalizedArtistName(row.name)).filter(Boolean));
+  const moondogHeard = new Set((catalog.moondog_suggestions ?? []).map((row) => trackMatchKey(row.label, row.artist_credit)).filter(Boolean));
+  return { referenceMs, tracks, artists, moondogHeard };
+}
+
+export function mixSlot(track, familiarity) {
+  if (!familiarity) return "unknown";
+  const names = Array.isArray(track?.artists) && track.artists.length ? track.artists : creditNames(track?.artist_credit);
+  let plays = 0;
+  let lastMs = 0;
+  let moondogHeard = false;
+  for (const name of names) {
+    const key = trackMatchKey(track?.title, name);
+    moondogHeard ||= familiarity.moondogHeard?.has(key) === true;
+    const known = familiarity.tracks.get(key);
+    if (!known) continue;
+    plays += known.plays;
+    lastMs = Math.max(lastMs, known.lastMs);
+  }
+  if (plays >= 3) return familiarity.referenceMs - lastMs <= 365 * DAY_MS ? "familiar" : "returning";
+  if (plays > 0 || moondogHeard) return "heard";
+  return names.some((name) => familiarity.artists.has(normalizedArtistName(name))) ? "known_artist" : "new";
+}
+
+/** Counts per slot for a mix line, or null when no song could be placed. */
+export function mixCounts(slots) {
+  if (!slots.some((slot) => MIX_SLOTS.includes(slot))) return null;
+  return Object.fromEntries(MIX_SLOTS.map((slot) => [slot, slots.filter((value) => value === slot).length]));
+}

package/src/profile/music-providers.mjs

@@ -1,8 +1,10 @@
 export const MUSIC_PROVIDER_LABELS = Object.freeze({
   spotify_account_data: "Spotify",
+  spotify_web_api: "Spotify",
   youtube_music: "YouTube Music",
+  lastfm: "Last.fm",
   qq_music: "QQ Music",
-  netease: "NetEase Cloud Music",
+  netease: "NetEase Music",
 });
 
 export function musicProviderLabel(system) {
@@ -10,16 +12,18 @@ export function musicProviderLabel(system) {
 }
 
 export function collectionCoverage(coverage) {
-  const spotify = coverage.collection_sources?.find((source) => source.system === "spotify_account_data");
+  // An export and a live library read are both Spotify; evidence is already deduplicated across them.
+  const spotify = (coverage.collection_sources ?? []).filter((source) => ["spotify_account_data", "spotify_web_api"].includes(source.system));
+  const total = (key) => spotify.reduce((sum, source) => sum + (source[key] ?? 0), 0);
   return {
     collection_tracks: coverage.collection_tracks ?? 0,
     collection_sources: coverage.collection_sources ?? [],
     saved_tracks: coverage.saved_tracks,
     playlist_memberships: coverage.playlist_memberships,
-    spotify_profile_evidence: spotify?.evidence_records ?? 0,
-    spotify_saved_tracks: spotify?.saved_tracks ?? 0,
-    spotify_saved_albums: spotify?.saved_albums ?? 0,
-    spotify_followed_artists: spotify?.followed_artists ?? 0,
-    spotify_playlist_memberships: spotify?.playlist_memberships ?? 0,
+    spotify_profile_evidence: total("evidence_records"),
+    spotify_saved_tracks: total("saved_tracks"),
+    spotify_saved_albums: total("saved_albums"),
+    spotify_followed_artists: total("followed_artists"),
+    spotify_playlist_memberships: total("playlist_memberships"),
   };
 }

package/src/profile/profile-exploration.mjs

@@ -0,0 +1,92 @@
+// The limits below apply to delivery, never to the corpus being analyzed.
+export const PROFILE_SECTIONS = Object.freeze([
+  "overview", "history_artists", "history_tracks", "recent_artists", "recent_tracks",
+  "history_years", "history_releases", "saved_tracks", "playlist_tracks", "saved_albums",
+  "followed_artists", "provider_genres", "listener_preferences", "listener_avoids",
+  "provider_evidence", "apple_tracks", "apple_artists", "apple_genres",
+]);
+
+export const TRAJECTORIES = Object.freeze(["rising", "steady", "fading", "returning", "burst", "unknown"]);
+
+const normalize = (value) => String(value ?? "").normalize("NFKC").toLocaleLowerCase("und");
+
+export function profileExplorationInput(value = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+    Object.keys(value).some((key) => !["section", "query", "offset", "limit", "sort", "trajectory"].includes(key))) {
+    throw new TypeError("Profile exploration arguments are invalid");
+  }
+  const { section = "overview", query = "", offset = 0, limit = 12, sort = "ranked", trajectory } = value;
+  if (!PROFILE_SECTIONS.includes(section) || typeof query !== "string" || query.length > 256 ||
+    !Number.isSafeInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 20 ||
+    !["ranked", "least_played", "recent"].includes(sort) ||
+    (trajectory !== undefined && !TRAJECTORIES.includes(trajectory))) {
+    throw new TypeError("Profile exploration selection is invalid");
+  }
+  if (sort !== "ranked" && !["history_tracks", "history_artists", "recent_tracks", "recent_artists", "apple_tracks"].includes(section)) {
+    throw new TypeError("This profile section supports ranked order only");
+  }
+  if (sort === "recent" && section === "apple_tracks") {
+    throw new TypeError("Apple library play counts have no event chronology");
+  }
+  if (trajectory !== undefined && section !== "history_artists") {
+    throw new TypeError("Only history artists have a trajectory");
+  }
+  return { section, query: query.trim(), offset, limit, sort, ...(trajectory ? { trajectory } : {}) };
+}
+
+export function exploreProfileCatalog({ listening, apple, input }) {
+  const { section, query, offset, limit, sort, trajectory } = profileExplorationInput(input);
+  const catalog = { ...listening?.sections, ...apple?.sections };
+  const all = catalog[section] ?? [];
+  const needle = normalize(query);
+  let matches = all.filter((row) => (!trajectory || row.trajectory === trajectory) && (!needle || [
+    row.name, row.label, row.artist_credit, row.release, row.genre, row.year, row.evidence_kind,
+    row.source_label, row.period, row.text, row.playlist_name, ...(row.playlist_names ?? []),
+  ]
+    .some((text) => normalize(text).includes(needle))));
+  if (sort !== "ranked") {
+    matches = matches.map((row, index) => ({ row, index })).sort((left, right) => {
+      const order = sort === "least_played"
+        ? (left.row.play_count ?? Number.MAX_SAFE_INTEGER) - (right.row.play_count ?? Number.MAX_SAFE_INTEGER)
+        : String(right.row.last_played_at ?? "").localeCompare(String(left.row.last_played_at ?? ""));
+      return order || left.index - right.index;
+    }).map(({ row }) => row);
+  }
+  const items = matches.slice(offset, offset + limit).map((row) => {
+    if (!needle || !row.playlist_names) return row;
+    // Search every membership, and keep matching names in the bounded display.
+    return { ...row, playlist_names: [...row.playlist_names].sort((left, right) =>
+      Number(normalize(right).includes(needle)) - Number(normalize(left).includes(needle))) };
+  });
+  return structuredClone({
+    schema_version: "profile-exploration/1",
+    analysis_scope: "all_retained_supported_data",
+    section,
+    coverage: { ...listening?.coverage, ...apple?.coverage },
+    sources: listening?.sources ?? [],
+    context: listening?.context ?? {},
+    section_note: trajectory
+      ? "Artists with this trajectory label, computed from their share of yearly plays across the retained history. It describes attention over time, not liking."
+      : section.startsWith("recent_")
+      ? "Recent rankings use the retained-history reference date and recent_window_days, not today's date."
+      : section === "history_releases"
+        ? "Release depth includes releases meeting release_minimum_distinct_tracks. It does not prove album completion."
+        : section === "provider_genres"
+          ? "Named provider genre labels only. Unresolved labels remain in provider_evidence."
+          : "Complete selected evidence section, before search and pagination.",
+    sections: Object.entries(catalog).map(([name, rows]) => ({ name, total: rows.length })),
+    total: all.length,
+    matched: matches.length,
+    offset,
+    next_offset: offset + items.length < matches.length ? offset + items.length : null,
+    items,
+    limitations: [
+      "All retained supported records contribute before search, sorting, or pagination. A page is a selection, not the complete profile.",
+      "History describes attention; library membership, saved tracks, ratings, provider labels, and explicit listener choices are separate signals.",
+      "Spotify private-session plays are excluded from behavioral analysis. Superseded export overlaps are not counted again.",
+      "Apple Music is a library snapshot. Its aggregate play counts are not dated plays and must not be added to Spotify event totals.",
+      "Apple preferred-track counts exclude active listener Avoids. Original library membership, ratings, and love states remain visible.",
+      "Provider genre labels describe catalog metadata, not measured sound. Absence from an export is not a dislike.",
+    ],
+  });
+}

package/src/profile/recorded-measures.mjs

@@ -0,0 +1,24 @@
+// Sources record different measures for each play. Spotify's extended history
+// records how long a play lasted and, for most plays, whether it was skipped.
+// Spotify account data records only the length. Last.fm and most ListenBrainz
+// listens record neither, and an Apple library counts plays for some tracks
+// only. A measure that no play recorded is unknown: it never becomes a zero
+// that reads as no listening time, never skipped, or unplayed.
+
+/** Whether all, some or none of `total` items recorded a measure. */
+export function recordedShare(total, recorded, atLeast = 1) {
+  if (recorded >= total * atLeast) return "all";
+  return recorded === 0 ? "none" : "some";
+}
+
+/**
+ * What a set of plays recorded: its listening time and its skips, each "all",
+ * "some" or "none". `timedPlayCount` counts plays with a recorded length, and
+ * `skipKnownCount` counts plays that say whether they were skipped.
+ */
+export function recordedMeasures({ playCount, timedPlayCount, skipKnownCount }) {
+  return {
+    time: recordedShare(playCount, timedPlayCount),
+    skips: recordedShare(playCount, skipKnownCount),
+  };
+}

package/src/profile/spotify-archive-taste.mjs

@@ -235,10 +235,6 @@ export function createSpotifyListeningProfileProjection(listening, options) {
   return createListeningProfileProjection(listening, options);
 }
 
-export function createSpotifyArchiveProfileProjection(listening, options) {
-  return createSpotifyListeningProfileProjection(listening, options);
-}
-
 function validatedArchivePaths(value) {
   if (
     !Array.isArray(value) ||