@audiofool/moondog 0.1.0 → 0.2.0-beta.2

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-profile-build.mjs

@@ -0,0 +1,378 @@
+import { createHash } from "node:crypto";
+
+import { recordedShare } from "./recorded-measures.mjs";
+
+export const LISTENER_PROFILE_ANALYSIS_VERSION = "listener-profile/2";
+export const LISTENER_PROFILE_SYNTHESIS_VERSION = "listener-synthesis/4";
+// 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 === "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",
+  ]);
+  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)) {
+    if (Array.isArray(value)) {
+      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 })),
+    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),
+  };
+}
+
+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);
+}
+
+export function readListenerProfile({ input, getInput, store }, { 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) return { state: "missing", total_claims: 0, claims: [], next_offset: null };
+  // 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 }] : []),
+  };
+  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) {
+  if (!value || value.state === "missing") return { state: "missing" };
+  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;
+  return {
+    state: behind ? "current_through" : value.state, revision_id: value.revision_id, sequence: value.sequence, built_at: value.built_at,
+    ...(value.state === "current" || behind ? {
+      ...(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." } : {}),
+      summary: value.summary,
+      claims: value.highlights,
+      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." }),
+  };
+}

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

@@ -0,0 +1,130 @@
+import { randomUUID } from "node:crypto";
+import { profileDigest } from "./listener-profile-build.mjs";
+
+// listener_profile_partitions holds page findings from builds before
+// listener-synthesis/4. New builds no longer write it; it stays so existing
+// databases open unchanged.
+export const listenerProfileSchema = `
+  CREATE TABLE IF NOT EXISTS listener_profile_builds (
+    build_id TEXT PRIMARY KEY NOT NULL, subject_id TEXT NOT NULL,
+    input_digest TEXT NOT NULL, model_key TEXT NOT NULL,
+    lease_token TEXT NOT NULL, state TEXT NOT NULL, record_json TEXT NOT NULL
+  ) STRICT;
+  CREATE INDEX IF NOT EXISTS listener_profile_build_input
+    ON listener_profile_builds(subject_id, input_digest, model_key);
+  CREATE TABLE IF NOT EXISTS listener_profile_partitions (
+    build_id TEXT NOT NULL, partition_id TEXT NOT NULL,
+    review_json TEXT NOT NULL,
+    PRIMARY KEY (build_id, partition_id),
+    FOREIGN KEY (build_id) REFERENCES listener_profile_builds(build_id)
+  ) STRICT;
+  CREATE INDEX IF NOT EXISTS listener_profile_partition_cache ON listener_profile_partitions(partition_id);
+  CREATE TABLE IF NOT EXISTS listener_profile_revisions (
+    revision_id TEXT PRIMARY KEY NOT NULL, subject_id TEXT NOT NULL,
+    sequence INTEGER NOT NULL, input_digest TEXT NOT NULL, record_json TEXT NOT NULL,
+    UNIQUE (subject_id, sequence)
+  ) STRICT;
+`;
+
+export class ListenerProfileStore {
+  constructor(database, subjectId) {
+    this.database = database;
+    this.subjectId = subjectId;
+  }
+
+  current() {
+    const row = this.database.prepare(`SELECT record_json FROM listener_profile_revisions
+      WHERE subject_id = ? ORDER BY sequence DESC LIMIT 1`).get(this.subjectId);
+    return row ? JSON.parse(row.record_json) : null;
+  }
+
+  revision(id) {
+    const row = this.database.prepare(`SELECT record_json FROM listener_profile_revisions
+      WHERE subject_id = ? AND revision_id = ?`).get(this.subjectId, id);
+    return row ? JSON.parse(row.record_json) : null;
+  }
+
+  /** When a build last started or resumed, whether the listener asked for it or not. */
+  lastAttemptAt() {
+    return this.database.prepare(`SELECT MAX(COALESCE(json_extract(record_json, '$.attempted_at'),
+      json_extract(record_json, '$.started_at'))) AS attempted_at
+      FROM listener_profile_builds WHERE subject_id = ?`).get(this.subjectId)?.attempted_at ?? null;
+  }
+
+  /** Resume an unfinished build for the same input and model, or start a new one. */
+  begin(input, model, { force = false } = {}) {
+    const modelKey = profileDigest(model);
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      const parent = this.current()?.revision_id ?? null;
+      const existing = force ? null : this.database.prepare(`SELECT record_json FROM listener_profile_builds
+        WHERE subject_id = ? AND input_digest = ? AND model_key = ? AND state <> 'complete'
+        ORDER BY rowid DESC LIMIT 1`).get(this.subjectId, input.input_digest, modelKey);
+      const saved = existing ? JSON.parse(existing.record_json) : null;
+      // A checkpoint written against an older current reading cannot replace the newer one.
+      const resumable = saved?.parent_revision_id === parent ? saved : null;
+      const build = resumable ?? {
+        build_id: randomUUID(), input_digest: input.input_digest, model,
+        parent_revision_id: parent, started_at: new Date().toISOString(),
+      };
+      build.lease_token = randomUUID();
+      build.attempted_at = new Date().toISOString();
+      this.database.prepare(`INSERT INTO listener_profile_builds
+        (build_id, subject_id, input_digest, model_key, lease_token, state, record_json)
+        VALUES (?, ?, ?, ?, ?, 'building', ?) ON CONFLICT(build_id) DO UPDATE
+        SET lease_token = excluded.lease_token, state = 'building', record_json = excluded.record_json`)
+        .run(build.build_id, this.subjectId, input.input_digest, modelKey, build.lease_token, JSON.stringify(build));
+      this.database.exec("COMMIT");
+      return { ...build, resumed: Boolean(resumable) };
+    } catch (error) { this.database.exec("ROLLBACK"); throw error; }
+  }
+
+  #assertLease(build) {
+    const row = this.database.prepare(`SELECT lease_token, state FROM listener_profile_builds
+      WHERE subject_id = ? AND build_id = ?`).get(this.subjectId, build.build_id);
+    if (row?.lease_token !== build.lease_token || row.state !== "building") {
+      throw new Error("Another profile build has taken over; continue from its saved progress");
+    }
+  }
+
+  checkpointFinalization(build, finalization) {
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      this.#assertLease(build);
+      const row = this.database.prepare("SELECT record_json FROM listener_profile_builds WHERE build_id = ?")
+        .get(build.build_id);
+      const record = { ...JSON.parse(row.record_json), finalization };
+      this.database.prepare("UPDATE listener_profile_builds SET record_json = ? WHERE build_id = ?")
+        .run(JSON.stringify(record), build.build_id);
+      this.database.exec("COMMIT");
+    } catch (error) { this.database.exec("ROLLBACK"); throw error; }
+  }
+
+  interrupt(build) {
+    this.database.prepare(`UPDATE listener_profile_builds SET state = 'interrupted'
+      WHERE subject_id = ? AND build_id = ? AND lease_token = ? AND state = 'building'`)
+      .run(this.subjectId, build.build_id, build.lease_token);
+  }
+
+  complete(build, profile, assertCurrentInput = () => {}) {
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      this.#assertLease(build);
+      assertCurrentInput();
+      const previous = this.current();
+      if ((previous?.revision_id ?? null) !== build.parent_revision_id) {
+        throw new Error("The current profile changed during this build; start again from the new version");
+      }
+      const revision = {
+        ...profile, revision_id: randomUUID(), sequence: (previous?.sequence ?? 0) + 1,
+        parent_revision_id: previous?.revision_id ?? null, built_at: new Date().toISOString(), model: build.model,
+      };
+      this.database.prepare(`INSERT INTO listener_profile_revisions
+        (revision_id, subject_id, sequence, input_digest, record_json) VALUES (?, ?, ?, ?, ?)`)
+        .run(revision.revision_id, this.subjectId, revision.sequence, revision.input_digest, JSON.stringify(revision));
+      this.database.prepare("UPDATE listener_profile_builds SET state = 'complete' WHERE build_id = ?").run(build.build_id);
+      this.database.exec("COMMIT");
+      return revision;
+    } catch (error) { this.database.exec("ROLLBACK"); throw error; }
+  }
+}