fluncle 0.213.0 → 0.215.0

package/bin/fluncle.mjs

@@ -610,7 +610,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.213.0".trim() ? "0.213.0".trim() : "0.1.0";
+  currentVersion = "0.215.0".trim() ? "0.215.0".trim() : "0.1.0";
 });
 
 // src/update-notifier.ts
@@ -2452,7 +2452,7 @@ function parseVersion2(version) {
 var currentVersion2, latestReleaseUrl = "https://api.github.com/repos/mauricekleine/fluncle/releases/latest";
 var init_version2 = __esm(() => {
   init_output();
-  currentVersion2 = "0.213.0".trim() ? "0.213.0".trim() : "0.1.0";
+  currentVersion2 = "0.215.0".trim() ? "0.215.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -3550,6 +3550,22 @@ var init_src = __esm(() => {
       title: "Spotify anchors",
       weights: { status: "hidden" }
     },
+    {
+      exposedContent: [
+        "mirror the anchored, explicitly allowlisted public catalogue into the shared read-only device replica"
+      ],
+      kind: "cron",
+      name: "cron.device-mirror",
+      operatorNotes: "hourly, run by a host systemd timer (docs/agents/hermes/device-mirror-timer/). Reads one consistent anchored-cut snapshot through a read-only source credential, diffs every whitelisted tuple against the shared device database, then applies dependent-first deletes and parent-first upserts in bounded parameterized batches. The target is mutated IN PLACE: rebuilding it would reset the libSQL replication log and force every device to bootstrap the full database again. A schema-version mismatch stops for an operator migration; the content fingerprint and derived timestamp update only after a verified zero-drift tick. Zero LLM tokens. Source: docs/agents/hermes/scripts/device-mirror.*. See docs/planning/offline-first-mobile-research.md.",
+      probeConfig: {
+        cadenceMs: 60 * MINUTE_MS,
+        cronName: "fluncle-device-mirror",
+        kind: "cron"
+      },
+      statusDescription: "keeps the offline catalogue replica in step",
+      title: "Device catalogue mirror",
+      weights: { status: "hidden" }
+    },
     {
       command: "fluncle admin frontier refresh",
       exposedContent: [
@@ -3781,9 +3797,9 @@ var init_src = __esm(() => {
       weights: { status: "hidden" }
     },
     {
-      command: "fluncle admin backfills discogs && fluncle admin backfills lastfm && fluncle admin backfills apple-music && fluncle admin backfills apple-catalogue",
+      command: "fluncle admin backfills discogs && fluncle admin backfills lastfm && fluncle admin backfills apple-music && fluncle admin backfills apple-catalogue && fluncle admin backfills beatport && fluncle admin backfills discogs-facts",
       exposedContent: [
-        "Discogs id + Last.fm love + Apple Music link repair, findings then catalogue (--no-agent, Worker HTTP)"
+        "Discogs id + Last.fm love + Apple Music link + Beatport link repair, findings then catalogue, then each record's catalogue number (--no-agent, Worker HTTP)"
       ],
       kind: "cron",
       name: "cron.backfill",
@@ -4478,9 +4494,21 @@ __export(exports_admin_telemetry, {
 });
 async function telemetryCommand(options) {
   const params = new URLSearchParams({ limit: String(options.limit) });
+  if (options.blind === true) {
+    params.set("blind", "true");
+  }
   if (options.cursor !== undefined) {
     params.set("cursor", options.cursor);
   }
+  if (options.liar === true) {
+    params.set("liar", "true");
+  }
+  if (options.missing === true) {
+    params.set("missing", "true");
+  }
+  if (options.missingField !== undefined) {
+    params.set("missingField", options.missingField);
+  }
   if (options.ok !== undefined) {
     params.set("ok", String(options.ok));
   }
@@ -4507,16 +4535,50 @@ function cell(value) {
 function padded(columns, widths) {
   return columns.map((column, index) => column.padEnd(widths[index] ?? 0)).join("  ").trimEnd();
 }
-function telemetryLines(page) {
+function cadence(expectedIntervalMs) {
+  if (expectedIntervalMs === null) {
+    return "-";
+  }
+  const units = [
+    { label: "d", milliseconds: 24 * 60 * 60 * 1000 },
+    { label: "h", milliseconds: 60 * 60 * 1000 },
+    { label: "m", milliseconds: 60 * 1000 },
+    { label: "s", milliseconds: 1000 }
+  ];
+  for (const unit of units) {
+    if (expectedIntervalMs % unit.milliseconds === 0) {
+      return `${expectedIntervalMs / unit.milliseconds}${unit.label}`;
+    }
+  }
+  return `${expectedIntervalMs}ms`;
+}
+function telemetryLines(page, options = {}) {
   if (!page.available) {
     return ["Telemetry database is not configured."];
   }
-  if (page.rows.length === 0) {
+  if (options.missing === true || page.missingRoster.length > 0) {
+    if (page.missingRoster.length === 0) {
+      return ["No expected writers are missing."];
+    }
+    const missingHeader = ["MISSING UNIT", "CADENCE"];
+    const missingRows = page.missingRoster.map((entry) => [
+      entry.unit,
+      cadence(entry.expectedIntervalMs)
+    ]);
+    const missingWidths = missingHeader.map((header, index) => Math.max(header.length, ...missingRows.map((row) => row[index]?.length ?? 0)));
+    return [
+      `Expected writers with no run (${missingRows.length})`,
+      padded(missingHeader, missingWidths),
+      ...missingRows.map((row) => padded(row, missingWidths))
+    ];
+  }
+  if (page.rows.length === 0 && page.rollups.length === 0) {
     return ["No run events matched."];
   }
-  const rollupHeader = ["UNIT", "RUNS", "LAST", "OK=0", "LIAR", "BLIND"];
+  const rollupHeader = ["UNIT", "CADENCE", "RUNS", "LAST", "OK=0", "LIAR", "BLIND"];
   const rollupRows = page.rollups.map((rollup) => [
     rollup.unit,
+    cadence(rollup.expectedIntervalMs),
     String(rollup.runCount),
     rollup.lastOccurredAt,
     String(rollup.failedCount),
@@ -4547,15 +4609,18 @@ function telemetryLines(page) {
     row.summaryStatus
   ]);
   const runWidths = runHeader.map((header, index) => Math.max(header.length, ...runRows.map((row) => row[index]?.length ?? 0)));
-  const lines = [
-    `Unit rollups (${page.totalCount} matching runs)`,
-    padded(rollupHeader, rollupWidths),
-    ...rollupRows.map((row) => padded(row, rollupWidths)),
-    "",
-    `Runs (${page.rows.length} on this page)`,
-    padded(runHeader, runWidths),
-    ...runRows.map((row) => padded(row, runWidths))
-  ];
+  const lines = [];
+  if (rollupRows.length > 0) {
+    lines.push("Unit rollups (all runs in the selected time/unit window)", padded(rollupHeader, rollupWidths), ...rollupRows.map((row) => padded(row, rollupWidths)));
+  }
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  if (runRows.length === 0) {
+    lines.push("No evidence rows matched.");
+  } else {
+    lines.push(`Evidence rows (${page.rows.length} of ${page.totalCount} matching; this page)`, padded(runHeader, runWidths), ...runRows.map((row) => padded(row, runWidths)));
+  }
   if (page.nextCursor !== null) {
     lines.push("", `Next cursor: ${page.nextCursor}`);
   }
@@ -4663,6 +4728,7 @@ __export(exports_admin_tracks, {
   captureQueueCommand: () => captureQueueCommand,
   backfillRecordingMbidsCommand: () => backfillRecordingMbidsCommand,
   backfillLastfmCommand: () => backfillLastfmCommand,
+  backfillDiscogsFactsCommand: () => backfillDiscogsFactsCommand,
   backfillDiscogsCommand: () => backfillDiscogsCommand,
   backfillBeatportCommand: () => backfillBeatportCommand,
   backfillArtistEdgesCommand: () => backfillArtistEdgesCommand,
@@ -4848,6 +4914,10 @@ async function backfillAppleMusicCommand(limit, dryRun, cursor) {
   }
   return adminApiPost(`/api/v1/admin/backfill/apple-music?${params.toString()}`);
 }
+async function backfillDiscogsFactsCommand(limit, dryRun) {
+  const params = new URLSearchParams({ dryRun: String(dryRun), limit: String(limit) });
+  return adminApiPost(`/api/v1/admin/backfill/discogs-facts?${params.toString()}`);
+}
 async function backfillBeatportCommand(limit, dryRun, cursor) {
   const params = new URLSearchParams({ dryRun: String(dryRun), limit: String(limit) });
   if (cursor) {
@@ -9768,7 +9838,19 @@ function addAdminCommands(program2) {
   adminTelemetry.action(() => {
     adminTelemetry.outputHelp();
   });
-  adminTelemetry.command("read").description("Run-ledger rows plus per-unit rollups").option("--unit <unit>", "Only this systemd unit").option("--since <iso>", "Only runs at or after this occurred-at instant").option("--until <iso>", "Only runs at or before this occurred-at instant").option("--ok <true|false>", "Filter by the Worker's derived run verdict").option("--limit <limit>", "Rows to show (1-100)", "50").option("--cursor <cursor>", "Opaque cursor from the previous page").option("--json", "Print the lossless 20-column rows as JSON", false).action(async (options) => {
+  adminTelemetry.command("read").description("Run-ledger rows plus per-unit rollups").option("--unit <unit>", "Only this systemd unit").option("--since <iso|age>", "Only runs at or after this instant (ISO, 24h, or 90m)").option("--until <iso>", "Only runs at or before this occurred-at instant").option("--ok <true|false>", "Filter by the Worker's derived run verdict").option("--liar", "Only rows whose claimed ok contradicts the derived verdict").option("--blind", "Only rows missing every work counter").option("--missing-field <name>", "Only rows missing this canonical counter").option("--missing", "List expected writers with no run in the selected window").option("--limit <limit>", "Rows to show (1-100)", "50").option("--cursor <cursor>", "Opaque cursor from the previous page").option("--json", "Print lossless rows, rollups, and missing writers as JSON", false).addHelpText("after", `
+Evidence and rollups:
+  --ok, --liar, --blind, and --missing-field filter evidence rows only.
+  RUNS always counts every run in the selected --unit/--since/--until window.
+  --missing is a separate roster view; combine it only with --unit/--since/--until.
+  --missing-field names: checked, produced, queue_depth, errors, expected_interval_ms.
+
+JSON field reference:
+  top-level ok        Request acknowledgement only; never a run verdict.
+  rows[].ok           Worker's derived verdict for that run.
+  rollups[]           Whole-window unit totals, including expectedIntervalMs.
+  missingRoster[]     Expected writers with no run in the selected window.
+`).action(async (options) => {
     const { telemetryCommand: telemetryCommand2 } = await Promise.resolve().then(() => (init_admin_telemetry(), exports_admin_telemetry));
     await runAdminTelemetry(options, telemetryCommand2);
   });
@@ -10409,6 +10491,10 @@ function addAdminCommands(program2) {
     const { backfillDiscogsCommand: backfillDiscogsCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runBackfillDiscogs(options, backfillDiscogsCommand2);
   });
+  backfill.command("discogs-facts").description("Read album catalogue numbers + styles from already-resolved Discogs releases").option("--dry-run", "Report the eligible albums without reading Discogs or writing", false).option("--limit <limit>", "Max albums to read", "50").option("--json", "Print JSON", false).action(async (options) => {
+    const { backfillDiscogsFactsCommand: backfillDiscogsFactsCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
+    await runBackfillDiscogsFacts(options, backfillDiscogsFactsCommand2);
+  });
   backfill.command("apple-music").description("Resolve missing Apple Music URLs for published findings (exact ISRC match)").option("--dry-run", "Report the eligible set without resolving or writing", false).option("--limit <limit>", "Max findings to resolve", "50").option("--json", "Print JSON", false).action(async (options) => {
     const { backfillAppleMusicCommand: backfillAppleMusicCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runBackfillAppleMusic(options, backfillAppleMusicCommand2);
@@ -11206,6 +11292,63 @@ async function runBackfillAppleCatalogue(options, backfillAppleCatalogueCommand2
     process.exitCode = 1;
   }
 }
+async function runBackfillDiscogsFacts(options, backfillDiscogsFactsCommand2) {
+  const limit = parseListLimit(options.limit);
+  const resolved = [];
+  const none = [];
+  const failed = [];
+  let dryRun = options.dryRun;
+  let throttled = false;
+  let configured = true;
+  while (resolved.length + none.length + failed.length < limit) {
+    const remaining = limit - (resolved.length + none.length + failed.length);
+    const result = await backfillDiscogsFactsCommand2(remaining, options.dryRun);
+    dryRun = result.dryRun;
+    configured = result.configured;
+    resolved.push(...result.resolved);
+    none.push(...result.none);
+    failed.push(...result.failed);
+    if (!options.json) {
+      const verb2 = result.dryRun ? "would read" : "read";
+      console.log(`  \u2026${verb2} ${result.resolvedCount} catalogue number(s); ${result.noneCount} with none; ${result.failedCount} failed`);
+    }
+    if (!result.configured) {
+      break;
+    }
+    if (result.rateLimited) {
+      throttled = true;
+      break;
+    }
+    if (result.resolvedCount === 0 && result.noneCount === 0 && result.failedCount === 0) {
+      break;
+    }
+  }
+  if (options.json) {
+    printSweepJson({
+      configured,
+      dryRun,
+      failed,
+      none,
+      noneCount: none.length,
+      rateLimited: throttled,
+      resolved,
+      resolvedCount: resolved.length
+    }, failed.length);
+    return;
+  }
+  if (!configured) {
+    console.log("Discogs facts backfill is not configured (the Worker's DISCOGS_USER_TOKEN is unset) \u2014 nothing read.");
+    return;
+  }
+  const verb = dryRun ? "Would read" : "Read";
+  console.log(`${verb} ${resolved.length} catalogue number(s); ${none.length} release(s) carry none; ${failed.length} failed.`);
+  for (const item of failed) {
+    console.log(`  ${item.slug}: ${item.error}`);
+  }
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
 async function runBackfillArtists(options, backfillArtistsCommand2) {
   const limit = parseListLimit(options.limit);
   const upserted = [];
@@ -12677,13 +12820,62 @@ function parseTelemetryOk(value) {
   }
   return value === "true";
 }
-function parseTelemetryTimestamp(value, flag) {
+var telemetryMissingFields = [
+  "checked",
+  "errors",
+  "expected_interval_ms",
+  "produced",
+  "queue_depth"
+];
+function parseTelemetryMissingField(value) {
   if (value === undefined) {
     return;
   }
+  const field = telemetryMissingFields.find((candidate) => candidate === value);
+  if (field === undefined) {
+    throw new Error(`--missing-field must be one of: ${telemetryMissingFields.join(", ")}`);
+  }
+  return field;
+}
+function parseExplicitTelemetryInstant(value) {
+  if (value.length > 64) {
+    return null;
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(value);
+  if (match === null) {
+    return null;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  const maximumDay = daysInMonth[month - 1];
+  if (maximumDay === undefined || day < 1 || day > maximumDay) {
+    return null;
+  }
   const timestamp = new Date(value);
-  if (Number.isNaN(timestamp.getTime())) {
-    throw new Error(`${flag} must be an ISO-8601 timestamp`);
+  return Number.isNaN(timestamp.getTime()) ? null : timestamp;
+}
+function parseTelemetryTimestamp(value, flag) {
+  if (value === undefined) {
+    return;
+  }
+  const relative = flag === "--since" ? value.match(/^([1-9]\d*)([mhdw])$/) : null;
+  if (relative !== null) {
+    const amount = Number(relative[1]);
+    const unitMs = relative[2] === "w" ? 604800000 : relative[2] === "d" ? 86400000 : relative[2] === "h" ? 3600000 : 60000;
+    const durationMs = amount * unitMs;
+    const maximumDurationMs = 315360000000;
+    if (value.length > 32 || !Number.isSafeInteger(amount) || !Number.isSafeInteger(durationMs) || durationMs > maximumDurationMs) {
+      throw new Error("--since relative age must not exceed 3650d");
+    }
+    return value;
+  }
+  const timestamp = parseExplicitTelemetryInstant(value);
+  if (timestamp === null) {
+    const expected = flag === "--since" ? "an explicit ISO-8601 instant (with Z or offset) or a relative age like 24h or 90m" : "an explicit ISO-8601 instant with Z or offset";
+    throw new Error(`${flag} must be ${expected}`);
   }
   return timestamp.toISOString();
 }
@@ -12755,14 +12947,23 @@ async function runAdminAttention(options, attentionQueueCommand2) {
 `));
 }
 async function runAdminTelemetry(options, telemetryCommand2) {
+  if (options.missing === true && (options.blind === true || options.cursor !== undefined || options.liar === true || options.missingField !== undefined || options.ok !== undefined)) {
+    throw new Error("--missing cannot be combined with --ok, --liar, --blind, --missing-field, or --cursor");
+  }
   const since = parseTelemetryTimestamp(options.since, "--since");
   const until = parseTelemetryTimestamp(options.until, "--until");
-  if (since !== undefined && until !== undefined && since > until) {
+  const sinceMs = since === undefined ? Number.NaN : Date.parse(since);
+  const untilMs = until === undefined ? Number.NaN : Date.parse(until);
+  if (Number.isFinite(sinceMs) && Number.isFinite(untilMs) && sinceMs > untilMs) {
     throw new Error("--since must be before or equal to --until");
   }
   const page = await telemetryCommand2({
+    blind: options.blind,
     cursor: options.cursor,
+    liar: options.liar,
     limit: parseTelemetryLimit(options.limit),
+    missing: options.missing,
+    missingField: parseTelemetryMissingField(options.missingField),
     ok: parseTelemetryOk(options.ok),
     since,
     unit: options.unit,
@@ -12773,7 +12974,7 @@ async function runAdminTelemetry(options, telemetryCommand2) {
     return;
   }
   const { telemetryLines: telemetryLines2 } = await Promise.resolve().then(() => (init_admin_telemetry(), exports_admin_telemetry));
-  console.log(telemetryLines2(page).join(`
+  console.log(telemetryLines2(page, { missing: options.missing === true }).join(`
 `));
 }
 async function runAdminQueue(options, queueCommand2) {
@@ -13240,6 +13441,7 @@ var stringOptions = new Set([
   "--max-hop",
   "--max-overlap",
   "--metrics",
+  "--missing-field",
   "--mime",
   "--min-phrase-words",
   "--model",
@@ -13323,5 +13525,6 @@ if (__require.main == __require.module) {
   await main();
 }
 export {
+  parseTelemetryTimestamp,
   createProgram
 };

package/package.json

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