fluncle 0.181.0 → 0.183.0

package/bin/fluncle.mjs

@@ -561,7 +561,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.181.0".trim() ? "0.181.0".trim() : "0.1.0";
+  currentVersion = "0.183.0".trim() ? "0.183.0".trim() : "0.1.0";
 });
 
 // src/update-notifier.ts
@@ -2260,7 +2260,7 @@ function parseVersion2(version) {
 var currentVersion2, latestReleaseUrl = "https://api.github.com/repos/mauricekleine/fluncle/releases/latest";
 var init_version2 = __esm(() => {
   init_output();
-  currentVersion2 = "0.181.0".trim() ? "0.181.0".trim() : "0.1.0";
+  currentVersion2 = "0.183.0".trim() ? "0.183.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -3134,7 +3134,7 @@ var init_src = __esm(() => {
       ],
       kind: "cron",
       name: "cron.label-releases",
-      operatorNotes: "every 24h, run by a rave-02 HOST systemd timer (docs/agents/hermes/label-releases-timer/). The FRESHNESS TAP (D8): MusicBrainz WALKS the graph (cron.crawl) but lags a release ~2 weeks; Spotify has it day one, so this mints METADATA-ONLY catalogue rows (a `tracks` row with no `findings` row) for each ENABLED seed label's fresh releases with their real dates — closing the /fresh lag cliff. Runs OFF the official (dev-mode) Spotify app, which is rate-limited to death at its tier and must stay for user paths: the box reads the due seed labels (`list_label_releases_work`), runs an Apify Spotify-scraper actor per label (`label:\"<name>\" tag:new`), maps each result album (inline tracks[] + ISRCs + artists[]) to a candidate, and POSTs them to the agent-tier `backfill_label_releases` op — where the WORKER re-runs the FULL gate (the box's verdict is never trusted) and mints. The gate: artist-grounding (an album's Spotify artist already in `artists.spotify_artist_id` — the PRIMARY anchor that stops cross-genre homonym junk, always required) AND, when the actor gives a label signal (album_label/copyright — both null in albums-search mode, so grounding-only there), an exact fold-match to the seed name. It certifies nothing, publishes nothing, never widens the graph (no new labels, no artist hops). Deduped against the MB crawl from both directions (Spotify id/uri/ISRC + same-album title fold). Reuses the anchor sweep's APIFY_API_TOKEN (no new secret). Calls the oRPC HTTP endpoints directly (no CLI command the pinned box CLI would lack). Zero LLM tokens. Source: docs/agents/hermes/scripts/label-releases-sweep.*. See docs/catalogue-crawler.md.",
+      operatorNotes: "every 24h, run by a rave-02 HOST systemd timer (docs/agents/hermes/label-releases-timer/). The FRESHNESS TAP (D8): MusicBrainz WALKS the graph (cron.crawl) but lags a release ~2 weeks; Spotify has it day one, so this mints METADATA-ONLY catalogue rows (a `tracks` row with no `findings` row) for each ENABLED seed label's fresh releases with their real dates — closing the /fresh lag cliff. The WORKER does all of it (`backfill_label_releases`, agent tier): it searches the official Spotify API (`label:\"<name>\" tag:new`), reads each hit as a SINGLE `GET /albums/{id}` then `GET /tracks/{id}` (the batch endpoints are 403 at our tier), and mints. The box sweep is a thin HTTP TRIGGER that POSTs bounded passes with the agent token — no vendor token, no CLI dependency (a pinned box CLI missing a flag broke an earlier run). The gate, both required: artist-grounding (an album's Spotify artist already in `artists.spotify_artist_id` — the PRIMARY anchor that stops cross-genre homonym junk) AND an EXACT fold-match of the seed name in the ℗/© copyright; an album with no release_date is dropped outright (/fresh could never show it). BUDGET: the tap shares the official app's per-app window with the user-facing paths, so it paces itself against the shared call meter and stops at a FRACTION of the window (its own ceiling) — user write paths get the window, the tap takes only slack. Hitting that ceiling ends the pass cleanly and the durable per-label cadence stamps resume it next tick. It certifies nothing, publishes nothing, never widens the graph (no new labels, no artist hops). Deduped against the MB crawl from both directions (Spotify id/uri/ISRC + same-album title fold). No vendor spend and zero LLM tokens. Source: docs/agents/hermes/scripts/label-releases-sweep.*. See docs/catalogue-crawler.md.",
       probeConfig: {
         cadenceMs: 24 * 60 * MINUTE_MS,
         cronName: "fluncle-label-releases",
@@ -3212,6 +3212,19 @@ var init_src = __esm(() => {
       title: "Recording MBIDs",
       weights: { status: "hidden" }
     },
+    {
+      command: "fluncle admin backfills artist-edges",
+      exposedContent: [
+        "fold each edge-less track's artists_json names onto existing artist identities → track_artists edges"
+      ],
+      kind: "cron",
+      name: "cron.artist-edges",
+      operatorNotes: "every 60m, run by a rave-02 HOST systemd timer (docs/agents/hermes/artist-edges-timer/). The track_artists GRAPH BACKFILL (RFC artist-primary-capture, slice 0): the graph is crawl-era-only (born 2026-07-15) — only ~12.3k of ~37.5k tracks carry edges — so this folds each edge-less track's `artists_json` NAMES onto EXISTING `artists` identities and writes the `track_artists` edges, making the graph as full as honest matching allows (slice 1's identity-keyed capture authorization reads it). The matcher is IDENTITY-HONEST: each name matches by exact case-insensitive fold, then via `artist_aliases` (kind='name', status auto|confirmed — the search resolver's alias semantics); a fold two distinct identities share is ambiguous and matches nothing (fail-closed). It MINTS NOTHING — a bare name is not enough identity to create an entity — and reports the UNMATCHED RESIDUAL (credited names with no identity), which decides whether a later paced MusicBrainz credit-sweep is worth running. METADATA / GRAPH IDENTITY ONLY — it certifies nothing and publishes nothing (agent tier, the `backfill_recording_mbids` precedent). Worker-paced with NO vendor call (pure DB set-based matching, so no rate limit / circuit breaker): one bounded batch per tick folds the whole ~1.8k-row artist+alias corpus into one in-memory map and matches each track batch against it. The `tracks` row carries the durable reliability state (the `artist_edges_backfilled_at` stamp on EVERY visited row — matched, partial, or zero — so the worklist drains and a re-run is a no-op). New tracks are minted WITH edges (publish path + crawler link), so this catches history up and drains in a handful of ticks. Zero LLM tokens. Source: docs/agents/hermes/scripts/artist-edges-sweep.*. See docs/artist-relationship.md.",
+      probeConfig: { cadenceMs: 60 * MINUTE_MS, cronName: "fluncle-artist-edges", kind: "cron" },
+      statusDescription: "folds artists_json names onto artist identities",
+      title: "Artist edges",
+      weights: { status: "hidden" }
+    },
     {
       command: "fluncle admin backfills label-lineage",
       exposedContent: [
@@ -4136,6 +4149,7 @@ __export(exports_admin_tracks, {
   backfillRecordingMbidsCommand: () => backfillRecordingMbidsCommand,
   backfillLastfmCommand: () => backfillLastfmCommand,
   backfillDiscogsCommand: () => backfillDiscogsCommand,
+  backfillArtistEdgesCommand: () => backfillArtistEdgesCommand,
   backfillAppleMusicCommand: () => backfillAppleMusicCommand,
   backfillAppleCatalogueCommand: () => backfillAppleCatalogueCommand
 });
@@ -4328,6 +4342,13 @@ async function backfillRecordingMbidsCommand(limit, dryRun, cursor) {
   }
   return adminApiPost(`/api/admin/backfill/recording-mbids?${params.toString()}`);
 }
+async function backfillArtistEdgesCommand(limit, dryRun, cursor) {
+  const params = new URLSearchParams({ dryRun: String(dryRun), limit: String(limit) });
+  if (cursor) {
+    params.set("cursor", cursor);
+  }
+  return adminApiPost(`/api/admin/backfill/artist-edges?${params.toString()}`);
+}
 async function vehiclesCommand(limit) {
   const tracks = await fetchAdminTracks({ hasVideo: true, max: limit, order: "desc" });
   return tracks.map((track) => ({
@@ -9741,6 +9762,10 @@ function addAdminCommands(program2) {
     const { backfillRecordingMbidsCommand: backfillRecordingMbidsCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runBackfillRecordingMbids(options, backfillRecordingMbidsCommand2);
   });
+  backfill.command("artist-edges").description("Fold artists_json names onto existing artist identities \u2192 track_artists").option("--dry-run", "Report the classification without writing edges or stamps", false).option("--limit <limit>", "Max tracks to visit", "200").option("--json", "Print JSON", false).action(async (options) => {
+    const { backfillArtistEdgesCommand: backfillArtistEdgesCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
+    await runBackfillArtistEdges(options, backfillArtistEdgesCommand2);
+  });
   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("--retry-none", "First re-queue a bounded batch of terminal none rows to pending, then run the pass", 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);
@@ -10740,6 +10765,54 @@ async function runBackfillRecordingMbids(options, backfillRecordingMbidsCommand2
     process.exitCode = 1;
   }
 }
+async function runBackfillArtistEdges(options, backfillArtistEdgesCommand2) {
+  const limit = parseListLimit(options.limit) ?? 200;
+  const fullyMatched = [];
+  const partiallyMatched = [];
+  const zeroMatched = [];
+  let cursor;
+  let dryRun = options.dryRun;
+  let edgesWritten = 0;
+  let scanned = 0;
+  let unmatchedNames = 0;
+  while (scanned < limit) {
+    const remaining = limit - scanned;
+    const result = await backfillArtistEdgesCommand2(remaining, options.dryRun, cursor);
+    dryRun = result.dryRun;
+    scanned += result.scanned;
+    edgesWritten += result.edgesWritten;
+    unmatchedNames += result.unmatchedNames;
+    fullyMatched.push(...result.fullyMatched);
+    partiallyMatched.push(...result.partiallyMatched);
+    zeroMatched.push(...result.zeroMatched);
+    if (!options.json) {
+      const verb2 = result.dryRun ? "would write" : "wrote";
+      console.log(`  \u2026visited ${result.scanned}; ${verb2} ${result.edgesWritten} edge(s); ${result.fullyMatchedCount} full, ${result.partiallyMatchedCount} partial, ${result.zeroMatchedCount} zero; ${result.unmatchedNames} name(s) unmatched`);
+    }
+    if (result.nextCursor === null) {
+      break;
+    }
+    cursor = result.nextCursor;
+  }
+  if (options.json) {
+    printJson({
+      dryRun,
+      edgesWritten,
+      fullyMatched,
+      fullyMatchedCount: fullyMatched.length,
+      ok: true,
+      partiallyMatched,
+      partiallyMatchedCount: partiallyMatched.length,
+      scanned,
+      unmatchedNames,
+      zeroMatched,
+      zeroMatchedCount: zeroMatched.length
+    });
+    return;
+  }
+  const verb = dryRun ? "Would write" : "Wrote";
+  console.log(`${verb} ${edgesWritten} track_artists edge(s) over ${scanned} track(s): ${fullyMatched.length} fully matched, ${partiallyMatched.length} partially, ${zeroMatched.length} with none; ${unmatchedNames} credited name(s) left unmatched.`);
+}
 async function runArtistResolveQueue(options, listArtistsCommand2) {
   const limit = parseListLimit(options.limit);
   const result = await listArtistsCommand2(limit ?? 50);

package/package.json

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