@1agh/maude 0.43.0 → 0.44.0

package/apps/studio/generation/registry.ts

@@ -0,0 +1,88 @@
+// generation/registry.ts — the provider/model registry (DDR-16x). Maps a
+// provider id → its descriptor + adapter factory, and answers capability
+// lookups ("which providers can do image?") for routing + the Settings panel.
+//
+// Adding a provider = one entry here. Phase 0 ships Gemini (image); Phase 1 adds
+// fal, Phase 2 ElevenLabs, etc. — each is a factory + descriptor, no route change.
+//
+// The registry holds FACTORIES, not live adapters: an adapter is instantiated
+// per-request with the resolved key + localizer injected (AdapterContext), so a
+// key never lives on a long-held adapter object.
+
+import {
+  createElevenLabsAdapter,
+  ELEVENLABS_DESCRIPTOR,
+  ELEVENLABS_MODELS,
+} from './adapters/elevenlabs.ts';
+import { createGeminiAdapter, GEMINI_DESCRIPTOR, GEMINI_MODELS } from './adapters/gemini.ts';
+import { createGroqAdapter, GROQ_DESCRIPTOR, GROQ_MODELS } from './adapters/groq.ts';
+import type {
+  AdapterContext,
+  AdapterFactory,
+  Modality,
+  ModelDescriptor,
+  ProviderAdapter,
+  ProviderDescriptor,
+} from './types.ts';
+
+interface ProviderEntry {
+  descriptor: ProviderDescriptor;
+  factory: AdapterFactory;
+  /** Static model list (aggregators refresh via adapter.listModels at runtime). */
+  models: ModelDescriptor[];
+}
+
+const PROVIDERS: Record<string, ProviderEntry> = {
+  gemini: {
+    descriptor: GEMINI_DESCRIPTOR,
+    factory: createGeminiAdapter,
+    models: GEMINI_MODELS,
+  },
+  elevenlabs: {
+    descriptor: ELEVENLABS_DESCRIPTOR,
+    factory: createElevenLabsAdapter,
+    models: ELEVENLABS_MODELS,
+  },
+  // Task 2.6 — Groq managed Whisper STT (transcription only). A CHOSEN cloud
+  // engine, never auto-selected; the local whisper.cpp path stays the default.
+  groq: {
+    descriptor: GROQ_DESCRIPTOR,
+    factory: createGroqAdapter,
+    models: GROQ_MODELS,
+  },
+};
+
+/** Every registered provider descriptor (inert — safe to serialize to the UI). */
+export function listProviders(): ProviderDescriptor[] {
+  return Object.values(PROVIDERS).map((p) => p.descriptor);
+}
+
+/** The descriptor for one provider, or null when unknown. */
+export function getProviderDescriptor(id: string): ProviderDescriptor | null {
+  return PROVIDERS[id]?.descriptor ?? null;
+}
+
+/** The static model list for one provider. */
+export function getProviderModels(id: string): ModelDescriptor[] {
+  return PROVIDERS[id]?.models ?? [];
+}
+
+/** All providers that can produce a given modality (routing + capability UI). */
+export function providersForModality(modality: Modality): ProviderDescriptor[] {
+  return listProviders().filter((d) => d.modalities.includes(modality));
+}
+
+/** Whether a provider id is registered. */
+export function hasProvider(id: string): boolean {
+  return id in PROVIDERS;
+}
+
+/**
+ * Instantiate the adapter for `providerId` with a per-request context. Throws on
+ * an unknown provider (the route validates first, so this is a defensive guard).
+ */
+export function createAdapter(providerId: string, ctx: AdapterContext): ProviderAdapter {
+  const entry = PROVIDERS[providerId];
+  if (!entry) throw new Error(`unknown provider: ${providerId}`);
+  return entry.factory(ctx);
+}

package/apps/studio/generation/types.test.ts

@@ -0,0 +1,123 @@
+// generation/types.test.ts — type-level invariants proven through a fake
+// adapter + the request validator (the security surface behind
+// /_api/generate-jobs). Mirrors photo/schema.test.ts's dependency-free style.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  type AdapterContext,
+  type GenAsset,
+  type GenResult,
+  type Job,
+  type ProviderAdapter,
+  validateGenRequest,
+} from './types.ts';
+
+// A minimal sync fake — returns an already-`done` Job, proving the contract is
+// implementable without branching on sync/async.
+function fakeAdapter(_ctx: AdapterContext): ProviderAdapter {
+  return {
+    descriptor: {
+      id: 'fake',
+      label: 'Fake',
+      kind: 'cloud',
+      auth: 'api-key',
+      keychainService: 'com.maude.app.fake',
+      modalities: ['image'],
+    },
+    async submit() {
+      const result: GenResult = {
+        assets: [{ kind: 'image', mime: 'image/png', bytes: new Uint8Array([1, 2, 3]) }],
+        usage: { ms: 1 },
+      };
+      const job: Job = {
+        id: 'job_1',
+        status: () => 'done',
+        async *events() {
+          yield { status: 'done' as const };
+        },
+        result: async () => result,
+        cancel: () => {},
+      };
+      return job;
+    },
+  };
+}
+
+describe('generation contract', () => {
+  test('a sync adapter returns an already-done Job whose result localizes', async () => {
+    const localized: GenAsset[] = [];
+    const ctx: AdapterContext = {
+      apiKey: 'k',
+      localize: async (a) => {
+        localized.push(a);
+        return 'assets/deadbeef.png';
+      },
+    };
+    const adapter = fakeAdapter(ctx);
+    const job = await adapter.submit({ modality: 'image', provider: 'fake', prompt: 'a circle' });
+    expect(job.status()).toBe('done');
+    const res = await job.result();
+    expect(res.assets).toHaveLength(1);
+    const rel = await ctx.localize(res.assets[0]);
+    expect(rel).toBe('assets/deadbeef.png');
+    expect(localized).toHaveLength(1);
+  });
+});
+
+describe('validateGenRequest', () => {
+  test('accepts a well-formed image request', () => {
+    const r = validateGenRequest({ modality: 'image', provider: 'gemini', prompt: 'a red circle' });
+    expect(r.ok).toBe(true);
+    expect(r.errors).toEqual([]);
+  });
+
+  test('accepts a source-only edit request (no prompt)', () => {
+    const r = validateGenRequest({
+      modality: 'transcription',
+      provider: 'whisper',
+      sourceAsset: 'assets/abcd1234.mp4',
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  test('rejects a non-object', () => {
+    expect(validateGenRequest(null).ok).toBe(false);
+    expect(validateGenRequest('x').ok).toBe(false);
+  });
+
+  test('rejects unknown modality + malformed provider', () => {
+    const r = validateGenRequest({ modality: 'hologram', provider: '../etc' });
+    expect(r.ok).toBe(false);
+    expect(r.errors.some((e) => e.startsWith('modality'))).toBe(true);
+    expect(r.errors.some((e) => e.startsWith('provider'))).toBe(true);
+  });
+
+  test('rejects a traversing sourceAsset', () => {
+    const r = validateGenRequest({
+      modality: 'image',
+      provider: 'gemini',
+      sourceAsset: '../../etc/passwd',
+    });
+    expect(r.ok).toBe(false);
+    expect(r.errors.some((e) => e.startsWith('sourceAsset'))).toBe(true);
+  });
+
+  test('rejects a bad aspect ratio + an over-long prompt', () => {
+    const r = validateGenRequest({
+      modality: 'image',
+      provider: 'gemini',
+      prompt: 'x'.repeat(9000),
+      aspectRatio: 'wide',
+    });
+    expect(r.ok).toBe(false);
+    expect(r.errors.some((e) => e.startsWith('prompt'))).toBe(true);
+    expect(r.errors.some((e) => e.startsWith('aspectRatio'))).toBe(true);
+  });
+
+  test('rejects a request with neither prompt nor sourceAsset', () => {
+    const r = validateGenRequest({ modality: 'image', provider: 'gemini' });
+    expect(r.ok).toBe(false);
+    expect(r.errors.some((e) => e.includes('prompt or a sourceAsset'))).toBe(true);
+  });
+});

package/apps/studio/generation/types.ts

@@ -0,0 +1,266 @@
+/**
+ * @file       generation/types.ts — the provider-adapter contract (DDR-16x).
+ * @scope      apps/studio/generation/types.ts
+ * @purpose    The single normalized contract every media-generation provider —
+ *             cloud aggregator (fal), direct-BYOK provider (Gemini/ElevenLabs),
+ *             or local runtime (Ollama/ComfyUI) — is expressed through:
+ *             `submit(req) → Job`, and the produced bytes localize into the
+ *             content-addressed `assets/<sha8>` store (DDR-088).
+ *
+ * @invariant  DEPENDENCY-FREE. Imported by BOTH the server (registry, adapters,
+ *             the /_api/generate-jobs route) and — for the descriptor/model
+ *             shapes only — the client Settings panel. It MUST NOT import any
+ *             provider SDK, `node:*`, or browser lib. Pure TS types + plain
+ *             hand-rolled validators (no Ajv), mirroring `photo/schema.ts` and
+ *             `footage/schema.ts`.
+ *
+ *             Key custody lives in `keys.ts`, NOT here — a descriptor only
+ *             DECLARES how it authenticates (`auth` + `keychainService`); the
+ *             host injects the resolved credential at call time so keys stay in
+ *             one place and never cross into the untrusted canvas realm (DDR-054).
+ */
+
+/** Schema version of the generation contract — bumped on incompatible change. */
+export const GENERATION_CONTRACT_VERSION = 1 as const;
+
+/** What a provider produces. */
+export type Modality = 'image' | 'video' | 'audio' | 'transcription';
+export const MODALITIES: readonly Modality[] = ['image', 'video', 'audio', 'transcription'];
+
+/** Where a provider runs — a `cloud` call needs a key + egress; `local` is a
+ *  loopback runtime on the user's own hardware (post-v1). */
+export type ProviderKind = 'cloud' | 'local';
+
+/** How a provider authenticates. `none` = local runtime (no credential). */
+export type AuthKind = 'api-key' | 'none';
+
+/**
+ * A provider — a vendor/runtime that exposes one or more models across one or
+ * more modalities. The descriptor is inert data (safe to serialize to the
+ * client Settings panel); it carries NO secret.
+ */
+export interface ProviderDescriptor {
+  /** Stable slug — the key custody + config + route all key off this. */
+  id: string;
+  /** Human label for the Settings UI. */
+  label: string;
+  kind: ProviderKind;
+  auth: AuthKind;
+  /**
+   * OS-keychain service name for the native tier (`com.maude.app.<id>`), and
+   * the lookup key in the `~/.config/maude/keys.json` browser fallback. Absent
+   * for `auth: 'none'` local runtimes.
+   */
+  keychainService?: string;
+  /** Modalities this provider can produce (drives capability lookup + routing). */
+  modalities: readonly Modality[];
+  /**
+   * Where the user gets a key + the pricing/licensing note the Settings UI must
+   * surface (music commercial-rights tier, voice-cloning consent, etc.). Inert
+   * copy, never a secret.
+   */
+  keyUrl?: string;
+  notes?: string;
+  /** Default loopback host:port for a `local` runtime (probe target). */
+  localEndpoint?: string;
+}
+
+/** One concrete model a provider offers. */
+export interface ModelDescriptor {
+  /** Provider-scoped id passed to `submit` (e.g. `gemini-2.5-flash-image`). */
+  id: string;
+  label: string;
+  modality: Modality;
+  /** Non-secret capability hints for the generate dialog + routing. */
+  aspectRatios?: readonly string[];
+  /** Rough per-unit cost note for the UI cost badge (`~$0.04/image`). */
+  costNote?: string;
+  /** True when the model round-trips synchronously (Job returns already `done`). */
+  sync?: boolean;
+}
+
+/** The user's generation request, normalized across every modality. */
+export interface GenRequest {
+  modality: Modality;
+  /** Provider id (`gemini`, `elevenlabs`, `fal`, …). */
+  provider: string;
+  /** Provider-scoped model id. Optional — adapter picks its default. */
+  model?: string;
+  /** The text prompt (image/video/audio) or the source asset (transcription). */
+  prompt?: string;
+  /** `assets/<sha8>.<ext>` source for edit/i2v/transcription flows. */
+  sourceAsset?: string;
+  /** `1:1` / `16:9` / … — adapter maps to the provider's own vocabulary. */
+  aspectRatio?: string;
+  /** Free-form provider-specific knobs (duration, voice_id, seed, …). Opaque
+   *  to the spine; each adapter validates its own subset. */
+  params?: Record<string, unknown>;
+}
+
+export type JobStatus = 'queued' | 'running' | 'done' | 'failed';
+
+/** A progress/log tick a long-running (async) job may emit. */
+export interface JobEvent {
+  status: JobStatus;
+  /** 0..1 fractional progress when the provider reports it. */
+  progress?: number;
+  message?: string;
+}
+
+/** One produced artifact — a URL (localize immediately, may expire), inline
+ *  base64/bytes, or a caption text blob. Exactly one payload field is set. */
+export interface GenAsset {
+  kind: Modality;
+  mime: string;
+  /** Expiring provider URL — MUST be downloaded through the hardened egress path
+   *  (`download.ts`) before it's referenced anywhere. */
+  url?: string;
+  /** Inline bytes (sync base64 providers decode into this). */
+  bytes?: Uint8Array;
+  /** Text payload (SRT/VTT captions from a transcription provider). */
+  text?: string;
+}
+
+/** The normalized result once a Job is `done`. */
+export interface GenResult {
+  assets: GenAsset[];
+  usage?: { cost?: number; ms?: number };
+  /** The provider's raw response, kept for audit/debug (never sent to canvas). */
+  raw?: unknown;
+}
+
+/**
+ * A generation handle. Sync providers return an already-`done` Job (so callers
+ * never branch on sync/async); async providers drive `queued → running → done`.
+ */
+export interface Job {
+  id: string;
+  status(): JobStatus;
+  /** Live progress stream (async providers). Sync providers yield one `done`. */
+  events(): AsyncIterable<JobEvent>;
+  result(): Promise<GenResult>;
+  cancel(): void;
+}
+
+/**
+ * One re-usable past generation from a provider's history (Task 2.5). The user's
+ * OWN prior audio, re-downloadable for NO credit (already paid) — ranked against
+ * a query alongside the project's local generated audio so reuse beats paying
+ * for a near-identical new generation.
+ */
+export interface HistoryAudioItem {
+  /** Provider-scoped id used to re-fetch the bytes (`fetchHistoryAudio`). */
+  id: string;
+  /** The stored source text / prompt this item was generated from (match key). */
+  text: string;
+  /** ISO timestamp when it was produced (recency tie-break). */
+  at?: string;
+  /** e.g. a voice_id for TTS — surfaced for provenance, never trusted blindly. */
+  voiceId?: string;
+}
+
+/**
+ * The one interface every adapter implements. `submit` returns immediately —
+ * even sync providers hand back a resolved Job so the host queue is uniform.
+ */
+export interface ProviderAdapter {
+  descriptor: ProviderDescriptor;
+  /** Refresh the model catalogue (aggregators). Static providers may omit it. */
+  listModels?(): Promise<ModelDescriptor[]>;
+  submit(req: GenRequest): Promise<Job>;
+  /**
+   * Task 2.5 — list the user's re-usable audio history (ElevenLabs). Optional;
+   * only providers with a free re-download history implement it. Used by the
+   * audio-search route to offer reuse before a paid generation.
+   */
+  listHistory?(): Promise<HistoryAudioItem[]>;
+  /**
+   * Task 2.5 — re-fetch a history item's bytes (NO credit — already paid) as an
+   * audio GenAsset the host localizes into `assets/<sha8>`. Optional, paired
+   * with `listHistory`.
+   */
+  fetchHistoryAudio?(id: string): Promise<GenAsset>;
+}
+
+/**
+ * Context the host injects into `submit` at call time — the resolved credential
+ * (never stored on the adapter) + a localizer that lands result bytes/URLs into
+ * `assets/<sha8>`. Passed alongside the request so key custody stays external.
+ */
+export interface AdapterContext {
+  /** The resolved API key, or null for a `local`/`none`-auth provider. */
+  apiKey: string | null;
+  /** Localize a produced asset into `assets/<sha8>.<ext>`; returns the rel path. */
+  localize(asset: GenAsset): Promise<string>;
+  /**
+   * Read a content-addressed `assets/<sha8>.<ext>` source's bytes + sniffed mime
+   * for edit / image-to-video flows (a `GenRequest.sourceAsset`). Host-provided
+   * so the adapter never touches the filesystem; returns null for an unknown or
+   * contained-out path. Absent when the host wires no source access (Phase 0).
+   */
+  readSourceAsset?(rel: string): Promise<{ bytes: Uint8Array; mime: string } | null>;
+  /** AbortSignal so a cancelled job tears down its provider request. */
+  signal?: AbortSignal;
+}
+
+/** An adapter factory — the registry stores these, one per provider. */
+export type AdapterFactory = (ctx: AdapterContext) => ProviderAdapter;
+
+// ── Structural validation (dependency-free — no Ajv) ─────────────────────────
+// The /_api/generate-jobs route validates the untrusted request body with this
+// before it reaches an adapter (security surface — a crafted field must never
+// reach a provider POST or the filesystem). Mirrors photo/schema.ts's style.
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+// Same content-addressed relative-path allowlist as photo/schema.ts — never a
+// data:/blob:/absolute/traversing path.
+const ASSET_REL_RE = /^assets\/[0-9a-f]{8,}[A-Za-z0-9._-]*$/;
+// Conservative provider/model id shape — slug-ish, no path separators.
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ASPECT_RE = /^\d{1,2}:\d{1,2}$/;
+const MAX_PROMPT_LEN = 8000;
+
+export function isModality(v: unknown): v is Modality {
+  return typeof v === 'string' && (MODALITIES as readonly string[]).includes(v);
+}
+
+/** Validate an untrusted `GenRequest` body. Returns collected errors. */
+export function validateGenRequest(input: unknown): ValidationResult {
+  const errors: string[] = [];
+  if (!isPlainObject(input)) return { ok: false, errors: ['request must be an object'] };
+
+  if (!isModality(input.modality)) errors.push(`modality: must be one of ${MODALITIES.join('|')}`);
+  if (typeof input.provider !== 'string' || !ID_RE.test(input.provider))
+    errors.push('provider: missing or malformed id');
+  if (input.model != null && (typeof input.model !== 'string' || !ID_RE.test(input.model)))
+    errors.push('model: malformed id');
+
+  if (input.prompt != null) {
+    if (typeof input.prompt !== 'string') errors.push('prompt: must be a string');
+    else if (input.prompt.length > MAX_PROMPT_LEN)
+      errors.push(`prompt: exceeds ${MAX_PROMPT_LEN} chars`);
+  }
+  if (input.sourceAsset != null) {
+    if (typeof input.sourceAsset !== 'string' || !ASSET_REL_RE.test(input.sourceAsset))
+      errors.push('sourceAsset: must be a content-addressed assets/<sha8>.<ext> path');
+  }
+  if (input.aspectRatio != null) {
+    if (typeof input.aspectRatio !== 'string' || !ASPECT_RE.test(input.aspectRatio))
+      errors.push('aspectRatio: must look like W:H');
+  }
+  if (input.params != null && !isPlainObject(input.params))
+    errors.push('params: must be an object');
+
+  // A request needs SOMETHING to act on — a prompt or a source asset.
+  if (input.prompt == null && input.sourceAsset == null)
+    errors.push('request needs a prompt or a sourceAsset');
+
+  return { ok: errors.length === 0, errors };
+}

package/apps/studio/generation/whisper-models.test.ts

@@ -0,0 +1,152 @@
+// whisper-models.test.ts — managed local whisper.cpp model registry + resolution
+// + download (Task 2.7, approach A). Uses a temp XDG_CACHE_HOME so the real
+// user cache is never touched, and a stubbed fetch for the download path.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  downloadWhisperModel,
+  getWhisperModel,
+  listWhisperModels,
+  removeWhisperModel,
+  resolveWhisperModel,
+  WHISPER_MODELS,
+  whisperModelsDir,
+  whisperModelUrl,
+} from './whisper-models.ts';
+
+const realFetch = globalThis.fetch;
+let cacheRoot: string;
+const prevXdg = process.env.XDG_CACHE_HOME;
+
+beforeEach(() => {
+  cacheRoot = mkdtempSync(join(tmpdir(), 'maude-wm-'));
+  process.env.XDG_CACHE_HOME = cacheRoot;
+});
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
+  else process.env.XDG_CACHE_HOME = prevXdg;
+});
+
+describe('registry', () => {
+  test('carries base (multilingual) + base.en (English-only)', () => {
+    expect(getWhisperModel('base')?.multilingual).toBe(true);
+    expect(getWhisperModel('base.en')?.multilingual).toBe(false);
+    expect(getWhisperModel('nope')).toBeNull();
+  });
+  test('whisperModelUrl derives the frozen ggerganov/whisper.cpp URL (SSRF-safe host)', () => {
+    const url = whisperModelUrl(getWhisperModel('base'));
+    expect(url).toBe('https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin');
+  });
+  test('whisperModelsDir honors XDG_CACHE_HOME', () => {
+    expect(whisperModelsDir()).toBe(join(cacheRoot, 'maude', 'whisper-models'));
+  });
+});
+
+describe('resolveWhisperModel', () => {
+  function fakeDownloaded(file: string) {
+    const dir = whisperModelsDir();
+    require('node:fs').mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, file), 'x');
+  }
+
+  test('returns null when nothing is downloaded', () => {
+    expect(resolveWhisperModel()).toBeNull();
+  });
+  test('prefers the configured id when present', () => {
+    fakeDownloaded('ggml-small.bin');
+    fakeDownloaded('ggml-base.bin');
+    expect(resolveWhisperModel('small')).toBe(join(whisperModelsDir(), 'ggml-small.bin'));
+  });
+  test('prefers a MULTILINGUAL model over an English-only one (Czech-footage safety)', () => {
+    fakeDownloaded('ggml-base.en.bin'); // English-only
+    fakeDownloaded('ggml-base.bin'); // multilingual
+    expect(resolveWhisperModel()).toBe(join(whisperModelsDir(), 'ggml-base.bin'));
+  });
+  test('falls back to any model if only English-only is present', () => {
+    fakeDownloaded('ggml-base.en.bin');
+    expect(resolveWhisperModel()).toBe(join(whisperModelsDir(), 'ggml-base.en.bin'));
+  });
+});
+
+describe('listWhisperModels', () => {
+  test('flags a downloaded model', () => {
+    const dir = whisperModelsDir();
+    require('node:fs').mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'ggml-tiny.bin'), 'abc');
+    const tiny = listWhisperModels().find((m) => m.id === 'tiny');
+    expect(tiny?.downloaded).toBe(true);
+    expect(tiny?.bytes).toBe(3);
+    expect(listWhisperModels().find((m) => m.id === 'base')?.downloaded).toBe(false);
+  });
+});
+
+describe('downloadWhisperModel', () => {
+  test('streams to the cache, reports progress, atomically lands the file', async () => {
+    const bytes = new Uint8Array(1024);
+    globalThis.fetch = (async () =>
+      new Response(bytes, {
+        status: 200,
+        headers: { 'content-length': String(bytes.byteLength) },
+      })) as typeof fetch;
+    const seen: number[] = [];
+    const path = await downloadWhisperModel('tiny', (r) => seen.push(r));
+    expect(path).toBe(join(whisperModelsDir(), 'ggml-tiny.bin'));
+    expect(existsSync(path)).toBe(true);
+    expect(existsSync(`${path}.part`)).toBe(false); // temp renamed away
+    expect(seen.at(-1)).toBe(1024);
+    expect(await removeWhisperModel('tiny')).toBe(true);
+    expect(existsSync(path)).toBe(false);
+  });
+
+  test('rejects an over-cap body (declared content-length) without writing', async () => {
+    globalThis.fetch = (async () =>
+      new Response(new Uint8Array(1), {
+        status: 200,
+        headers: { 'content-length': String(9999 * 1024 * 1024) }, // way over tiny's cap
+      })) as typeof fetch;
+    await expect(downloadWhisperModel('tiny', () => {})).rejects.toThrow(/larger than expected/);
+    expect(existsSync(join(whisperModelsDir(), 'ggml-tiny.bin'))).toBe(false);
+  });
+
+  test('unknown model id throws', async () => {
+    await expect(downloadWhisperModel('bogus', () => {})).rejects.toThrow(/unknown whisper model/);
+  });
+
+  test('rejects a redirect that lands off huggingface.co (Finding 2)', async () => {
+    // Simulate the HF blob redirect resolving to an attacker/on-path host.
+    globalThis.fetch = (async () => ({
+      url: 'https://evil.example/ggml-tiny.bin',
+      ok: true,
+      headers: new Headers(),
+      body: new Response(new Uint8Array(1)).body,
+    })) as unknown as typeof fetch;
+    await expect(downloadWhisperModel('tiny', () => {})).rejects.toThrow(/off huggingface\.co/);
+    expect(existsSync(join(whisperModelsDir(), 'ggml-tiny.bin'))).toBe(false);
+  });
+
+  test('accepts a redirect that stays on a huggingface.co CDN host', async () => {
+    const bytes = new Uint8Array(512);
+    globalThis.fetch = (async () => ({
+      url: 'https://cdn-lfs.huggingface.co/repos/x/ggml-tiny.bin',
+      ok: true,
+      headers: new Headers({ 'content-length': String(bytes.byteLength) }),
+      body: new Response(bytes).body,
+    })) as unknown as typeof fetch;
+    const path = await downloadWhisperModel('tiny', () => {});
+    expect(existsSync(path)).toBe(true);
+  });
+});
+
+describe('registry integrity', () => {
+  test('every model has a positive size and a ggml- file', () => {
+    for (const m of WHISPER_MODELS) {
+      expect(m.sizeMB).toBeGreaterThan(0);
+      expect(m.file.startsWith('ggml-')).toBe(true);
+    }
+  });
+});