feat(server): checksum-verified downloads + pinned whisper runtime/model manifest (WSP-1)

[eliotlim]

Problem

Local transcription depends on hand-installed whisper-cli/ffmpeg, and the whisper model download has no checksum and no update path (exists → done). Epic WSP (zero-setup local transcription); board: OB WSP-1.

Solution

Foundation layer in packages/server:

• ai/download.ts — shared verified streamer: stream to .part while hashing, size + SHA-256 checks, fsync, atomic rename; every failure path (HTTP, transport, overrun, short, hash, disk) unlinks the partial and preserves the old destination.
• ai/runtimeManifest.ts — per-target pins (4 release triples) for whisper-cli + ffmpeg with self-computed SHA-256s from actually-downloaded artifacts, typed unsupported entries where no trustworthy upstream prebuilt exists, extractDir capturing the Windows companion-DLL requirement, plus the model pin (HF commit-sha URL).
• ai/pinnedDownload.ts — receipt-based version-aware skip/re-download (crash-safe ordering: unlink receipt → download → rename dest → write receipt); legacy files re-download; failed upgrades keep old bytes usable.
• Llama GGUF arbitrary-URL downloads keep today's behaviour byte-for-byte.
  Alternative considered: verifying only the model — rejected; the binary manifest is the contract WSP-2 (provisioning) and WSP-6 (own signed builds) build on.

Before / After

Behavior	Before	After
Model download integrity	none (any bytes accepted)	SHA-256 + size verified, atomic — no visual change
Model update on pin bump	impossible (exists → done)	receipt mismatch → re-download
Runtime binary sourcing	undocumented/manual	pinned manifest; unsupported targets typed (macOS/Linux whisper-cli, mac-ARM ffmpeg → WSP-6 own builds)
Partial/corrupt downloads	.part could strand; corrupt file kept	cleaned up on every path (unit-tested)

Test procedure

• pnpm verify — full suite green (server 105 files / 1418 passed; foreground, outside sandbox)
• Focused: pnpm --filter @book.dev/server exec vitest run src/ai/download.test.ts src/ai/runtimeManifest.test.ts src/ai/pinnedDownload.test.ts src/ai/serviceDownload.test.ts — 20 tests
• Artifact hashes independently reproducible: curl -fL <pinned url> | shasum -a 256 matches the manifest for all 5 artifacts (table in the manifest file).

Operational notes

• Coverage gaps are deliberate, typed state: no official upstream whisper-cli for macOS/Linux, no ARM64-mac ffmpeg from the pinned provider — WSP-6 (own signed builds in release CI, owner-approved) flips those entries; WSP-2 consumes the manifest either way.
• Upstream availability risk recorded (johnvansickle archives old releases; evermeet redirects to a nonstandard-port host) — mitigation lands with WSP-6 mirroring.
• No API/contract changes: AiStatus/progress shapes unchanged; transcription.downloadUrl now returns the pinned URL (UI already round-trips it).

Verify status: full pnpm verify green at 043faae + focused suites green at 81bbcf8 · Reviews cleared: code (Quinn — CLEAR-with-nits; F1/F2/F4 applied via pre-endorsed fixes @ 81bbcf8; F3/F5/F6 tracked on WSP-2/WSP-6 cards)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
app.book.pub	Ready	Preview	Oct 8, 2026 12:41am UTC