@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/transcription/build.ts

@@ -0,0 +1,332 @@
+/**
+ * Building `transcribe-cli` from source at install time (scribe-fold Phase 2b).
+ *
+ * transcribe.cpp v0.1.1 ships a **library** (`libtranscribe.{dylib,so}` +
+ * `libggml*`), NOT a prebuilt `transcribe-cli` executable — see
+ * `install.ts` + the provider-seam design doc. This module closes that gap: it
+ * fetches the CLI's source (`examples/cli/main.cpp` + `examples/common/wav.cpp`
+ * + the public headers) from the transcribe.cpp repo pinned at the v0.1.1 tag
+ * commit, applies the **vault#534 backend-init patch** (see
+ * `patchMainCppBackendInit` below — temporary until upstream ships the fix),
+ * then compiles it with the host C++ compiler against the extracted prebuilt
+ * dylibs. The result is a ~127KB driver that links the prebuilt
+ * `libtranscribe` at runtime — **no ggml / Metal rebuild**.
+ *
+ * ## The proven recipe (live-verified 2026-07-03, macOS arm64 M4)
+ *
+ *   c++ -std=c++17 -O2 \
+ *     -I<srcDir>/include \
+ *     -I<srcDir>/examples/common \
+ *     <srcDir>/examples/cli/main.cpp \
+ *     <srcDir>/examples/common/wav.cpp \
+ *     -L<libsDir> -ltranscribe \
+ *     -Wl,-rpath,@loader_path/../libs \        # Linux: $ORIGIN/../libs
+ *     -o <binDir>/transcribe-cli
+ *
+ * The rpath is load-bearing: `libtranscribe.dylib`'s install_name is
+ * `@rpath/libtranscribe.dylib` (with no rpath of its own), so the CLI carries
+ * `@loader_path/../libs` to resolve it from a sibling `libs/` dir. In turn
+ * `libtranscribe` references `libggml*` via `@loader_path/libggml*.dylib`, so
+ * having all dylibs in the same `libs/` dir is enough — the CLI never needs to
+ * know about libggml. On Linux the analogous `$ORIGIN/../libs` is passed as a
+ * single argv element (we spawn the compiler directly, NOT through a shell, so
+ * `$ORIGIN` is NOT expanded — it lands literally in the ELF RUNPATH for the
+ * runtime loader to expand).
+ *
+ * ## Testability
+ *
+ * `buildTranscribeCli` is a pure orchestrator over injected side effects
+ * (`which` / `fetchSource` / `readFile` / `writeFile` / `compile` / `exists` /
+ * `removeBin`), mirroring the provider's `SpawnRunner` seam. Tests exercise
+ * every branch — toolchain absent, fetch failure, patch failure, compile
+ * failure, success — with no network and no real compiler. The real compile is
+ * exercised only by the install-time live verify.
+ */
+
+import { join } from "path";
+
+/**
+ * Pinned source ref for the CLI build: the transcribe.cpp **v0.1.1 tag commit**.
+ * Kept in lockstep with `TRANSCRIBE_CPP_VERSION` in `install.ts` — bump both
+ * together (a newer CLI source may need different headers or flags, and the
+ * provider's output parsing is validated against a specific version).
+ */
+export const TRANSCRIBE_CPP_SOURCE_REF = "d89ecb75062e8457681c563994675dc60e31db80";
+
+const RAW_BASE = `https://raw.githubusercontent.com/handy-computer/transcribe.cpp/${TRANSCRIBE_CPP_SOURCE_REF}`;
+
+/**
+ * Repo-relative source files needed to build `transcribe-cli`, laid out under a
+ * local source dir so the include paths resolve exactly as upstream expects.
+ * `main.cpp` includes `transcribe.h` + `transcribe/{parakeet,voxtral_realtime,
+ * whisper}.h` + `wav.h`; `wav.cpp` includes `wav.h` + `dr_wav.h`. We fetch the
+ * complete `include/` header set (the two extra sub-headers are tiny and keep
+ * the tree self-consistent). Verified sufficient by a real compile at this ref.
+ */
+export const CLI_SOURCE_FILES: readonly string[] = [
+  "include/transcribe.h",
+  "include/transcribe/extensions.h",
+  "include/transcribe/moonshine_streaming.h",
+  "include/transcribe/parakeet.h",
+  "include/transcribe/voxtral_realtime.h",
+  "include/transcribe/whisper.h",
+  "examples/common/wav.h",
+  "examples/common/wav.cpp",
+  "examples/common/dr_wav.h",
+  "examples/cli/main.cpp",
+];
+
+/** Full raw.githubusercontent URL for a repo-relative path at the pinned ref. */
+export function cliSourceUrl(repoPath: string): string {
+  return `${RAW_BASE}/${repoPath}`;
+}
+
+// ---------------------------------------------------------------------------
+// Build-time source patch: unconditional backend init (vault#534 blocker 2)
+// ---------------------------------------------------------------------------
+
+/** Marker comment baked into the injected code — makes the patch idempotent
+ *  and greppable in a fetched source tree. */
+export const BACKEND_INIT_PATCH_MARKER = "[parachute-vault vault#534 backend-init patch]";
+
+/**
+ * The anchor line in the pinned `examples/cli/main.cpp` the patch injects
+ * before: the batch-mode comment that opens the inference half of `main()`,
+ * directly AFTER the log-sink install (so backend plugin-load logs route
+ * through the CLI's log callback) and after the `--list-devices` early return.
+ * Unique at the pinned ref (verified); if the pin ever advances and this
+ * anchor drifts, the build fails LOUDLY (stage "patch") so the patch gets
+ * re-evaluated against the new source instead of silently shipping a CLI that
+ * can't transcribe on Linux.
+ */
+export const BACKEND_INIT_PATCH_ANCHOR =
+  "    // Batch mode: --batch reads a file list, one wav path per line. Loads";
+
+const BACKEND_INIT_PATCH_BLOCK = `    // ${BACKEND_INIT_PATCH_MARKER}
+    // Upstream (at the pinned ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)}) only calls
+    // transcribe_init_backends_default() in the --list-devices path. On Linux
+    // the CPU backends are dlopen plugins (libggml-cpu-*.so), so with no init
+    // the ggml device registry is empty and EVERY transcription fails
+    // ("whisper: failed to initialize CPU backend", exit 1). macOS is masked:
+    // its libtranscribe.dylib direct-links libggml-cpu, which self-registers
+    // at library load. Init the default backends unconditionally before any
+    // inference (batch or single-file). Verified fix on real Linux containers,
+    // both arches — see vault#534. DROP THIS PATCH when upstream ships the fix
+    // and the source pin advances past it.
+    transcribe_init_backends_default();
+
+`;
+
+/**
+ * Apply the vault#534 backend-init patch to the fetched `main.cpp` source.
+ * Pure (string → string) so tests pin the behavior without a filesystem.
+ * Idempotent: an already-patched source is returned unchanged. Throws with a
+ * clear operator-facing message when the anchor is missing — the caller
+ * surfaces it as a `stage: "patch"` build failure (fail loudly; never compile
+ * an unpatched CLI on the assumption it'll work).
+ */
+export function patchMainCppBackendInit(source: string): string {
+  if (source.includes(BACKEND_INIT_PATCH_MARKER)) return source;
+  const idx = source.indexOf(BACKEND_INIT_PATCH_ANCHOR);
+  if (idx === -1) {
+    throw new Error(
+      `backend-init patch anchor not found in examples/cli/main.cpp at ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)} — ` +
+        `the pinned source no longer matches the vault#534 patch. If the pin advanced, check whether upstream ` +
+        `now calls transcribe_init_backends_default() unconditionally (then drop the patch); otherwise re-anchor it.`,
+    );
+  }
+  return source.slice(0, idx) + BACKEND_INIT_PATCH_BLOCK + source.slice(idx);
+}
+
+/** C++ compiler binaries we probe for, in preference order. */
+export const CXX_CANDIDATES = ["c++", "clang++", "g++"] as const;
+
+/**
+ * Resolve a C++ compiler path via the injected `which` (production:
+ * `Bun.which`). Returns the first candidate found, or `null` when none is on
+ * PATH — the caller keeps the current provider and prints a platform hint.
+ */
+export function detectCompiler(which: (cmd: string) => string | null | undefined): string | null {
+  for (const c of CXX_CANDIDATES) {
+    const p = which(c);
+    if (p) return p;
+  }
+  return null;
+}
+
+/** A short "install a compiler" hint tailored to the host platform. */
+export function compilerInstallHint(platform: string): string {
+  if (platform === "darwin") return "install the Xcode command-line tools: xcode-select --install";
+  if (platform === "linux") {
+    return "install a C++ toolchain: apt install build-essential (Debian/Ubuntu) | dnf install gcc-c++ (Fedora/RHEL)";
+  }
+  return "install a C++ compiler (c++/clang++/g++) on PATH";
+}
+
+export interface CompileCommandInput {
+  /** Host platform (`process.platform`) — selects the rpath flavor. */
+  platform: string;
+  /** Resolved compiler path (`detectCompiler`). */
+  compiler: string;
+  /** The local source dir the CLI sources were fetched into. */
+  srcDir: string;
+  /** The extracted prebuilt dylibs dir to link `-ltranscribe` from. */
+  libsDir: string;
+  /** Where the compiled `transcribe-cli` lands. */
+  outPath: string;
+}
+
+/**
+ * Build the compiler argv (the proven recipe). Pure — a test pins the shape,
+ * mirroring `buildTranscribeArgs` for the provider. The rpath resolves the
+ * sibling `libs/` dir from `bin/`: `@loader_path/../libs` (macOS) /
+ * `$ORIGIN/../libs` (Linux, passed literally — no shell expansion).
+ */
+export function buildCompileCommand(input: CompileCommandInput): string[] {
+  const includeDir = join(input.srcDir, "include");
+  const commonDir = join(input.srcDir, "examples", "common");
+  const mainCpp = join(input.srcDir, "examples", "cli", "main.cpp");
+  const wavCpp = join(input.srcDir, "examples", "common", "wav.cpp");
+  const rpath = input.platform === "darwin" ? "@loader_path/../libs" : "$ORIGIN/../libs";
+  return [
+    input.compiler,
+    "-std=c++17",
+    "-O2",
+    `-I${includeDir}`,
+    `-I${commonDir}`,
+    mainCpp,
+    wavCpp,
+    `-L${input.libsDir}`,
+    "-ltranscribe",
+    `-Wl,-rpath,${rpath}`,
+    "-o",
+    input.outPath,
+  ];
+}
+
+/** Result of running the compiler: exit code + captured stderr. */
+export interface CompileResult {
+  exitCode: number;
+  stderr: string;
+}
+
+/** Injected side effects for `buildTranscribeCli` (tests pass mocks). */
+export interface BuildCliDeps {
+  /** Host platform (`process.platform`). */
+  platform: string;
+  /** Compiler probe (production: `Bun.which`). */
+  which: (cmd: string) => string | null | undefined;
+  /** Fetch `files` (repo-relative) into `srcDir`. Throws on network failure. */
+  fetchSource: (files: readonly string[], srcDir: string) => Promise<void>;
+  /** Read a fetched source file as UTF-8 (production: `fs.readFileSync`). */
+  readFile: (p: string) => string;
+  /** Write a patched source file (production: `fs.writeFileSync`). */
+  writeFile: (p: string, content: string) => void;
+  /** Run the compiler argv. */
+  compile: (cmd: string[]) => CompileResult | Promise<CompileResult>;
+  /** Existence probe (production: `fs.existsSync`). */
+  exists: (p: string) => boolean;
+  /** Remove a stale / half-built binary (production: `fs.rmSync{force}`). */
+  removeBin: (p: string) => void;
+  /** Move a file into place (production: `fs.renameSync`). Used to promote the
+   *  freshly-built binary atomically, so a failed rebuild never clobbers a
+   *  previously working binary. */
+  rename: (from: string, to: string) => void;
+}
+
+export interface BuildCliInput {
+  /** Local dir to fetch the CLI sources into. */
+  srcDir: string;
+  /** The extracted prebuilt dylibs dir. */
+  libsDir: string;
+  /** Output binary path. */
+  binPath: string;
+}
+
+/** The outcome of a build attempt — a discriminated union the CLI branches on. */
+export type CliBuildResult =
+  | { ok: true; binPath: string; compiler: string; command: string }
+  | {
+      ok: false;
+      /** Which stage failed — drives the operator guidance. */
+      stage: "toolchain" | "fetch" | "patch" | "compile";
+      message: string;
+      compiler?: string;
+      /** The compile argv (as a string) when we got far enough to build one. */
+      command?: string;
+    };
+
+/**
+ * Fetch the CLI source at the pinned ref and compile it against the extracted
+ * dylibs. Non-throwing: every failure is a typed `{ ok: false }` so the caller
+ * keeps the current provider and reports honestly. Never leaves a half-built
+ * binary — a nonzero compile (or a missing output) removes `binPath` so
+ * `available()` can't mistake a partial artifact for a runnable CLI.
+ */
+export async function buildTranscribeCli(
+  input: BuildCliInput,
+  deps: BuildCliDeps,
+): Promise<CliBuildResult> {
+  const compiler = detectCompiler(deps.which);
+  if (!compiler) {
+    return {
+      ok: false,
+      stage: "toolchain",
+      message: `no C++ compiler on PATH (looked for ${CXX_CANDIDATES.join(", ")}) — ${compilerInstallHint(deps.platform)}`,
+    };
+  }
+
+  try {
+    await deps.fetchSource(CLI_SOURCE_FILES, input.srcDir);
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "fetch",
+      compiler,
+      message: `failed to fetch transcribe-cli source at ${TRANSCRIBE_CPP_SOURCE_REF}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // Apply the vault#534 backend-init source patch BEFORE compiling — without
+  // it the built CLI exits 1 on every transcription on Linux (dlopen'd CPU
+  // backends are never registered). A missing anchor is a loud, typed failure,
+  // never a silent skip.
+  const mainCppPath = join(input.srcDir, "examples", "cli", "main.cpp");
+  try {
+    deps.writeFile(mainCppPath, patchMainCppBackendInit(deps.readFile(mainCppPath)));
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "patch",
+      compiler,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const common = { platform: deps.platform, compiler, srcDir: input.srcDir, libsDir: input.libsDir };
+  // The reported command targets the FINAL binPath (what an operator would run
+  // by hand to reproduce). The actual compile writes to a temp sibling and is
+  // promoted on success — so a failed rebuild (e.g. `--force` that then fails)
+  // never clobbers a previously working binary, and no half-built artifact is
+  // ever left where available() would treat it as runnable. The temp is a
+  // sibling in the same dir, so the @loader_path/../libs rpath is unaffected.
+  const command = buildCompileCommand({ ...common, outPath: input.binPath }).join(" ");
+  const tmpOut = `${input.binPath}.building`;
+  const argv = buildCompileCommand({ ...common, outPath: tmpOut });
+
+  deps.removeBin(tmpOut); // clear any stale temp from a prior interrupted build
+  const res = await deps.compile(argv);
+  if (res.exitCode !== 0 || !deps.exists(tmpOut)) {
+    deps.removeBin(tmpOut); // drop any partial output; the existing binary stands
+    return {
+      ok: false,
+      stage: "compile",
+      compiler,
+      command,
+      message: (res.stderr || "").trim() || `compiler exited ${res.exitCode}`,
+    };
+  }
+
+  deps.rename(tmpOut, input.binPath); // atomic promote over any prior binary
+  return { ok: true, binPath: input.binPath, compiler, command };
+}

package/src/transcription/capability.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { resolveTranscriptionCapability, defaultTranscriptionProvider } from "./capability.ts";
+import { ScribeHttpProvider } from "./providers/scribe-http.ts";
+import { TranscribeCppProvider } from "./providers/transcribe-cpp.ts";
+import type { TranscriptionProvider } from "../../core/src/transcription/provider.ts";
+
+/**
+ * Capability-flag tests (scribe-fold Phase 1). The vault landing surfaces
+ * `transcription: { enabled, provider? }`; `enabled` iff a provider is
+ * configured AND available. Notes gates its mic on this.
+ */
+
+/** A minimal fake provider so tests don't depend on live scribe discovery. */
+function fakeProvider(available: boolean, name = "fake"): TranscriptionProvider {
+  return {
+    name,
+    available: async () => (available ? { ok: true } : { ok: false, reason: "off" }),
+    transcribe: async () => ({ text: "" }),
+  };
+}
+
+describe("resolveTranscriptionCapability", () => {
+  test("enabled:true + provider name when the provider is available", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(true, "scribe-http"));
+    expect(cap).toEqual({ enabled: true, provider: "scribe-http" });
+  });
+
+  test("enabled:false + no provider name when the provider is unavailable", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(false));
+    expect(cap).toEqual({ enabled: false });
+    expect(cap.provider).toBeUndefined();
+  });
+
+  test("no provider configured (scribe-http with no URL) resolves to disabled, no throw", async () => {
+    // The "no provider configured" path: a scribe-http provider whose URL is
+    // undefined reports unavailable rather than throwing, so the landing never
+    // crashes when scribe is absent.
+    const cap = await resolveTranscriptionCapability(new ScribeHttpProvider({ url: undefined }));
+    expect(cap.enabled).toBe(false);
+    expect(cap.provider).toBeUndefined();
+  });
+
+  test("a configured scribe-http provider resolves to enabled: scribe-http", async () => {
+    const cap = await resolveTranscriptionCapability(new ScribeHttpProvider({ url: "http://scribe.test" }));
+    expect(cap).toEqual({ enabled: true, provider: "scribe-http" });
+  });
+
+  test("never omits minutes_remaining as an unmetered self-host concern", async () => {
+    const cap = await resolveTranscriptionCapability(fakeProvider(true));
+    expect("minutes_remaining" in cap).toBe(false);
+  });
+
+  test("a transcribe-cpp provider (installed) resolves to enabled: transcribe-cpp", async () => {
+    // existsImpl stubs the binary + model as present so available() is ok
+    // without touching disk.
+    const p = new TranscribeCppProvider({
+      binPath: "/tc/transcribe-cli",
+      modelPath: "/tc/model.gguf",
+      existsImpl: () => true,
+    });
+    const cap = await resolveTranscriptionCapability(p);
+    expect(cap).toEqual({ enabled: true, provider: "transcribe-cpp" });
+  });
+
+  test("a transcribe-cpp provider (not installed) resolves to disabled", async () => {
+    const p = new TranscribeCppProvider({ binPath: "/tc/transcribe-cli", modelPath: "/tc/model.gguf", existsImpl: () => false });
+    const cap = await resolveTranscriptionCapability(p);
+    expect(cap.enabled).toBe(false);
+    expect(cap.provider).toBeUndefined();
+  });
+});
+
+/**
+ * `defaultTranscriptionProvider` honors `TRANSCRIPTION_PROVIDER` so the
+ * capability flag reflects whichever provider is configured (scribe-fold 2a).
+ */
+describe("defaultTranscriptionProvider — provider selection", () => {
+  const saved = process.env.TRANSCRIPTION_PROVIDER;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.TRANSCRIPTION_PROVIDER;
+    else process.env.TRANSCRIPTION_PROVIDER = saved;
+  });
+
+  test("default (unset) → the scribe-http provider", () => {
+    delete process.env.TRANSCRIPTION_PROVIDER;
+    expect(defaultTranscriptionProvider().name).toBe("scribe-http");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=transcribe-cpp → the transcribe-cpp provider", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "transcribe-cpp";
+    expect(defaultTranscriptionProvider().name).toBe("transcribe-cpp");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=parakeet-mlx → the parakeet-mlx provider (2b)", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "parakeet-mlx";
+    expect(defaultTranscriptionProvider().name).toBe("parakeet-mlx");
+  });
+
+  test("TRANSCRIPTION_PROVIDER=onnx-asr → the onnx-asr provider (2b)", () => {
+    process.env.TRANSCRIPTION_PROVIDER = "onnx-asr";
+    expect(defaultTranscriptionProvider().name).toBe("onnx-asr");
+  });
+
+  test("an unconfigured python provider resolves to disabled (no throw)", async () => {
+    // No venv/PATH binary in a fresh env → available() is ok:false and the
+    // landing capability is {enabled:false} rather than a crash.
+    process.env.TRANSCRIPTION_PROVIDER = "parakeet-mlx";
+    const prevBin = process.env.PARAKEET_MLX_BIN;
+    process.env.PARAKEET_MLX_BIN = "/definitely/not/a/real/parakeet-mlx";
+    try {
+      const cap = await resolveTranscriptionCapability(defaultTranscriptionProvider());
+      expect(cap.enabled).toBe(false);
+    } finally {
+      if (prevBin === undefined) delete process.env.PARAKEET_MLX_BIN;
+      else process.env.PARAKEET_MLX_BIN = prevBin;
+    }
+  });
+});

package/src/transcription/capability.ts

@@ -0,0 +1,96 @@
+/**
+ * Transcription capability flag (scribe-fold Phase 1).
+ *
+ * The vault landing (`GET /vault/<name>/api/vault`) surfaces a `transcription`
+ * capability so a surface (Notes) can gate its microphone affordance on
+ * whether transcription is actually possible — distinct from the
+ * `auto_transcribe.enabled` POLICY toggle (which defaults on even when no
+ * provider is reachable). `enabled` is true only when a provider is configured
+ * AND its `available()` probe passes.
+ *
+ * `minutes_remaining` is deliberately omitted: it's a cloud/plan concern, and
+ * self-host is unmetered. The cloud voice build, whose Workers-AI provider
+ * implements the same `TranscriptionProvider` interface, will add metering at
+ * that layer.
+ */
+
+import type { TranscriptionProvider } from "../../core/src/transcription/provider.ts";
+import { ScribeHttpProvider } from "./providers/scribe-http.ts";
+import { TranscribeCppProvider } from "./providers/transcribe-cpp.ts";
+import { ParakeetMlxProvider } from "./providers/parakeet-mlx.ts";
+import { OnnxAsrProvider } from "./providers/onnx-asr.ts";
+import { getCachedScribeUrl } from "../scribe-discovery.ts";
+import { resolveScribeAuthToken } from "../scribe-env.ts";
+import {
+  resolveTranscriptionProviderName,
+  resolveTranscribeCppPaths,
+  resolveParakeetMlxBin,
+  resolveParakeetMlxModel,
+  resolveOnnxAsrBin,
+  resolveOnnxAsrModel,
+} from "./select.ts";
+
+export interface TranscriptionCapability {
+  /** True when a provider is configured AND available. Notes gates the mic on this. */
+  enabled: boolean;
+  /** The active provider's name (e.g. "scribe-http"). Omitted when disabled. */
+  provider?: string;
+}
+
+/**
+ * Build the default provider from live per-process config, honoring
+ * `TRANSCRIPTION_PROVIDER` (scribe-fold Phase 2a) so the capability flag
+ * reflects whichever provider is actually configured:
+ *
+ *   - `transcribe-cpp` → the local provider, resolving the installed binary +
+ *     GGUF model paths; `available()` is `false` until `transcription install`
+ *     has run.
+ *   - `parakeet-mlx` / `onnx-asr` (scribe-fold Phase 2b) → the Python-based
+ *     local providers, resolving the binary via env override → managed venv →
+ *     PATH; `available()` is `false` until a runnable binary exists.
+ *   - `scribe-http` (default) → the remote provider (URL from
+ *     `SCRIBE_URL`/services.json, bearer from `SCRIBE_AUTH_TOKEN`). When scribe
+ *     isn't discoverable the URL is undefined and it reports itself unavailable
+ *     rather than throwing.
+ */
+export function defaultTranscriptionProvider(): TranscriptionProvider {
+  const name = resolveTranscriptionProviderName();
+  if (name === "transcribe-cpp") {
+    const paths = resolveTranscribeCppPaths();
+    return new TranscribeCppProvider({ binPath: paths.binPath, modelPath: paths.modelPath });
+  }
+  if (name === "parakeet-mlx") {
+    return new ParakeetMlxProvider({
+      binPath: resolveParakeetMlxBin(),
+      model: resolveParakeetMlxModel(),
+    });
+  }
+  if (name === "onnx-asr") {
+    return new OnnxAsrProvider({
+      binPath: resolveOnnxAsrBin(),
+      model: resolveOnnxAsrModel(),
+    });
+  }
+  return new ScribeHttpProvider({
+    url: getCachedScribeUrl(),
+    token: resolveScribeAuthToken(),
+  });
+}
+
+/**
+ * Resolve the transcription capability for the vault landing. `enabled` is the
+ * provider's `available()` result; `provider` is its name when enabled. A
+ * "no provider configured" deployment resolves cleanly to `{ enabled: false }`
+ * (no throw), so the landing never crashes when scribe is absent.
+ *
+ * The `provider` arg is an injection seam for tests + a future explicit
+ * provider selection; production omits it and uses the default scribe-http
+ * provider built from live config.
+ */
+export async function resolveTranscriptionCapability(
+  provider: TranscriptionProvider = defaultTranscriptionProvider(),
+): Promise<TranscriptionCapability> {
+  const avail = await provider.available();
+  if (!avail.ok) return { enabled: false };
+  return { enabled: true, provider: provider.name };
+}

package/src/transcription/download.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { downloadTo } from "./download.ts";
+
+/**
+ * `downloadTo` tests (vault#534 blocker 1). The manual body→FileSink pump
+ * replaced `Bun.write(dest, resp)`, which hangs forever on Linux for large
+ * responses. These run the pump against an in-process `Bun.serve` (no
+ * subprocess involved — see CLAUDE.md's spawnSync note; plain in-process
+ * fetches are fine) and pin: bytes land intact, HTTP errors throw, and a
+ * mid-stream failure never leaves a partial file behind.
+ */
+
+const dir = mkdtempSync(join(tmpdir(), "vault-download-test-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+// 4MB of deterministic non-trivial bytes — large enough to stream in many
+// chunks (the hang was specific to the large-response path).
+const PAYLOAD = new Uint8Array(4 * 1024 * 1024);
+for (let i = 0; i < PAYLOAD.length; i++) PAYLOAD[i] = (i * 31 + (i >> 8)) & 0xff;
+
+function serve(handler: (req: Request) => Response | Promise<Response>) {
+  const server = Bun.serve({ port: 0, fetch: handler });
+  return { server, url: `http://127.0.0.1:${server.port}` };
+}
+
+describe("downloadTo", () => {
+  test("streams a multi-MB body to disk byte-for-byte", async () => {
+    const { server, url } = serve(() => new Response(PAYLOAD));
+    const dest = join(dir, "ok.bin");
+    try {
+      await downloadTo(`${url}/file`, dest);
+      const got = readFileSync(dest);
+      expect(got.byteLength).toBe(PAYLOAD.byteLength);
+      expect(Buffer.from(got).equals(Buffer.from(PAYLOAD))).toBe(true);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("non-OK status throws with the status + URL, writes nothing", async () => {
+    const { server, url } = serve(() => new Response("nope", { status: 404 }));
+    const dest = join(dir, "missing.bin");
+    try {
+      expect(downloadTo(`${url}/gone`, dest)).rejects.toThrow(/download failed \(404\)/);
+      expect(existsSync(dest)).toBe(false);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("truncated download throws AND removes the partial file", async () => {
+    // Raw TCP fixture: a real content-length response (how GitHub releases +
+    // HuggingFace serve these binaries) whose connection dies mid-body.
+    // Bun.serve can't fixture this — it re-frames streamed responses as
+    // chunked (dropping content-length), and Bun's fetch ends a truncated
+    // chunked stream CLEANLY, so truncation is only detectable on the
+    // content-length path `downloadTo` verifies.
+    const partial = PAYLOAD.slice(0, 64 * 1024);
+    const listener = Bun.listen({
+      hostname: "127.0.0.1",
+      port: 0,
+      socket: {
+        data(socket) {
+          socket.write(
+            `HTTP/1.1 200 OK\r\ncontent-type: application/octet-stream\r\ncontent-length: ${PAYLOAD.byteLength}\r\n\r\n`,
+          );
+          socket.write(partial);
+          socket.end(); // die after 64KB of a declared 4MB
+        },
+        open() {},
+        close() {},
+        error() {},
+      },
+    });
+    const dest = join(dir, "partial.bin");
+    try {
+      let threw = false;
+      try {
+        await downloadTo(`http://127.0.0.1:${listener.port}/flaky`, dest);
+      } catch (err) {
+        threw = true;
+        // The truncation surfaces differently per platform: on macOS the body
+        // stream errors mid-pump (wrapped "failed after N bytes") or the
+        // short read trips the content-length check ("truncated"); on Linux
+        // Bun's fetch() itself rejects on the early socket close. All are
+        // loud failures — the invariants are THROWS + NO PARTIAL FILE.
+        expect(String(err)).toMatch(
+          /failed after \d+ bytes|truncated|socket connection was closed|connection closed/i,
+        );
+      }
+      expect(threw).toBe(true);
+      // The half-written file must not survive to be mistaken for a good artifact.
+      expect(existsSync(dest)).toBe(false);
+    } finally {
+      listener.stop(true);
+    }
+  });
+});