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

package/src/profile/listening-profile-projection.mjs

@@ -1,3 +1,4 @@
+import { createAvoidGate } from "../core/listener-avoids.mjs";
 import { uuidV5 } from "../core/uuid-v5.mjs";
 import { musicProviderLabel } from "./music-providers.mjs";
 import { recordedMeasures } from "./recorded-measures.mjs";
@@ -26,6 +27,27 @@ const extendedSequenceMinimumPlays = 5;
 const backToBackMinimumConsecutivePlays = 2;
 const backToBackMinimumPlayedMs = 30_000;
 const backToBackMaximumGapMinutes = 30;
+// Movement compares an artist's share of each year's plays, so a year with
+// less listening overall, or fewer records, does not read as fading. Play
+// counts are the measure because every dated play records one.
+const movementMinimumPlays = 20;
+const movementMinimumYears = 3;
+// A year counts only when the history holds this many plays in it.
+const movementMinimumYearPlays = 50;
+// The latest year is read only when the artist has, or at its earlier share
+// would have, this many plays in it, so a few plays more or less, such as in a
+// barely started partial year, cannot swing a label.
+const movementMinimumLatestPlays = 10;
+const movementSeriesYears = 12;
+const movementViewLimit = 5;
+const returningMinimumGapYears = 2;
+const returningMinimumPlays = 3;
+const burstMinimumPeakShare = 0.7;
+// A burst drops off at once: the next counted year holds under a tenth of the
+// peak year's share. A decline that tapers is fading.
+const burstMaximumAfterRatio = 0.1;
+const fadingMaximumRatio = 0.5;
+const risingMinimumRatio = 2;
 const monthlyActivityMaximumMonths = 240;
 const listeningSeasonMaximumSeasons = 80;
 const spotifyExtendedHistorySystem = "spotify-extended-history";
@@ -197,6 +219,10 @@ function trackFields(track) {
       track?.identity_status === "resolved" ? "resolved" : "provisional",
     title,
     artist,
+    // Every credited artist, so an Avoid on a featured artist also keeps the track out.
+    artists: (Array.isArray(track?.artist_credits) ? track.artist_credits : [])
+      .map((credit) => (typeof credit?.name === "string" ? credit.name.trim() : ""))
+      .filter(Boolean),
     artistKnown: Boolean(track?.artist_credits?.[0]?.name?.trim()),
     release,
   };
@@ -275,6 +301,109 @@ function aggregateHistoryArc(rows) {
     });
 }
 
+// Years with plays, oldest first. Years before the most recent twelve roll
+// into one entry so a long history stays small.
+function yearlyPlays(years) {
+  const series = [...years.entries()]
+    .sort(([left], [right]) => left - right)
+    .map(([year, value]) => ({ year, plays: value.playCount }));
+  if (series.length <= movementSeriesYears) return series;
+  const earlier = series.slice(0, -movementSeriesYears);
+  return [
+    {
+      from_year: earlier[0].year,
+      to_year: earlier.at(-1).year,
+      plays: earlier.reduce((sum, item) => sum + item.plays, 0),
+    },
+    ...series.slice(-movementSeriesYears),
+  ];
+}
+
+function meanShare(items) {
+  return items.reduce((sum, item) => sum + item.share, 0) / items.length;
+}
+
+// A deterministic label for how an artist's share of yearly plays moved, from
+// its first year to the latest counted year. Checked in order: returning (at
+// least two counted years with no plays, then back in the latest two), burst
+// (one year that is not the latest holds 70% of the share and the next year
+// drops off at once), then fading or rising (the latest share is at most half,
+// or at least twice, the mean share of the years before it), else steady.
+// Fading also needs the recent window to agree: an artist played again at its
+// earlier share there is returning. Too few plays or years is unknown.
+function artistTrajectory(artist, yearTotals, referenceYear, recentTotal) {
+  const firstYear = Math.min(...artist.years.keys());
+  let counted = [...yearTotals.entries()]
+    .filter(([year, total]) => year >= firstYear && total >= movementMinimumYearPlays)
+    .sort(([left], [right]) => left - right)
+    .map(([year, total]) => {
+      const plays = artist.years.get(year)?.playCount ?? 0;
+      return { year, plays, total, share: plays / total };
+    });
+  const readable = (item, before) =>
+    Math.max(item.plays, meanShare(before) * item.total) >= movementMinimumLatestPlays;
+  if (counted.length > 1 && counted.at(-1).year === referenceYear &&
+    !readable(counted.at(-1), counted.slice(0, -1))) {
+    counted = counted.slice(0, -1);
+  }
+  const plays = counted.reduce((sum, item) => sum + item.plays, 0);
+  if (counted.length < movementMinimumYears || plays < movementMinimumPlays) {
+    return "unknown";
+  }
+  const latest = counted.at(-1);
+  const lastAbsent = counted.slice(0, -1).findLastIndex((item) => item.plays === 0);
+  if (lastAbsent >= 0 && lastAbsent >= counted.length - 3) {
+    let gapStart = lastAbsent;
+    while (gapStart > 0 && counted[gapStart - 1].plays === 0) gapStart -= 1;
+    const returnedPlays = counted
+      .slice(lastAbsent + 1)
+      .reduce((sum, item) => sum + item.plays, 0);
+    if (
+      lastAbsent - gapStart + 1 >= returningMinimumGapYears &&
+      counted.slice(0, gapStart).some((item) => item.plays > 0) &&
+      latest.plays > 0 &&
+      returnedPlays >= returningMinimumPlays
+    ) {
+      return "returning";
+    }
+  }
+  const shareSum = counted.reduce((sum, item) => sum + item.share, 0);
+  const peakIndex = counted.reduce(
+    (best, item, index) => (item.share > counted[best].share ? index : best),
+    0,
+  );
+  const peak = counted[peakIndex];
+  if (
+    peak !== latest &&
+    peak.share >= shareSum * burstMinimumPeakShare &&
+    counted[peakIndex + 1].share < peak.share * burstMaximumAfterRatio
+  ) {
+    return "burst";
+  }
+  const before = counted.slice(0, -1);
+  if (!readable(latest, before)) return "unknown";
+  const beforeShare = meanShare(before);
+  if (latest.share <= beforeShare * fadingMaximumRatio) {
+    const recentShare = recentTotal > 0 ? artist.recentPlayCount / recentTotal : 0;
+    if (
+      artist.recentPlayCount < movementMinimumLatestPlays ||
+      recentShare <= beforeShare * fadingMaximumRatio
+    ) {
+      return "fading";
+    }
+    return recentShare >= beforeShare ? "returning" : "steady";
+  }
+  if (latest.share >= beforeShare * risingMinimumRatio) return "rising";
+  return "steady";
+}
+
+// ACT-R base-level activation at the history's latest play: the log of the
+// summed play ages in days (at least one) to the power -0.5. Recent plays
+// weigh more, and an old archive is read against its own end, not today.
+function activation(sum) {
+  return Math.round(Math.log(sum) * 100) / 100;
+}
+
 function monthIndex(monthKey) {
   if (!/^\d{4}-(?:0[1-9]|1[0-2])$/u.test(monthKey)) return null;
   const year = Number(monthKey.slice(0, 4));
@@ -635,6 +764,7 @@ function aggregateMonthlyActivity(subjectId, eventAnalysis, explanations) {
 
 function aggregateEvents(subjectId, eventRows, explanations) {
   const eligible = [];
+  const moondogStarted = [];
   let incognitoEventsExcluded = 0;
   let rawPlayedMs = 0;
   let eventsWithPlayedDuration = 0;
@@ -648,6 +778,11 @@ function aggregateEvents(subjectId, eventRows, explanations) {
       incognitoEventsExcluded += 1;
       continue;
     }
+    // Moondog chose these, so they are not the listener's own attention.
+    if (row.moondog_suggestion_id) {
+      moondogStarted.push(row);
+      continue;
+    }
     const skipped =
       event?.event_type === "play_skipped" ||
       event?.extensions?.["spotify.skipped"] === true;
@@ -680,6 +815,15 @@ function aggregateEvents(subjectId, eventRows, explanations) {
   const recentCutoff = latest
     ? new Date(Date.parse(latest) - recentWindowDays * dayMs).toISOString()
     : null;
+  const latestMs = latest ? Date.parse(latest) : null;
+  const referenceYear = latest ? Number(latest.slice(0, 4)) : null;
+  const yearTotals = new Map();
+  let recentTotal = 0;
+  for (const row of eligible) {
+    const year = Number(row.event.occurred_at.slice(0, 4));
+    if (Number.isInteger(year)) yearTotals.set(year, (yearTotals.get(year) ?? 0) + 1);
+    if (row.event.occurred_at >= recentCutoff) recentTotal += 1;
+  }
 
   function aggregate(rows, windowKind) {
     const artists = new Map();
@@ -745,8 +889,13 @@ function aggregateEvents(subjectId, eventRows, explanations) {
         years: new Map(),
         firstPlayedAt: occurredAt,
         lastPlayedAt: occurredAt,
+        activationSum: 0,
+        recentPlayCount: 0,
       };
       artist.playCount += 1;
+      if (occurredAt >= recentCutoff) artist.recentPlayCount += 1;
+      artist.activationSum +=
+        Math.max((latestMs - Date.parse(occurredAt)) / dayMs, 1) ** -0.5;
       artist.playedMs += row.playedMs;
       if (row.timed) artist.timedPlayCount += 1;
       if (row.skipKnown) artist.skipKnownCount += 1;
@@ -801,6 +950,14 @@ function aggregateEvents(subjectId, eventRows, explanations) {
           ...recordedMinutes(item),
           distinct_tracks: item.trackRefs.size,
           ...recordedSkips(item),
+          ...(windowKind === "lifetime"
+            ? {
+                first_played_at: item.firstPlayedAt,
+                yearly_plays: yearlyPlays(item.years),
+                activation: activation(item.activationSum),
+                trajectory: artistTrajectory(item, yearTotals, referenceYear, recentTotal),
+              }
+            : {}),
           last_played_at: item.lastPlayedAt,
           evidence_id: evidenceId,
         };
@@ -913,9 +1070,11 @@ function aggregateEvents(subjectId, eventRows, explanations) {
       (row) => row.event.extensions?.["spotify.offline"] === true,
     ).length,
     incognito_events_excluded: incognitoEventsExcluded,
+    ...(moondogStarted.length ? { moondog_started_events_excluded: moondogStarted.length } : {}),
   };
   return {
     eligible,
+    moondogStarted,
     earliest,
     latest,
     recentCutoff,
@@ -1355,11 +1514,9 @@ function backToBackTracks(
     byTrack.set(metadata.trackRefId, aggregate);
   }
 
-  const avoids = combinedAvoids(direct.avoids, evidence.avoids);
+  const avoided = historyAvoidCheck(direct, evidence);
   return [...byTrack.values()]
-    .filter(
-      (item) => !avoids.some((avoid) => assertionMatchesTrack(avoid, item)),
-    )
+    .filter((item) => !avoided(item))
     .sort((left, right) => {
       if (
         right.maximumConsecutivePlays !== left.maximumConsecutivePlays
@@ -1901,6 +2058,13 @@ function combinedAvoids(listenerAvoids, providerAvoids) {
   return [...selected.values()];
 }
 
+// The shared Avoid check of every play path (src/core/listener-avoids.mjs), for history tracks.
+function historyAvoidCheck(direct, evidence) {
+  const gate = createAvoidGate(combinedAvoids(direct.avoids, evidence.avoids));
+  return (track) => gate.size > 0 &&
+    gate.avoidsTrack({ title: track.title, artist_credit: track.artist, artists: track.artists?.length ? track.artists : [track.artist] });
+}
+
 function assertionMatchesTrack(assertion, track) {
   if (assertion.entity_type === "artist") {
     return normalizedText(assertion.label) === normalizedText(track.artist);
@@ -1966,7 +2130,7 @@ function rediscoveryTracks(
 ) {
   const latestMs = Date.parse(eventAnalysis.latest ?? "");
   if (!Number.isFinite(latestMs)) return [];
-  const avoids = combinedAvoids(direct.avoids, evidence.avoids);
+  const avoided = historyAvoidCheck(direct, evidence);
   const candidates = [...eventAnalysis.lifetime.tracks.values()]
     .map((track) => {
       const lastPlayedMs = Date.parse(track.lastPlayedAt);
@@ -1986,7 +2150,7 @@ function rediscoveryTracks(
         track.engagedPlayCount >= rediscoveryMinimumEngagedPlays &&
         (!fullyTimed(track) || track.playedMs >= rediscoveryMinimumPlayedMs) &&
         track.engagedPlayCount >= track.skippedCount &&
-        !avoids.some((item) => assertionMatchesTrack(item, track)),
+        !avoided(track),
     );
   const byTime = candidates.every(({ track }) => fullyTimed(track));
   return candidates
@@ -2081,7 +2245,7 @@ function historicalReturnTracks(
   direct,
   explanations,
 ) {
-  const avoids = combinedAvoids(direct.avoids, evidence.avoids);
+  const avoided = historyAvoidCheck(direct, evidence);
   const candidates = [...eventAnalysis.lifetime.tracks.values()]
     .map((track) => ({
       track,
@@ -2095,7 +2259,7 @@ function historicalReturnTracks(
         track.engagedPlayCount >= historicalReturnMinimumEngagedPlays &&
         (!fullyTimed(track) || track.playedMs >= historicalReturnMinimumPlayedMs) &&
         track.engagedPlayCount >= track.skippedCount &&
-        !avoids.some((item) => assertionMatchesTrack(item, track)),
+        !avoided(track),
     );
   const byTime = candidates.every(({ track }) => fullyTimed(track));
   return candidates
@@ -2200,10 +2364,10 @@ function timeCapsuleTracks(
   explanations,
   maximum,
 ) {
-  const avoids = combinedAvoids(direct.avoids, evidence.avoids);
+  const avoided = historyAvoidCheck(direct, evidence);
   const byYear = new Map();
   for (const track of eventAnalysis.lifetime.tracks.values()) {
-    if (avoids.some((item) => assertionMatchesTrack(item, track))) continue;
+    if (avoided(track)) continue;
     const peak = rediscoveryPeakYear(track);
     if (
       !peak ||
@@ -2305,12 +2469,32 @@ function timeCapsuleTracks(
   });
 }
 
+// Plays Moondog started, one row per song, kept apart from the listener's own rankings.
+// Adopted means the listener later played the song again on their own.
+function moondogSuggestionTracks(rows, adoptedSuggestionIds) {
+  const tracks = new Map();
+  for (const row of rows) {
+    const metadata = trackFields(row.track);
+    const track = tracks.get(metadata.trackRefId) ?? {
+      label: metadata.title, artist_credit: metadata.artist, play_count: 0,
+      last_played_at: row.event.occurred_at, adopted: false,
+    };
+    track.play_count += 1;
+    if (row.event.occurred_at > track.last_played_at) track.last_played_at = row.event.occurred_at;
+    track.adopted ||= adoptedSuggestionIds.has(row.moondog_suggestion_id);
+    tracks.set(metadata.trackRefId, track);
+  }
+  return [...tracks.values()].sort((left, right) => right.play_count - left.play_count ||
+    descendingTimestamp(left.last_played_at, right.last_played_at) || lexicalCompare(left.label, right.label));
+}
+
 export function projectListeningProfile({
   subjectId,
   eventRows = [],
   profileEvidence = [],
   tasteEvents = [],
   maxItems = 10,
+  adoptedSuggestionIds = new Set(),
 } = {}) {
   if (typeof subjectId !== "string" || !subjectId.trim()) {
     throw new TypeError("Listening profile subject ID is required");
@@ -2524,6 +2708,14 @@ export function projectListeningProfile({
         history_arc: events.historyArc,
         monthly_activity: monthlyActivity,
         listening_seasons: listeningSeasons,
+        movement: Object.fromEntries(
+          ["fading", "returning", "rising"].map((label) => [
+            label,
+            events.lifetime.rankedArtists
+              .filter((artist) => artist.trajectory === label)
+              .slice(0, Math.min(maxItems, movementViewLimit)),
+          ]),
+        ),
         artist_relationships: slice(relationships, maxItems),
         year_transitions: slice(transitions, 12),
         release_depth: slice(releases, maxItems),
@@ -2552,6 +2744,10 @@ export function projectListeningProfile({
             timeCapsuleMinimumPlayedMs,
           ),
           relationship_minimum_years: relationshipMinimumYears,
+          movement_minimum_plays: movementMinimumPlays,
+          movement_minimum_years: movementMinimumYears,
+          movement_minimum_year_plays: movementMinimumYearPlays,
+          movement_minimum_latest_plays: movementMinimumLatestPlays,
           continuity_artist_limit: continuityArtistLimit,
           release_minimum_distinct_tracks: releaseMinimumDistinctTracks,
           session_gap_minutes: sessionGapMinutes,
@@ -2649,6 +2845,11 @@ export function projectListeningProfile({
               "Taste Profile, Wrapped, and Sound Capsule are Spotify's reading of you, not something you said.",
             ]
           : []),
+        ...(events.moondogStarted.length > 0
+          ? [
+              "Songs Moondog queued or played for you are left out of the rankings. Playing one again later on your own counts as yours.",
+            ]
+          : []),
         "What you tell Moondog counts for more than what the data suggests, you can undo it any time, and it never rewrites your history.",
       ],
     },
@@ -2668,6 +2869,7 @@ export function projectListeningProfile({
       provider_genres: evidence.genres,
       listener_preferences: direct.preferences,
       listener_avoids: combinedAvoids(direct.avoids, evidence.avoids),
+      ...(events.moondogStarted.length ? { moondog_suggestions: moondogSuggestionTracks(events.moondogStarted, adoptedSuggestionIds) } : {}),
       provider_evidence: deduplicatedEvidence.map((record) => ({
         evidence_id: record.profile_evidence_id,
         evidence_kind: record.evidence_kind,

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/profile-exploration.mjs

@@ -6,17 +6,20 @@ export const PROFILE_SECTIONS = Object.freeze([
   "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"].includes(key))) {
+    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" } = value;
+  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)) {
+    !["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)) {
@@ -25,19 +28,22 @@ export function profileExplorationInput(value = {}) {
   if (sort === "recent" && section === "apple_tracks") {
     throw new TypeError("Apple library play counts have no event chronology");
   }
-  return { section, query: query.trim(), offset, limit, sort };
+  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 } = profileExplorationInput(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) => !needle || [
+  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)));
+    .some((text) => normalize(text).includes(needle))));
   if (sort !== "ranked") {
     matches = matches.map((row, index) => ({ row, index })).sort((left, right) => {
       const order = sort === "least_played"
@@ -59,7 +65,9 @@ export function exploreProfileCatalog({ listening, apple, input }) {
     coverage: { ...listening?.coverage, ...apple?.coverage },
     sources: listening?.sources ?? [],
     context: listening?.context ?? {},
-    section_note: section.startsWith("recent_")
+    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."