Resume an interrupted install instead of re-downloading 448 MB

[devbadya]

What this is

Two things, in answer to "we don't have the right model, it's too big":

1. The model is the right one, and 448 MB is the floor. Researched against the Hub and Transformers.js upstream, then mechanized so it stays checked rather than remembered.
2. The 448 MB is now genuinely a one-time cost. An install that broke at 90% used to start over from zero; it now continues from what arrived.

The research

Export of Qwen3.5-0.8B	q4f16 total	Loads through
onnx-community/Qwen3.5-0.8B-Text-ONNX (in use)	448 MiB	pipeline('text-generation')
onnx-community/Qwen3.5-0.8B-ONNX-OPT	616 MiB	Qwen3_5ForConditionalGeneration + vision encoder
onnx-community/Qwen3.5-0.8B-ONNX	617 MiB	Qwen3_5ForConditionalGeneration + vision encoder

• The export in use is exactly what Transformers.js added text-only Qwen3.5 support for (#1602), and the pinned 4.2.0 supports qwen3_5_text.
• q4f16 is the smallest of the five variants published in it: q4 526 MiB, int8 896 MiB, fp16 1.4 GiB, fp32 2.9 GiB. INT4 is as far as ONNX Runtime Web goes.
• Every other Qwen3.5-0.8B ONNX repository on the Hub is a copy of one of the three first-party ones, or larger.
• Qwen3.5 has no size below 0.8B (the small series is 0.8B/2B/4B/9B), and a 248,320-token vocabulary tied to the output layer is why 0.8B parameters at four bits land at 448 MB rather than nearer 400 MB.

node tools/verify-model.mjs now surveys every variant through the Hub API and fails if a smaller one appears, so this does not have to be re-derived by hand.

The resume

Transformers.js reads a whole response into memory before handing it to a cache, so a put-side backend never sees a failure — at 400 MB of 448 MB there is nothing on disk. opfsCache.match therefore performs the download: into .part, retried three times from wherever it stopped, published under the real name, and only then answered with the file. Upstream shipped this for Node's filesystem cache in #1715; the browser half is still open.

Four details make it work rather than merely sound good:

• Writes go through createSyncAccessHandle(). A FileSystemWritableFileStream discards its swap file unless it closes cleanly, which is why the old .part file was always empty after a failure.
• The ETag is compared here, not by the server. The Hub's CDN ignores If-Range — verified by hand: a stale validator still comes back 206 with the old range, which would splice two different files together. The ETag and total size are recorded beside the partial instead, and a mismatch restarts the file.
• A body that stops short is unfinished, not shorter. Transformers.js sizes its buffer from Content-Length and zero-pads the remainder, so publishing a truncated transfer would mean silently corrupt weights.
• The download completes before the response is returned. Streaming the body back looked neater and was wrong: Transformers.js also calls match as an existence-and-size check and drops the body, which stranded the OPFS write lock and made the next store of that file fail with NoModificationAllowedError. Progress is therefore reported by the cache and mapped onto the library's own file names by the worker.

Also: modelCached now means the weights are present rather than "at least one of the seven files", so a half-install no longer reports itself as installed; Remove model reclaims partials, which listCachedFiles used to hide from it; and the gate offers Resume install (155 MB left) with a Discard download alternative.

Gate screen showing a partly downloaded model with a Resume install button

Verification

• pnpm check (386 tests) and pnpm build.
• 24 tests over the cache: resume after a drop, three failures leaving a valid resume point, a stale ETag, a host ignoring Range, a short body, one download shared by concurrent callers.
• In headless Chrome against a range-serving host: a fresh download, a transfer killed mid-body that recovers byte for byte with Range: bytes=3145728- on the retry, and one that never finishes leaving a 3 MiB partial plus sidecar.
• In headless Chrome against the real Hub through AutoTokenizer: the file is published to OPFS at its exact size, progress is reported, and a second load makes zero network requests.
• node tools/verify-model.mjs against the live Hub, including the new resume preconditions and the variant survey.

_{To show artifacts inline, enable in settings.}