@cofhe/sdk 0.7.0 → 0.8.0

package/web/index.ts

@@ -9,6 +9,8 @@ import {
   type ZkBuilderAndCrsGenerator,
   type FheKeyDeserializer,
   type EncryptableItem,
+  type TfheInitializer,
+  type TfheThreadsSetting,
   fheTypeToString,
   TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT,
 } from '@/core';
@@ -25,21 +27,86 @@ import { getWorkerManager, terminateWorker, areWorkersAvailable } from './worker
 // reference `self` at module top — into the import graph during Next.js SSR.
 import type { TfheCompactPublicKey, ProvenCompactCiphertextList, CompactPkeCrs } from 'tfhe';
 import { hasDOM } from './const';
+import { initTfheThreadPool, type TfheThreadPoolResult } from './tfheThreadPool.js';
 
-/**
- * Internal function to initialize TFHE for web
- * Called automatically on first encryption - users don't need to call this manually
- * @returns true if TFHE was initialized, false if already initialized
- */
 let tfheModule: typeof import('tfhe') | null = null;
 let tfheInitialized = false;
-async function initTfhe(): Promise<boolean> {
+let tfheInitPromise: Promise<void> | null = null;
+let threadPoolPromise: Promise<TfheThreadPoolResult> | null = null;
+let threadPoolResult: TfheThreadPoolResult | null = null;
+
+/**
+ * Outcome of the rayon thread pool setup on the main thread, or `null` if the
+ * main thread hasn't had to generate a proof yet. `enabled: false` carries a
+ * `reason`.
+ *
+ * Note this reflects the *main thread* only. When workers are enabled (the
+ * default) proving happens inside the zkProve worker, which runs its own pool,
+ * and the main thread never starts one — so `null` is the normal value there.
+ */
+export function getTfheThreadPoolStatus(): TfheThreadPoolResult | null {
+  return threadPoolResult;
+}
+
+/**
+ * Internal TFHE initializer used on web.
+ * Called automatically on first encryption - users don't need to call this manually.
+ *
+ * The wasm instance is a module-level singleton, so initialization is memoised.
+ * It deliberately does NOT start the rayon thread pool: the main thread only
+ * needs one when it generates a proof itself, see `createStartMainThreadPool`.
+ *
+ * @returns true if it performed the initialization, false if TFHE was already initialized
+ */
+const initTfhe: TfheInitializer = async () => {
   if (tfheInitialized) return false;
-  tfheModule = await import('tfhe');
-  await tfheModule.default();
-  await tfheModule.init_panic_hook();
-  tfheInitialized = true;
+
+  if (tfheInitPromise) {
+    // Another caller is already initializing; wait it out but don't claim
+    // credit for having done it.
+    await tfheInitPromise;
+    return false;
+  }
+
+  tfheInitPromise = (async () => {
+    const mod = await import('tfhe');
+    await mod.default();
+    await mod.init_panic_hook();
+    tfheModule = mod;
+    tfheInitialized = true;
+  })();
+
+  try {
+    await tfheInitPromise;
+  } catch (error) {
+    // Let the next call retry from scratch.
+    tfheInitPromise = null;
+    throw error;
+  }
+
   return true;
+};
+
+/**
+ * Starts the main thread's rayon pool right before the main thread generates a
+ * proof (workers disabled, unavailable, or the worker failed). With workers on
+ * the proof runs in the zkProve worker, which has its own pool, so a second one
+ * here would just be idle Web Workers plus another shared wasm memory.
+ *
+ * Must run before the FIRST main-thread proof: rayon locks in its global pool
+ * on first use, and `initThreadPool` fails from then on. Deserializing keys and
+ * packing inputs beforehand is fine. Memoised because `initThreadPool` may only
+ * run once per wasm instance — if an app creates several clients with different
+ * `tfheThreads` values, whichever proves on the main thread first wins.
+ *
+ * Best-effort: leaves tfhe single-threaded when the page isn't cross-origin
+ * isolated rather than failing the encryption.
+ */
+function createStartMainThreadPool(tfheThreads: TfheThreadsSetting) {
+  return async (): Promise<void> => {
+    threadPoolPromise ??= initTfheThreadPool(requireTfhe(), tfheThreads);
+    threadPoolResult = await threadPoolPromise;
+  };
 }
 
 function requireTfhe(): typeof import('tfhe') {
@@ -101,22 +168,27 @@ const zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator = (fhe: string, crs: st
 /**
  * Worker-enabled zkProve function
  * This submits proof generation to a Web Worker
+ *
+ * Bound to the client's `tfheThreads` setting, which the worker applies when it
+ * first initialises tfhe.
  */
-async function zkProveWithWorker(
-  fheKeyHex: string,
-  crsHex: string,
-  items: EncryptableItem[],
-  metadata: Uint8Array
-): Promise<Uint8Array> {
-  // Serialize items for worker (convert enum to string name)
-  const serializedItems = items.map((item) => ({
-    utype: fheTypeToString(item.utype),
-    data: typeof item.data === 'bigint' ? item.data.toString() : item.data,
-  }));
-
-  // Submit to worker
-  const workerManager = getWorkerManager();
-  return await workerManager.submitProof(fheKeyHex, crsHex, serializedItems, metadata);
+function createZkProveWithWorker(tfheThreads: TfheThreadsSetting) {
+  return async function zkProveWithWorker(
+    fheKeyHex: string,
+    crsHex: string,
+    items: EncryptableItem[],
+    metadata: Uint8Array
+  ): Promise<Uint8Array> {
+    // Serialize items for worker (convert enum to string name)
+    const serializedItems = items.map((item) => ({
+      utype: fheTypeToString(item.utype),
+      data: typeof item.data === 'bigint' ? item.data.toString() : item.data,
+    }));
+
+    // Submit to worker
+    const workerManager = getWorkerManager();
+    return await workerManager.submitProof(fheKeyHex, crsHex, serializedItems, metadata, tfheThreads);
+  };
 }
 
 /**
@@ -147,9 +219,10 @@ export function createCofheClient<TConfig extends CofheConfig>(config: TConfig):
     tfhePublicKeyDeserializer,
     compactPkeCrsDeserializer,
     initTfhe,
+    beforeMainThreadProve: createStartMainThreadPool(config.tfheThreads),
     // Always provide the worker function if available - config.useWorkers controls usage
     // areWorkersAvailable will return true if the Worker API is available and false in Node.js
-    zkProveWorkerFn: areWorkersAvailable() ? zkProveWithWorker : undefined,
+    zkProveWorkerFn: areWorkersAvailable() ? createZkProveWithWorker(config.tfheThreads) : undefined,
   });
 }
 
@@ -182,6 +255,7 @@ export function createCofheClientWithCustomWorker(
     tfhePublicKeyDeserializer,
     compactPkeCrsDeserializer,
     initTfhe,
+    beforeMainThreadProve: createStartMainThreadPool(config.tfheThreads),
     zkProveWorkerFn: customZkProveWorkerFn,
   });
 }

package/web/test/countingZkProveWorker.ts

@@ -0,0 +1,31 @@
+/**
+ * Test-only wrapper around the real zkProve worker.
+ *
+ * tfhe's rayon threads are Web Workers that the zkProve worker creates itself,
+ * so the page never sees them. This wrapper counts them from the inside: it
+ * swaps this worker's global `Worker` for a counting subclass, then loads the
+ * real `zkProve.worker` into the same global scope. The zkProve protocol is
+ * untouched; one extra message type reports the count.
+ */
+
+/* eslint-disable no-undef */
+
+const scope = self as any;
+const RealWorker = scope.Worker;
+let rayonWorkersStarted = 0;
+
+scope.Worker = class extends RealWorker {
+  constructor(url: string | URL, options?: WorkerOptions) {
+    super(url, options);
+    if (String(url).includes('workerHelpers')) rayonWorkersStarted++;
+  }
+};
+
+scope.addEventListener('message', (event: MessageEvent) => {
+  if (event.data?.type !== 'countRayonWorkers') return;
+  scope.postMessage({ id: event.data.id, type: 'rayonWorkerCount', count: rayonWorkersStarted });
+});
+
+// Loaded after the counting `Worker` is in place. The real worker installs its
+// own `onmessage` handler and signals `ready` as usual.
+import('../zkProve.worker');

package/web/test/inherited.web.test.ts

@@ -17,6 +17,10 @@ import { createPublicClient, createWalletClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia, baseSepolia, sepolia } from 'viem/chains';
 
+// Live-chain suite: needs the funded TEST_PRIVATE_KEY (transacts against pre-deployed
+// testnet fixtures). Without it — fork PRs, where secrets are unavailable — the suite
+// skips; CI runs it separately with the key (test-live job).
+const LIVE_TESTS = Boolean(TEST_PRIVATE_KEY);
 const DEFAULT_TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
 const BOB_PRIVATE_KEY = (TEST_PRIVATE_KEY || DEFAULT_TEST_PRIVATE_KEY) as `0x${string}`;
 const ALICE_PRIVATE_KEY = '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
@@ -33,7 +37,7 @@ const VIEM_CHAINS: Record<number, Chain> = {
 const testViemChain = STAGING_TESTS ? stagingViemChain : arbitrumSepolia;
 const testCofheChain = STAGING_TESTS ? stagingCofhe : cofheArbSepolia;
 
-describe('@cofhe/web - Inherited Client Tests', () => {
+describe.skipIf(!LIVE_TESTS)('@cofhe/web - Inherited Client Tests', () => {
   let cofheClient: CofheClient;
   let publicClient: PublicClient;
   let bobWalletClient: WalletClient;

package/web/test/mainThreadPool.web.test.ts

@@ -0,0 +1,174 @@
+import { STAGING_TESTS, stagingViemChain } from '../../core/test/stagingRedirect';
+import { arbSepolia as cofheArbSepolia, stagingCofhe } from '@/chains';
+import { Encryptable, fheTypeToString, type EncryptableItem } from '@/core';
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { PublicClient, WalletClient } from 'viem';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia as viemArbitrumSepolia } from 'viem/chains';
+import {
+  createCofheClient,
+  createCofheConfig,
+  createCofheClientWithCustomWorker,
+  getTfheThreadPoolStatus,
+} from '../index';
+import { THREADPOOL_TESTS } from './threadPoolBenchHelper';
+
+// Which thread needs a rayon pool?
+//
+// With workers on (the default) the ZK proof is generated inside the zkProve
+// worker, which runs its own rayon pool. The main thread only deserializes keys
+// and packs inputs, so a pool there is pure overhead: N idle Web Workers plus a
+// second shared wasm memory. The main thread should start one only when it has
+// to generate a proof itself.
+//
+// Rayon threads started by the main thread are `new Worker(...)` calls made by
+// the page. The ones the zkProve worker starts are made inside that worker and
+// never reach the page's `Worker` constructor. Counting page-level helper
+// workers therefore measures the main-thread pool and nothing else.
+//
+// Own file on purpose: every vitest browser file gets a fresh tfhe wasm
+// instance, and a rayon pool can only be started once per instance. The tests
+// below share that instance and depend on their order.
+
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const THREADS = 2;
+
+const testViemChain = STAGING_TESTS ? stagingViemChain : viemArbitrumSepolia;
+const testCofheChain = STAGING_TESTS ? stagingCofhe : cofheArbSepolia;
+
+/**
+ * Drives the real zkProve worker. The SDK's worker manager points at the built
+ * `zkProve.worker.js`, which doesn't exist when tests run from source, so the
+ * default client always falls back to the main thread here. Loading the worker
+ * from its `.ts` source gives these tests a worker path that actually works.
+ */
+function createRealWorkerProver(tfheThreads: number) {
+  const worker = new Worker(new URL('../zkProve.worker.ts', import.meta.url), { type: 'module' });
+
+  const ready = new Promise<void>((resolve, reject) => {
+    worker.addEventListener('message', function onReady(event: MessageEvent) {
+      if (event.data?.type !== 'ready') return;
+      worker.removeEventListener('message', onReady);
+      resolve();
+    });
+    worker.addEventListener('error', (event) => reject(new Error(`zkProve worker failed to load: ${event.message}`)));
+  });
+
+  let requests = 0;
+
+  const prove = async (
+    fheKeyHex: string,
+    crsHex: string,
+    items: EncryptableItem[],
+    metadata: Uint8Array
+  ): Promise<Uint8Array> => {
+    await ready;
+    const id = `main-thread-pool-test-${requests++}`;
+
+    return new Promise<Uint8Array>((resolve, reject) => {
+      worker.addEventListener('message', function onResponse(event: MessageEvent) {
+        if (event.data?.id !== id) return;
+        worker.removeEventListener('message', onResponse);
+        if (event.data.type === 'success') resolve(new Uint8Array(event.data.result));
+        else reject(new Error(event.data.error ?? 'zkProve worker error'));
+      });
+
+      worker.postMessage({
+        id,
+        type: 'zkProve',
+        fheKeyHex,
+        crsHex,
+        items: items.map((item) => ({
+          utype: fheTypeToString(item.utype),
+          data: typeof item.data === 'bigint' ? item.data.toString() : item.data,
+        })),
+        metadata: Array.from(metadata),
+        tfheThreads,
+      });
+    });
+  };
+
+  return { prove, terminate: () => worker.terminate() };
+}
+
+describe.skipIf(!THREADPOOL_TESTS)('@cofhe/sdk/web - main-thread rayon pool', () => {
+  const RealWorker = globalThis.Worker;
+  let rayonWorkersStartedByPage = 0;
+  let prover: ReturnType<typeof createRealWorkerProver>;
+  let publicClient: PublicClient;
+  let walletClient: WalletClient;
+  let consumingContract: `0x${string}`;
+  let proveContext: any;
+
+  beforeAll(async () => {
+    (globalThis as any).Worker = class extends RealWorker {
+      constructor(url: string | URL, options?: WorkerOptions) {
+        super(url, options);
+        if (String(url).includes('workerHelpers')) rayonWorkersStartedByPage++;
+      }
+    };
+
+    publicClient = createPublicClient({ chain: testViemChain, transport: http() });
+    const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+    walletClient = createWalletClient({ chain: testViemChain, transport: http(), account });
+    consumingContract = account.address;
+
+    prover = createRealWorkerProver(THREADS);
+
+    const config = createCofheConfig({ supportedChains: [testCofheChain], tfheThreads: THREADS });
+    const client = createCofheClientWithCustomWorker(config, prover.prove);
+    await client.connect(publicClient, walletClient);
+
+    await client
+      .encryptInputs([Encryptable.uint32(7n)])
+      .setConsumingContract(consumingContract)
+      .onStep((step, context) => {
+        if (step === 'prove' && context?.isEnd) proveContext = context;
+      })
+      .execute();
+  }, 240000);
+
+  afterAll(() => {
+    (globalThis as any).Worker = RealWorker;
+    prover?.terminate();
+  });
+
+  it('generates the proof in the worker', () => {
+    expect(globalThis.crossOriginIsolated).toBe(true);
+    expect(proveContext?.usedWorker).toBe(true);
+    expect(proveContext?.workerFailedError).toBeUndefined();
+  });
+
+  it('does not start a rayon pool on the main thread when the worker proves', () => {
+    expect(rayonWorkersStartedByPage).toBe(0);
+    expect(getTfheThreadPoolStatus()).toBeNull();
+  });
+
+  // Runs after a worker-path encryption on the same wasm instance: the main
+  // thread has already deserialized keys and packed inputs by now, and the
+  // pool must still come up.
+  it('starts the pool once the main thread has to prove', async () => {
+    const config = createCofheConfig({
+      supportedChains: [testCofheChain],
+      tfheThreads: THREADS,
+      useWorkers: false,
+    });
+    const client = createCofheClient(config);
+    await client.connect(publicClient, walletClient);
+
+    let mainThreadProveContext: any;
+    await client
+      .encryptInputs([Encryptable.uint32(8n)])
+      .setConsumingContract(consumingContract)
+      .onStep((step, context) => {
+        if (step === 'prove' && context?.isEnd) mainThreadProveContext = context;
+      })
+      .execute();
+
+    expect(mainThreadProveContext?.usedWorker).toBe(false);
+    expect(rayonWorkersStartedByPage).toBe(THREADS);
+    expect(getTfheThreadPoolStatus()).toEqual({ enabled: true, threads: THREADS });
+  }, 240000);
+});

package/web/test/threadPoolBenchHelper.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared harness for the initThreadPool verification tests.
+ *
+ * Each vitest browser test file runs in its own iframe, so each gets a fresh
+ * tfhe wasm instance — which is what lets us compare single-threaded vs
+ * multi-threaded proving (`initThreadPool` may only run once per instance).
+ */
+
+import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from '../../core/consts';
+import { STAGING_TESTS } from '../../core/test/stagingRedirect';
+import { arbSepolia as cofheArbSepolia, stagingCofhe } from '@/chains';
+import { initTfheThreadPool, type TfheThreadPoolResult } from '../tfheThreadPool.js';
+
+// Same backend as the rest of the web suite: Arbitrum Sepolia, or staging when
+// TEST_STAGING_ENABLED=true.
+const COFHE_URL = (STAGING_TESTS ? stagingCofhe : cofheArbSepolia).coFheUrl;
+
+// Injected by vitest.config.mts from TEST_THREADPOOL_ENABLED.
+declare const __THREADPOOL_TESTS__: boolean | undefined;
+
+/**
+ * Gate for the suites that generate real proofs on a rayon pool. They are
+ * CPU-heavy: inside the regular, fully parallel test run they starve other
+ * proving tests into timeouts on small CI runners, and skew their own timings.
+ * So they are skipped by default and run on their own, one file at a time:
+ *
+ *   TEST_THREADPOOL_ENABLED=true pnpm test:threadpool
+ *
+ * which is what the "Test (thread pool)" CI job does.
+ */
+export const THREADPOOL_TESTS = typeof __THREADPOOL_TESTS__ !== 'undefined' ? __THREADPOOL_TESTS__ : false;
+
+function fromHexString(hexString: string): Uint8Array {
+  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
+  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
+  if (!arr) return new Uint8Array();
+  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
+}
+
+/** Fetch the network's real FHE public key + CRS. Proving itself is fully local. */
+export async function fetchNetworkKeys(securityZone = 0): Promise<{ fheKey: string; crs: string }> {
+  const post = async (path: string) => {
+    const res = await fetch(`${COFHE_URL}/${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ securityZone }),
+    });
+    if (!res.ok) throw new Error(`${path} failed: ${res.status} ${res.statusText}`);
+    return res.json();
+  };
+
+  const [pk, crs] = await Promise.all([post('GetNetworkPublicKey'), post('GetCrs')]);
+  return { fheKey: (pk as { publicKey: string }).publicKey, crs: (crs as { crs: string }).crs };
+}
+
+export type BenchResult = {
+  threadPool: TfheThreadPoolResult;
+  /** Workers constructed during initThreadPool (the rayon threads) */
+  rayonWorkers: number;
+  /** Per-iteration proving durations in ms */
+  durations: number[];
+  medianMs: number;
+};
+
+/**
+ * Init tfhe (optionally with the rayon pool) and time `build_with_proof_packed`.
+ *
+ * @param threads rayon threads to request; <= 1 skips the pool entirely
+ * @param iterations how many proofs to time
+ */
+export async function benchProve(threads: number, iterations = 5): Promise<BenchResult> {
+  const mod: any = await import('tfhe');
+  await mod.default();
+  await mod.init_panic_hook();
+
+  // Count the Workers initThreadPool spawns — direct evidence the rayon threads
+  // are real, separate from any timing signal.
+  const RealWorker = globalThis.Worker;
+  let rayonWorkers = 0;
+  (globalThis as any).Worker = class extends RealWorker {
+    constructor(url: string | URL, opts?: WorkerOptions) {
+      super(url as any, opts);
+      rayonWorkers++;
+    }
+  };
+
+  let threadPool: TfheThreadPoolResult;
+  try {
+    threadPool =
+      threads > 1
+        ? await initTfheThreadPool(mod, threads)
+        : { enabled: false, threads: 1, reason: 'skipped by benchmark' };
+  } finally {
+    (globalThis as any).Worker = RealWorker;
+  }
+
+  const { fheKey, crs } = await fetchNetworkKeys();
+  const pk = mod.TfheCompactPublicKey.safe_deserialize(fromHexString(fheKey), TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT);
+  const zkCrs = mod.CompactPkeCrs.safe_deserialize(fromHexString(crs), TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT);
+
+  // Dummy metadata: we only measure local proof generation, never verify it.
+  const metadata = new Uint8Array(32).fill(7);
+
+  const durations: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const builder = mod.ProvenCompactCiphertextList.builder(pk);
+    builder.push_u128(BigInt(1000 + i));
+    builder.push_u64(BigInt(2000 + i));
+    builder.push_u32(3000 + i);
+
+    const started = performance.now();
+    builder.build_with_proof_packed(zkCrs, metadata, 1);
+    durations.push(performance.now() - started);
+  }
+
+  const sorted = [...durations].sort((a, b) => a - b);
+  const medianMs = sorted[Math.floor(sorted.length / 2)];
+
+  return { threadPool, rayonWorkers, durations, medianMs };
+}
+
+export function reportBench(label: string, result: BenchResult): void {
+  console.log(
+    `[THREADPOOL BENCH] ${label} ` +
+      JSON.stringify(
+        {
+          crossOriginIsolated: (globalThis as any).crossOriginIsolated,
+          hardwareConcurrency: navigator.hardwareConcurrency,
+          poolEnabled: result.threadPool.enabled,
+          poolThreads: result.threadPool.threads,
+          poolReason: result.threadPool.reason,
+          rayonWorkers: result.rayonWorkers,
+          medianMs: Math.round(result.medianMs),
+          durations: result.durations.map((d) => Math.round(d)),
+        },
+        null,
+        2
+      )
+  );
+}

package/web/test/threadPoolOff.web.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { THREADPOOL_TESTS, benchProve, reportBench } from './threadPoolBenchHelper.js';
+
+// Baseline: same workload, no rayon pool. Kept in its own file because each
+// vitest browser file gets a fresh tfhe wasm instance, and `initThreadPool`
+// can only run once per instance — so single- vs multi-threaded can't be
+// compared inside one file.
+describe.skipIf(!THREADPOOL_TESTS)('tfhe proving — single-threaded baseline', () => {
+  it('proves without a rayon thread pool', async () => {
+    const result = await benchProve(1);
+    reportBench('single-threaded', result);
+
+    expect(result.threadPool.enabled).toBe(false);
+    expect(result.rayonWorkers).toBe(0);
+    expect(result.medianMs).toBeGreaterThan(0);
+  }, 300000);
+});

package/web/test/threadPoolOn.web.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { MAX_AUTO_THREADS, initTfheThreadPool, resolveThreadCount } from '../tfheThreadPool.js';
+import { THREADPOOL_TESTS, benchProve, reportBench } from './threadPoolBenchHelper.js';
+
+describe('resolveThreadCount', () => {
+  it("derives from hardwareConcurrency for 'auto', capped", () => {
+    const expected = Math.min(navigator.hardwareConcurrency, MAX_AUTO_THREADS);
+
+    expect(resolveThreadCount('auto')).toBe(expected);
+    expect(resolveThreadCount()).toBe(expected); // 'auto' is the default
+  });
+
+  it('honours an explicit count, even above the auto cap', () => {
+    expect(resolveThreadCount(1)).toBe(1);
+    expect(resolveThreadCount(3)).toBe(3);
+    // An explicit request is trusted over hardwareConcurrency and the cap.
+    expect(resolveThreadCount(MAX_AUTO_THREADS + 4)).toBe(MAX_AUTO_THREADS + 4);
+  });
+
+  it('collapses false and nonsense values to single-threaded', () => {
+    expect(resolveThreadCount(false)).toBe(1);
+    expect(resolveThreadCount(0)).toBe(1);
+    expect(resolveThreadCount(-8)).toBe(1);
+    expect(resolveThreadCount(Number.NaN)).toBe(1);
+  });
+});
+
+describe('initTfheThreadPool', () => {
+  it('reports disabled without touching tfhe when config says false', async () => {
+    let called = false;
+    const result = await initTfheThreadPool(
+      {
+        initThreadPool: async () => {
+          called = true;
+        },
+      },
+      false
+    );
+
+    expect(result.enabled).toBe(false);
+    expect(result.threads).toBe(1);
+    expect(result.reason).toContain('config.tfheThreads');
+    expect(called).toBe(false);
+  });
+
+  it('degrades instead of throwing when initThreadPool fails', async () => {
+    const result = await initTfheThreadPool(
+      {
+        initThreadPool: async () => {
+          throw new Error('nested worker blocked');
+        },
+      },
+      4
+    );
+
+    expect(result.enabled).toBe(false);
+    expect(result.threads).toBe(1);
+    expect(result.reason).toContain('nested worker blocked');
+  });
+});
+
+describe.skipIf(!THREADPOOL_TESTS)('tfhe proving — rayon thread pool', () => {
+  it('starts the pool and spawns real worker threads', async () => {
+    const expectedThreads = resolveThreadCount('auto');
+    const result = await benchProve(expectedThreads);
+    reportBench('multi-threaded', result);
+
+    // The page must be cross-origin isolated for this to work at all.
+    expect((globalThis as any).crossOriginIsolated).toBe(true);
+
+    expect(result.threadPool.enabled).toBe(true);
+    expect(result.threadPool.threads).toBe(expectedThreads);
+
+    // Direct evidence the threads are real: initThreadPool constructed one
+    // Worker per rayon thread.
+    expect(result.rayonWorkers).toBe(expectedThreads);
+
+    expect(result.medianMs).toBeGreaterThan(0);
+  }, 300000);
+});