sparkforensics-mcp 0.2.3 → 0.2.4

package/bin/sparkforensics-mcp.mjs

@@ -19,20 +19,26 @@ async function loadCreateMcpServer() {
   return mod.createMcpServer;
 }
 
-const USAGE = `Usage: sparkforensics-mcp
+// Tool names come from the server the bin actually builds, so --help can't drift
+// from the registered set. Building the server registers tools only: no transport,
+// no I/O. _registeredTools is the SDK's registry; the MCP package test checks that
+// this list matches what listTools reports.
+function usage(toolNames) {
+  return `Usage: sparkforensics-mcp
 
 Starts the SparkForensics MCP server, speaking the MCP protocol over
 stdio. Point an MCP client (Claude Desktop, Claude Code, etc.) at this
-command; it exposes five tools for diagnosing Apache Spark event logs:
-diagnose_run, get_run_summary, compare_runs, evaluate_budgets,
-get_finding_evidence.
+command; it exposes ${toolNames.length} tools for diagnosing Apache Spark event logs:
+${toolNames.join(', ')}.
 
 See https://github.com/shuffle-works/sparkforensics#readme for details.
 `;
+}
 
 async function main() {
   if (process.argv.includes('--help') || process.argv.includes('-h')) {
-    process.stderr.write(USAGE);
+    const createMcpServer = await loadCreateMcpServer();
+    process.stderr.write(usage(Object.keys(createMcpServer()._registeredTools)));
     return;
   }
   const createMcpServer = await loadCreateMcpServer();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "sparkforensics-mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "mcpName": "io.github.shuffle-works/sparkforensics-mcp",
   "type": "module",
   "license": "MIT",
-  "description": "MCP server exposing Apache Spark event-log diagnostics (diagnose_run, get_run_summary, compare_runs, get_finding_evidence, evaluate_budgets) over stdio.",
+  "description": "MCP server exposing Apache Spark event-log diagnostics over stdio.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/shuffle-works/sparkforensics.git"
@@ -23,7 +23,7 @@
     "performance"
   ],
   "bin": {
-    "sparkforensics-mcp": "./bin/sparkforensics-mcp.mjs"
+    "sparkforensics-mcp": "bin/sparkforensics-mcp.mjs"
   },
   "engines": {
     "node": ">=18"

package/vendor-core/impact-estimator.js

@@ -1,4 +1,5 @@
                                                                                                        
+import { nsToMs } from './format-utils.js';
 import {
   computeOccupancy, estimateSingleStage, estimateMultiStage, tailRecoveryMs, tailRemovedWorkMs, stragglerFixLongestTaskMs,
                                                                                 
@@ -82,6 +83,24 @@ const EXECUTOR_STARTUP_OVERHEAD_MS = 15000;
 // Assumed re-read throughput, shared by cachingOpportunity and cacheUtilization.
 const RE_READ_THROUGHPUT_BPS = 125_000_000;
 
+// Below this share of executorRunTime spent on CPU, a stage's tasks were idle, waiting on something
+// outside Spark: on 14 real logs (2026-09-23) every non-Python stage under 1% was a JDBC read, a
+// file listing or a Delta log read, while file writes, which more partitions do parallelize,
+// start at 2%.
+const IDLE_CPU_SHARE_MAX = 0.01;
+
+// True when the stage's tasks spent under IDLE_CPU_SHARE_MAX of their run time on CPU. False when
+// the share can't be trusted: no CPU time recorded (older Spark logs omit the metric), or Python
+// code run through PythonRDD, whose worker-process CPU executorCpuTime (the JVM task thread's)
+// never counts (such stages read 0.1% on the same logs while computing).
+function tasksMostlyIdle(stage       )          {
+  const runMs = stage.executorRunTime ?? 0;
+  const cpuMs = nsToMs(stage.executorCpuTime ?? 0);
+  if (runMs <= 0 || cpuMs <= 0) return false;
+  if (/PythonRDD/.test(stage.name ?? '') || /org\.apache\.spark\.api\.python\./.test(stage.details ?? '')) return false;
+  return cpuMs / runMs < IDLE_CPU_SHARE_MAX;
+}
+
 // skew and straggler claim time off the stage's longest task itself, so the occupancy clip must
 // not floor them at that same task (see estimateSingleStage). detectors.ts's clippedWasteMs gates
 // both detectors on the same option so the firing floor and the displayed estimate agree.
@@ -332,14 +351,15 @@ function computeEstimateForFinding(
       // is queueing no partition count recovers. Splitting partitions splits the longest task
       // too, hence TAIL_CLAIM's post-fix floor. Unknown cluster size: no defensible figure.
       if (totalCores <= 0) return costOnly('modeled');
-      // A stage that read no input and no shuffle has no data for more partitions to split (a
-      // 1-task count stage open 27 minutes on 5s of CPU was claimed 99% recoverable): claim 0.
+      // A stage that read no input and no shuffle, its tasks idle waiting on an external system,
+      // gains nothing from more partitions (a 1-task JDBC count stage open 27 minutes on 5s of CPU
+      // was claimed 99% recoverable): claim 0. Stages that read bytes keep their claim.
       const readBytes = (stage.inputBytes ?? 0) + (stage.shuffleReadBytes ?? 0);
       const activeMs = typeof stage.taskActiveMs === 'number'
         ? stage.taskActiveMs
         : Math.max(0, (stage.completedAt ?? 0) - (stage.submittedAt ?? 0));
       const taskCount = stage.taskCount ?? 0;
-      const wasteMs = readBytes > 0 ? activeMs * Math.max(0, 1 - taskCount / totalCores) : 0;
+      const wasteMs = readBytes <= 0 && tasksMostlyIdle(stage) ? 0 : activeMs * Math.max(0, 1 - taskCount / totalCores);
       return singleStageImpact(wasteMs, finding.stageId, stages, occupancy, 'modeled', { value: wasteMs, unit: 'ms' }, TAIL_CLAIM);
     }
     case 'partitionSizing': {

package/vendor-core/occupancy.js

@@ -152,18 +152,19 @@ const SERIAL_GATE_THRESHOLD = 0.999;
                                
                           
                                  
+                                
                            
                            
  
 
-// Wall-clock a skew/straggler fix recovers, given the slowest task's excess over the median. A
-// lone straggler costs that excess; a tail of many slow tasks (a bimodal stage: 26% of 1400
-// tasks over 4x P50 on a real log) costs its summed excess (stragglerExcessMs) spread over the
-// slots the stage had (peakConcurrentTasks), far more than one task's. The task-level replay in
-// dev/eval-tail-replay.mjs recovers about the larger of the two. Average concurrency would be the
-// wrong divisor: a tail-dominated stage runs few tasks for most of its span (5.7 average vs 14
-// peak on one real stage), which doubled the claim.
+// Wall-clock a skew/straggler fix recovers: finalizeStage's task-level replay
+// (tailReplayRecoveryMs, computeTailReplayRecoveryMs) when the stage carries it. Without it (a
+// stage built by hand, as in detector tests) an estimate from the slowest task's excess over the
+// median: a lone straggler costs that excess; a tail of many slow tasks costs its summed excess
+// (stragglerExcessMs) spread over the slots the stage had (peakConcurrentTasks), and the replay
+// recovers about the larger of the two.
 export function tailRecoveryMs(stage           , singleTaskExcessMs        )         {
+  if (stage.tailReplayRecoveryMs != null) return stage.tailReplayRecoveryMs;
   const excessMs = stage.stragglerExcessMs ?? 0;
   const slots = stage.peakConcurrentTasks ?? 0;
   if (excessMs <= 0 || slots <= 0) return singleTaskExcessMs;

package/vendor-core/parser-worker.js

@@ -5,6 +5,7 @@ import { createSnappyBlockDecoder } from './snappy-block.js';
 import { createState, dispatchLine, buildChunkDecoder, emitParseCompletion,                                   } from './event-handlers.js';
 import { TASK_FIELD_NAMES } from './stage-quantiles.js';
 import { runParseFromUrl, sniffCodec } from './shs-fetch.js';
+import { createWorkerZstdDecoders } from './zstd-worker-client.js';
 
 export {
   buildChunkDecoder, createState, normalizeSparkProperties, parseSparkMemoryMB, extractResources,
@@ -61,9 +62,11 @@ const PROGRESS_EMIT_LINES = 300;
 // without touching the vendored files (mirrors shs-fetch.ts's shim).
                                                                            
                                                                                            
-// A Node decoder may decompress off the main thread: streamFile awaits each push.
+// A Node decoder, or the browser's decompress worker (zstd-worker-client.ts), may decompress off
+// the calling thread: streamFile awaits each push, and calls cancel() when it abandons the stream.
                                                                             
                                                                  
+                  
   
 
 // Stream one File's (possibly compressed) bytes through the codec dispatch,
@@ -89,7 +92,7 @@ export async function streamFile(
   const gunzip = codec === 'gz' ? new (Gunzip                                   )((inflated) => onChunk(inflated, currentPct)) : null;
   const lz4 = codec === 'lz4' ? createLz4BlockDecoder((inflated) => onChunk(inflated, currentPct)) : null;
   const onZstdChunk = (inflated            ) => onChunk(inflated, currentPct);
-  const zstd = codec !== 'zstd' ? null
+  const zstd                                        = codec !== 'zstd' ? null
     : zstdDecoder ? zstdDecoder(onZstdChunk)
       : new (ZstdDecompress                                   )(onZstdChunk);
   const snappy = codec === 'snappy' ? createSnappyBlockDecoder((inflated) => onChunk(inflated, currentPct)) : null;
@@ -101,17 +104,22 @@ export async function streamFile(
   const stepSize = Math.max(1, Math.min(chunkSize, Math.ceil(file.size / MIN_PROGRESS_STEPS)));
 
   let offset = 0;
-  while (offset < file.size) {
-    const start = offset;
-    const slice = new Uint8Array(await file.slice(start, start + stepSize).arrayBuffer());
-    offset += stepSize;
-    const final = offset >= file.size;
-    currentPct = start / file.size;
-    if (gunzip) gunzip.push(slice, final);
-    else if (lz4) lz4.push(slice);
-    else if (zstd) await zstd.push(slice, final);
-    else if (snappy) snappy.push(slice);
-    else onChunk(slice, currentPct);
+  try {
+    while (offset < file.size) {
+      const start = offset;
+      const slice = new Uint8Array(await file.slice(start, start + stepSize).arrayBuffer());
+      offset += stepSize;
+      const final = offset >= file.size;
+      currentPct = start / file.size;
+      if (gunzip) gunzip.push(slice, final);
+      else if (lz4) lz4.push(slice);
+      else if (zstd) await zstd.push(slice, final);
+      else if (snappy) snappy.push(slice);
+      else onChunk(slice, currentPct);
+    }
+  } catch (e) {
+    zstd?.cancel?.();
+    throw e;
   }
   if (lz4) lz4.end();
   if (snappy) snappy.end();
@@ -232,17 +240,25 @@ const isWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof Wor
 
 if (isWorker) {
   let workerState                     = null;
+  // Dropped zstd files decompress in a second worker, overlapping with parsing here. The
+  // `new Worker(new URL(...))` stays inline for Vite's worker detection (see ingest.ts). The SHS
+  // path (runParseFromUrl) decodes whole zip entries synchronously and keeps in-thread fzstd.
+  const zstdDecoder = createWorkerZstdDecoders(
+    () => new Worker(new URL('./zstd-worker.js', import.meta.url), { type: 'module' }),
+    (onChunk) => new (ZstdDecompress                                   )(onChunk),
+    { onFallback: (reason) => console.warn(`zstd: decompressing on the parse worker: ${reason}`) },
+  );
 
   self.onmessage = async ({ data }                                     ) => {
     if (data.type === 'parse') {
       workerState = createState();
-      await runParse(data.file, workerState);
+      await runParse(data.file, workerState, { zstdDecoder });
     } else if (data.type === 'parseFromUrl') {
       workerState = createState();
       await runParseFromUrl(data.request, workerState);
     } else if (data.type === 'parseFiles') {
       workerState = createState();
-      await runParseFiles(data.files, workerState);
+      await runParseFiles(data.files, workerState, { zstdDecoder });
     } else if (data.type === 'getTaskData') {
       const { stageId, reqId } = data;
       const stored = workerState?.taskStore.get(stageId) ?? new Float64Array(0);

package/vendor-core/plan-summary.js

@@ -45,7 +45,7 @@ function pushLongFilterWarning(result             , len        )       {
 }
 
 // Stable relation-identity key for a scan node: "<format>:<relation>" (e.g.
-// "delta:mx.t_emp_whitelist", "parquet:business_prd.sales", "jdbc:dw.d_producto")
+// "delta:mx.store_map", "parquet:warehouse.sales", "jdbc:dw.dim_product")
 // or null when the node is internal Delta metadata / a non-scan / un-nameable.
 // The single source of truth for scan identity, shared by `visitScan` (summary)
 // and the `cachingOpportunity` detector so the regexes live in one place.

package/vendor-core/stage-quantiles.js

@@ -150,6 +150,11 @@ export function finalizeStage(
     }
   }
 
+  const peakConcurrentTasks = computePeakConcurrentTasks(arr);
+  const tailReplayRecoveryMs = stragglerCount > 0
+    ? computeTailReplayRecoveryMs(arr, p50, peakConcurrentTasks)
+    : 0; // no task over 4x P50: both replays schedule the same durations
+
   const hostStatsArr = [...hostStats.entries()].map(
     ([host, s]) => ({ host, taskCount: s.taskCount, totalDuration: s.totalDuration })
   );
@@ -166,10 +171,11 @@ export function finalizeStage(
   const data                          = {
     ...stage,
     hostStats: hostStatsArr, executorStats: executorStatsArr, failureReasons: failureReasonsArr, localityStats: localityStatsArr, stragglerCount, stragglerExcessMs, longestNonStragglerMs,
+    tailReplayRecoveryMs,
     failedTaskSamples,
     peakExecutionMemoryMax,
     taskActiveMs: computeTaskActiveMs(arr),
-    peakConcurrentTasks: computePeakConcurrentTasks(arr),
+    peakConcurrentTasks,
     taskDurationP50: p50,
     taskDurationP95: p95,
     taskDurationMax: max,
@@ -234,6 +240,52 @@ export function computePeakConcurrentTasks(arr              )         {
   return peak;
 }
 
+// Wall-clock a tail fix recovers, replayed from the stage's own tasks: list scheduling (tasks in
+// launch order, each on the slot that frees first) over `slots` slots, once with the real
+// durations and once with every task over 4x P50 (the straggler definition above) capped at P50.
+// The difference is the claim; dev/eval-tail-replay.mjs keeps an independent copy as its ground
+// truth. Equal free times are interchangeable slots, so which one a min-heap picks can't change
+// the result. Equal launch times keep the task array's order.
+export function computeTailReplayRecoveryMs(arr              , p50        , slots        )         {
+  const taskCount = arr.length / FIELDS.STRIDE;
+  if (taskCount < 2 || !(p50 > 0)) return 0;
+  const order = new Uint32Array(taskCount);
+  for (let i = 0; i < taskCount; i++) order[i] = i;
+  order.sort((a, b) => arr[a * FIELDS.STRIDE + FIELDS.LAUNCH_TIME] - arr[b * FIELDS.STRIDE + FIELDS.LAUNCH_TIME] || a - b);
+  const free = new Float64Array(Math.max(1, Math.min(slots, taskCount)));
+  const capAboveMs = 4 * p50;
+  const actualEndMs = listScheduleEndMs(arr, order, free, Infinity, p50);
+  const fixedEndMs = listScheduleEndMs(arr, order, free, capAboveMs, p50);
+  return Math.max(0, actualEndMs - fixedEndMs);
+}
+
+// End of a list schedule over `free` (a min-heap of slot free times, reset here), each task's
+// duration replaced by `cappedMs` when over `capAboveMs`.
+function listScheduleEndMs(
+  arr              , order             , free              , capAboveMs        , cappedMs        ,
+)         {
+  free.fill(0);
+  const n = free.length;
+  let endMs = 0;
+  for (let t = 0; t < order.length; t++) {
+    const duration = arr[order[t] * FIELDS.STRIDE + FIELDS.DURATION];
+    const finish = free[0] + (duration > capAboveMs ? cappedMs : duration);
+    if (finish > endMs) endMs = finish;
+    // Replace the root (earliest free slot) and sift it down.
+    let i = 0;
+    for (;;) {
+      const left = 2 * i + 1;
+      if (left >= n) break;
+      const child = left + 1 < n && free[left + 1] < free[left] ? left + 1 : left;
+      if (free[child] >= finish) break;
+      free[i] = free[child];
+      i = child;
+    }
+    free[i] = finish;
+  }
+  return endMs;
+}
+
 export function computeFieldQuantiles(arr              , fieldIndex        )                                            {
   const taskCount = arr.length / FIELDS.STRIDE;
   if (taskCount === 0) return { p50: 0, p95: 0, max: 0 };

package/vendor-core/types.js

@@ -77,6 +77,8 @@
                                                            
                      
                            
+                                                                                            
+                           
                  
                            
                            
@@ -89,6 +91,9 @@
                              
                                                                                          
                                  
+                                                                                                  
+                                                                     
+                                
                                                                                             
                                
                                                         

package/vendor-core/zstd-worker-client.js

@@ -0,0 +1,180 @@
+// Parse-worker side of the zstd decompress worker (zstd-worker.ts). Builds a ZstdDecoderFactory
+// for streamFile whose push() ships each compressed read slice to the decompress worker and
+// returns while the worker decodes it, so the parse worker parses slice N's output while the
+// decompress worker decodes slice N+1.
+//
+// Flow control is a window of input slices: push() resolves once fewer than `maxInFlight`
+// slices are unacknowledged, and a slice is acknowledged only when its `consumed` reply is
+// handled, which comes after all of its decoded chunks (each fed to onChunk from the message
+// handler). So at most `maxInFlight` slices' output is ever queued on the parse worker, and a
+// fast decompressor on a slow parse cannot grow memory without bound. The final push resolves
+// only after every chunk was fed, which is what streamFile's callers need before they flush.
+//
+// Buffers move by transfer both ways: push() takes ownership of the slice it is given.
+                                                             
+                                                                           
+
+// Three 512 KiB slices of a ~20x-compressed log keep about 30 MB of output queued at most,
+// and give the decompress worker a slice of slack while the parse worker reads the next one.
+export const MAX_IN_FLIGHT_SLICES = 3;
+
+// The slice of the Worker API this client uses; tests pass a MessagePort adapter.
+                                 
+                                                                      
+                                                                  
+                                             
+                     
+ 
+
+                                           
+                       
+                                                                 
+                                        
+ 
+
+               
+             
+                                      
+                         
+  
+
+// `spawn` starts the decompress worker; it runs at most once, on the first zstd stream, and the
+// worker then serves every later stream (the files of a rolling log) one at a time. When it
+// cannot start (no nested workers, a blocked script, a crash), each stream is decoded by
+// `fallback` on the calling thread instead, the path used before this worker existed.
+export function createWorkerZstdDecoders(
+  spawn                      ,
+  fallback                    ,
+  { maxInFlight = MAX_IN_FLIGHT_SLICES, onFallback }                           = {},
+)                     {
+  let port                        = null;
+  let ready                          = null;
+  let active                = null;
+  let nextId = 0;
+
+  const giveUp = (reason        ) => {
+    port?.terminate?.();
+    port = null;
+    ready = Promise.resolve(false);
+    onFallback?.(reason);
+  };
+
+  const startWorker = ()                   => new Promise((resolve) => {
+    let candidate                ;
+    try {
+      candidate = spawn();
+    } catch (e) {
+      giveUp(`could not start the decompress worker: ${e instanceof Error ? e.message : String(e)}`);
+      resolve(false);
+      return;
+    }
+    let settled = false;
+    const settle = (ok         , reason = '') => {
+      if (settled) return;
+      settled = true;
+      if (ok) port = candidate;
+      else {
+        candidate.terminate?.();
+        giveUp(reason);
+      }
+      resolve(ok);
+    };
+    candidate.onmessage = ({ data }) => {
+      if (data.type === 'ready') settle(true);
+      else if (active && 'id' in data && data.id === active.id) active.onReply(data);
+    };
+    candidate.onerror = (ev) => {
+      // Handled here: left alone, a nested worker's error also reaches the parse worker's own
+      // global handler and from there the page's "Worker crashed" path.
+      ev.preventDefault();
+      const message = ev.message || 'unknown error';
+      if (!settled) {
+        settle(false, `the decompress worker failed to load: ${message}`);
+        return;
+      }
+      const stream = active;
+      giveUp(`the decompress worker crashed: ${message}`);
+      stream?.fail(new Error(`Decompress worker crashed: ${message}`));
+    };
+  });
+
+  return (onChunk) => {
+    const id = nextId++;
+    let started = false;
+    let local                                        = null;
+    let seq = 0;
+    let inFlight = 0;
+    let failure               = null;
+    let wake                      = null;
+
+    const until = (done               ) => new Promise      ((resolve) => {
+      const check = () => {
+        if (!done()) return;
+        wake = null;
+        resolve();
+      };
+      wake = check;
+      check();
+    });
+
+    const stream         = {
+      id,
+      onReply(msg) {
+        if (failure) return;
+        if (msg.type === 'chunk') {
+          try {
+            onChunk(new Uint8Array(msg.bytes, 0, msg.length));
+          } catch (e) {
+            port?.postMessage({ type: 'cancel', id }, []);
+            stream.fail(e instanceof Error ? e : new Error(String(e)));
+          }
+        } else if (msg.type === 'consumed') {
+          inFlight--;
+          wake?.();
+        } else if (msg.type === 'error') {
+          stream.fail(new Error(msg.message));
+        }
+      },
+      fail(err) {
+        if (failure) return;
+        failure = err;
+        if (active === stream) active = null;
+        wake?.();
+      },
+    };
+
+    const begin = async () => {
+      started = true;
+      ready ??= startWorker();
+      if (!(await ready) || !port) {
+        local = fallback(onChunk);
+        return;
+      }
+      active = stream;
+      port.postMessage({ type: 'start', id }, []);
+    };
+
+    return {
+      async push(chunk, final = false) {
+        if (!started) await begin();
+        if (local) return local.push(chunk, final);
+        if (failure) throw failure;
+        // Transfer the slice's own buffer when it spans all of it; copy a view of a larger one.
+        const bytes = chunk.byteOffset === 0 && chunk.byteLength === chunk.buffer.byteLength
+          ? chunk.buffer               
+          : chunk.slice().buffer;
+        if (!port) throw new Error('Decompress worker is gone');
+        port.postMessage({ type: 'data', id, seq: seq++, bytes, final }, [bytes]);
+        inFlight++;
+        await until(() => failure !== null || inFlight < (final ? 1 : maxInFlight));
+        if (failure) throw failure;
+        if (final && active === stream) active = null;
+      },
+      cancel() {
+        if (local || !started || failure) return;
+        port?.postMessage({ type: 'cancel', id }, []);
+        stream.fail(new Error('Decompression cancelled'));
+      },
+    };
+  };
+}

package/vendor-core/zstd-worker.js

@@ -0,0 +1,103 @@
+// Decompress worker: runs the vendored fzstd off the parse worker's thread, so decompression and
+// NDJSON parsing of a zstd log overlap instead of taking turns. The parse worker spawns it and
+// drives it through zstd-worker-client.ts; both ends of the message protocol live in the types
+// below, and zstd-worker-client.ts documents the flow control.
+import { Decompress as ZstdDecompress } from './vendor/fzstd.js';
+
+// Parse worker -> decompress worker. `seq` numbers a stream's input slices from 0.
+                               
+                                 
+                                                                                 
+                                   
+
+// Decompress worker -> parse worker. Every `chunk` for input slice `seq` is posted before that
+// slice's `consumed`, and a stream's `error` is the last message it gets.
+                             
+                     
+                                                                     
+                                                 
+                                                   
+
+                                                                                       
+
+// fzstd emits one chunk per zstd block (128 KiB at most). Batching them into 1 MiB messages cuts
+// the per-message cost on both threads about eight-fold.
+export const OUTPUT_BATCH_BYTES = 1024 * 1024;
+
+                                                                           
+                                                                                           
+
+// The decompress side of the protocol, transport-free so tests can drive it over a
+// MessageChannel. Holds at most one live stream: `start` replaces it, and a message for any
+// other stream id (one already cancelled or failed) is dropped.
+export function createZstdWorkerHandler(
+  post                ,
+  batchBytes         = OUTPUT_BATCH_BYTES,
+)                                   {
+  let streamId = -1;
+  let decoder                          = null;
+  let batch = new Uint8Array(batchBytes);
+  let batchUsed = 0;
+
+  // Hand `batch` over without copying it again: transfer its whole buffer with the filled
+  // length and start a fresh one. fzstd's chunk is a view of a buffer it reuses, so the copy
+  // into `batch` is the one copy this path cannot avoid.
+  const flush = () => {
+    if (batchUsed === 0) return;
+    const bytes = batch.buffer               ;
+    post({ type: 'chunk', id: streamId, bytes, length: batchUsed }, [bytes]);
+    batch = new Uint8Array(batchBytes);
+    batchUsed = 0;
+  };
+
+  const collect = (chunk            ) => {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const n = Math.min(chunk.length - offset, batchBytes - batchUsed);
+      batch.set(chunk.subarray(offset, offset + n), batchUsed);
+      batchUsed += n;
+      offset += n;
+      if (batchUsed === batchBytes) flush();
+    }
+  };
+
+  const reset = () => {
+    decoder = null;
+    batchUsed = 0;
+  };
+
+  return (msg) => {
+    if (msg.type === 'start') {
+      streamId = msg.id;
+      batchUsed = 0;
+      decoder = new (ZstdDecompress                                   )(collect);
+      return;
+    }
+    if (msg.id !== streamId || !decoder) return;
+    if (msg.type === 'cancel') {
+      reset();
+      return;
+    }
+    try {
+      decoder.push(new Uint8Array(msg.bytes), msg.final);
+      flush();
+    } catch (e) {
+      reset();
+      post({ type: 'error', id: msg.id, message: e instanceof Error ? e.message : String(e) });
+      return;
+    }
+    post({ type: 'consumed', id: msg.id, seq: msg.seq });
+    if (msg.final) reset();
+  };
+}
+
+// ─── Worker message bus (only active when running as a Web Worker) ──────────────
+
+const isWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
+
+if (isWorker) {
+  const scope = self                                         ;
+  const handle = createZstdWorkerHandler((msg, transfer) => scope.postMessage(msg, transfer ?? []));
+  scope.onmessage = ({ data }                                 ) => handle(data);
+  scope.postMessage({ type: 'ready' }                          );
+}