@openparachute/vault 0.6.5-rc.2 → 0.6.5

package/src/transcription/tiers.test.ts

@@ -0,0 +1,197 @@
+import { describe, test, expect } from "bun:test";
+import { selectDefaultProvider, NOMINAL_SLACK_GB, type TierPlan } from "./tiers.ts";
+import { DEFAULT_ONNX_ASR_MODEL, DEFAULT_PARAKEET_MLX_MODEL } from "./select.ts";
+
+/**
+ * The ratified RAM/arch/OS tier matrix (scribe-fold Phase 2b, 2026-07-03).
+ * Pure decision layer — no host probes, no network. The load-bearing
+ * invariants:
+ *
+ *   - macOS Apple Silicon 8GB+ → parakeet-mlx
+ *   - Linux 4GB+ → onnx-asr
+ *   - Linux ~2GB → transcribe-cpp with a SMALL WHISPER GGUF, never a Parakeet
+ *     variant (scribe#82: Parakeet peak RAM exceeds 2GB on meeting-length
+ *     audio → OOM)
+ *   - Linux ~1GB → remote default, tiny local model only as explicit opt-in
+ *   - below floor / unknown host → remote guidance, never a forced local pick
+ */
+
+const GB = 2 ** 30;
+
+function pick(platform: string, arch: string, gb: number): TierPlan {
+  return selectDefaultProvider({ platform, arch, totalRamBytes: gb * GB });
+}
+
+/** True when the plan's model is any Parakeet variant. */
+function isParakeet(plan: TierPlan): boolean {
+  return !!plan.model && /parakeet/i.test(plan.model);
+}
+
+describe("selectDefaultProvider — macOS Apple Silicon", () => {
+  test("darwin/arm64 8GB → parakeet-mlx (ratified default)", () => {
+    const plan = pick("darwin", "arm64", 8);
+    expect(plan.provider).toBe("parakeet-mlx");
+    expect(plan.model).toBe(DEFAULT_PARAKEET_MLX_MODEL);
+    expect(plan.approxDiskMb).toBe(2500);
+  });
+
+  test("darwin/arm64 16GB → parakeet-mlx", () => {
+    expect(pick("darwin", "arm64", 16).provider).toBe("parakeet-mlx");
+  });
+
+  test("darwin/arm64 just under 8GB nominal (7.7GB reported) → still parakeet-mlx (slack)", () => {
+    expect(pick("darwin", "arm64", 8 - NOMINAL_SLACK_GB).provider).toBe("parakeet-mlx");
+  });
+
+  test("darwin/arm64 well under 8GB → transcribe-cpp fallback, NOT parakeet-mlx", () => {
+    const plan = pick("darwin", "arm64", 6);
+    expect(plan.provider).toBe("transcribe-cpp");
+  });
+
+  test("darwin/x64 (Intel — no MLX) 16GB → transcribe-cpp fallback, never parakeet-mlx", () => {
+    const plan = pick("darwin", "x64", 16);
+    expect(plan.provider).toBe("transcribe-cpp");
+  });
+});
+
+describe("selectDefaultProvider — Linux", () => {
+  test("linux/x64 4GB → onnx-asr (ratified default)", () => {
+    const plan = pick("linux", "x64", 4);
+    expect(plan.provider).toBe("onnx-asr");
+    expect(plan.model).toBe(DEFAULT_ONNX_ASR_MODEL);
+    expect(plan.approxDiskMb).toBe(670);
+  });
+
+  test("linux/x64 8GB → onnx-asr, NOT parakeet-mlx (MLX is Apple-only)", () => {
+    expect(pick("linux", "x64", 8).provider).toBe("onnx-asr");
+  });
+
+  test("linux/arm64 4GB → onnx-asr", () => {
+    expect(pick("linux", "arm64", 4).provider).toBe("onnx-asr");
+  });
+
+  test("nominal-4GB box reporting 3.8GB (kernel reservation) → still onnx-asr (slack)", () => {
+    expect(pick("linux", "x64", 3.8).provider).toBe("onnx-asr");
+  });
+
+  test("linux 3.4GB (below the 4GB tier even with slack) → transcribe-cpp small whisper", () => {
+    const plan = pick("linux", "x64", 3.4);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+  });
+});
+
+describe("selectDefaultProvider — the 2GB-not-Parakeet floor (scribe#82)", () => {
+  test("linux 2GB → transcribe-cpp whisper-small.en — NEVER a Parakeet variant", () => {
+    const plan = pick("linux", "x64", 2);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+    expect(isParakeet(plan)).toBe(false);
+    expect(plan.reason).toContain("scribe#82");
+  });
+
+  test("nominal-2GB box reporting 1.9GB → still the whisper-small tier (slack), not tiny/remote", () => {
+    const plan = pick("linux", "x64", 1.9);
+    expect(plan.provider).toBe("transcribe-cpp");
+    expect(plan.model).toBe("whisper-small.en");
+  });
+
+  test("the whole 2–4GB Linux band never defaults to any Parakeet variant", () => {
+    for (const gb of [1.7, 2, 2.5, 3, 3.5]) {
+      const plan = pick("linux", "x64", gb);
+      expect(isParakeet(plan)).toBe(false);
+      expect(plan.provider).not.toBe("onnx-asr");
+      expect(plan.provider).not.toBe("parakeet-mlx");
+    }
+  });
+
+  // Regression for the double-applied-slack bug (reviewer, PR #537): the
+  // transcribe-cpp fallback used to add NOMINAL_SLACK_GB a SECOND time before
+  // install.ts's 4GB Parakeet-GGUF floor, so a real-3.6GB Darwin box picked a
+  // ~3.5GB-peak Parakeet model (~0.1GB headroom — the scribe#82 OOM class).
+  // Slack belongs to tier-entry boundaries only, never to model-floor checks.
+  test("darwin/x64 in the 3.6–3.9GB band → whisper-small.en, NEVER a Parakeet variant", () => {
+    for (const gb of [3.6, 3.8, 3.9]) {
+      const plan = pick("darwin", "x64", gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("whisper-small.en");
+      expect(isParakeet(plan)).toBe(false);
+    }
+  });
+
+  test("darwin/arm64 in the 3.6–3.9GB band → whisper-small.en, NEVER a Parakeet variant", () => {
+    for (const gb of [3.6, 3.9]) {
+      const plan = pick("darwin", "arm64", gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("whisper-small.en");
+      expect(isParakeet(plan)).toBe(false);
+    }
+  });
+
+  test("darwin just over a TRUE 4GB → the un-inflated Phase 2a pick (parakeet GGUF)", () => {
+    // At a genuine ≥4GB, install.ts's own matrix governs — same model an
+    // explicit `--provider transcribe-cpp` install would choose.
+    for (const [arch, gb] of [["x64", 4], ["x64", 4.1], ["arm64", 4]] as const) {
+      const plan = pick("darwin", arch, gb);
+      expect(plan.provider).toBe("transcribe-cpp");
+      expect(plan.model).toBe("parakeet-tdt-0.6b-v3");
+    }
+  });
+});
+
+describe("selectDefaultProvider — the ~1GB remote tier", () => {
+  test("linux 1GB → scribe-http by default (never a forced local install)", () => {
+    const plan = pick("linux", "x64", 1);
+    expect(plan.provider).toBe("scribe-http");
+  });
+
+  test("linux 1GB carries the explicit whisper-tiny local opt-in", () => {
+    const plan = pick("linux", "x64", 1);
+    expect(plan.localOptIn).toBeDefined();
+    expect(plan.localOptIn!.provider).toBe("transcribe-cpp");
+    expect(plan.localOptIn!.model).toBe("whisper-tiny.en");
+  });
+
+  test("nominal-1GB box reporting 0.95GB → still the opt-in tier", () => {
+    expect(pick("linux", "x64", 0.95).localOptIn).toBeDefined();
+  });
+
+  test("linux 1.4GB (below the 2GB tier) → remote default + tiny opt-in", () => {
+    const plan = pick("linux", "x64", 1.4);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn?.model).toBe("whisper-tiny.en");
+  });
+});
+
+describe("selectDefaultProvider — below floor / unknown hosts", () => {
+  test("linux 0.5GB → remote guidance with NO local opt-in", () => {
+    const plan = pick("linux", "x64", 0.5);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn).toBeUndefined();
+  });
+
+  test("unknown platform (win32) → remote guidance regardless of RAM", () => {
+    const plan = pick("win32", "x64", 32);
+    expect(plan.provider).toBe("scribe-http");
+    expect(plan.localOptIn).toBeUndefined();
+    expect(plan.reason).toContain("win32");
+  });
+
+  test("unknown arch (linux/riscv64) → remote guidance", () => {
+    expect(pick("linux", "riscv64", 8).provider).toBe("scribe-http");
+  });
+});
+
+describe("selectDefaultProvider — plan shape", () => {
+  test("carries the host facts for the human print", () => {
+    const plan = pick("linux", "x64", 4);
+    expect(plan.platform).toBe("linux");
+    expect(plan.arch).toBe("x64");
+    expect(plan.totalRamGb).toBe(4);
+    expect(plan.reason.length).toBeGreaterThan(0);
+  });
+
+  test("rounds detected RAM to 1dp", () => {
+    expect(selectDefaultProvider({ platform: "linux", arch: "x64", totalRamBytes: 3.84 * GB }).totalRamGb).toBe(3.8);
+  });
+});

package/src/transcription/tiers.ts

@@ -0,0 +1,184 @@
+/**
+ * RAM/arch/OS tier selection for `transcription install` (scribe-fold
+ * Phase 2b — the ratified tier table, 2026-07-03).
+ *
+ * This is the PURE decision layer for the install verb's AUTO-DEFAULT: given
+ * host facts (OS, arch, total RAM), which local provider should this box run?
+ * No side effects — the CLI probes the host, prints the pick + footprint, and
+ * the operator confirms or overrides with `--provider`/`--model`.
+ *
+ * ## The ratified table
+ *
+ *   | Host                        | Default                                    |
+ *   |-----------------------------|--------------------------------------------|
+ *   | macOS Apple Silicon, 8GB+   | parakeet-mlx (parakeet-tdt-0.6b-v3;        |
+ *   |                             |   ~2.5GB disk, ~2.5–3GB peak)              |
+ *   | Linux 4GB+                  | onnx-asr (parakeet-0.6b int8; ~670MB disk, |
+ *   |                             |   ~1.2–2GB+ peak)                          |
+ *   | Linux ~2GB                  | transcribe-cpp + whisper-small GGUF — NOT  |
+ *   |                             |   Parakeet (scribe#82: Parakeet peak RAM   |
+ *   |                             |   exceeds 2GB on meeting-length audio)     |
+ *   | Linux ~1GB                  | REMOTE (scribe-http) by default; local     |
+ *   |                             |   whisper-tiny only as explicit opt-in     |
+ *   | Below floor / unknown host  | remote guidance — never force local        |
+ *
+ * Hosts the table doesn't name fall back to transcribe-cpp with its own
+ * Phase 2a RAM tiers (e.g. Intel macs; a hypothetical <8GB Apple-Silicon
+ * box) — that matrix already carries the scribe#82 Parakeet-at-4GB floor.
+ *
+ * ## Nominal-RAM slack
+ *
+ * Tier boundaries are NOMINAL sizes ("a 4GB droplet"), but the kernel/firmware
+ * reserve memory before userspace sees it — a nominal-4GB Linux box reports
+ * ~3.6–3.9GB via MemTotal. `NOMINAL_SLACK_GB` absorbs that so the box the
+ * table targets actually lands in its tier. The 1GB remote floor uses a
+ * smaller slack: below-floor boxes must steer remote, never get a local
+ * install forced on them.
+ */
+
+import {
+  MODELS,
+  selectAsset,
+  selectModelForRam,
+  type ModelChoice,
+} from "./install.ts";
+import { DEFAULT_ONNX_ASR_MODEL, DEFAULT_PARAKEET_MLX_MODEL } from "./select.ts";
+
+const GB = 2 ** 30;
+
+/** Kernel/firmware reservation tolerance on nominal tier boundaries. */
+export const NOMINAL_SLACK_GB = 0.4;
+
+/** Slack at the 1GB remote floor (a nominal-1GB box reports ~0.94–0.97GB). */
+const FLOOR_SLACK_GB = 0.1;
+
+/** A provider name the tier table can select. */
+export type TierProviderName = "parakeet-mlx" | "onnx-asr" | "transcribe-cpp" | "scribe-http";
+
+/** The resolved tier pick for a host. */
+export interface TierPlan {
+  /** The tier-default provider for this host. */
+  provider: TierProviderName;
+  platform: string;
+  arch: string;
+  /** Detected total RAM, GB (rounded to 1dp) for the human print. */
+  totalRamGb: number;
+  /**
+   * Model id for the pick: an HF repo (parakeet-mlx), an onnx-asr registry
+   * name, or a transcribe-cpp GGUF id from `MODELS`. Absent for scribe-http.
+   */
+  model?: string;
+  /** Approx download footprint, MB (model + runtime), for the confirm prompt. */
+  approxDiskMb?: number;
+  /** Human peak-RAM note for the confirm prompt. */
+  peakRamNote?: string;
+  /** One-line rationale for the pick (printed to the operator). */
+  reason: string;
+  /**
+   * Set on the remote-default tier when a local install is still POSSIBLE as
+   * an explicit opt-in (Linux ~1GB → transcribe-cpp + whisper-tiny). The CLI
+   * prints it as guidance; it is never auto-installed.
+   */
+  localOptIn?: { provider: "transcribe-cpp"; model: string; note: string };
+}
+
+/** Host facts the tier decision needs. */
+export interface TierInput {
+  /** Node `os.platform()` value ("darwin" / "linux" / …). */
+  platform: string;
+  /** Node `os.arch()` value ("arm64" / "x64" / …). */
+  arch: string;
+  /** Detected total physical RAM in bytes. */
+  totalRamBytes: number;
+}
+
+/**
+ * Pick the tier-default provider for a host. Pure — see the module header for
+ * the ratified table. The scribe#82 invariant this encodes: **no Parakeet
+ * variant is ever the default below 4GB** (and on Linux, below-4GB boxes get
+ * transcribe-cpp whisper models or the remote steer — never onnx-asr).
+ */
+export function selectDefaultProvider(input: TierInput): TierPlan {
+  const { platform, arch, totalRamBytes } = input;
+  const gb = totalRamBytes / GB;
+  const base = { platform, arch, totalRamGb: Math.round(gb * 10) / 10 };
+
+  // macOS Apple Silicon, 8GB+ → parakeet-mlx (MLX uses the GPU/unified memory;
+  // the best quality/speed on this hardware).
+  if (platform === "darwin" && arch === "arm64" && gb >= 8 - NOMINAL_SLACK_GB) {
+    return {
+      ...base,
+      provider: "parakeet-mlx",
+      model: DEFAULT_PARAKEET_MLX_MODEL,
+      approxDiskMb: 2500,
+      peakRamNote: "~2.5–3GB peak while transcribing",
+      reason: "Apple Silicon with 8GB+ RAM — parakeet-mlx (MLX) is the best local quality/speed here.",
+    };
+  }
+
+  // Linux 4GB+ → onnx-asr (Parakeet int8 ONNX — the proven scribe Linux
+  // path). Arch-gated: onnxruntime publishes wheels for x64/arm64 only.
+  if (platform === "linux" && (arch === "x64" || arch === "arm64") && gb >= 4 - NOMINAL_SLACK_GB) {
+    return {
+      ...base,
+      provider: "onnx-asr",
+      model: DEFAULT_ONNX_ASR_MODEL,
+      approxDiskMb: 670,
+      peakRamNote: "~1.2–2GB+ peak while transcribing (meeting-length audio uses the high end)",
+      reason: "Linux with 4GB+ RAM — onnx-asr runs Parakeet (int8 ONNX) comfortably at this size.",
+    };
+  }
+
+  // transcribe-cpp fallback tiers — only where a release asset exists for the
+  // host. Covers Linux ~2GB (whisper-small — NOT Parakeet, scribe#82) and the
+  // hosts the ratified table doesn't name (Intel macs etc.), reusing the
+  // Phase 2a RAM matrix (which already floors Parakeet-GGUF at 4GB).
+  const asset = selectAsset(platform, arch);
+  if (asset && gb >= 2 - NOMINAL_SLACK_GB) {
+    // Model pick: slack belongs to TIER-ENTRY boundaries, never to model-floor
+    // checks. The 4GB Parakeet-GGUF floor is checked against the UN-INFLATED
+    // RAM (adding slack here once picked a ~3.5GB-peak model for a real-3.6GB
+    // Intel Mac — ~0.1GB headroom, the scribe#82 OOM class resurrected).
+    // Below a true 4GB, the ratified "~2GB → small whisper" row covers the
+    // whole band (entry already vetted ≥ ~2GB nominal above).
+    const model: ModelChoice =
+      gb >= 4
+        ? (selectModelForRam(totalRamBytes) ?? MODELS["whisper-small.en"]!)
+        : MODELS["whisper-small.en"]!;
+    return {
+      ...base,
+      provider: "transcribe-cpp",
+      model: model.name,
+      approxDiskMb: model.approxSizeMb,
+      peakRamNote: `~${model.approxRuntimeGb}GB peak while transcribing`,
+      reason:
+        gb < 4
+          ? `~${base.totalRamGb}GB RAM — a small whisper GGUF via transcribe-cpp fits; Parakeet's peak RAM exceeds 2GB on meeting-length audio (scribe#82).`
+          : `${platform}/${arch} isn't a parakeet-mlx/onnx-asr tier host — transcribe-cpp with a RAM-tier GGUF is the local default.`,
+    };
+  }
+
+  // Linux ~1GB (and any asset-supported host just above the floor) → remote
+  // by default; whisper-tiny via transcribe-cpp only as an explicit opt-in.
+  if (asset && gb >= 1 - FLOOR_SLACK_GB) {
+    return {
+      ...base,
+      provider: "scribe-http",
+      reason: `only ~${base.totalRamGb}GB RAM — a remote provider is the reliable default at this size.`,
+      localOptIn: {
+        provider: "transcribe-cpp",
+        model: "whisper-tiny.en",
+        note: "a tiny local model is possible but slow/low-quality: `transcription install --provider transcribe-cpp --model whisper-tiny.en`",
+      },
+    };
+  }
+
+  // Below the floor, or a host with no local runtime at all → remote guidance.
+  return {
+    ...base,
+    provider: "scribe-http",
+    reason: asset
+      ? `only ~${base.totalRamGb}GB RAM — below the 1GB local floor; use a remote provider.`
+      : `no local transcription runtime for ${platform}/${arch} — use a remote provider.`,
+  };
+}

package/src/transcription-worker.test.ts

@@ -140,6 +140,50 @@ describe("transcription worker", () => {
     expect(att.metadata?.transcript).toBe("hello world transcript");
   });
 
+  test("injected provider (scribe-fold 2a): worker routes audio→text through it, not scribe-http", async () => {
+    const note = await store.createNote(
+      "# 🎙️ Voice memo\n\n_Transcript pending._\n",
+      { id: "n1cpp", metadata: { transcribe_stub: true } },
+    );
+    seedAudio("memos/cpp.webm");
+    await store.addAttachment(note.id, "memos/cpp.webm", "audio/webm", {
+      transcribe_status: "pending",
+    });
+
+    // A fake local provider (stands in for transcribe-cpp). If the worker used
+    // it, the note gets this text; a `fetchImpl` that throws proves scribe-http
+    // was NOT called.
+    let called = 0;
+    const provider = {
+      name: "transcribe-cpp",
+      available: async () => ({ ok: true }),
+      transcribe: async () => {
+        called++;
+        return { text: "local transcript" };
+      },
+    };
+    const worker = startTranscriptionWorker({
+      vaultList: () => ["default"],
+      getStore: () => store as unknown as Store,
+      resolveAssetsDir: () => assetsRoot,
+      provider,
+      fetchImpl: (() => {
+        throw new Error("scribe-http must not be called when a provider is injected");
+      }) as unknown as typeof fetch,
+      pollIntervalMs: 10_000_000,
+      logger: silentLogger,
+    });
+    try {
+      expect(await worker.tick()).toBe(1);
+    } finally {
+      await worker.stop();
+    }
+
+    expect(called).toBe(1);
+    const updated = await store.getNote("n1cpp");
+    expect(updated!.content).toBe("# 🎙️ Voice memo\n\nlocal transcript\n");
+  });
+
   test("no-clobber: stub flag absent → does not touch note content", async () => {
     await store.createNote("my own edit", { id: "n2" });
     seedAudio("memos/b.webm");

package/src/transcription-worker.ts

@@ -55,9 +55,14 @@ import { join, normalize } from "path";
 import { existsSync, readFileSync, unlinkSync } from "fs";
 import type { Store, Attachment, Note } from "../core/src/types.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
-import { appendContextPart, fetchContextEntries, type ContextPayload } from "./context.ts";
+import { fetchContextEntries, type ContextPayload } from "./context.ts";
 import type { TriggerIncludeContext } from "./config.ts";
 import { upsertTranscriptNote } from "./transcript-note.ts";
+import {
+  TranscriptionError,
+  type TranscriptionProvider,
+} from "../core/src/transcription/provider.ts";
+import { ScribeHttpProvider } from "./transcription/providers/scribe-http.ts";
 
 /** Placeholder pattern written by the voice-memo capture stub. */
 const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
@@ -118,8 +123,12 @@ export interface TranscriptionWorkerOpts {
   vaultList: () => string[];
   /** Get a store for a vault name. */
   getStore: (name: string) => Store;
-  /** Scribe base URL (no trailing slash). */
-  scribeUrl: string;
+  /**
+   * Scribe base URL (no trailing slash). Only used to build the default
+   * `scribe-http` provider when no `provider` is injected — a `transcribe-cpp`
+   * (or any injected) provider needs no scribe URL, so this is optional.
+   */
+  scribeUrl?: string;
   /** Optional bearer token for scribe. */
   scribeToken?: string;
   /** Resolve the assets root for a vault name. */
@@ -138,6 +147,15 @@ export interface TranscriptionWorkerOpts {
   maxAttempts?: number;
   timeoutMs?: number;
   fetchImpl?: typeof fetch;
+  /**
+   * Transcription provider (scribe-fold Phase 1). When omitted, a behavior-
+   * preserving `scribe-http` provider is built from `scribeUrl` / `scribeToken`
+   * / `timeoutMs` / `fetchImpl` — reproducing exactly the former `callScribe`.
+   * Phase 2+ (local-ASR backends, the cloud Workers-AI provider) inject one
+   * here; the worker's queue/backoff/retry/transcript-note/retention logic is
+   * unchanged regardless.
+   */
+  provider?: TranscriptionProvider;
   logger?: { info?: (...args: unknown[]) => void; error: (...args: unknown[]) => void };
 }
 
@@ -180,25 +198,6 @@ interface PendingMeta {
   [k: string]: unknown;
 }
 
-/**
- * Structured error thrown when scribe returns a 4xx with a recognized
- * `error_code` — we surface the code on the transcript note's frontmatter
- * so callers can branch on stable strings instead of regex-matching message
- * text. Today the canonical code is `missing_provider` (scribe#47).
- */
-class ScribeApiError extends Error {
-  readonly errorCode?: string;
-  readonly httpStatus: number;
-  readonly retriable: boolean;
-  constructor(message: string, opts: { errorCode?: string; httpStatus: number; retriable: boolean }) {
-    super(message);
-    this.name = "ScribeApiError";
-    this.errorCode = opts.errorCode;
-    this.httpStatus = opts.httpStatus;
-    this.retriable = opts.retriable;
-  }
-}
-
 /**
  * Start the worker loop. Returns a handle with `stop()` + `tick()`.
  * Tests should build the worker and call `tick()` directly; production
@@ -217,6 +216,18 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const retentionFor = opts.getAudioRetention ?? (() => "keep" as const);
 
+  // Resolve the transcription provider (scribe-fold Phase 1). Default: the
+  // behavior-preserving `scribe-http` provider built from the same
+  // scribeUrl/token/timeout/fetch the worker was already constructed with —
+  // so existing installs transcribe byte-identically. Callers may inject a
+  // different provider without touching any of the queue/retry logic below.
+  const provider: TranscriptionProvider = opts.provider ?? new ScribeHttpProvider({
+    url: opts.scribeUrl,
+    token: opts.scribeToken,
+    timeoutMs,
+    fetchImpl,
+  });
+
   let stopped = false;
   let inflight: Promise<void> = Promise.resolve();
   let timer: ReturnType<typeof setTimeout> | null = null;
@@ -474,30 +485,35 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
 
     let scribeResult: { text: string; durationMs: number };
     try {
-      scribeResult = await callScribe({
-        url: opts.scribeUrl,
-        token: opts.scribeToken,
-        filePath,
+      // Read the audio + call the provider inside this try so a read failure
+      // (a race deleting the file between existsSync and read) is handled the
+      // same way as a transcription failure — as a retriable error — exactly
+      // as the former `callScribe` (which read the file internally) did. The
+      // worker owns the wall-clock timing (`durationMs`); the provider owns
+      // only the audio→text step.
+      const audio = readFileSync(filePath);
+      const startedAt = Date.now();
+      const result = await provider.transcribe({
+        audio,
         filename: attachment.path.split("/").pop() ?? "audio",
         mimeType: attachment.mimeType,
         context,
-        timeoutMs,
-        fetchImpl,
       });
+      scribeResult = { text: result.text, durationMs: Date.now() - startedAt };
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
-      const apiErr = err instanceof ScribeApiError ? err : null;
-      // 4xx with structured error code → terminal immediately. Re-POSTing the
-      // same audio at a scribe with no provider configured (or that rejects
-      // our bearer) will keep failing — the operator has to act, retries don't
-      // help. This is the "graceful first-boot path" from design Q5.
+      const apiErr = err instanceof TranscriptionError ? err : null;
+      // A non-retriable provider error (a 4xx the operator must fix — no
+      // provider configured, bad auth) is terminal immediately. Re-POSTing the
+      // same audio would keep failing; retries don't help. This is the
+      // "graceful first-boot path" from design Q5.
       const nonRetriable = apiErr !== null && !apiErr.retriable;
       const nextAttempts = attempts + 1;
       const terminal = nonRetriable || nextAttempts >= maxAttempts;
 
       if (terminal) {
         if (nonRetriable) {
-          logger.error(`[transcribe] non-retriable scribe error on attachment ${attachment.id} (status ${apiErr!.httpStatus}${apiErr!.errorCode ? `, ${apiErr!.errorCode}` : ""}):`, errMsg);
+          logger.error(`[transcribe] non-retriable provider error on attachment ${attachment.id} (status ${apiErr!.httpStatus ?? "n/a"}${apiErr!.code ? `, ${apiErr!.code}` : ""}):`, errMsg);
         } else {
           logger.error(`[transcribe] giving up on attachment ${attachment.id} after ${nextAttempts} attempts:`, errMsg);
         }
@@ -506,10 +522,10 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
           transcribe_status: "failed",
           transcribe_attempts: nextAttempts,
           transcribe_error: errMsg,
-          ...(apiErr?.errorCode ? { transcribe_error_code: apiErr.errorCode } : {}),
+          ...(apiErr?.code ? { transcribe_error_code: apiErr.code } : {}),
         });
         if (isAutoOrigin) {
-          await writeFailureTranscriptNote(store, attachment, errMsg, apiErr?.errorCode, undefined);
+          await writeFailureTranscriptNote(store, attachment, errMsg, apiErr?.code, undefined);
         } else {
           await applyFailureMarker(store, attachment.noteId);
         }
@@ -744,90 +760,9 @@ export function registerTranscriptionHook(
 }
 
 /**
- * Call scribe's `POST /v1/audio/transcriptions` with the audio file + optional
- * context part. Returns the transcript text plus the wall-clock duration of
- * the request, so the worker can surface `transcript_duration_ms` on the
- * transcript note.
- *
- * Failure modes (encoded as throws):
- *   - 4xx with a JSON body carrying `error_code`: throws `ScribeApiError`
- *     with the code (`missing_provider` etc.). Treated as a non-retriable
- *     terminal failure — re-POSTing the same audio at the same broken scribe
- *     would just fail the same way; the operator has to act.
- *   - 4xx without `error_code` (auth, malformed multipart): throws
- *     `ScribeApiError` with the body text. Non-retriable.
- *   - 5xx, network error, or timeout: throws a plain `Error`. Retriable —
- *     the worker's backoff path picks it up.
- *   - 200 with missing/invalid `text` field: throws a plain `Error`.
- *     Retriable (could be a transient provider-output glitch).
- */
-async function callScribe(args: {
-  url: string;
-  token?: string;
-  filePath: string;
-  filename: string;
-  mimeType: string;
-  context: ContextPayload | null;
-  timeoutMs: number;
-  fetchImpl: typeof fetch;
-}): Promise<{ text: string; durationMs: number }> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), args.timeoutMs);
-  const startedAt = Date.now();
-  try {
-    const fileBuffer = readFileSync(args.filePath);
-    const file = new File([fileBuffer], args.filename, { type: args.mimeType });
-    const form = new FormData();
-    form.append("file", file);
-    if (args.context) appendContextPart(form, args.context);
-
-    const endpoint = `${args.url.replace(/\/$/, "")}/v1/audio/transcriptions`;
-    const headers: Record<string, string> = {};
-    if (args.token) headers["Authorization"] = `Bearer ${args.token}`;
-
-    const resp = await args.fetchImpl(endpoint, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: controller.signal,
-    });
-    if (!resp.ok) {
-      const body = await resp.text().catch(() => "");
-      // Try to extract structured error_code from JSON body (scribe#47).
-      let errorCode: string | undefined;
-      let errorMessage: string | undefined;
-      try {
-        const parsed = JSON.parse(body) as { error?: string; error_code?: string; message?: string };
-        if (typeof parsed.error_code === "string") errorCode = parsed.error_code;
-        if (typeof parsed.error === "string") errorMessage = parsed.error;
-        else if (typeof parsed.message === "string") errorMessage = parsed.message;
-      } catch {
-        // Not JSON — leave errorCode undefined; the raw body becomes the message.
-      }
-      // 4xx is terminal (re-POSTing the same audio at the same broken scribe
-      // will just fail again). 5xx is retriable — provider hiccup, will likely
-      // succeed on backoff.
-      const retriable = resp.status >= 500;
-      const message = errorMessage
-        ?? (errorCode ? `scribe ${errorCode}` : `scribe returned ${resp.status}: ${body}`);
-      throw new ScribeApiError(message, {
-        errorCode,
-        httpStatus: resp.status,
-        retriable,
-      });
-    }
-    const result = await resp.json() as { text?: string };
-    if (typeof result.text !== "string") {
-      throw new Error("scribe response missing text field");
-    }
-    return { text: result.text, durationMs: Date.now() - startedAt };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * Re-export the structured error type so tests + callers can `instanceof`-check
- * for terminal-failure semantics.
+ * Re-export the structured provider error so tests + callers can
+ * `instanceof`-check for terminal-failure semantics. The scribe HTTP call
+ * itself now lives in `src/transcription/providers/scribe-http.ts` behind the
+ * `TranscriptionProvider` seam (scribe-fold Phase 1).
  */
-export { ScribeApiError };
+export { TranscriptionError };