spotifify 0.1.1

package/src/config.ts

@@ -0,0 +1,215 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { z } from "zod";
+import template from "../config.example.toml" with { type: "text" };
+
+const SpotifySchema = z.object({
+  client_id: z.string().default(""),
+  redirect_port: z.number().int().min(1024).max(65535).default(8765),
+  market: z.string().min(2).default("from_token"),
+});
+
+const NeteaseSchema = z.object({
+  enabled: z.boolean().default(true),
+  include_liked: z.boolean().default(true),
+  include_playlists: z.array(z.string()).default([]),
+  exclude_playlists: z.array(z.string()).default([]),
+  like_matched: z.boolean().default(true),
+});
+
+const LocalSchema = z.object({
+  enabled: z.boolean().default(true),
+  dirs: z.array(z.string()).default([]),
+  playlist_name: z.string().min(1).default("Local Library"),
+  /** false: local files only supply audio for tracks of other playlists (export path); no "Local Library" playlist is mirrored */
+  mirror_playlist: z.boolean().default(true),
+  extensions: z.array(z.string().min(1)).default(["mp3", "flac", "m4a", "ogg", "wav", "ncm"]),
+  filename_pattern: z.enum(["artist-title", "title-artist"]).default("artist-title"),
+  like_matched: z.boolean().default(false),
+});
+
+const ExportSchema = z.object({
+  dir: z.string().default(""),
+  ffmpeg: z.string().default("ffmpeg"),
+  bitrate: z.string().regex(/^\d+k$/).default("320k"),
+});
+
+const MatchingSchema = z
+  .object({
+    auto_threshold: z.number().min(0).max(1).default(0.9),
+    review_threshold: z.number().min(0).max(1).default(0.6),
+    duration_tolerance_ms: z.number().int().nonnegative().default(3000),
+    retry_unmatched_after_days: z.number().int().positive().default(30),
+    search_cache_ttl_days: z.number().int().positive().default(30),
+    /** network searches allowed per run (cache hits are free); 0 = unlimited. Spotify dev-mode apps get a daily quota. */
+    max_searches_per_run: z.number().int().nonnegative().default(400),
+    /** queries tried per track before giving up (isrc / fielded / free text / aliases / bare title) */
+    max_queries_per_track: z.number().int().min(1).default(4),
+    search_concurrency: z.number().int().min(1).max(8).default(2),
+    search_min_interval_ms: z.number().int().nonnegative().default(120),
+    fingerprint: z.boolean().default(false),
+    fpcalc: z.string().default("fpcalc"),
+    acoustid_key: z.string().default(""),
+    artist_aliases: z.record(z.string(), z.string()).default({}),
+  })
+  .refine((m) => m.review_threshold <= m.auto_threshold, {
+    message: "matching.review_threshold must be <= matching.auto_threshold",
+  });
+
+const SyncSchema = z.object({
+  playlist_prefix: z.string().default(""),
+});
+
+// `prefault` (zod v4) fills a missing section with `{}` *before* parsing, so inner field defaults apply.
+export const ConfigSchema = z.object({
+  spotify: SpotifySchema.prefault({}),
+  netease: NeteaseSchema.prefault({}),
+  local: LocalSchema.prefault({}),
+  export: ExportSchema.prefault({}),
+  matching: MatchingSchema.prefault({}),
+  sync: SyncSchema.prefault({}),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const CONFIG_TEMPLATE: string = template;
+
+export function stateDir(override?: string): string {
+  return expandPath(override ?? process.env.SPOTIFIFY_STATE_DIR ?? join(homedir(), ".spotifify"));
+}
+
+export const CONFIG_FILENAME = "config.toml";
+
+export function expandPath(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+  return resolve(p);
+}
+
+export async function loadConfig(path = join(stateDir(), CONFIG_FILENAME)): Promise<Config> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new Error(`config not found: ${path} (run \`spotifify init\`)`);
+  }
+  const raw = parseToml(await file.text());
+  const cfg = ConfigSchema.parse(raw);
+  cfg.local.dirs = cfg.local.dirs.map(expandPath);
+  if (cfg.export.dir) cfg.export.dir = expandPath(cfg.export.dir);
+  cfg.local.extensions = cfg.local.extensions.map((e) => e.replace(/^\./, "").toLowerCase());
+  return cfg;
+}
+
+export interface ConfigUpgrade {
+  text: string;
+  /** dotted keys that were absent from the user's file and now carry the template default */
+  added: string[];
+}
+
+/** Merge entries into `[matching.artist_aliases]`, re-rendering the file through the template (comments/order preserved). */
+export function withArtistAliases(existing: string, aliases: Record<string, string>): string {
+  const current = parseToml(existing) as Record<string, unknown>;
+  const matching = (current.matching ??= {}) as Record<string, unknown>;
+  const table = (matching.artist_aliases ??= {}) as Record<string, unknown>;
+  Object.assign(table, aliases);
+  return upgradeConfig(stringifyToml(current)).text;
+}
+
+/**
+ * Rewrite a config file against the current template: template order and comments, the user's values
+ * where present, template defaults for options the file predates. Keys the template does not know are
+ * kept at the end of their section; unknown sections are appended verbatim.
+ */
+export function upgradeConfig(existing: string, tmpl: string = CONFIG_TEMPLATE): ConfigUpgrade {
+  const current = parseToml(existing) as Record<string, unknown>;
+  const out: string[] = [];
+  const added: string[] = [];
+  const seenSections = new Set<string>();
+  let section: string[] = [];
+  let emitted = new Set<string>();
+
+  const table = (path: string[]): Record<string, unknown> | undefined => {
+    let node: unknown = current;
+    for (const p of path) {
+      if (typeof node !== "object" || node === null || !(p in node)) return undefined;
+      node = (node as Record<string, unknown>)[p];
+    }
+    return typeof node === "object" && node !== null && !Array.isArray(node) ? (node as Record<string, unknown>) : undefined;
+  };
+  const isTable = (v: unknown) => typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+  const flushExtras = () => {
+    const t = table(section);
+    if (!t) return;
+    for (const [k, v] of Object.entries(t)) {
+      if (emitted.has(k) || isTable(v)) continue;
+      while (out.length > 0 && out[out.length - 1] === "") out.pop();
+      out.push(`${tomlKey(k)} = ${tomlValue(v)}`);
+    }
+    out.push("");
+  };
+
+  for (const line of tmpl.split(/\r?\n/)) {
+    const header = line.match(/^\[([^\]]+)\]\s*$/);
+    if (header) {
+      flushExtras();
+      section = header[1]!.split(".");
+      seenSections.add(header[1]!);
+      emitted = new Set();
+      out.push(line);
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_-]+)\s*=\s*(.*)$/);
+    if (kv) {
+      const key = kv[1]!;
+      const t = table(section);
+      emitted.add(key);
+      if (t && key in t && !isTable(t[key])) {
+        out.push(`${key} = ${tomlValue(t[key])}${trailingComment(kv[2]!)}`);
+      } else {
+        out.push(line);
+        added.push([...section, key].join("."));
+      }
+      continue;
+    }
+    out.push(line);
+  }
+  flushExtras();
+
+  // Sections the template does not know at all (e.g. removed or user-invented): keep them.
+  const walk = (node: Record<string, unknown>, path: string[]) => {
+    for (const [k, v] of Object.entries(node)) {
+      if (!isTable(v)) continue;
+      const full = [...path, k];
+      const name = full.join(".");
+      if (!seenSections.has(name)) {
+        out.push(`[${name}]`);
+        for (const [ik, iv] of Object.entries(v as Record<string, unknown>)) if (!isTable(iv)) out.push(`${tomlKey(ik)} = ${tomlValue(iv)}`);
+        out.push("");
+      }
+      walk(v as Record<string, unknown>, full);
+    }
+  };
+  walk(current, []);
+
+  return { text: out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n"), added };
+}
+
+/** Options present in the template but missing from `existing` (what `init --upgrade` would add). */
+export function missingConfigKeys(existing: string, tmpl: string = CONFIG_TEMPLATE): string[] {
+  return upgradeConfig(existing, tmpl).added;
+}
+
+function tomlValue(v: unknown): string {
+  const line = stringifyToml({ v });
+  return line.slice(line.indexOf("=") + 1).trim();
+}
+
+function tomlKey(k: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k);
+}
+
+/** Keep an inline `# comment` that follows the template value. */
+function trailingComment(rest: string): string {
+  const m = rest.match(/\s+(#.*)$/);
+  return m ? `   ${m[1]}` : "";
+}

package/src/env.d.ts

@@ -0,0 +1,15 @@
+// Bun text imports: `import s from "./x.sql" with { type: "text" }`
+declare module "*.sql" {
+  const text: string;
+  export default text;
+}
+declare module "*.toml" {
+  const text: string;
+  export default text;
+}
+
+// NeteaseCloudMusicApi internals loaded by src/sources/netease/lib.ts (the package ships types only for main.js).
+declare namespace NeteaseApi {
+  type Request = (uri: string, data: Record<string, unknown>, options: Record<string, unknown>) => Promise<unknown>;
+  type Module = (query: Record<string, unknown>, request: Request) => Promise<unknown>;
+}

package/src/match/aliases.ts

@@ -0,0 +1,76 @@
+/**
+ * Mine `matching.artist_aliases` candidates from matches whose identity is certain (user-confirmed,
+ * ISRC or fingerprint hits): when exactly one source artist and one Spotify artist are left unpaired
+ * after applying the current alias table, they are the same act under two names (周杰倫 → Jay Chou).
+ */
+import type { Config } from "../config.ts";
+import type { Repo } from "../state/repo.ts";
+import { normalizeArtists, normalizeText, similarity, splitArtists } from "./normalize.ts";
+
+export interface AliasSuggestion {
+  /** raw source artist name as it appears in the source */
+  from: string;
+  /** raw Spotify artist name */
+  to: string;
+  /** confirmed matches supporting this pairing */
+  count: number;
+  /** a few "artist - title" examples */
+  examples: string[];
+  /** other Spotify names the same source artist was paired with (ambiguous; the most frequent wins) */
+  conflicts: string[];
+}
+
+/** Below this similarity the two names would not be matched by fuzzy scoring, so an alias actually changes outcomes. */
+const FUZZY_ENOUGH = 0.8;
+const EXAMPLES = 3;
+
+export function inferArtistAliases(repo: Repo, cfg: Config["matching"]): AliasSuggestion[] {
+  const rows = repo.listMatches("matched").filter((m) => m.decidedBy === "user" || m.decidedBy === "isrc" || m.decidedBy === "fingerprint");
+  const tracks = repo.representativeTracks(rows.map((m) => m.canonicalKey));
+  // normalized source name → normalized spotify name → tally
+  const tally = new Map<string, Map<string, { from: string; to: string; count: number; examples: string[] }>>();
+
+  for (const m of rows) {
+    const track = tracks.get(m.canonicalKey);
+    const cand = m.candidates.find((c) => c.id === m.spotifyId);
+    if (!track || !cand) continue;
+
+    const srcRaw = splitArtists(track.artists);
+    const candRaw = splitArtists(cand.artists);
+    const srcNorm = normalizeArtists(track.artists, cfg.artist_aliases);
+    const candNorm = normalizeArtists(cand.artists, cfg.artist_aliases);
+    const candSet = new Set(candNorm);
+    const srcSet = new Set(srcNorm);
+
+    const leftSrc = srcRaw.filter((r) => !candSet.has(normalizeArtists([r], cfg.artist_aliases)[0] ?? ""));
+    const leftCand = candRaw.filter((r) => !srcSet.has(normalizeArtists([r], cfg.artist_aliases)[0] ?? ""));
+    if (leftSrc.length !== 1 || leftCand.length !== 1) continue;
+
+    const from = leftSrc[0]!;
+    const to = leftCand[0]!;
+    const nf = normalizeText(from);
+    const nt = normalizeText(to);
+    if (nf === "" || nt === "" || similarity(nf, nt) >= FUZZY_ENOUGH) continue;
+
+    let byTarget = tally.get(nf);
+    if (!byTarget) {
+      byTarget = new Map();
+      tally.set(nf, byTarget);
+    }
+    let entry = byTarget.get(nt);
+    if (!entry) {
+      entry = { from, to, count: 0, examples: [] };
+      byTarget.set(nt, entry);
+    }
+    entry.count++;
+    if (entry.examples.length < EXAMPLES) entry.examples.push(`${track.artists.join(", ")} - ${track.title}  →  ${cand.artists.join(", ")} - ${cand.title}`);
+  }
+
+  const out: AliasSuggestion[] = [];
+  for (const byTarget of tally.values()) {
+    const ranked = [...byTarget.values()].sort((a, b) => b.count - a.count);
+    const best = ranked[0]!;
+    out.push({ from: best.from, to: best.to, count: best.count, examples: best.examples, conflicts: ranked.slice(1).map((r) => r.to) });
+  }
+  return out.sort((a, b) => b.count - a.count || a.from.localeCompare(b.from));
+}

package/src/match/fingerprint.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import type { Config } from "../config.ts";
+import type { Repo } from "../state/repo.ts";
+import { log } from "../util/log.ts";
+import { RetryableError, sleep, withRetry } from "../util/retry.ts";
+
+const ACOUSTID_MIN_SCORE = 0.7;
+const MAX_RECORDINGS = 3;
+const MUSICBRAINZ_GAP_MS = 1100;
+const USER_AGENT = "Spotifify/0.1 (https://github.com/spotifify)";
+
+const FpcalcOutput = z.object({ duration: z.number(), fingerprint: z.string().min(1) });
+
+const AcoustIdResponse = z.object({
+  status: z.string(),
+  error: z.object({ message: z.string() }).optional(),
+  results: z.array(z.object({ id: z.string(), score: z.number(), recordings: z.array(z.object({ id: z.string() })).optional() })).optional(),
+});
+
+const MusicBrainzRecording = z.object({ isrcs: z.array(z.string()).optional() });
+
+/** Set once per process when `fpcalc` cannot be spawned, so every later track skips silently. */
+let fpcalcMissing = false;
+/** All AcoustID / MusicBrainz traffic is serialized so the 1 req/s MusicBrainz budget holds across concurrent tracks. */
+let queue: Promise<unknown> = Promise.resolve();
+let lastMusicBrainzAt = 0;
+
+async function fetchJson<T>(url: string, schema: z.ZodType<T>): Promise<T> {
+  return withRetry(async () => {
+    const res = await fetch(url, { headers: { "User-Agent": USER_AGENT, Accept: "application/json" } });
+    if (res.status === 429 || res.status >= 500) {
+      const retryAfter = Number(res.headers.get("retry-after"));
+      throw new RetryableError(`${res.status} from ${new URL(url).host}`, retryAfter > 0 ? retryAfter * 1000 : undefined);
+    }
+    if (!res.ok) throw new Error(`${res.status} from ${new URL(url).host}: ${(await res.text()).slice(0, 200)}`);
+    return schema.parse(await res.json());
+  });
+}
+
+/** Returns null (and disables fingerprinting for the process) when the binary is not installed. */
+async function runFpcalc(fpcalc: string, path: string): Promise<z.infer<typeof FpcalcOutput> | null> {
+  let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    proc = Bun.spawn([fpcalc, "-json", path], { stdout: "pipe", stderr: "pipe" });
+  } catch (e) {
+    if (e instanceof Error && "code" in e && e.code === "ENOENT") {
+      fpcalcMissing = true;
+      log.warn(`fpcalc not found (${fpcalc}); fingerprint lookups disabled for this run`);
+      return null;
+    }
+    throw e;
+  }
+  const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  if (code !== 0) throw new Error(`fpcalc exited ${code}: ${stderr.trim().slice(0, 200)}`);
+  return FpcalcOutput.parse(JSON.parse(stdout));
+}
+
+async function lookup(path: string, contentHash: string, cfg: Config["matching"], repo: Repo, now: number): Promise<string[]> {
+  const fp = await runFpcalc(cfg.fpcalc, path);
+  if (!fp) return [];
+  const durationS = Math.round(fp.duration);
+  const acoustid = await fetchJson(
+    `https://api.acoustid.org/v2/lookup?client=${encodeURIComponent(cfg.acoustid_key)}&meta=recordings&duration=${durationS}&fingerprint=${encodeURIComponent(fp.fingerprint)}`,
+    AcoustIdResponse,
+  );
+  if (acoustid.status !== "ok") throw new Error(`acoustid: ${acoustid.error?.message ?? acoustid.status}`);
+  const mbids: string[] = [];
+  for (const r of acoustid.results ?? []) {
+    if (r.score < ACOUSTID_MIN_SCORE) continue;
+    for (const rec of r.recordings ?? []) {
+      if (mbids.length >= MAX_RECORDINGS) break;
+      if (!mbids.includes(rec.id)) mbids.push(rec.id);
+    }
+  }
+  const isrcs = new Set<string>();
+  for (const mbid of mbids) {
+    const wait = lastMusicBrainzAt + MUSICBRAINZ_GAP_MS - Date.now();
+    if (wait > 0) await sleep(wait);
+    lastMusicBrainzAt = Date.now();
+    const rec = await fetchJson(`https://musicbrainz.org/ws/2/recording/${mbid}?inc=isrcs&fmt=json`, MusicBrainzRecording);
+    for (const isrc of rec.isrcs ?? []) isrcs.add(isrc.toUpperCase());
+  }
+  const out = [...isrcs];
+  repo.setFingerprint({ contentHash, fp: fp.fingerprint, durationS, acoustid: acoustid.results ?? null, isrcs: out, fetchedAt: now });
+  return out;
+}
+
+/**
+ * ISRCs for a local file via Chromaprint → AcoustID → MusicBrainz, cached by content hash.
+ * Returns [] when fingerprinting is disabled, `fpcalc`/key are missing, or any step fails (failures are not cached).
+ */
+export async function isrcsByFingerprint(path: string, contentHash: string, cfg: Config["matching"], repo: Repo, now: number): Promise<string[]> {
+  if (!cfg.fingerprint || !cfg.acoustid_key || fpcalcMissing) return [];
+  const cached = repo.getFingerprint(contentHash);
+  if (cached) return cached.isrcs;
+  const job = queue.then(() => lookup(path, contentHash, cfg, repo, now));
+  queue = job.catch(() => {});
+  try {
+    return await job;
+  } catch (e) {
+    log.warn(`fingerprint lookup failed for ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    return [];
+  }
+}

package/src/match/matcher.ts

@@ -0,0 +1,182 @@
+import type { Config } from "../config.ts";
+import type { SpotifyApi } from "../spotify/api.ts";
+import type { SpotifyTrack } from "../spotify/types.ts";
+import type { Repo, SourceTrackRow } from "../state/repo.ts";
+import { mapLimit } from "../util/retry.ts";
+import { isrcsByFingerprint } from "./fingerprint.ts";
+import { passesAutoGate, prepareSource, scorePrepared, type PreparedSource } from "./score.ts";
+import { queryTitle, TrackSearch } from "./search.ts";
+import type { Candidate, DecidedBy, MatchRow, ScoreParts } from "./types.ts";
+
+const MAX_CANDIDATES = 10;
+/** DESIGN.md §5.1 step 5: a bare-title query only contributes candidates whose artist already looks right. */
+const BARE_TITLE_MIN_ARTIST = 0.8;
+const SEARCH_CONCURRENCY = 4;
+const TRACK_REF = /^(?:spotify:track:|https?:\/\/open\.spotify\.com\/(?:intl-[a-z-]+\/)?track\/)([0-9A-Za-z]{22})(?:[?#].*)?$/;
+
+/** Dedupes search results by id (and relinked origin id) and scores each one once. */
+class CandidatePool {
+  private readonly seen = new Set<string>();
+  private readonly candidates: Candidate[] = [];
+
+  constructor(
+    private readonly src: PreparedSource,
+    private readonly cfg: Config["matching"],
+  ) {}
+
+  /** Scores unseen tracks; returns those admitted. Unplayable tracks are skipped when `playableOnly`. */
+  add(tracks: SpotifyTrack[], playableOnly: boolean, minArtist: number): Candidate[] {
+    const added: Candidate[] = [];
+    for (const t of tracks) {
+      if (t.id === null || t.is_local) continue;
+      if (this.seen.has(t.id) || (t.linked_from !== undefined && this.seen.has(t.linked_from.id))) continue;
+      this.seen.add(t.id);
+      if (t.linked_from) this.seen.add(t.linked_from.id);
+      if (playableOnly && t.is_playable === false) continue;
+      const scored = scorePrepared(this.src, t, this.cfg);
+      if (scored.parts.artist < minArtist) continue;
+      const c = toCandidate(t.id, t, scored);
+      this.candidates.push(c);
+      added.push(c);
+    }
+    return added;
+  }
+
+  sorted(): Candidate[] {
+    return [...this.candidates].sort((a, b) => b.score - a.score);
+  }
+}
+
+function toCandidate(id: string, t: SpotifyTrack, scored: { score: number; parts: ScoreParts }): Candidate {
+  return {
+    id,
+    uri: t.uri,
+    title: t.name,
+    artists: t.artists.map((a) => a.name),
+    album: t.album.name,
+    durationMs: t.duration_ms,
+    isPlayable: t.is_playable !== false,
+    score: scored.score,
+    parts: scored.parts,
+  };
+}
+
+type Hit = { by: "isrc" | "fingerprint"; candidate: Candidate } | { by: "auto" };
+
+export class Matcher {
+  private readonly api: SpotifyApi;
+  private readonly repo: Repo;
+  private readonly cfg: Config;
+  private readonly market: string;
+  private readonly search: TrackSearch;
+
+  constructor(deps: { api: SpotifyApi; repo: Repo; cfg: Config; market: string }) {
+    this.api = deps.api;
+    this.repo = deps.repo;
+    this.cfg = deps.cfg;
+    this.market = deps.market;
+    this.search = new TrackSearch(deps.api, deps.repo, deps.cfg.matching, deps.market);
+  }
+
+  /** Network searches spent by this matcher (cache hits excluded). */
+  get searchesUsed(): number {
+    return this.search.used;
+  }
+
+  /**
+   * Runs queries in order, admitting playable results into the pool. Stops at the first ISRC hit
+   * (returned as the decision) or as soon as some candidate passes the auto gate.
+   */
+  private async runQueries(pool: CandidatePool, queries: string[], bareTitle: string | null, isrcBy: "isrc" | "fingerprint", now: number): Promise<Hit | null> {
+    const m = this.cfg.matching;
+    for (const q of queries) {
+      const tracks = await this.search.search(q, now);
+      const added = pool.add(tracks, true, q === bareTitle ? BARE_TITLE_MIN_ARTIST : 0);
+      if (added.length === 0) continue;
+      if (q.startsWith("isrc:")) {
+        let best = added[0]!;
+        for (const c of added) if (c.score > best.score) best = c;
+        return { by: isrcBy, candidate: best };
+      }
+      if (added.some((c) => passesAutoGate(c.score, c.parts, m))) return { by: "auto" };
+    }
+    return null;
+  }
+
+  /**
+   * Decides `matched` / `review` / `local` for one source track. User decisions are returned untouched.
+   * Does not persist: the caller writes the returned row with `repo.upsertMatch`.
+   */
+  async matchOne(track: SourceTrackRow, existing: MatchRow | null, now: number): Promise<MatchRow> {
+    if (existing?.decidedBy === "user") return existing;
+    const m = this.cfg.matching;
+    const pool = new CandidatePool(prepareSource(track, m), m);
+    const bareTitle = track.artists.length > 0 ? queryTitle(track.title) : null;
+    let hit = await this.runQueries(pool, this.search.queriesFor(track), bareTitle, "isrc", now);
+    if (hit === null && track.file && m.fingerprint) {
+      const isrcs = await isrcsByFingerprint(track.file.path, track.file.contentHash, m, this.repo, now);
+      for (const isrc of isrcs) {
+        hit = await this.runQueries(pool, [`isrc:${isrc}`], null, "fingerprint", now);
+        if (hit !== null) break;
+      }
+    }
+
+    let candidates = pool.sorted();
+    let winner: { candidate: Candidate; decidedBy: DecidedBy; score: number } | null = null;
+    if (hit !== null && hit.by !== "auto") {
+      winner = { candidate: hit.candidate, decidedBy: hit.by, score: 1 };
+    } else {
+      const auto = candidates.find((c) => passesAutoGate(c.score, c.parts, m));
+      if (auto) winner = { candidate: auto, decidedBy: "auto", score: auto.score };
+    }
+    if (winner !== null && !candidates.slice(0, MAX_CANDIDATES).includes(winner.candidate)) {
+      candidates = [winner.candidate, ...candidates.filter((c) => c !== winner.candidate)];
+    }
+    candidates = candidates.slice(0, MAX_CANDIDATES);
+
+    const row: MatchRow = {
+      canonicalKey: track.canonicalKey,
+      status: "local",
+      spotifyId: null,
+      spotifyUri: null,
+      score: candidates[0]?.score ?? null,
+      decidedBy: "auto",
+      candidates,
+      decidedAt: now,
+      lastSearchAt: now,
+      searchCount: (existing?.searchCount ?? 0) + 1,
+    };
+    if (winner !== null) {
+      row.status = "matched";
+      row.spotifyId = winner.candidate.id;
+      row.spotifyUri = `spotify:track:${winner.candidate.id}`;
+      row.score = winner.score;
+      row.decidedBy = winner.decidedBy;
+    } else if (candidates[0] !== undefined && candidates[0].score >= m.review_threshold) {
+      row.status = "review";
+      row.decidedBy = null;
+      row.decidedAt = null;
+    }
+    return row;
+  }
+
+  /** Every scored candidate for the TUI: the full §5.1 query union, or one custom query. Unplayable tracks are kept and flagged. */
+  async candidatesFor(track: SourceTrackRow, query?: string): Promise<Candidate[]> {
+    const m = this.cfg.matching;
+    const pool = new CandidatePool(prepareSource(track, m), m);
+    const queries = query === undefined ? this.search.queriesFor(track) : [query];
+    const now = Date.now();
+    for (const tracks of await mapLimit(queries, SEARCH_CONCURRENCY, (q) => this.search.search(q, now))) pool.add(tracks, false, 0);
+    return pool.sorted();
+  }
+
+  /** Scores a pasted `spotify:track:` URI or open.spotify.com track URL against the source track. */
+  async candidateFromUri(track: SourceTrackRow, uriOrUrl: string): Promise<Candidate | null> {
+    const id = TRACK_REF.exec(uriOrUrl.trim())?.[1];
+    if (id === undefined) return null;
+    const t = await this.api.getTrack(id, this.market);
+    if (t === null || t.id === null) return null;
+    const m = this.cfg.matching;
+    return toCandidate(t.id, t, scorePrepared(prepareSource(track, m), t, m));
+  }
+}