@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/profile/history-import.mjs

@@ -6,28 +6,58 @@ import { fileURLToPath } from "node:url";
 import { readSpotifyHistoryArchive } from "../integrations/spotify/history-archive.mjs";
 import { readListenBrainzHistoryFile } from "../integrations/listenbrainz/history-file.mjs";
 import { projectSpotifyRecentActivity } from "../integrations/spotify/recent-activity.mjs";
+import { projectSpotifyLibrarySnapshot } from "../integrations/spotify/library-snapshot.mjs";
 import { buildAppleMusicLibraryImport } from "../importers/apple-music-library/index.mjs";
 import { readYouTubeMusicTakeout } from "../integrations/youtube-music/takeout.mjs";
 import { readPublicPlaylist } from "../integrations/public-playlists.mjs";
+import { readLastfmHistory } from "../integrations/lastfm/history.mjs";
 
-export function prepareSpotifyRecentImport({ page, subjectId, capturedAt = new Date().toISOString() }) {
+/**
+ * Spotify quick start: the latest plays plus the listener's library (saves,
+ * follows, own playlists and Spotify's top artists and tracks) in one preview.
+ * The library is optional so an older recent-plays-only sign-in still works.
+ */
+export function prepareSpotifyQuickImport({ page, librarySnapshot = null, libraryUnavailable = null, subjectId, capturedAt = new Date().toISOString() }) {
   const bundle = projectSpotifyRecentActivity({ page, subjectId, capturedAt });
+  const library = librarySnapshot ? projectSpotifyLibrarySnapshot({ subjectId, snapshot: librarySnapshot, capturedAt }) : null;
   const dates = bundle.listening_events.map((event) => event.occurred_at).sort();
   return {
-    provider: "spotify-recent",
+    provider: "spotify-quick",
     bundle,
+    libraryBundle: library?.bundle ?? null,
     preview: {
-      sourceLabel: "Spotify recent listening",
+      kind: "spotify-quick",
+      source: library ? "spotify-quick-library" : "spotify-quick-recent",
+      sourceLabel: library ? "Your Spotify library and recent plays" : "Spotify recent listening",
+      capturedAt,
       listeningEvents: bundle.listening_events.length,
-      tracks: bundle.track_refs.length,
+      tracks: new Set([...bundle.track_refs, ...(library?.bundle.track_refs ?? [])].map((ref) => ref.track_ref_id)).size,
       earliestListeningAt: dates[0],
       latestListeningAt: dates.at(-1),
       eventsWithPlayedMs: 0,
-      scopeNote: "Your latest plays, up to 50. Spotify doesn't say how long you listened here. A history ZIP can add the older ones later.",
+      ...(library ? { library: library.preview } : {}),
+      ...(libraryUnavailable ? { libraryUnavailable } : {}),
+      scopeNote: library
+        ? "Your library shows what you keep and what Spotify ranks highest for you. Recent plays are your latest 50. A history ZIP can add years of listening later."
+        : "Your latest plays, up to 50. Spotify doesn't say how long you listened here. A history ZIP can add the older ones later.",
     },
   };
 }
 
+/** Save both parts of an inspected quick import; returns one combined receipt. */
+// Both writes are idempotent, so retrying after a partial failure is safe.
+export function commitSpotifyQuickImport(store, prepared) {
+  const library = prepared.libraryBundle ? store.ingestImport(prepared.libraryBundle) : null;
+  const recent = store.ingest(prepared.bundle);
+  if (!library) return { ...recent, provider: "spotify-quick" };
+  return {
+    ...recent, provider: "spotify-quick",
+    inserted_track_refs: (recent.inserted_track_refs ?? 0) + (library.inserted_track_refs ?? 0),
+    inserted_profile_evidence: library.inserted_profile_evidence ?? 0,
+    library_already_imported: library.already_imported === true,
+  };
+}
+
 function fail(code, message) {
   const error = new Error(message);
   error.code = code;
@@ -85,7 +115,11 @@ function literalPath(input) {
   return path.resolve(decoded);
 }
 
-export async function prepareHistoryImport({ filePath, subjectId, provider: selectedProvider, capturedAt = new Date().toISOString(), fetchImpl } = {}) {
+export async function prepareHistoryImport({ filePath, subjectId, provider: selectedProvider, capturedAt = new Date().toISOString(), fetchImpl, onProgress, signal } = {}) {
+  // Last.fm is read by username (or profile link) rather than from a file.
+  if (selectedProvider === "lastfm") {
+    return readLastfmHistory({ username: filePath, subjectId, capturedAt, onProgress, signal, ...(fetchImpl ? { fetchImpl } : {}) });
+  }
   if (/https?:\/\//iu.test(filePath ?? "") && !String(filePath).startsWith("file:")) {
     return readPublicPlaylist({ input: filePath, subjectId, capturedAt, provider: selectedProvider, fetchImpl });
   }
@@ -115,6 +149,7 @@ export async function prepareHistoryImport({ filePath, subjectId, provider: sele
       bundle,
       preview: {
         kind: "library",
+        source: "apple-library",
         sourceLabel: "Apple Music library",
         fileName: path.basename(resolvedPath),
         tracks: bundle.trackRefs.length,
@@ -143,6 +178,7 @@ export async function prepareHistoryImport({ filePath, subjectId, provider: sele
     provider,
     bundle,
     preview: {
+      source: provider === "listenbrainz" ? "listenbrainz" : extended ? "spotify-extended" : "spotify-account",
       sourceLabel: provider === "listenbrainz" ? "ListenBrainz history" : extended ? "Spotify Extended Streaming History" : "Spotify Account Data",
       fileName: path.basename(resolvedPath),
       sourceFormat: bundle.import_batch.source_format,

package/src/profile/listener-corrections.mjs

@@ -194,6 +194,28 @@ export function createListenerCorrectionRetraction({
   };
 }
 
+/**
+ * Records a Like or Avoid the way the profile command does, or retracts the active choice for
+ * the same artist or track. A retraction with no such choice changes nothing.
+ */
+export function recordListenerChoice(store, {
+  subjectId, entityType, label, artistCredit, stance, occurredAt = new Date().toISOString(),
+} = {}) {
+  if (stance !== "retract") {
+    return store.recordListenerCorrection({ subjectId, entityType, label, artistCredit, stance, occurredAt, recordedAt: occurredAt });
+  }
+  const key = (value) => typeof value === "string" ? normalizedIdentity(value.replace(/\s+/gu, " ").trim()) : "";
+  const active = store.listListenerCorrections({ subjectId, limit: 100 }).find((choice) =>
+    choice.entity_type === entityType && key(choice.label) === key(label) &&
+    (entityType !== "track" || key(choice.artist_credit) === key(artistCredit)));
+  if (!active) return { state: "not_found", entity_type: entityType, label };
+  return {
+    ...store.retractListenerCorrection({ subjectId, correctionId: active.correction_id, occurredAt, recordedAt: occurredAt }),
+    stance: active.stance,
+    ...(active.artist_credit ? { artist_credit: active.artist_credit } : {}),
+  };
+}
+
 export function listenerCorrectionTargetKey(record) {
   if (
     !record ||

package/src/profile/listener-profile-build.mjs

@@ -0,0 +1,461 @@
+import { createHash } from "node:crypto";
+
+import { avoidKey } from "../core/listener-avoids.mjs";
+import { recordedShare } from "./recorded-measures.mjs";
+
+export const LISTENER_PROFILE_ANALYSIS_VERSION = "listener-profile/2";
+export const LISTENER_PROFILE_SYNTHESIS_VERSION = "listener-synthesis/5";
+// A saved reading is current only after its whole-profile check has run.
+export const CHECKED_PROFILE_STATES = new Set(["passed", "revised", "flagged"]);
+
+const LISTENER_SECTIONS = new Set(["listener_preferences", "listener_avoids"]);
+// Curation already appears in its own sections; these provider rows only repeat it.
+const SPOTIFY_TOP_KINDS = new Set(["top_artist_ranked", "top_track_ranked"]);
+const DUPLICATED_PROVIDER_KINDS = new Set([
+  "playlist_track_added", "library_track_saved", "library_album_saved", "library_artist_followed",
+]);
+
+const RANKED_LISTENING_SECTIONS = new Set(["history_artists", "history_tracks", "recent_artists", "recent_tracks"]);
+const PLAY_COUNT_SECTIONS = new Set([...RANKED_LISTENING_SECTIONS, "history_releases"]);
+// Below this share of plays with a recorded duration, minutes can't compare artists, years or
+// sources (Last.fm and many ListenBrainz files record none), so the build compares by plays.
+const TIMED_PLAY_SHARE = 0.95;
+
+function measurement(listening) {
+  const plays = listening?.coverage?.effective_listening_events ?? 0;
+  const timed = listening?.coverage?.events_with_played_duration;
+  const time = timed === undefined ? "all" : recordedShare(plays, timed, TIMED_PLAY_SHARE);
+  // Listening rows state skips only where some play recorded them, so no row with skips means
+  // no play in the history recorded one.
+  const rows = Object.entries(listening?.sections ?? {})
+    .filter(([section]) => RANKED_LISTENING_SECTIONS.has(section)).flatMap(([, rows]) => rows);
+  const unskipped = rows.length > 0 && !rows.some(row => row.explicit_skips !== undefined);
+  return { plays, timed, time, unskipped };
+}
+
+const without = (row, keys) => Object.fromEntries(Object.entries(row).filter(([key]) => !keys.includes(key)));
+
+// Listening rows already leave out what their plays never recorded. Here a row also drops minutes
+// that can't compare it with others, and an Apple facet drops a play count none of its tracks
+// carry. Rows that lose a measure are marked, because the host's prose explanations still state it.
+function measuredRows(section, rows, { time }, withheld) {
+  const unrecordedKeys = row => section.startsWith("apple_")
+    ? (recordedShare(row.library_tracks, row.tracks_with_play_count) === "none" ? ["play_count"] : [])
+    : time !== "all" ? ["listening_minutes"] : [];
+  const next = rows.map(row => {
+    const keys = unrecordedKeys(row).filter(key => key in row);
+    const topArtist = time !== "all" && row.top_artist && "listening_minutes" in row.top_artist;
+    if (!keys.length && !topArtist) return row;
+    const measured = { ...without(row, keys), ...(topArtist ? { top_artist: without(row.top_artist, ["listening_minutes"]) } : {}) };
+    withheld.add(measured);
+    return measured;
+  });
+  if (time === "all" || !PLAY_COUNT_SECTIONS.has(section)) return next;
+  // A row without skip data counts every play as engaged.
+  const engaged = row => row.engaged_play_count ?? row.play_count ?? 0;
+  return next.sort((left, right) => engaged(right) - engaged(left) || (right.play_count ?? 0) - (left.play_count ?? 0));
+}
+
+function sectionSemantics(section, { time = "all" } = {}) {
+  const common = {
+    ordering: "Catalog order, not chronology or preference strength unless explicitly stated.",
+    limitations: "Row position and repeated rows are not independent evidence of importance. Use the row's dated fields for time claims.",
+  };
+  if (RANKED_LISTENING_SECTIONS.has(section)) {
+    return { ordering: time === "all" ? "Ranked by measured listening duration, descending."
+      : "Ranked by plays, descending, because listening time is not known for every play.",
+      limitations: "Attention in the imported history is not a direct statement of liking. Recent and lifetime views overlap; do not add their totals." };
+  }
+  if (section === "history_years") return { ...common,
+    ordering: time === "all" ? "top_artist is selected by measured listening duration, not play count. Row position is not a preference ranking."
+      : "top_artist is selected by measured listening duration where the year records it, otherwise by plays. Row position is not a preference ranking.",
+    limitations: "Years have unequal coverage. Sparse or missing imported records do not establish a gap in the listener's actual listening." };
+  if (section === "saved_tracks") return {
+    ordering: time === "all" ? "Measured listening duration descending, then playlist membership count descending, then title."
+      : "Not a preference ranking; listening time is not known for every play.",
+    limitations: "Row order is not save or addition chronology. Missing listening minutes mean no matched duration in this import, not proof the listener never played a saved track.",
+  };
+  if (section === "moondog_suggestions") return {
+    ordering: "Plays descending, then most recent.",
+    limitations: "Moondog queued or played these, so they are left out of every listening ranking and are not the listener's taste. adopted means the listener later played the song again on their own, which is a reaction to a suggestion, not a preference by itself.",
+  };
+  if (section === "playlist_tracks") return { ...common,
+    ordering: "Playlist membership count descending, then measured listening duration descending, then title." };
+  if (section.startsWith("apple_")) return {
+    ordering: section === "apple_tracks" ? "Imported preference strength descending, then snapshot play count descending, then internal stable identity."
+      : "Imported preference strength descending, then library track count descending, then name.",
+    limitations: "A library snapshot is not dated listening history or addition chronology. Missing play counts are unknown, not zero; aggregate counts cover only tracks_with_play_count. Versions and reissues are not independent evidence of attachment.",
+  };
+  return common;
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort()
+    .filter(key => value[key] !== undefined).map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+export function profileDigest(value) {
+  return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function text(value, maximum, field) {
+  if (typeof value !== "string" || !value.trim() || Array.from(value).length > maximum ||
+      /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f‪-‮⁦-⁩]/u.test(value)) {
+    throw new TypeError(`Listener profile ${field} is invalid`);
+  }
+  return value.trim();
+}
+
+export function createListenerProfileInput({ subjectId, evidenceRevision, listening, apple }) {
+  const measured = measurement(listening);
+  const withheld = new Set();
+  const sections = Object.fromEntries(Object.entries({ ...listening?.sections, ...apple?.sections })
+    .map(([section, rows]) => [section, measuredRows(section, rows, measured, withheld)]));
+  const context = listening?.context ?? {};
+  const coverage = { ...listening?.coverage, ...apple?.coverage };
+  const evidence = new Map();
+  const unrecorded = new Set();
+  for (const [section, rows] of Object.entries(sections).sort(([a], [b]) => a.localeCompare(b))) {
+    for (const row of rows) {
+      const reference_id = `ev_${profileDigest([section, row]).slice(0, 32)}`;
+      evidence.set(reference_id, { reference_id, section, data: structuredClone(row) });
+      if (withheld.has(row)) unrecorded.add(reference_id);
+    }
+  }
+  const manifest = {
+    analysis_version: LISTENER_PROFILE_ANALYSIS_VERSION,
+    coverage,
+    sources: listening?.sources ?? [], context,
+    sections: Object.entries(sections).map(([section, rows]) => ({ section, rows: rows.length, ...sectionSemantics(section, measured) })),
+    evidence_rows: evidence.size,
+    limitations: [
+      "Every supported record contributes to local analysis before the dossier selects rows. Rows are aggregates or observations, not a count of distinct plays.",
+      "History measures attention. Apple snapshot counts are separate from dated plays; private-session plays and superseded overlaps do not become behavioral evidence.",
+      "Provider labels are not listener assertions or measured audio features.",
+      ...(measured.time === "none" ? ["No play in this history records how long it lasted, so listening time is unknown, not zero; rows rank by plays."] : []),
+      ...(measured.time === "some" ? [`Listening time is known for only ${measured.timed} of ${measured.plays} plays, so minutes and hours cannot compare artists, years or sources; rows rank by plays, and coverage.listening_hours covers only the timed plays.`] : []),
+      ...(measured.unskipped ? ["No play in this history is marked as skipped. These sources may not record skips, so skips and engaged plays are unknown, and having no skips says nothing about approval."] : []),
+    ],
+  };
+  // Rows are content-addressed, so the ordered references cover every evidence value.
+  const input_digest = profileDigest({ subjectId, evidenceRevision, manifest, evidence: [...evidence.keys()] });
+  // Unrecorded measures change the evidence rows, so the digest already covers this set.
+  return { subjectId, input_digest, manifest, evidence, unrecorded };
+}
+
+export function modelEvidence(entry, offset = 0, limit = 12) {
+  // Only music observations cross the model boundary. Local identities and
+  // provider handles remain in the private frozen evidence snapshot.
+  const fields = new Set([
+    "name", "label", "title", "artist_credit", "release", "genre", "entity_type", "stance", "asserted_at",
+    "first_played_at", "last_played_at", "source_label", "identity_status", "evidence_kind", "period",
+    "text", "playlist_name", "unit", "observed_at", "last_added_at", "play_count", "engaged_play_count",
+    "explicit_skips", "listening_minutes", "distinct_tracks", "year", "event_count", "first_observed_tracks",
+    "playlist_count", "library_tracks", "preferred_tracks", "tracks_with_play_count", "preference_strength",
+    "loved", "favorited", "rating_value", "rating_computed", "rank", "playlist_position", "value",
+    "stream_count", "played_seconds", "playlist_names", "top_artist", "first_year", "last_year", "active_years", "adopted",
+    "yearly_plays", "activation", "trajectory",
+  ]);
+  const data = Object.fromEntries(Object.entries(entry.data).filter(([key]) => fields.has(key)));
+  if (data.top_artist) data.top_artist = Object.fromEntries(Object.entries(data.top_artist)
+    .filter(([key]) => ["name", "play_count", "listening_minutes"].includes(key)));
+  const continuations = {};
+  for (const [key, value] of Object.entries(data)) {
+    // A yearly series is already capped, and a page of it would hide the latest years.
+    if (Array.isArray(value) && key !== "yearly_plays") {
+      data[key] = value.slice(offset, offset + limit);
+      if (value.length > offset + limit) continuations[key] = { total: value.length, next_offset: offset + limit };
+    }
+  }
+  return { ...entry, data, ...(Object.keys(continuations).length ? { continuations } : {}) };
+}
+
+const artistKey = value => typeof value === "string" ? value.normalize("NFKC").trim().toLocaleLowerCase() : null;
+
+/**
+ * A compact, deterministic view of the complete evidence for one synthesis
+ * session. Every row keeps its reference so the model can cite it; the full
+ * catalog stays searchable for anything the dossier leaves out.
+ */
+export function listenerProfileDossier(input) {
+  const rows = section => [...input.evidence.values()].filter(entry => entry.section === section);
+  const row = entry => ({ ref: entry.reference_id, ...modelEvidence(entry, 0, 6).data });
+  const take = (section, limit) => rows(section).slice(0, limit).map(row);
+  const lifetime = rows("history_artists");
+  const lifetimeRank = new Map(lifetime.map((entry, index) => [artistKey(entry.data.name), index + 1]));
+  const listened = new Set(lifetime.slice(0, 80).map(entry => artistKey(entry.data.name)));
+  const curated = new Map();
+  const curate = (name, entry, signal) => {
+    const key = artistKey(name);
+    if (!key || listened.has(key)) return;
+    const item = curated.get(key) ?? { artist: name, signals: [], refs: [] };
+    if (item.refs.length < 4) item.refs.push(entry.reference_id);
+    item.signals.push(signal);
+    curated.set(key, item);
+  };
+  for (const entry of rows("followed_artists")) curate(entry.data.name, entry, "followed");
+  for (const entry of rows("saved_albums")) curate(entry.data.artist_credit, entry, `saved album ${entry.data.label}`);
+  for (const entry of rows("apple_artists")) {
+    if ((entry.data.preferred_tracks ?? 0) >= 2 || (entry.data.library_tracks ?? 0) >= 20) {
+      curate(entry.data.name, entry, `Apple library: ${entry.data.library_tracks} tracks, ${entry.data.preferred_tracks ?? 0} preferred`);
+    }
+  }
+  for (const entry of rows("playlist_tracks").slice(0, 300)) curate(entry.data.artist_credit, entry, `playlist track ${entry.data.label}`);
+  const provider = rows("provider_evidence").filter(entry => !DUPLICATED_PROVIDER_KINDS.has(entry.data.evidence_kind) && !SPOTIFY_TOP_KINDS.has(entry.data.evidence_kind));
+  // Spotify ranks the same names across three periods; one row per name keeps them comparable.
+  const spotifyTop = (kind, limit) => {
+    const grouped = new Map();
+    for (const entry of rows("provider_evidence").filter(entry => entry.data.evidence_kind === kind)) {
+      const key = artistKey(`${entry.data.label}\0${entry.data.artist_credit ?? ""}`);
+      const item = grouped.get(key) ?? { ref: entry.reference_id, label: entry.data.label,
+        ...(entry.data.artist_credit ? { artist_credit: entry.data.artist_credit } : {}), ranks: {}, best: Infinity };
+      item.ranks[entry.data.period] = entry.data.rank;
+      if (entry.data.rank < item.best) Object.assign(item, { best: entry.data.rank, ref: entry.reference_id });
+      grouped.set(key, item);
+    }
+    return [...grouped.values()].sort((a, b) => a.best - b.best || Object.keys(b.ranks).length - Object.keys(a.ranks).length)
+      .slice(0, limit).map(({ best: _best, ...item }) => item);
+  };
+  const sections = Object.fromEntries(input.manifest.sections.map(({ section, rows: total, ordering, limitations }) =>
+    [section, { total, ordering, limitations }]));
+  return {
+    coverage: input.manifest.coverage, sources: input.manifest.sources, context: input.manifest.context,
+    sections,
+    lifetime_artists: lifetime.slice(0, 40).map(row),
+    next_lifetime_artists: lifetime.slice(40, 80).map(entry => ({ ref: entry.reference_id, name: entry.data.name,
+      listening_minutes: entry.data.listening_minutes, play_count: entry.data.play_count, distinct_tracks: entry.data.distinct_tracks,
+      trajectory: entry.data.trajectory })),
+    movement: {
+      note: "Trajectory labels are computed from each artist's share of yearly plays: fading and rising compare the latest counted year with the years before it, returning means whole years without plays, or a decline, and then plays again, burst means one earlier year holds most of the plays and the next year drops off at once. They describe attention over time, not liking.",
+      ...Object.fromEntries(["fading", "returning", "rising", "burst"].map(label => [label, lifetime
+        .filter(entry => entry.data.trajectory === label).slice(0, 12)
+        .map(entry => ({ ref: entry.reference_id, name: entry.data.name, play_count: entry.data.play_count,
+          first_played_at: entry.data.first_played_at, last_played_at: entry.data.last_played_at,
+          yearly_plays: entry.data.yearly_plays }))])),
+    },
+    recent_artists: rows("recent_artists").slice(0, 25).map(entry => ({ ...row(entry),
+      lifetime_rank: lifetimeRank.get(artistKey(entry.data.name)) ?? null })),
+    years: take("history_years", 64),
+    lifetime_tracks: take("history_tracks", 25),
+    recent_tracks: take("recent_tracks", 15),
+    releases_in_depth: take("history_releases", 15),
+    curated_beyond_listening: [...curated.values()].sort((a, b) => b.signals.length - a.signals.length).slice(0, 20)
+      .map(item => ({ ...item, signals: item.signals.slice(0, 4) })),
+    saved_albums: take("saved_albums", 20),
+    saved_tracks: take("saved_tracks", 15),
+    playlist_tracks: take("playlist_tracks", 15),
+    followed_artists: rows("followed_artists").map(entry => ({ ref: entry.reference_id, name: entry.data.name,
+      listening_minutes: entry.data.listening_minutes ?? null })),
+    apple_artists: take("apple_artists", 20),
+    apple_genres: take("apple_genres", 20),
+    apple_tracks: take("apple_tracks", 15),
+    provider_genres: take("provider_genres", 15),
+    spotify_top: {
+      note: "Spotify's own affinity ranks (1 is highest) for the last four weeks, six months and about a year, read from the live account. Short-term ranks reflect recent attention; ranks held across all periods suggest something more enduring. Not play counts.",
+      artists: spotifyTop("top_artist_ranked", 40),
+      tracks: spotifyTop("top_track_ranked", 25),
+    },
+    provider_signals: provider.slice(0, 50).map(row),
+    explicit_choices: [...rows("listener_preferences"), ...rows("listener_avoids")].slice(0, 100).map(row),
+    ...(rows("moondog_suggestions").length ? { played_from_moondog: {
+      note: "Plays Moondog itself queued or played. They are not in any ranking above and are not taste. adopted means the listener played the song again later on their own.",
+      plays: input.manifest.context.moondog_started_events_excluded ?? null,
+      tracks: rows("moondog_suggestions").length,
+      adopted_tracks: rows("moondog_suggestions").filter(entry => entry.data.adopted === true).length,
+      examples: take("moondog_suggestions", 8),
+    } } : {}),
+  };
+}
+
+function validateClaim(input, raw) {
+  if (!["observation", "hypothesis"].includes(raw?.kind)) {
+    throw new TypeError("Only the listener can establish a direct preference");
+  }
+  const references = (values, minimum, role) => {
+    if (!Array.isArray(values) || values.length < minimum || values.length > 8 || new Set(values).size !== values.length) {
+      throw new TypeError(`Listener profile evidence reference is invalid: ${role} needs ${minimum} to 8 unique references`);
+    }
+    const unknown = values.filter(id => !input.evidence.has(id));
+    if (unknown.length) throw new TypeError(`Listener profile evidence reference is invalid: ${role} contains unknown IDs ${JSON.stringify(unknown)}. Copy exact refs from the dossier or the evidence tools.`);
+    return [...values];
+  };
+  const supporting_refs = references(raw.supporting_refs, 1, "supporting_refs");
+  const contradicting_refs = references(raw.contradicting_refs ?? [], 0, "contradicting_refs");
+  if (contradicting_refs.some(id => supporting_refs.includes(id))) throw new TypeError("Supporting and conflicting evidence must differ");
+  const claim = {
+    kind: raw.kind, statement: text(raw.statement, 700, "statement"),
+    scope: text(raw.scope, 300, "scope"), uncertainty: text(raw.uncertainty, 500, "uncertainty"),
+    supporting_refs, contradicting_refs,
+  };
+  return { claim_id: `claim_${profileDigest(claim).slice(0, 32)}`, ...claim };
+}
+
+/** Direct choices come from the listener's own records, never from the model. */
+export function listenerAssertionClaims(input) {
+  return [...input.evidence.values()].filter(entry => LISTENER_SECTIONS.has(entry.section)).map(({ reference_id, section, data }) => {
+    const stance = section === "listener_avoids" ? "avoid" : "like";
+    const direct = Boolean(data.correction_id);
+    const claim = {
+      kind: direct ? "listener_assertion" : "observation",
+      statement: `${data.label ?? data.name}${data.artist_credit ? ` by ${data.artist_credit}` : ""}: ${stance === "avoid" ? "keep out of suggestions" : "explicit positive choice"}.`,
+      scope: data.entity_type ?? "listener choice",
+      uncertainty: direct ? "An explicit listener choice; it does not rewrite past listening."
+        : "An exclusion or choice in imported source data; it is not a new statement by the listener.",
+      stance, supporting_refs: [reference_id], contradicting_refs: [],
+    };
+    return { claim_id: `claim_${profileDigest(claim).slice(0, 32)}`, ...claim };
+  });
+}
+
+export function compileListenerProfile(input, submission) {
+  const needsInsights = [...input.evidence.values()].some(entry => !LISTENER_SECTIONS.has(entry.section));
+  if (!Array.isArray(submission?.insights) || submission.insights.length > 12 || (needsInsights && !submission.insights.length)) {
+    throw new TypeError("Listener profile synthesis needs one to twelve evidence-linked insights");
+  }
+  const insights = submission.insights.map(raw => validateClaim(input, raw));
+  const claims = [...new Map([...insights, ...listenerAssertionClaims(input)].map(claim => [claim.claim_id, claim])).values()];
+  const referenced = new Set(claims.flatMap(claim => [...claim.supporting_refs, ...claim.contradicting_refs]));
+  return {
+    analysis_version: LISTENER_PROFILE_ANALYSIS_VERSION,
+    synthesis_version: LISTENER_PROFILE_SYNTHESIS_VERSION,
+    input_digest: input.input_digest,
+    summary: text(submission.summary, 1_600, "summary"),
+    coverage: input.manifest,
+    claims, highlight_claim_ids: [...new Set(insights.map(claim => claim.claim_id))],
+    evidence: Object.fromEntries([...referenced].map(id => [id, input.evidence.get(id)])),
+  };
+}
+
+// Whether two evidence maps hold the same Likes and Avoids. New plays change neither.
+export function sameListenerChoices(evidence, otherEvidence) {
+  const choices = (entries) => listenerAssertionClaims({ evidence: entries }).map(claim => claim.claim_id).sort().join("\n");
+  return choices(evidence) === choices(otherEvidence);
+}
+
+const CHOICES_SHOWN = 30;
+
+// A choice as the model reads it: no correction or evidence IDs.
+function choiceItems(evidence) {
+  return [...evidence.values()].filter(entry => LISTENER_SECTIONS.has(entry.section)).map(({ section, data }) => ({
+    key: [section, data.entity_type, avoidKey(data.label ?? data.name), avoidKey(data.artist_credit)].join("\0"),
+    choice: {
+      stance: section === "listener_avoids" ? "avoid" : "like",
+      subject: data.entity_type ?? "artist", name: data.label ?? data.name,
+      ...(data.artist_credit ? { artist: data.artist_credit } : {}),
+      ...(data.asserted_at ? { chosen_at: data.asserted_at } : {}),
+      ...(data.correction_id ? {} : { from_import: true }),
+    },
+  }));
+}
+
+// The listener's choices now, newest first, and how they differ from the ones a reading was built with.
+function listenerChoices(current, previous) {
+  const now = choiceItems(current);
+  const then = choiceItems(previous);
+  const direct = now.filter(item => !item.choice.from_import)
+    .sort((left, right) => (right.choice.chosen_at ?? "").localeCompare(left.choice.chosen_at ?? ""));
+  const missing = (items, others) => {
+    const keys = new Set(others.map(item => item.key));
+    return items.filter(item => !keys.has(item.key)).slice(0, CHOICES_SHOWN).map(item => item.choice);
+  };
+  return {
+    listener_choices: { total: direct.length, items: direct.slice(0, CHOICES_SHOWN).map(item => item.choice) },
+    choices_since_reading: { added: missing(now, then), retracted: missing(then, now) },
+  };
+}
+
+// The listener's current choices read straight from their saved corrections, newest first, for
+// when there is no saved reading to compare them with.
+export function savedListenerChoices(corrections, total) {
+  return {
+    total,
+    items: corrections.slice(0, CHOICES_SHOWN).map(choice => ({
+      stance: choice.stance, subject: choice.entity_type, name: choice.label,
+      ...(choice.artist_credit ? { artist: choice.artist_credit } : {}),
+      ...(choice.occurred_at ? { chosen_at: choice.occurred_at } : {}),
+    })),
+  };
+}
+
+export function readListenerProfile({ input, getInput, store, getChoices }, { offset = 0, limit = 12, claimId, revisionId } = {}) {
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 20) {
+    throw new TypeError("Saved profile page is invalid");
+  }
+  const current = store.current();
+  const revision = revisionId ? store.revision(revisionId) : current;
+  if (revisionId && !revision) throw new Error("That saved profile version is unavailable");
+  if (!revision) {
+    const choices = getChoices?.();
+    return { state: "missing", total_claims: 0, claims: [], next_offset: null, ...(choices ? { listener_choices: choices } : {}) };
+  }
+  // Most new listeners have no saved reading. Do not scan their source archive
+  // merely to tell an ordinary conversation that the reading is missing.
+  input ??= getInput();
+  const analysisHolds = revision.synthesis_version === LISTENER_PROFILE_SYNTHESIS_VERSION &&
+    CHECKED_PROFILE_STATES.has(revision.verification?.state);
+  const state = analysisHolds && revision.input_digest === input.input_digest ? "current" : "stale";
+  const result = {
+    state,
+    // New plays alone change the input. A reading whose analysis and listener choices
+    // still hold stays usable as taste up to the listening it was built from.
+    ...(state === "stale" && analysisHolds && sameListenerChoices(new Map(Object.entries(revision.evidence ?? {})), input.evidence)
+      ? { newer_listening_only: true } : {}),
+    revision_id: revision.revision_id, sequence: revision.sequence,
+    parent_revision_id: revision.parent_revision_id, built_at: revision.built_at, model: revision.model,
+    synthesis_version: revision.synthesis_version,
+    verification: revision.verification,
+    summary: revision.summary, coverage: revision.coverage,
+    total_claims: revision.claims.length,
+    claims: revision.claims.slice(offset, offset + limit), offset,
+    next_offset: offset + limit < revision.claims.length ? offset + limit : null,
+    highlights: revision.highlight_claim_ids.map(id => {
+      const index = revision.claims.findIndex(claim => claim.claim_id === id);
+      return { ...revision.claims[index], finding_number: index + 1 };
+    }),
+    listener_assertions: revision.claims.flatMap((claim, index) => claim.kind === "listener_assertion"
+      ? [{ ...claim, finding_number: index + 1 }] : []),
+    ...listenerChoices(input.evidence ?? new Map(), new Map(Object.entries(revision.evidence ?? {}))),
+  };
+  if (claimId !== undefined) {
+    const claim = revision.claims.find(item => item.claim_id === claimId);
+    if (!claim) throw new Error("That finding is not part of this saved profile");
+    result.claim = claim;
+    result.supporting_evidence = claim.supporting_refs.map(ref => modelEvidence(revision.evidence[ref]));
+    result.contradicting_evidence = claim.contradicting_refs.map(ref => modelEvidence(revision.evidence[ref]));
+  }
+  return result;
+}
+
+export function compactListenerProfile(value) {
+  // With no reading, the listener's own choices still hold.
+  if (!value || value.state === "missing") {
+    return { state: "missing", ...(value?.listener_choices?.total ? { listener_choices: value.listener_choices } : {}) };
+  }
+  const coverage = value.coverage?.coverage ?? {};
+  const flagged = value.verification?.state === "flagged"
+    ? value.verification.checks.at(-1).issues.slice(0, 3).map(issue => issue.problem) : [];
+  const behind = value.state === "stale" && value.newer_listening_only === true;
+  // A stale reading still shows what it said, marked as the previous one, under the current choices.
+  const previous = value.state === "stale" && !behind && typeof value.summary === "string";
+  const since = value.choices_since_reading;
+  return {
+    state: behind ? "current_through" : value.state, revision_id: value.revision_id, sequence: value.sequence, built_at: value.built_at,
+    ...(value.state === "current" || behind || previous ? {
+      ...(behind ? { note: "Built from listening up to coverage.last_played_at. Plays stored since then are not in this reading; listening coverage shows them. Listener choices and analysis are unchanged." } : {}),
+      ...(previous ? { previous_reading: true,
+        note: "The previous reading. It predates listener_choices and choices_since_reading, or the analysis has changed since. Use it only as background: where they differ, the listener's choices win. Update the reading before treating it as current taste." } : {}),
+      summary: value.summary,
+      claims: value.highlights,
+      // A previous reading's own choices may be out of date; listener_choices holds the current ones.
+      ...(previous ? {} : { listener_assertions: value.listener_assertions }),
+      coverage: { listening_events: coverage.effective_listening_events ?? null,
+        first_played_at: coverage.earliest_played_at ?? null, last_played_at: coverage.latest_played_at ?? null,
+        library_tracks: coverage.apple_library_tracks ?? null },
+      ...(flagged.length ? { unresolved_check_notes: flagged } : {}),
+    } : { message: "Source evidence, listener choices or analysis changed. Update the reading before using the previous interpretation as current taste." }),
+    ...(value.listener_choices ? { listener_choices: value.listener_choices } : {}),
+    ...(since?.added?.length || since?.retracted?.length ? { choices_since_reading: since } : {}),
+  };
+}