@drakulavich/kesha-voice-kit 1.31.0 → 2.0.0

package/src/engine-install.ts

@@ -2,22 +2,34 @@ import { dirname, join, resolve, sep } from "path";
 import { errorMessage } from "./error-utils";
 import { homedir, tmpdir } from "os";
 import { existsSync, mkdirSync, chmodSync, accessSync, constants, rmSync } from "fs";
-import { getDescribe, getEngineBinPath, protocolEnv, spawnEngineProcess } from "./engine";
+import { getDescribe, getEngineBinPath } from "./engine";
 import { engineFunctionalHealth, probeExecutable, readExecutableVersion } from "./engine-health";
-import { engineTarget, engineTargetEntries, isDarwinArm64, targetKey } from "./engine-targets";
+import {
+  engineTarget,
+  engineTargetEntries,
+  isDarwinArm64,
+  parseSha256Sums,
+  SIDECARS,
+  type SidecarSpec,
+  targetKey,
+} from "./engine-targets";
 import { validateArgv } from "./engine/describe";
-import { engineFailure, KeshaError, readEvents, type StderrOutcome } from "./engine/events";
+import { engineFailure, KeshaError, offProtocolLine } from "./engine/events";
+import { runEngineProcess } from "./engine/spawn";
 import { acquireInstallLock } from "./install-lock";
 import { log } from "./log";
-import { engineVersion } from "./package-info";
+import { engineVersion, injectedEnginePins } from "./package-info";
 import { keshaCacheDir } from "./paths";
 import { createLiveStatus, streamResponseToFile } from "./progress";
-import { registerProcessTree } from "./process-tree";
+import { interruptedRun } from "./process-tree";
+import { DEFAULT_VOICE_ID } from "./voice-routing";
 import {
+  getVersionMarkerPath,
   readInstalledEngineVersion,
   writeInstalledEngineVersion,
 } from "./engine-version-marker";
 
+export { SIDECARS } from "./engine-targets";
 export {
   getVersionMarkerPath,
   readInstalledEngineVersion,
@@ -26,6 +38,120 @@ export {
 
 const GITHUB_REPO = "drakulavich/kesha-voice-kit";
 
+interface ExpectedSha256 {
+  sha256: string;
+  source: string;
+}
+
+/** `package.json#kesha.engine`, injected at publish by `engine-pin.ts`: what every downloaded asset of that Engine hashes to and weighs. */
+export interface AssetPins {
+  version: string;
+  sha256: Readonly<Record<string, string>>;
+  size: Readonly<Record<string, number>>;
+}
+
+/** Without `--engine-version` nothing but the maintainer can make an unverifiable pinned release verifiable. */
+function unverifiableFix(version: string): string {
+  return version === engineVersion
+    ? `report it at https://github.com/${GITHUB_REPO}/issues: the pinned engine release v${version} must publish its checksums.`
+    : `pick a release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases), or run ` +
+        `\`kesha install\` without --engine-version to install the pinned v${engineVersion}.`;
+}
+
+async function fetchSha256Sums(version: string): Promise<Map<string, string>> {
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/SHA256SUMS`;
+  let res: Response;
+  try {
+    res = await fetch(url, { redirect: "follow" });
+  } catch (e) {
+    throw new Error(
+      `Failed to fetch SHA256SUMS for release v${version}: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `Cannot verify engine v${version}: release v${version} publishes no SHA256SUMS (HTTP ${res.status}), ` +
+        `so its binaries cannot be checked before they are installed.\n  Fix: ${unverifiableFix(version)}`,
+    );
+  }
+  return parseSha256Sums(await res.text());
+}
+
+/**
+ * The pinned Engine's assets against the pins, never the network; any other release, and every release
+ * in a source checkout (which carries no pin), against that release's own SHA256SUMS.
+ */
+export function releaseChecksums(
+  version: string,
+  pins: AssetPins | undefined,
+): (assetName: string) => Promise<ExpectedSha256> {
+  let sums: Promise<Map<string, string>> | undefined;
+  return async (assetName) => {
+    if (version === pins?.version) {
+      const pinned = pins.sha256[assetName];
+      if (!pinned) throw new Error(`No pinned SHA-256 for ${assetName} of engine v${version}; this CLI build is incomplete.\n  Fix: report it at https://github.com/${GITHUB_REPO}/issues.`);
+      return { sha256: pinned, source: "its pinned SHA-256" };
+    }
+    sums ??= fetchSha256Sums(version);
+    const sha256 = (await sums).get(assetName);
+    if (!sha256) {
+      throw new Error(
+        `Cannot verify ${assetName}: the SHA256SUMS of release v${version} does not list it, ` +
+          `so it cannot be checked before it is installed.\n  Fix: ${unverifiableFix(version)}`,
+      );
+    }
+    return { sha256, source: `the SHA-256 in the SHA256SUMS of release v${version}` };
+  };
+}
+
+/** Tests that serve a stand-in engine replace these, the way they replace `fetch`. */
+export const engineChecksums = {
+  pins: injectedEnginePins,
+  forRelease: (version: string) => releaseChecksums(version, engineChecksums.pins),
+};
+
+async function sha256OfFile(path: string): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  for await (const chunk of Bun.file(path).stream()) hasher.update(chunk);
+  return hasher.digest("hex");
+}
+
+/** Deletes a download that does not hash to `expected` and returns the refusal; null when it matches. */
+async function rejectMismatchedDownload(
+  path: string,
+  what: string,
+  version: string,
+  expected: ExpectedSha256,
+): Promise<string | null> {
+  const actual = await sha256OfFile(path);
+  if (actual === expected.sha256) return null;
+  rmSync(path, { force: true });
+  return (
+    `${what} from release v${version} does not match ${expected.source}: ` +
+    `expected sha256 ${expected.sha256}, got ${actual}. The download was corrupted or altered, ` +
+    "so it was deleted instead of installed.\n" +
+    `  Fix: re-run \`kesha install\`; if the mismatch persists, report it at https://github.com/${GITHUB_REPO}/issues.`
+  );
+}
+
+/**
+ * Whether a cached asset of the pinned release still hashes to its pin; one that does not is
+ * deleted so the verified download replaces it. `--engine-version` caches are not re-hashed.
+ */
+async function cachedAssetMatchesPin(path: string, assetName: string, what: string, version: string): Promise<boolean> {
+  // KESHA_ENGINE_BIN names the user's own build, which no release pin describes.
+  if (version !== engineChecksums.pins?.version || process.env.KESHA_ENGINE_BIN || !existsSync(path)) return true;
+  const expected = await engineChecksums.forRelease(version)(assetName);
+  const actual = await sha256OfFile(path);
+  if (actual === expected.sha256) return true;
+  log.warn(
+    `Installed ${what} ${assetName} does not match ${expected.source} (expected sha256 ${expected.sha256}, ` +
+      `got ${actual}); deleting it and downloading a verified copy.`,
+  );
+  rmSync(path, { force: true });
+  return false;
+}
+
 export function getEngineBinaryName(
   platform: string = process.platform,
   arch: string = process.arch,
@@ -55,44 +181,6 @@ export function assertPlatformCanInstall(
   }
 }
 
-/** Sidecar spec — centralises AVSpeech (#141) and future sidecars so each is one entry. */
-interface SidecarSpec {
-  /** Written next to the engine binary; Rust probes this exact name. */
-  fileBasename: string;
-  /** Release asset name — may differ from fileBasename (e.g. `say-avspeech-darwin-arm64` vs `say-avspeech`). */
-  assetName: string;
-  displayName: string;
-  availableHint: string;
-  unavailableHint: string;
-}
-
-export const SIDECARS: SidecarSpec[] = [
-  {
-    fileBasename: "say-avspeech",
-    assetName: "say-avspeech-darwin-arm64",
-    displayName: "AVSpeech sidecar",
-    availableHint: "macOS voices available",
-    unavailableHint: "macos-* voices unavailable",
-  },
-  // Kokoro TTS (#207) and speaker diarization (#199) no longer ship as Swift
-  // sidecars — both run in-engine via the native `fluidaudio-rs` binding. Only
-  // the AVSpeech and text-lang sidecars remain.
-  {
-    // Runtime resolver looks for plain `kesha-textlang` next to the engine
-    // (see `rust/src/text_lang.rs::helper_path`), not the platform-suffixed
-    // release-asset name. Mismatch is intentional: the asset name needs the
-    // suffix for GitHub-release uniqueness; the sidecar lookup wants the
-    // unsuffixed binary so the same Rust code path works on the build-time
-    // OUT_DIR baked fallback.
-    fileBasename: "kesha-textlang",
-    assetName: "kesha-textlang-darwin-arm64",
-    displayName: "Text-lang sidecar",
-    availableHint: "detect-text-lang fast path",
-    unavailableHint:
-      "detect-text-lang will fail until next `kesha install` (no swift -e fallback)",
-  },
-];
-
 const RETIRED_SIDECAR_FILENAMES = [
   // Historical installed filenames.
   "kesha-kokoro",
@@ -194,12 +282,22 @@ async function downloadSidecar(
   spec: SidecarSpec,
   binPath: string,
   version: string,
+  checksums: (assetName: string) => Promise<ExpectedSha256>,
 ): Promise<void> {
   if (!isDarwinArm64()) return;
 
   const sidecarPath = join(dirname(binPath), spec.fileBasename);
   const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${spec.assetName}`;
 
+  let expected: ExpectedSha256;
+  try {
+    expected = await checksums(spec.assetName);
+  } catch (e) {
+    rmSync(sidecarPath, { force: true });
+    log.warn(`Could not verify ${spec.displayName} for v${version} (${errorMessage(e)}); ${spec.unavailableHint}.`);
+    return;
+  }
+
   let res: Response;
   try {
     res = await fetch(url, { redirect: "follow" });
@@ -220,6 +318,11 @@ async function downloadSidecar(
   // Catch stream/chmod failures so a sidecar error can't poison the engine install.
   try {
     await streamResponseToFile(res, sidecarPath, spec.displayName);
+    const refusal = await rejectMismatchedDownload(sidecarPath, `${spec.displayName} ${spec.assetName}`, version, expected);
+    if (refusal) {
+      log.warn(`${refusal}\n  ${spec.displayName} not installed; ${spec.unavailableHint}.`);
+      return;
+    }
     chmodSync(sidecarPath, 0o755);
     darwinTrustBinary(sidecarPath, spec.displayName);
     log.success(`${spec.displayName} installed (${spec.availableHint}).`);
@@ -230,7 +333,8 @@ async function downloadSidecar(
   }
 }
 
-async function warmDarwinKokoro(binPath: string): Promise<void> {
+/** `timeoutMs` exists for tests; install always uses the default. */
+export async function warmDarwinKokoro(binPath: string, timeoutMs = 180_000): Promise<void> {
   if (!isDarwinArm64()) return;
   // Kokoro now runs in-engine (FluidAudio CoreML, system_kokoro) — warm it by
   // exercising the engine's own `say`, not a sidecar. The first synthesis
@@ -238,30 +342,28 @@ async function warmDarwinKokoro(binPath: string): Promise<void> {
   if (!existsSync(binPath)) return;
 
   const outPath = join(tmpdir(), `kesha-kokoro-warmup-${process.pid}.wav`);
+  let args: string[];
+  try {
+    const validated = validateArgv(["say", "--voice", DEFAULT_VOICE_ID, "--out", outPath, "Kesha warmup."], await getDescribe());
+    for (const warning of validated.warnings) log.warn(warning);
+    args = validated.argv;
+  } catch (e) {
+    log.warn(`FluidAudio Kokoro warmup skipped (${errorMessage(e)}); first \`kesha say en-*\` may still be slow.`);
+    return;
+  }
   log.progress("Warming FluidAudio Kokoro CoreML cache...");
 
   const startedAt = performance.now();
-  const proc = spawnEngineProcess(
-    binPath,
-    ["say", "--voice", "en-am_michael", "--out", outPath, "Kesha warmup."],
-    ["ignore", "pipe", "pipe"],
-    protocolEnv(),
-  );
-  const tree = registerProcessTree(proc);
-
-  let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    proc.kill();
-  }, 180_000);
-
   try {
-    const [events, exitCode] = await Promise.all([
-      readEvents(proc.stderr as ReadableStream<Uint8Array>),
-      proc.exited,
-    ]);
+    const { exitCode, aborted, events } = await runEngineProcess(binPath, args, {
+      stdio: ["ignore", "ignore", "pipe"],
+      signal: AbortSignal.timeout(timeoutMs),
+    });
 
-    if (timedOut) {
+    // A Ctrl+C that lands while the deadline is stopping the engine is still the user's interrupt.
+    const interrupted = interruptedRun(exitCode);
+    if (interrupted) throw interrupted;
+    if (aborted) {
       log.warn("FluidAudio Kokoro warmup timed out; first `kesha say en-*` may still be slow.");
       return;
     }
@@ -278,13 +380,13 @@ async function warmDarwinKokoro(binPath: string): Promise<void> {
       `FluidAudio Kokoro warmed (${Math.round(performance.now() - startedAt)}ms).`,
     );
   } catch (e) {
+    // A launch failure was never the warmup's to swallow, and an interrupt is the user's.
+    if (e instanceof KeshaError && (e.code === "E_INTERRUPTED" || e.code === "E_ENGINE_SPAWN")) throw e;
     log.warn(
       `FluidAudio Kokoro warmup failed (${errorMessage(e)}); ` +
         "first `kesha say en-*` may still be slow.",
     );
   } finally {
-    clearTimeout(timer);
-    tree.dispose();
     try {
       rmSync(outPath, { force: true });
     } catch {
@@ -358,14 +460,22 @@ async function refreshCachedEngine(
   // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them);
   // skip on read-only fs (Nix-store) to avoid confusing "install failed" warnings.
   if (canWriteEngineDir) {
+    const checksums = engineChecksums.forRelease(version);
     await Promise.all(
       SIDECARS.map(async (spec) => {
         const path = join(engineDir, spec.fileBasename);
         // Re-trust before probing, for the Sequoia upgrade scenario: a provenance-blocked
         // sidecar is SIGKILLed on spawn, and re-downloading it would not lift the block.
-        if (existsSync(path)) darwinTrustBinary(path, spec.displayName);
+        let pinned = false;
+        try {
+          pinned = existsSync(path) && (await cachedAssetMatchesPin(path, spec.assetName, spec.displayName, version));
+        } catch (e) {
+          log.warn(`Could not read ${spec.displayName} at ${path} (${errorMessage(e)}); removing it and downloading it again.`);
+          rmSync(path, { force: true });
+        }
+        if (pinned) darwinTrustBinary(path, spec.displayName);
         if (await sidecarNeedsDownload(spec, engineDir)) {
-          await downloadSidecar(spec, binPath, version);
+          await downloadSidecar(spec, binPath, version, checksums);
         }
       }),
     );
@@ -399,9 +509,10 @@ export async function waitUntilSpawnable(binPath: string, deadlineMs = 60_000):
     lastError = health.status === "unusable" ? health.detail : "the binary is gone";
     // Only a lock is worth waiting out — a missing or corrupt binary never becomes spawnable.
     if (!isTransientSpawnLock(lastError)) {
-      throw new Error(
-        `Downloaded the engine to ${binPath} but it could not be started: ${lastError}\n` +
-          `  Fix: delete ${dirname(binPath)} and re-run \`kesha install\`.`,
+      throw new KeshaError(
+        "E_ENGINE_SPAWN",
+        `Downloaded the engine to ${binPath} but it could not be started: ${lastError}`,
+        { hint: `delete ${dirname(binPath)} and re-run \`kesha install\`.` },
       );
     }
     if (Date.now() + delay > deadline) break;
@@ -413,11 +524,15 @@ export async function waitUntilSpawnable(binPath: string, deadlineMs = 60_000):
     delay = Math.min(delay * 2, 2_000);
   }
 
-  throw new Error(
+  throw new KeshaError(
+    "E_ENGINE_SPAWN",
     `Downloaded the engine to ${binPath} but it is still locked after ` +
-      `${Math.round(deadlineMs / 1000)}s: ${lastError}\n` +
-      `  Fix: a security scanner is likely holding the file. Re-run \`kesha install\`, ` +
-      `or exclude ${dirname(binPath)} from real-time scanning.`,
+      `${Math.round(deadlineMs / 1000)}s: ${lastError}`,
+    {
+      hint:
+        "a security scanner is likely holding the file. Re-run `kesha install`, " +
+        `or exclude ${dirname(binPath)} from real-time scanning.`,
+    },
   );
 }
 
@@ -466,13 +581,22 @@ async function fetchEngineBinary(
   mkdirSync(dirname(binPath), { recursive: true });
 
   // Overlap sidecar fetches with the engine fetch (~15-30s saved on cold install).
+  const checksums = engineChecksums.forRelease(version);
   const sidecarPromises = SIDECARS.map((s) =>
-    downloadSidecar(s, binPath, version),
+    downloadSidecar(s, binPath, version, checksums),
   );
   // If the engine fetch throws, silence in-flight sidecar rejections so unhandledRejection doesn't obscure the engine error.
   const muteSidecarRejections = () =>
     sidecarPromises.forEach((p) => p.catch(() => {}));
 
+  let expected: ExpectedSha256;
+  try {
+    expected = await checksums(binaryName);
+  } catch (e) {
+    muteSidecarRejections();
+    throw e;
+  }
+
   let res: Response;
   try {
     res = await fetch(url, { redirect: "follow" });
@@ -492,6 +616,12 @@ async function fetchEngineBinary(
   }
 
   await streamResponseToFile(res, binPath, "kesha-engine binary");
+  const refusal = await rejectMismatchedDownload(binPath, `kesha-engine binary ${binaryName}`, version, expected);
+  if (refusal) {
+    muteSidecarRejections();
+    rmSync(getVersionMarkerPath(binPath), { force: true });
+    throw new Error(refusal);
+  }
   chmodSync(binPath, 0o755);
   darwinTrustBinary(binPath, "kesha-engine binary");
   // Marker last: writing it first sends the retry down the cacheValid branch, which never waits.
@@ -520,7 +650,7 @@ function checkEngineWritable(engineDir: string): boolean {
 /**
  * The install path's pre-spawn gate: checks the requested backend against the describe
  * document, then validates the built engine argv through it. `--diarize` on a build that
- * lacks `system_diarize` (the Nix build, which omits it on purpose — docs/nix-install.md)
+ * lacks `system_diarize` (the Nix build, which omits it on purpose — docs/distribution.md#nix)
  * gets the npm-release remedy instead of `validateArgv`'s generic "needs" message.
  *
  * A bare `install` (no backend, no flags) skips `getDescribe()` entirely: a read-only
@@ -558,7 +688,7 @@ async function validateInstallRequest(
       throw new KeshaError(
         "E_INVALID_ARG",
         "The installed engine was built without the system_diarize feature, so --diarize is unavailable " +
-          "(the Nix build in docs/nix-install.md is one such case).",
+          "(the Nix build in docs/distribution.md is one such case).",
         {
           hint: "install via the npm release with `bun add -g @drakulavich/kesha-voice-kit`, which ships the diarize-enabled engine on darwin-arm64",
         },
@@ -571,15 +701,13 @@ async function validateInstallRequest(
 /** Runs `kesha-engine install` to download/verify models. */
 async function runEngineModelInstall(binPath: string, installArgs: string[]): Promise<void> {
   log.progress("Installing models...");
-  const proc = spawnEngineProcess(binPath, installArgs, ["inherit", "inherit", "pipe"], protocolEnv());
-  const tree = registerProcessTree(proc);
   // The byte percentage repaints one row; `GET`/`OK`/`retrying` are discrete steps that must stay in the log.
   const status = createLiveStatus();
-  let events: StderrOutcome;
-  let exitCode: number;
+  let run: Awaited<ReturnType<typeof runEngineProcess>>;
   try {
-    [events, exitCode] = await Promise.all([
-      readEvents(proc.stderr as ReadableStream<Uint8Array>, {
+    run = await runEngineProcess(binPath, installArgs, {
+      stdio: ["inherit", "inherit", "pipe"],
+      sinks: {
         onProgress: (line, event) => {
           if (event.pct !== undefined) {
             status.update(line);
@@ -592,14 +720,17 @@ async function runEngineModelInstall(binPath: string, installArgs: string[]): Pr
           status.clear();
           log.warn(line);
         },
-      }),
-      proc.exited,
-    ]);
+      },
+    });
   } finally {
     status.clear();
-    tree.dispose();
   }
-
+  const { exitCode, events } = run;
+  // #1301: engine 1.26.0 lets FluidAudio log a download retry it recovers from on raw fd 2; a clean exit outranks that line.
+  if (exitCode === 0 && events.error === null) {
+    for (const line of events.invalid) log.warn(offProtocolLine("install", line));
+    return;
+  }
   if (events.error || events.invalid.length > 0) throw engineFailure("install", events, exitCode);
   if (exitCode !== 0) {
     // Nothing coded and nothing off-protocol: the engine failed without saying why, so neither do we.
@@ -795,8 +926,12 @@ async function installLockedEngine(
   // The marker vouches for a file, not for a working binary. Skipped on a read-only engine
   // dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
   // install into a hard error.
+  // Hashed before the health probe, so an altered binary is never run.
   const versionMatches =
-    markerMatches && (!canWriteEngineDir || (await engineWorks(binPath)));
+    markerMatches &&
+    (!canWriteEngineDir ||
+      ((await cachedAssetMatchesPin(binPath, getEngineBinaryName(), "kesha-engine binary", version)) &&
+        (await engineWorks(binPath))));
   // On read-only fs, --no-cache can't re-download; treat as cache-valid and forward flag to model install.
   const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 
@@ -835,19 +970,3 @@ async function installLockedEngine(
   log.success(`Backend installed successfully (engine v${version}).`);
   return binPath;
 }
-
-/** Installs the Pinned Engine version. Public API (`downloadModel`); the override is CLI-only. */
-export async function downloadEngine(
-  noCache = false,
-  backend?: string,
-  options: InstallOptions = {},
-): Promise<string> {
-  // Field-by-field, not a spread: a caller's stray `version` must not reach installEngine.
-  return installEngine({
-    noCache,
-    backend,
-    ttsLangs: options.ttsLangs,
-    vad: options.vad,
-    diarize: options.diarize,
-  });
-}

package/src/engine-targets.ts

@@ -9,28 +9,76 @@ export interface EngineTarget {
   /** GitHub release asset name — suffixed for uniqueness across platforms. */
   assetName: string;
   backend: "coreml" | "onnx";
-  /** Published asset size, for `kesha install --plan`. Verified by `check:engine-targets`. */
-  sizeBytes: number;
 }
 
 const ENGINE_TARGETS: Record<string, EngineTarget> = {
   "darwin-arm64": {
     assetName: "kesha-engine-darwin-arm64",
     backend: "coreml",
-    sizeBytes: 64_713_088,
   },
   "linux-x64": {
     assetName: "kesha-engine-linux-x64",
     backend: "onnx",
-    sizeBytes: 66_588_184,
   },
   "win32-x64": {
     assetName: "kesha-engine-windows-x64.exe",
     backend: "onnx",
-    sizeBytes: 65_587_712,
   },
 };
 
+/** Sidecar spec — centralises AVSpeech (#141) and future sidecars so each is one entry. */
+export interface SidecarSpec {
+  /** Written next to the engine binary; Rust probes this exact name. */
+  fileBasename: string;
+  /** Release asset name — may differ from fileBasename (e.g. `say-avspeech-darwin-arm64` vs `say-avspeech`). */
+  assetName: string;
+  displayName: string;
+  availableHint: string;
+  unavailableHint: string;
+}
+
+export const SIDECARS: SidecarSpec[] = [
+  {
+    fileBasename: "say-avspeech",
+    assetName: "say-avspeech-darwin-arm64",
+    displayName: "AVSpeech sidecar",
+    availableHint: "macOS voices available",
+    unavailableHint: "macos-* voices unavailable",
+  },
+  // Kokoro TTS (#207) and speaker diarization (#199) no longer ship as Swift
+  // sidecars — both run in-engine via the native `fluidaudio-rs` binding. Only
+  // the AVSpeech and text-lang sidecars remain.
+  {
+    // Runtime resolver looks for plain `kesha-textlang` next to the engine
+    // (see `rust/src/text_lang.rs::helper_path`), not the platform-suffixed
+    // release-asset name. Mismatch is intentional: the asset name needs the
+    // suffix for GitHub-release uniqueness; the sidecar lookup wants the
+    // unsuffixed binary so the same Rust code path works on the build-time
+    // OUT_DIR baked fallback.
+    fileBasename: "kesha-textlang",
+    assetName: "kesha-textlang-darwin-arm64",
+    displayName: "Text-lang sidecar",
+    availableHint: "detect-text-lang fast path",
+    unavailableHint:
+      "detect-text-lang will fail until next `kesha install` (no swift -e fallback)",
+  },
+];
+
+/** Every asset `kesha install` downloads, and so every asset a published CLI's Engine pin covers. */
+export function downloadedAssetNames(): string[] {
+  return [...Object.values(ENGINE_TARGETS).map((t) => t.assetName), ...SIDECARS.map((s) => s.assetName)];
+}
+
+/** Asset name to SHA-256 from a release's `sha256sum`-format SHA256SUMS, whose names carry a `./` prefix. */
+export function parseSha256Sums(text: string): Map<string, string> {
+  const sums = new Map<string, string>();
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^([0-9a-f]{64}) [ *]?(?:\.\/)?(\S.*)$/.exec(line.trim());
+    if (m) sums.set(m[2]!, m[1]!);
+  }
+  return sums;
+}
+
 /**
  * The one target whose engine links FluidAudio, so the only one with ANE Kokoro assets,
  * Swift sidecars and diarization. Kept beside the target table because that is what makes