fluncle 0.139.0 → 0.141.0

package/bin/fluncle.mjs

@@ -561,7 +561,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.139.0".trim() ? "0.139.0".trim() : "0.1.0";
+  currentVersion = "0.141.0".trim() ? "0.141.0".trim() : "0.1.0";
 });
 
 // src/update-notifier.ts
@@ -2189,7 +2189,7 @@ function parseVersion2(version) {
 var currentVersion2, latestReleaseUrl = "https://api.github.com/repos/mauricekleine/fluncle/releases/latest";
 var init_version2 = __esm(() => {
   init_output();
-  currentVersion2 = "0.139.0".trim() ? "0.139.0".trim() : "0.1.0";
+  currentVersion2 = "0.141.0".trim() ? "0.141.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -2654,7 +2654,7 @@ var init_src = __esm(() => {
       exposedContent: ["the XML sitemap index of every public page"],
       kind: "discovery",
       name: "discovery.sitemap",
-      operatorNotes: "A sitemap INDEX, not a flat urlset: the URLs live in children at /sitemap/<kind>-<n>.xml (pages/findings/graph/logbook), each auto-paged under Google's 50,000-URL ceiling so a breach cannot happen rather than merely not having happened yet. robots.txt still names this one URL — a crawler discovers the children from here. Splitting by kind is also the diagnostic: Search Console reports coverage PER sitemap.",
+      operatorNotes: "A sitemap INDEX, not a flat urlset: the URLs live in children at /sitemap/<kind>-<n>.xml, ONE CHILD PER ENTITY TYPE (pages/findings/artists/labels/albums/galaxies/logbook), each auto-paged under Google's 50,000-URL ceiling so a breach cannot happen rather than merely not having happened yet. robots.txt still names this one URL — a crawler discovers the children from here. Splitting per entity type is also the diagnostic: Search Console reports coverage PER sitemap, so each entity type gets its own submitted/indexed count.",
       probeConfig: { cadenceMs: PROBE_CADENCE_MS, kind: "http", timeoutMs: PROBE_TIMEOUT_MS },
       route: "/sitemap.xml",
       url: `${SITE}/sitemap.xml`,
@@ -2662,7 +2662,9 @@ var init_src = __esm(() => {
     },
     {
       apiFormat: "application/xml",
-      exposedContent: ["one child sitemap: the pages / findings / graph / logbook URLs, auto-paged"],
+      exposedContent: [
+        "one child sitemap, per entity type: the pages / findings / artists / labels / albums / galaxies / logbook URLs, auto-paged"
+      ],
       kind: "discovery",
       name: "discovery.sitemap-shard",
       probeConfig: { cadenceMs: PROBE_CADENCE_MS, kind: "http", timeoutMs: PROBE_TIMEOUT_MS },
@@ -2956,6 +2958,17 @@ var init_src = __esm(() => {
       probeConfig: { cadenceMs: 60 * MINUTE_MS, cronName: "fluncle-label-images", kind: "cron" },
       weights: { status: "hidden" }
     },
+    {
+      command: "fluncle admin backfills cover-masters",
+      exposedContent: [
+        "resolve each pending album/artist its OWN ≤1200² cover master (best source wins) → its own R2 image"
+      ],
+      kind: "cron",
+      name: "cron.cover-masters",
+      operatorNotes: "every 60m, run by a rave-02 HOST systemd timer (docs/agents/hermes/cover-masters-timer/). The DURABLE other half of the album/artist cover (RFC musickit-second-authority U3b): the publish path + catalogue crawl MINT albums/artists (each `image_state='pending'`) and this cron gives each its OWN ≤1200²-capped cover derivative in R2 (found.fluncle.com, `albums/<slug>.<ext>` / `artists/<slug>.<ext>`) instead of hotlinking a third party — the label-logo posture, two entities over. IMAGE ONLY — a downscaled display derivative, reversible, the REF-05-conscious 1200 line (docs/album-artwork.md); it certifies nothing and publishes nothing (agent tier, the `backfill_label_images` precedent). Worker-paced: one bounded batch of albums (Apple template → Cover Art Archive → Spotify floor), then one of artists (Spotify floor), per tick; every rung requests a ≤1200 rendition and a byte read enforces the cap before the R2 put, so no un-downscaled original is ever stored. The `albums`/`artists` row carries the durable reliability state (image_state/image_attempted_at/image_failures), so a resolved/none entity is terminal. Served via Cloudflare Images `/cdn-cgi/image/…` (decision B). Zero LLM tokens. Source: docs/agents/hermes/scripts/cover-masters-sweep.*. See docs/album-artwork.md.",
+      probeConfig: { cadenceMs: 60 * MINUTE_MS, cronName: "fluncle-cover-masters", kind: "cron" },
+      weights: { status: "hidden" }
+    },
     {
       command: "fluncle admin tracks capture-audio --queue",
       exposedContent: [
@@ -3666,7 +3679,8 @@ __export(exports_admin_tracks, {
   captureQueueCommand: () => captureQueueCommand,
   backfillLastfmCommand: () => backfillLastfmCommand,
   backfillDiscogsCommand: () => backfillDiscogsCommand,
-  backfillAppleMusicCommand: () => backfillAppleMusicCommand
+  backfillAppleMusicCommand: () => backfillAppleMusicCommand,
+  backfillAppleCatalogueCommand: () => backfillAppleCatalogueCommand
 });
 async function fetchAdminTracks(options) {
   const {
@@ -3846,6 +3860,10 @@ async function backfillAppleMusicCommand(limit, dryRun, cursor) {
   }
   return adminApiPost(`/api/admin/backfill/apple-music?${params.toString()}`);
 }
+async function backfillAppleCatalogueCommand(limit, dryRun) {
+  const params = new URLSearchParams({ dryRun: String(dryRun), limit: String(limit) });
+  return adminApiPost(`/api/admin/backfill/apple-catalogue?${params.toString()}`);
+}
 async function vehiclesCommand(limit) {
   const tracks = await fetchAdminTracks({ hasVideo: true, max: limit, order: "desc" });
   return tracks.map((track) => ({
@@ -5699,6 +5717,7 @@ var exports_admin_catalogue = {};
 __export(exports_admin_catalogue, {
   crawlStatusCommand: () => crawlStatusCommand,
   crawlCatalogueCommand: () => crawlCatalogueCommand,
+  clearWrongAudioCommand: () => clearWrongAudioCommand,
   catalogueRankCommand: () => catalogueRankCommand,
   catalogueListCommand: () => catalogueListCommand
 });
@@ -5709,12 +5728,17 @@ async function catalogueRankCommand(options) {
 }
 async function catalogueListCommand(options) {
   const params = new URLSearchParams;
-  params.set("lens", options.lens === "capture" ? "capture" : "ear");
+  params.set("lens", options.lens === "capture" ? "capture" : options.lens === "quarantine" ? "quarantine" : "ear");
   if (options.limit) {
     params.set("limit", options.limit);
   }
   return adminApiGet(`/api/admin/catalogue?${params.toString()}`);
 }
+async function clearWrongAudioCommand(trackId) {
+  return adminApiPost("/api/admin/catalogue/wrong-audio/clear", {
+    trackId
+  });
+}
 async function crawlCatalogueCommand(limit, maxHop, dryRun) {
   const params = new URLSearchParams({ limit: String(limit), maxHop: String(maxHop) });
   if (dryRun) {
@@ -5781,6 +5805,22 @@ var init_admin_labels = __esm(() => {
   init_api();
 });
 
+// src/commands/admin-covers.ts
+var exports_admin_covers = {};
+__export(exports_admin_covers, {
+  backfillCoverMastersCommand: () => backfillCoverMastersCommand
+});
+async function backfillCoverMastersCommand(kind, limit, dryRun, cursor) {
+  const params = new URLSearchParams({ dryRun: String(dryRun), kind, limit: String(limit) });
+  if (cursor) {
+    params.set("cursor", cursor);
+  }
+  return adminApiPost(`/api/admin/backfill/cover-masters?${params.toString()}`);
+}
+var init_admin_covers = __esm(() => {
+  init_api();
+});
+
 // src/commands/preview-migration.ts
 var exports_preview_migration = {};
 __export(exports_preview_migration, {
@@ -8761,10 +8801,19 @@ function addAdminCommands(program2) {
     const { catalogueRankCommand: catalogueRankCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCatalogueRank(options, catalogueRankCommand2);
   });
-  catalogue.command("list").description("The ranked catalogue: closest to a finding (ear), or next to capture").option("--lens <lens>", "ear (default) or capture", "ear").option("--limit <limit>", "Rows (default 50, max 200)").option("--json", "Print JSON", false).action(async (options) => {
+  catalogue.command("list").description("The ranked catalogue: closest to a finding (ear), next to capture, or wrong audio").option("--lens <lens>", "ear (default), capture, or quarantine", "ear").option("--limit <limit>", "Rows (default 50, max 200)").option("--json", "Print JSON", false).action(async (options) => {
     const { catalogueListCommand: catalogueListCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCatalogueList(options, catalogueListCommand2);
   });
+  catalogue.command("clear-wrong-audio").description("Overrule the wrong-audio quarantine on one catalogue row (operator)").argument("<trackId>", "The catalogue track id to keep").option("--json", "Print JSON", false).action(async (trackId, options) => {
+    const { clearWrongAudioCommand: clearWrongAudioCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
+    const { cleared } = await clearWrongAudioCommand2(trackId);
+    if (options.json) {
+      printJson({ cleared, ok: true });
+      return;
+    }
+    console.log(cleared ? `Kept ${trackId}. Its audio re-embeds and rejoins the ranking on the next sweep.` : `${trackId} was not quarantined \u2014 nothing to clear.`);
+  });
   catalogue.command("crawl").description("Run one bounded, resumable pass of the catalogue crawler").option("--dry-run", "Report the seed plan and write nothing at all", false).option("--limit <limit>", "Frontier nodes to expand this pass", "10").option("--max-hop <maxHop>", "Graph distance from a seed label (0-3)", "2").option("--json", "Print JSON", false).action(async (options) => {
     const { crawlCatalogueCommand: crawlCatalogueCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCrawlCatalogue(options, crawlCatalogueCommand2);
@@ -8793,6 +8842,10 @@ function addAdminCommands(program2) {
     const { backfillAppleMusicCommand: backfillAppleMusicCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runBackfillAppleMusic(options, backfillAppleMusicCommand2);
   });
+  backfill.command("apple-catalogue").description("Resolve Apple URLs + album facts for catalogue tracks (batched exact ISRC)").option("--dry-run", "Report the eligible set without resolving or writing", false).option("--limit <limit>", "Max catalogue rows to resolve", "50").option("--json", "Print JSON", false).action(async (options) => {
+    const { backfillAppleCatalogueCommand: backfillAppleCatalogueCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
+    await runBackfillAppleCatalogue(options, backfillAppleCatalogueCommand2);
+  });
   backfill.command("artists").description("Back-fill the artist entity (artists + track_artists) for existing findings").option("--dry-run", "Report which findings would be upserted without touching the DB", false).option("--limit <limit>", "Max findings to process", "50").option("--json", "Print JSON", false).action(async (options) => {
     const { backfillArtistsCommand: backfillArtistsCommand2 } = await Promise.resolve().then(() => (init_admin_artists(), exports_admin_artists));
     await runBackfillArtists(options, backfillArtistsCommand2);
@@ -8805,6 +8858,10 @@ function addAdminCommands(program2) {
     const { backfillLabelImagesCommand: backfillLabelImagesCommand2 } = await Promise.resolve().then(() => (init_admin_labels(), exports_admin_labels));
     await runBackfillLabelImages(options, backfillLabelImagesCommand2);
   });
+  backfill.command("cover-masters").description("Resolve owned \u22641200\xB2 cover masters (album/artist) into R2").option("--kind <kind>", "Which entity to drain: album | artist", "album").option("--dry-run", "Report the eligible worklist without any fetch or write", false).option("--limit <limit>", "Max entities to process", "50").option("--json", "Print JSON", false).action(async (options) => {
+    const { backfillCoverMastersCommand: backfillCoverMastersCommand2 } = await Promise.resolve().then(() => (init_admin_covers(), exports_admin_covers));
+    await runBackfillCoverMasters(options, backfillCoverMastersCommand2);
+  });
   artists.command("resolve").description("Resolve an artist's social identity (MB url-rels + Firecrawl gap-fill)").argument("[artistId]").option("--queue", "Show the resolve worklist (artists awaiting resolution), oldest first", false).option("--limit <limit>", "Number of artists to show with --queue", "50").option("--json", "Print JSON", false).allowExcessArguments().action(async (artistId, options) => {
     if (options.queue) {
       const { listArtistsCommand: listArtistsCommand2 } = await Promise.resolve().then(() => (init_admin_artists(), exports_admin_artists));
@@ -9213,23 +9270,30 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
   let cursor;
   let dryRun = options.dryRun;
   let throttled = false;
+  let breakerTripped = false;
   let configured = true;
+  let albumFactsWritten = 0;
   while (resolved.length + unresolved.length + failed.length < limit) {
     const remaining = limit - (resolved.length + unresolved.length + failed.length);
     const result = await backfillAppleMusicCommand2(remaining, options.dryRun, cursor);
     dryRun = result.dryRun;
     configured = result.configured;
+    albumFactsWritten += result.albumFactsWritten;
     resolved.push(...result.resolved);
     unresolved.push(...result.unresolved);
     failed.push(...result.failed);
     skipped.push(...result.skipped);
     if (!options.json) {
       const verb2 = result.dryRun ? "would resolve" : "resolved";
-      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.skippedCount} skipped`);
+      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.skippedCount} skipped; ${result.albumFactsWritten} album facts`);
     }
     if (!result.configured) {
       break;
     }
+    if (result.breakerTripped) {
+      breakerTripped = true;
+      break;
+    }
     if (result.rateLimited) {
       throttled = true;
       break;
@@ -9241,6 +9305,8 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
   }
   if (options.json) {
     printSweepJson({
+      albumFactsWritten,
+      breakerTripped,
       configured,
       dryRun,
       failed,
@@ -9259,7 +9325,7 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
     return;
   }
   const verb = dryRun ? "Would resolve" : "Resolved";
-  console.log(`${verb} ${resolved.length} Apple Music URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${skipped.length} skipped.`);
+  console.log(`${verb} ${resolved.length} Apple Music URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${skipped.length} skipped; ${albumFactsWritten} album facts.`);
   for (const item of resolved) {
     console.log(`  ${item.logId}: ${item.url}`);
   }
@@ -9270,6 +9336,72 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
     process.exitCode = 1;
   }
 }
+async function runBackfillAppleCatalogue(options, backfillAppleCatalogueCommand2) {
+  const limit = parseListLimit(options.limit);
+  const resolved = [];
+  const unresolved = [];
+  const failed = [];
+  let dryRun = options.dryRun;
+  let throttled = false;
+  let breakerTripped = false;
+  let configured = true;
+  let albumFactsWritten = 0;
+  while (resolved.length + unresolved.length + failed.length < limit) {
+    const remaining = limit - (resolved.length + unresolved.length + failed.length);
+    const result = await backfillAppleCatalogueCommand2(remaining, options.dryRun);
+    dryRun = result.dryRun;
+    configured = result.configured;
+    albumFactsWritten += result.albumFactsWritten;
+    resolved.push(...result.resolved);
+    unresolved.push(...result.unresolved);
+    failed.push(...result.failed);
+    if (!options.json) {
+      const verb2 = result.dryRun ? "would resolve" : "resolved";
+      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.albumFactsWritten} album facts`);
+    }
+    if (!result.configured) {
+      break;
+    }
+    if (result.breakerTripped) {
+      breakerTripped = true;
+      break;
+    }
+    if (result.rateLimited) {
+      throttled = true;
+      break;
+    }
+    if (result.resolvedCount === 0 && result.unresolvedCount === 0 && result.failedCount === 0) {
+      break;
+    }
+  }
+  if (options.json) {
+    printSweepJson({
+      albumFactsWritten,
+      breakerTripped,
+      configured,
+      dryRun,
+      failed,
+      rateLimited: throttled,
+      resolved,
+      resolvedCount: resolved.length,
+      unresolved,
+      unresolvedCount: unresolved.length
+    }, failed.length);
+    return;
+  }
+  if (!configured) {
+    console.log("Apple catalogue backfill is not configured (the Worker's MusicKit secrets are unset) \u2014 nothing resolved.");
+    return;
+  }
+  const verb = dryRun ? "Would resolve" : "Resolved";
+  console.log(`${verb} ${resolved.length} catalogue Apple URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${albumFactsWritten} album facts.`);
+  for (const item of failed) {
+    console.log(`  ${item.trackId}: ${item.error}`);
+  }
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
 async function runBackfillArtists(options, backfillArtistsCommand2) {
   const limit = parseListLimit(options.limit);
   const upserted = [];
@@ -9362,6 +9494,60 @@ async function runBackfillArtistImages(options, backfillArtistImagesCommand2) {
     process.exitCode = 1;
   }
 }
+async function runBackfillCoverMasters(options, backfillCoverMastersCommand2) {
+  const limit = parseListLimit(options.limit);
+  const kind = options.kind === "artist" ? "artist" : "album";
+  const resolved = [];
+  const none = [];
+  const failed = [];
+  let cursor;
+  let dryRun = options.dryRun;
+  while (resolved.length + none.length + failed.length < limit) {
+    const remaining = limit - (resolved.length + none.length + failed.length);
+    const result = await backfillCoverMastersCommand2(kind, remaining, options.dryRun, cursor);
+    dryRun = result.dryRun;
+    resolved.push(...result.resolved);
+    none.push(...result.none);
+    failed.push(...result.failed);
+    if (!options.json) {
+      const verb2 = result.dryRun ? "would resolve" : "resolved";
+      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.noneCount} without a source; ${result.failedCount} failed`);
+    }
+    if (result.nextCursor === null) {
+      break;
+    }
+    cursor = result.nextCursor;
+  }
+  if (options.json) {
+    printJson({
+      dryRun,
+      failed,
+      failedCount: failed.length,
+      kind,
+      none,
+      noneCount: none.length,
+      ok: true,
+      rateLimited: false,
+      resolved,
+      resolvedCount: resolved.length
+    });
+    if (failed.length > 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const verb = dryRun ? "Would resolve" : "Resolved";
+  console.log(`${verb} ${resolved.length} ${kind} cover master(s); ${none.length} without a source; ${failed.length} failed.`);
+  for (const slug of resolved) {
+    console.log(`  ${slug}`);
+  }
+  for (const item of failed) {
+    console.log(`  ${item.slug}: ${item.error}`);
+  }
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
 async function runBackfillLabelImages(options, backfillLabelImagesCommand2) {
   const limit = parseListLimit(options.limit);
   const resolved = [];
@@ -10280,7 +10466,8 @@ async function runCatalogueRank(options, catalogueRankCommand2) {
     printJson({ ok: true, summary });
     return;
   }
-  console.log(`Ranked ${summary.scored} against ${summary.embeddedFindings} embedded findings; prioritized ${summary.prioritized} for capture. ${summary.remaining} still stale.`);
+  const quarantine = summary.quarantined > 0 ? ` Quarantined ${summary.quarantined} as wrong audio.` : "";
+  console.log(`Ranked ${summary.scored} against ${summary.embeddedFindings} embedded findings; prioritized ${summary.prioritized} for capture.${quarantine} ${summary.remaining} still stale.`);
 }
 async function runCatalogueList(options, catalogueListCommand2) {
   const { summary, tracks } = await catalogueListCommand2({
@@ -10292,11 +10479,17 @@ async function runCatalogueList(options, catalogueListCommand2) {
     return;
   }
   if (tracks.length === 0) {
-    console.log("Nothing out there yet.");
+    console.log(options.lens === "quarantine" ? "No wrong-audio captures." : "Nothing out there yet.");
     return;
   }
   for (const track of tracks) {
     const identity = `${track.artists.join(", ")} \u2014 ${track.title}`;
+    if (options.lens === "quarantine") {
+      const collided = track.nearestFinding;
+      const why2 = collided ? `its audio came back as ${collided.logId ? `${collided.logId} ` : ""}${collided.artists.join(", ")} \u2014 ${collided.title}` : "its audio matched a track already in the archive";
+      console.log(`wrong-audio  ${identity.padEnd(52)} ${why2}`);
+      continue;
+    }
     const dup = track.duplicateOf;
     const dupWhy = dup ? `already in the archive \u2014 ${dup.logId ? `${dup.logId} ` : ""}${dup.artists.join(", ")} \u2014 ${dup.title}` : null;
     if (options.lens === "capture") {

package/package.json

@@ -31,5 +31,5 @@
     "url": "git+https://github.com/mauricekleine/fluncle.git"
   },
   "type": "module",
-  "version": "0.139.0"
+  "version": "0.141.0"
 }