diskformer 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.4.0 (2026-10-13)
+- Changed: errors are now `DiskformerError`s with a `code` (see below). A caller that checked `e.name === 'AbortError'`
+  after an aborted ingest should check `isDiskformerError(e, 'LOAD_ABORTED')`; messages are unchanged.
+- Coded errors (`src/errors.js`): `DiskformerError` with a `code`, checked by name and code through
+  `isDiskformerError(e, code)`. `ingestGguf` throws `LOAD_ABORTED` when its signal aborted, else `LOAD_FAILED` with the
+  original as `cause`.
+- `readStore(key)` and `listStores()`: a store is complete only when every file it names is on disk at full size;
+  zero-byte or short files left by a crash make it `invalid`. `examples/chat` lists the stored models and removes one
+  at a time.
+- `engines/`: `UNSUPPORTED_DEVICE`, `BUDGET_TOO_SMALL` (with the bytes in `detail`), `CONTEXT_FULL`,
+  `EXECUTION_FAILED`, `RESOURCE_DISPOSED`. `generate()` and `greedy()` on one engine run one at a time (they share the
+  KV cache); `dispose()` waits for the step in flight. A load that fails destroys its GPU device. An invalid store is
+  ingested again instead of loaded.
+- Gates that run from this repo: `test/browser/greedy.html` (token by token vs llama.cpp, references in `test/refs/`),
+  `test/browser/states.html` + `test/state-check.py` (per-layer states vs LocalMind's numpy pass).
+- New helpers: `opfsFileSize(path)`, `opfsSubdirs(path)`.
+- Not in the npm package, but new in the repo: the demo at diskformer.naklitechie.com now runs llama.cpp's WebGPU
+  backend with experts paged from OPFS (`ggml/`; LFM2 8B-A1B, OLMoE 1B-7B, Qwen3 30B-A3B, Qwen3-Next 80B-A3B); the
+  hand-engine page moved to `/classic/`.
+
+## 0.3.0 (2026-10-07)
+- `fileFetch(blob)`: ingest a GGUF that is already on disk (a `File` the user picked, e.g. from a Hugging Face or
+  LM Studio cache) through `ingestGguf({ fetch: fileFetch(file) })`, with no download. The store is byte-identical to a
+  download's, and an interrupted file ingest resumes from the same file (`test/ingest-resume.test.mjs`).
+- `engines/`: `load({ localFile })` ingests the pinned GGUF from a local file, refusing a file of another size.
+
 ## 0.2.0 (2026-10-05)
 - `engines/`: reference WebGPU engines for Gemma 4 26B-A4B (`Gemma4MoeSsd`), Qwen3.6 35B-A3B (`Qwen35MoeSsd`) and
   Qwen3-30B-A3B (`Qwen3MoeSsd`), copied from LocalMind with import paths rewritten (`scripts/sync-localmind.mjs`).

package/README.md

@@ -10,18 +10,20 @@ Plain ES modules, no dependencies, no build step. Chromium with WebGPU. Weights
 [![license](https://img.shields.io/badge/license-MIT-555?style=flat-square)](LICENSE)
 [![dependencies](https://img.shields.io/badge/dependencies-none-555?style=flat-square)](package.json)
 
+[![The diskformer.js card: keep model weights on disk in the browser, and page into WebGPU only what each step needs](marketing/social.png)](https://diskformer.naklitechie.com/)
+
 ## Install
 
 | How | Command |
 |---|---|
 | npm | `npm install diskformer` |
-| CDN | `import { Gemma4MoeSsd } from 'https://cdn.jsdelivr.net/npm/diskformer@0.2/engines/gemma4_moe_ssd.js'` |
+| CDN | `import { Gemma4MoeSsd } from 'https://cdn.jsdelivr.net/npm/diskformer@0.3/engines/gemma4_moe_ssd.js'` |
 | Copy | `src/`, `engines/` and `index.js`; nothing else is needed |
 
 ## Try it: a 14.4 GB model in 2.5 GB of GPU memory
 
-Open the [Hugging Face Space](https://naklitechie-diskformer-chat.static.hf.space/), or serve `examples/chat` yourself.
-Pick a model and a GPU memory budget. The page downloads the model once into OPFS, resumably, then chats.
+[diskformer.naklitechie.com](https://diskformer.naklitechie.com/) (also a [Hugging Face Space](https://huggingface.co/spaces/naklitechie/diskformer-chat)) runs llama.cpp's WebGPU backend with paged experts: LFM2 8B-A1B, OLMoE, Qwen3 30B-A3B, Qwen3-Next 80B (source in `ggml/`; references in `examples/chat/refs/`).
+The hand-written engines measured below are at [/classic/](https://diskformer.naklitechie.com/classic/); serve `examples/chat` to run them locally. Each page downloads a model once into OPFS, resumably.
 
 ```bash
 python3 -m http.server 8000      # then open http://localhost:8000/examples/chat/
@@ -36,10 +38,9 @@ Measured on a MacBook M4 Pro with 24 GB, Chrome 154, on 2026-10-05:
 | Gemma 4 26B-A4B, QAT Q4_0 | 14.4 GB | 7 GB | 6.63 GB | 17.9 tok/s | 9/9 |
 | Qwen3.6 35B-A3B, Q8_0 | 36.9 GB | 4 GB | 3.52 GB | 9.2 tok/s | not compared |
 
-"Identical" means the reply text matches llama.cpp b9830's Metal path character for character, on the same GGUF.
-llama-server echoes Gemma's empty thought-channel marker before each reply; the gate removes that marker first. The
-test covers 9 conversations, greedy decoding, up to 64 tokens each. Qwen3.6 has no llama.cpp comparison: its Metal path cannot
-hold 36.9 GB on this Mac.
+"Identical" means the reply text matches llama.cpp b9830's Metal path character for character on the same GGUF. The
+gate first drops the empty thought-channel marker llama-server echoes before each Gemma reply. 9 conversations,
+greedy, up to 64 tokens each. Qwen3.6 is not compared: llama.cpp's Metal path cannot hold 36.9 GB here.
 
 Each row is `node examples/run-demo.mjs chat --budget <GB>`; decode is the median over the 9 replies. A larger budget
 caches more experts. Only Apple silicon is tested; discrete GPUs and 8–16 GB machines are not.
@@ -53,14 +54,12 @@ const engine = await Gemma4MoeSsd.load(null, { gpuBudgetBytes: 3e9, onProgress:
 for await (const { text } of engine.generate([{ role: 'user', content: 'Hello' }], { maxNewTokens: 128 })) show(text);
 ```
 
-The first load downloads the GGUF from Hugging Face and copies it into OPFS in the engine's layout. Later loads take
-seconds.
+The first load downloads the GGUF from Hugging Face into OPFS, in the engine's layout. Later loads take seconds.
 
 ## Why
 
-Your model does not fit on the GPU, or it fits only by crowding out everything else. Browser engines load every
-weight onto the GPU at load time, including the ones a step never touches. A mixture-of-experts model uses under a
-tenth of its weights per token. Gemma 4's per-layer embedding table is read one row per token.
+Your model does not fit on the GPU, or fits only by crowding out everything else. Browser engines load every weight
+at load time, though a mixture-of-experts model uses under a tenth of its weights per token.
 
 diskformer keeps those weights in OPFS, read through sync access handles in workers. Only what each step needs
 moves into a GPU cache. The core is the store and the residency layer: your engine keeps its own kernels and decides
@@ -71,9 +70,8 @@ what a step needs. `engines/` shows two complete engines built on it.
 `engines/gemma4_moe_ssd.js` runs Gemma 4 26B-A4B. `engines/qwen35_moe_ssd.js` runs Qwen3.6 35B-A3B, and
 `engines/qwen3_moe_ssd.js` runs Qwen3-30B-A3B as their base. They are from-scratch WebGPU engines. The dense layers and
 KV cache live on the GPU. The experts stream from OPFS into a GPU cache, sized by `gpuBudgetBytes`. A budget that
-cannot hold the dense part and two tokens' experts is refused with the numbers. Decoding is greedy. The kernels are
-ported from gemma4-webgpu (Apache-2.0, `engines/NOTICE`). The engine files are LocalMind's, kept in step by
-`scripts/sync-localmind.mjs`.
+cannot hold the dense part and two tokens' experts is refused with the numbers. Decoding is greedy, one `generate()`
+at a time per engine. Kernels: gemma4-webgpu (Apache-2.0, `engines/NOTICE`); files kept in step with LocalMind.
 
 ## A table on disk
 
@@ -83,14 +81,18 @@ O(1) LRU and an optional GPU id→slot map that kernels can read. `examples/embe
 
 ## Experts on disk
 
-`ingestGguf({ url, key, plan })` streams a GGUF over HTTP ranges into OPFS in your engine's layout. `plan.layout` says
-where each tensor goes. `plan.units` lists the byte ranges to copy or split: Q8_0 and Q4_0 blocks become a value plane
-and an f16-scale plane, bit-exact. An interrupted ingest resumes from its last 1 GiB checkpoint. `ExpertStreamer`
-(also `RecordPool`) keeps a fixed GPU slot pool of expert records. `ensure(layer, ids)` returns pinned slots,
-`prefetch(layer, guesses)` never blocks, and uploads go through a mapped staging ring.
+`ingestGguf({ url, key, plan })` streams a GGUF over HTTP ranges into OPFS in your engine's layout: `plan.layout` says
+where each tensor goes, `plan.units` the byte ranges to copy or split (Q8_0 and Q4_0 blocks become a value plane and an
+f16-scale plane, bit-exact). It resumes from its last 1 GiB checkpoint. For a GGUF already on disk, pass a picked `File`
+as `fetch: fileFetch(file)`: no download, same store. `ExpertStreamer` (also `RecordPool`) keeps a fixed GPU slot pool
+of expert records: `ensure(layer, ids)` returns pinned slots, `prefetch(layer, guesses)` never blocks, and uploads go
+through a mapped staging ring.
+
+`listStores()` lists the stored models with size and state; a store with zero-byte or short files (a crash) is
+`invalid` and is ingested again, never loaded. `removeStore(key)` removes one and keeps the rest. Errors carry a `code`
+(`LOAD_ABORTED`, `BUDGET_TOO_SMALL`, … in `src/errors.js`), checked with `isDiskformerError(e, code)`.
 
-`measure({ path, recordBytes })` reports the disk's sequential MB/s and random record reads; OPFS speed varies a lot
-between machines, so measure where your users run.
+`measure({ path, recordBytes })` reports sequential MB/s and random record reads; OPFS speed varies by machine.
 
 ## Commands
 
@@ -101,17 +103,15 @@ node examples/run-demo.mjs embedding         # lookup → slots → a WGSL gathe
 node examples/run-demo.mjs chat --budget 2.5 # downloads Gemma once (14.4 GB) to a fixed profile, replays 9 llama.cpp replies, fails on any difference
 node examples/run-demo.mjs test/browser/ingest-resume.html --models <dir> --file <gguf>   # abort, resume, compare bytes
 node examples/run-demo.mjs test/browser/server.html --models <dir> --file <any file>   # the runner's file server rejects bad requests
+node examples/run-demo.mjs test/browser/greedy.html --models <dir> --file <gguf> --ref test/refs/<ref>.json   # token by token vs llama.cpp
+node examples/run-demo.mjs test/browser/states.html --models <dir> --file g4-6l.gguf   # per-layer states; then test/state-check.py
 npm run sync                                 # the files shared with LocalMind match their sources
 ```
 
-## Verify it yourself
-
-`node examples/run-demo.mjs chat` runs the chat page in headless Chrome under a GPU budget and replays
-`examples/chat/refs/gemma.json` (llama.cpp's replies); any differing reply exits 1. `--models <dir>` serves a local
-GGUF instead of downloading it; `--site <url>` gates a deployed copy, such as the Space.
+The chat gate replays `examples/chat/refs/gemma.json` (llama.cpp's replies) under a GPU budget; any differing reply
+exits 1. `--models <dir>` serves a local GGUF; `--site <url>` gates a deployed copy, such as the Space.
 
-The code runs in [LocalMind](https://github.com/NakliTechie/LocalMind) on its live site. `src/` (all but `measure.js`)
-and `engines/` are byte-identical to LocalMind's copies, apart from the engines' import paths.
+The code runs in [LocalMind](https://github.com/NakliTechie/LocalMind); `src/` and `engines/` are its copies.
 
 ## License
 

package/engines/gemma4_moe_ssd.js

@@ -1119,7 +1119,7 @@ export class Gemma4MoeSsd extends Qwen3MoeSsd {
   async prefillChunk(ids, want = 'none') {
     const c = this.cfg, dev = this.device, K = c.topK, H = c.hidden, T = ids.length, pos0 = this.position, S = pos0 + T;
     if (T > this.chunkTokens) throw new Error(`chunk of ${T} > ${this.chunkTokens}`);
-    if (S > this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    if (S > this.maxCtx) throw this.contextFull();
     const tStart = performance.now();
     dev.queue.writeBuffer(this.b.ids, 0, Uint32Array.from(ids));
     dev.queue.writeBuffer(this.qb, 0, new Uint32Array([T, pos0, S, 0]));

package/engines/qwen35_moe_ssd.js

@@ -964,7 +964,7 @@ export class Qwen35MoeSsd extends Qwen3MoeSsd {
   async prefillChunk(ids, want = 'none') {
     const c = this.cfg, dev = this.device, K = c.topK, H = c.hidden, T = ids.length, pos0 = this.position, S = pos0 + T;
     if (T > this.chunkTokens) throw new Error(`chunk of ${T} > ${this.chunkTokens}`);
-    if (S > this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    if (S > this.maxCtx) throw this.contextFull();
     const tStart = performance.now();
     dev.queue.writeBuffer(this.a.stop, 0, new Uint32Array(4));   // the head below uses guarded kernels
     dev.queue.writeBuffer(this.b.ids, 0, Uint32Array.from(ids));
@@ -1099,7 +1099,7 @@ export class Qwen35MoeSsd extends Qwen3MoeSsd {
   async step(token, want = 'argmax') {
     if (!this.gpuRouting) return super.step(token, want);
     const c = this.cfg, dev = this.device, K = c.topK, L = c.layers, seg = this.seg;
-    if (this.position >= this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    if (this.position >= this.maxCtx) throw this.contextFull();
     const tStart = performance.now();
     const pos = this.position, seqLen = pos + 1;
     this.writeTokenUniforms(token, pos);

package/engines/qwen3_moe_ssd.js

@@ -20,11 +20,12 @@
  * so the engine computes the same dot products llama.cpp does, up to summation order.
  */
 
-import { OpfsReaderPool, readOpfsText } from '../src/opfs-reader.js';
+import { OpfsReaderPool } from '../src/opfs-reader.js';
 import { ExpertStreamer } from '../src/expert-stream.js';
 // The store layer is diskformer.js's (github.com/NakliTechie/diskformer.js), byte-identical copies: gguf.js, ingest.js.
 import { GGML, Q8_BLOCK, Q4_BLOCK, Q6K_BLOCK, parseGguf, tensorBytes } from '../src/gguf.js';
-import { ingestGguf as ingestStore, ingestProgress, storeKey, removeStore } from '../src/ingest.js';
+import { ingestGguf as ingestStore, ingestProgress, fileFetch, storeKey, readStore, removeStore } from '../src/ingest.js';
+import { DiskformerError, isDiskformerError, codedError } from '../src/errors.js';
 export { GGML, Q4_BLOCK, Q6K_BLOCK, parseGguf, tensorBytes, splitQ4 } from '../src/gguf.js';
 export { ingestProgress } from '../src/ingest.js';
 
@@ -541,43 +542,60 @@ export class Qwen3MoeSsd {
   static get ingestPlan() { return undefined; }
   static tokenizerFrom(kv) { return new BpeTokenizer(kv); }
 
+  // Errors are coded (errors.js): UNSUPPORTED_DEVICE, BUDGET_TOO_SMALL, LOAD_ABORTED when opts.signal aborted, else
+  // LOAD_FAILED with the original as `cause`. A failed load destroys the GPU device it opened.
   static async load(modelId = QWEN3_30B_A3B.repo, opts = {}) {
-    const { fetch: fetchFn = (u, i) => fetch(u, i), onProgress = () => {}, signal } = opts;
+    try { return await this.open(modelId, opts); } catch (e) { throw codedError(e, { signal: opts.signal }); }
+  }
+
+  static async open(modelId, opts) {
+    const { onProgress = () => {}, signal, localFile } = opts;
     const src = opts.source || (modelId === QWEN3_30B_A3B.repo || !modelId ? QWEN3_30B_A3B : { repo: modelId, file: opts.file, revision: opts.revision || 'main' });
+    // localFile: the same GGUF already on disk (a File the user picked), ingested instead of downloaded. A size
+    // other than the pinned file's is refused before any write; the GGUF header check in the ingest plan follows.
+    if (localFile && src.size && localFile.size !== src.size) {
+      throw new Error(`${localFile.name} is ${localFile.size.toLocaleString()} bytes, not ${src.file} (${src.size.toLocaleString()} bytes). Pick that file.`);
+    }
+    const fetchFn = localFile ? fileFetch(localFile) : (opts.fetch || ((u, i) => fetch(u, i)));
     const url = opts.url || `https://huggingface.co/${src.repo}/resolve/${src.revision}/${src.file}`;
     const key = opts.key || storeKey(opts.file || src.file || url.split('/').pop());
     const root = opts.root || OPFS_ROOT;              // the OPFS folder for this engine's stores
     const dir = `${root}/${key}`;
 
     onProgress({ status: 'init' });
-    if (!navigator.gpu) throw new Error('WebGPU is not available');
+    const unsupported = (m) => new DiskformerError('UNSUPPORTED_DEVICE', m);
+    if (typeof navigator === 'undefined' || !navigator.gpu) throw unsupported('WebGPU is not available');
     const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
-    if (!adapter) throw new Error('no WebGPU adapter');
-    if (!adapter.features.has('shader-f16')) throw new Error('this GPU lacks shader-f16');
+    if (!adapter) throw unsupported('no WebGPU adapter');
+    if (!adapter.features.has('shader-f16')) throw unsupported('this GPU lacks shader-f16');
     const L = adapter.limits;
-    // subgroups: optional; an engine may use subgroup kernels when the adapter offers them.
-    const features = ['shader-f16', ...(adapter.features.has('subgroups') ? ['subgroups'] : [])];
+    // subgroups, subgroup matrices: optional; an engine may use subgroup (matrix) kernels when the adapter offers them.
+    const features = ['shader-f16', ...['subgroups', 'chromium-experimental-subgroup-matrix'].filter((f) => adapter.features.has(f))];
     const device = await adapter.requestDevice({
       requiredFeatures: features,
-      requiredLimits: { maxBufferSize: L.maxBufferSize, maxStorageBufferBindingSize: L.maxStorageBufferBindingSize, maxStorageBuffersPerShaderStage: L.maxStorageBuffersPerShaderStage, maxComputeWorkgroupsPerDimension: L.maxComputeWorkgroupsPerDimension },
+      requiredLimits: { maxBufferSize: L.maxBufferSize, maxStorageBufferBindingSize: L.maxStorageBufferBindingSize, maxStorageBuffersPerShaderStage: L.maxStorageBuffersPerShaderStage, maxComputeWorkgroupsPerDimension: L.maxComputeWorkgroupsPerDimension, maxComputeWorkgroupStorageSize: L.maxComputeWorkgroupStorageSize },
     });
     device.lost.then((info) => console.warn('qwen3-moe-ssd: GPU device lost:', info.message));
 
-    let manifest = null;
-    try { manifest = JSON.parse(await readOpfsText(`${dir}/manifest.json`) || 'null'); } catch (_) { manifest = null; }
-    if (opts.reingest || !manifest || !manifest.complete || manifest.format !== FORMAT) {
-      manifest = await ingestGguf({
-        url, key, root, fetch: fetchFn, signal, source: { repo: src.repo, file: src.file, revision: src.revision, sha256: src.sha256, size: src.size },
-        onProgress: (e) => onProgress(ingestProgress(e)),
-        plan: this.ingestPlan,
-      });
-    }
-    const headerFile = await (await (await navigator.storage.getDirectory()).getDirectoryHandle(root)).getDirectoryHandle(key);
-    const headerBytes = new Uint8Array(await (await (await headerFile.getFileHandle('header.bin')).getFile()).arrayBuffer());
-    const gguf = parseGguf(headerBytes);
-    const engine = new this(device, manifest, gguf, { ...opts, dir, key, url, adapterInfo: adapter.info || {} });
-    await engine.init(onProgress);
-    return engine;
+    try {
+      // Only a complete store with every file at full size is used; a partial one resumes, an invalid one (zero-byte
+      // or short files left by a crash) is ingested again.
+      const store = await readStore(key, { root, format: FORMAT });
+      let manifest = store.state === 'complete' ? store.manifest : null;
+      if (opts.reingest || !manifest) {
+        manifest = await ingestGguf({
+          url, key, root, fetch: fetchFn, signal, source: { repo: src.repo, file: src.file, revision: src.revision, sha256: src.sha256, size: src.size, ...(localFile ? { localFile: localFile.name } : {}) },
+          onProgress: (e) => onProgress(ingestProgress(e)),
+          plan: this.ingestPlan,
+        });
+      }
+      const headerFile = await (await (await navigator.storage.getDirectory()).getDirectoryHandle(root)).getDirectoryHandle(key);
+      const headerBytes = new Uint8Array(await (await (await headerFile.getFileHandle('header.bin')).getFile()).arrayBuffer());
+      const gguf = parseGguf(headerBytes);
+      const engine = new this(device, manifest, gguf, { ...opts, dir, key, url, adapterInfo: adapter.info || {} });
+      await engine.init(onProgress);
+      return engine;
+    } catch (e) { try { device.destroy(); } catch (_) {} throw e; }
   }
 
   constructor(device, manifest, gguf, opts) {
@@ -691,7 +709,7 @@ export class Qwen3MoeSsd {
     const fixed = this.gpuBytes.dense + this.kvBytes() + (o.workBytes ?? 512 * 2 ** 20);
     const rest = o.gpuBudgetBytes - fixed;
     const min = this.cfg.topK * 2 * this.manifest.experts.record;
-    if (rest < min) throw new Error(`GPU budget ${gb(o.gpuBudgetBytes)} is too small: weights that stay on the GPU, the KV cache and working buffers need ${gb(fixed)}, and the expert cache at least ${gb(min)} more`);
+    if (rest < min) throw new DiskformerError('BUDGET_TOO_SMALL', `GPU budget ${gb(o.gpuBudgetBytes)} is too small: weights that stay on the GPU, the KV cache and working buffers need ${gb(fixed)}, and the expert cache at least ${gb(min)} more`, { detail: { budget: o.gpuBudgetBytes, fixed, minCache: min } });
     return rest;
   }
   // KV cache bytes at this.maxCtx (f16 K and V for every layer); engines with other layouts override it.
@@ -875,7 +893,7 @@ export class Qwen3MoeSsd {
   // One token through all layers at position this.position. want: 'none' | 'argmax' | 'logits'.
   async step(token, want = 'argmax') {
     const c = this.cfg, dev = this.device, K = c.topK;
-    if (this.position >= this.maxCtx) throw new Error(`context full (${this.maxCtx} tokens)`);
+    if (this.position >= this.maxCtx) throw this.contextFull();
     const tStart = performance.now();
     const pos = this.position, seqLen = pos + 1;
     this.writeTokenUniforms(token, pos);
@@ -954,7 +972,11 @@ export class Qwen3MoeSsd {
 
   // Diagnostics for the llama.cpp comparison: greedy continuation of raw token ids, with the
   // top-n logits at every generated position.
-  async greedy(ids, n, { top = 5 } = {}) {
+  async greedy(ids, n, opts) {
+    const release = await this.acquire();
+    try { this.inflight = this.greedyTurn(ids, n, opts); return await this.inflight; } catch (e) { throw this.stepError(e); } finally { this.inflight = null; release(); }
+  }
+  async greedyTurn(ids, n, { top = 5 } = {}) {
     this.reset();
     const out = [], tops = [];
     let logits = await this.prefill(ids, 'logits');
@@ -973,7 +995,45 @@ export class Qwen3MoeSsd {
     return { ids: out, tops };
   }
 
-  async *generate(messages, { maxNewTokens = 512, signal, enableThinking = true } = {}) {
+  // generate() and greedy() share one KV cache, so calls on one engine run one at a time. A generate() takes its turn
+  // on its first next() (an async generator runs nothing before that), so turns follow iteration order. A caller
+  // that stops iterating early must end the loop (break / return()) so the next call can start. Errors are coded:
+  // EXECUTION_FAILED (original as `cause`), CONTEXT_FULL, RESOURCE_DISPOSED after dispose().
+  async *generate(messages, opts) {
+    const release = await this.acquire();
+    const it = this.generateTurn(messages, opts);
+    try {
+      for (;;) {
+        if (this.disposed) throw this.disposedError();
+        this.inflight = it.next();
+        const r = await this.inflight;
+        this.inflight = null;
+        if (r.done) return;
+        yield r.value;
+      }
+    } catch (e) { throw this.stepError(e); } finally { this.inflight = null; await it.return(); release(); }
+  }
+
+  // The turn lock: resolves with a release function once every earlier call has finished.
+  async acquire() {
+    if (this.disposed) throw this.disposedError();
+    const prev = this.turn;
+    let release;
+    this.turn = new Promise((r) => { release = r; });
+    await prev;
+    if (this.disposed) { release(); throw this.disposedError(); }
+    return release;
+  }
+  disposedError() { return new DiskformerError('RESOURCE_DISPOSED', 'this engine was disposed'); }
+  contextFull() { return new DiskformerError('CONTEXT_FULL', `context full (${this.maxCtx} tokens)`, { detail: { maxCtx: this.maxCtx } }); }
+  stepError(e) { return isDiskformerError(e) ? e : new DiskformerError('EXECUTION_FAILED', `generate failed: ${(e && e.message) || e}`, { cause: e }); }
+  // Marks the engine disposed and waits for a step in flight, so the device is never destroyed under a running step.
+  async retire() {
+    this.disposed = true;
+    if (this.inflight) await this.inflight.catch(() => {});
+  }
+
+  async *generateTurn(messages, { maxNewTokens = 512, signal, enableThinking = true } = {}) {
     const ids = this.tokenizer.encode(this.chatPrompt(messages, { enableThinking }));
     const stops = new Set(this.stopTokenIds);
     let next = await this.prefill(ids, 'argmax');
@@ -1013,6 +1073,7 @@ export class Qwen3MoeSsd {
   async warmup() {}
 
   async dispose() {
+    await this.retire();
     try { await this.xs.drain(); } catch (_) {}
     try { await this.expertReader.close(); } catch (_) {}
     try { this.device.destroy(); } catch (_) {}

package/index.js

@@ -1,8 +1,9 @@
 // diskformer — a disk tier for in-browser inference. Keep model weights in OPFS and page into WebGPU only
 // what each step needs. Plain ESM, no dependencies, no build step.
-export { OpfsReaderPool, OpfsWriter, canInline, opfsDir, readOpfsText, writeOpfsText, removeOpfs } from './src/opfs-reader.js';
+export { OpfsReaderPool, OpfsWriter, canInline, opfsDir, readOpfsText, writeOpfsText, removeOpfs, opfsFileSize, opfsSubdirs } from './src/opfs-reader.js';
 export { ExpertStreamer, ExpertStreamer as RecordPool } from './src/expert-stream.js';
 export { RowFile, RowCache, fingerprint } from './src/rows.js';
 export { parseGguf, tensorBytes, splitQ8, splitQ4, GGML, Q8_BLOCK, Q4_BLOCK, Q6K_BLOCK } from './src/gguf.js';
-export { ingestGguf, ingestProgress, readHeader, storeKey, removeStore } from './src/ingest.js';
+export { ingestGguf, ingestProgress, readHeader, fileFetch, storeKey, readStore, listStores, removeStore } from './src/ingest.js';
+export { DiskformerError, isDiskformerError, ERROR_CODES } from './src/errors.js';
 export { measure } from './src/measure.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diskformer",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Run a model larger than your GPU memory in a browser tab: weights stay in OPFS, WebGPU holds only what each step needs. A disk tier plus two reference MoE engines.",
   "type": "module",
   "license": "MIT",

package/src/errors.js

@@ -0,0 +1,36 @@
+/* errors.js — coded errors for the store, ingest and the engines. A host branches on `code`, never on the
+ * message text and never on `instanceof` (two copies of this module, e.g. a CDN copy and a vendored one, make
+ * instanceof false for the same error). Check with isDiskformerError(e, code).
+ *
+ *   try { await Engine.load(…) } catch (e) { if (isDiskformerError(e, 'LOAD_ABORTED')) … }
+ *
+ * Codes:
+ *   LOAD_FAILED         ingest or load failed (HTTP, quota, a GGUF the engine cannot run); `cause` holds the original
+ *   LOAD_ABORTED        the caller's signal aborted a load or ingest; decided from `signal.aborted`, not the error name
+ *   UNSUPPORTED_DEVICE  no WebGPU, no adapter, or a missing required feature (shader-f16)
+ *   BUDGET_TOO_SMALL    gpuBudgetBytes cannot hold the fixed GPU part plus the smallest expert cache; `detail` has the bytes
+ *   CONTEXT_FULL        the conversation outgrew the engine's context
+ *   EXECUTION_FAILED    a prefill or decode step failed; `cause` holds the original
+ *   RESOURCE_DISPOSED   the engine was disposed: no further generate()
+ */
+
+export const ERROR_CODES = Object.freeze(['LOAD_FAILED', 'LOAD_ABORTED', 'UNSUPPORTED_DEVICE', 'BUDGET_TOO_SMALL', 'CONTEXT_FULL', 'EXECUTION_FAILED', 'RESOURCE_DISPOSED']);
+
+export class DiskformerError extends Error {
+  constructor(code, message, { cause, detail } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'DiskformerError';
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+export const isDiskformerError = (e, code) => !!e && e.name === 'DiskformerError' && typeof e.code === 'string' && (code === undefined || e.code === code);
+
+// Re-code an error from a load or ingest: an aborted signal wins over whatever the abort threw; a coded error
+// passes through; anything else becomes `fallback` with the original as `cause`.
+export function codedError(e, { signal, fallback = 'LOAD_FAILED', what = 'load' } = {}) {
+  if (signal && signal.aborted) return isDiskformerError(e, 'LOAD_ABORTED') ? e : new DiskformerError('LOAD_ABORTED', `${what} aborted`, { cause: e });
+  if (isDiskformerError(e)) return e;
+  return new DiskformerError(fallback, `${what} failed: ${(e && e.message) || e}`, { cause: e });
+}

package/src/ingest.js

@@ -11,13 +11,14 @@
  *   // OPFS: <root>/<key>/{header.bin, dense.bin, experts.bin, manifest.json}
  */
 
-import { OpfsWriter, readOpfsText, writeOpfsText, removeOpfs } from './opfs-reader.js';
+import { OpfsWriter, readOpfsText, writeOpfsText, removeOpfs, opfsFileSize, opfsSubdirs } from './opfs-reader.js';
 import { parseGguf, splitQ8, splitQ4, Q8_BLOCK, Q4_BLOCK } from './gguf.js';
+import { codedError } from './errors.js';
 
 export const ROOT = 'diskformer';
 export const FORMAT = 'diskformer-gguf/1';
 
-// ── Ingest: GGUF (over HTTP Range) → OPFS, in the engine layout ─────────────
+// ── Ingest: GGUF (over HTTP Range, or a local file) → OPFS, in the engine layout ──
 export const storeKey = (file) => file.replace(/\.gguf$/i, '').toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
 
 export async function readHeader(url, fetchFn, signal) {
@@ -33,6 +34,20 @@ export async function readHeader(url, fetchFn, signal) {
   }
 }
 
+// A local file as the source: a fetch-shaped function that answers ingestGguf's Range requests from a Blob (a GGUF
+// the user picked, e.g. from a Hugging Face or LM Studio cache), so nothing is downloaded. Pass it as `fetch`.
+// No ETag: an interrupted ingest resumes from the same file (same header and size), never from a download's state.
+export function fileFetch(blob) {
+  return async (_url, { headers = {}, signal } = {}) => {
+    if (signal) signal.throwIfAborted();
+    const m = /^bytes=(\d+)-(\d+)$/.exec(headers.Range || '');
+    if (!m) throw new Error('fileFetch: only Range requests (bytes=a-b) are supported');
+    const start = Number(m[1]), end = Math.min(Number(m[2]), blob.size - 1);
+    if (start > end) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${blob.size}` } });
+    return new Response(blob.slice(start, end + 1), { status: 206, headers: { 'content-range': `bytes ${start}-${end}/${blob.size}` } });
+  };
+}
+
 // FNV-1a, for the resume identity: over bytes (the GGUF header) or a string (the plan's output layout).
 const fnv = (at, n) => { let h = 0x811c9dc5; for (let i = 0; i < n; i++) h = Math.imul(h ^ at(i), 0x01000193) >>> 0; return `${n}:${h.toString(16)}`; };
 const bytesId = (u8) => fnv((i) => u8[i], u8.length);
@@ -45,7 +60,12 @@ const textId = (s) => fnv((i) => s.charCodeAt(i), s.length);
 // An interrupted ingest resumes only when the GGUF header, the plan's output layout, and the source's size and ETag
 // (when the server sends them) match its checkpoint; otherwise it starts over. `rangeBytes` and `io` are for tests:
 // smaller range requests, and fake OPFS files.
-export async function ingestGguf({ url, key, plan, root = ROOT, format = FORMAT, fetch: fetchFn = fetch, onProgress = () => {}, signal, source = {},
+// Errors are coded (errors.js): LOAD_ABORTED when `signal` aborted, else LOAD_FAILED with the original as `cause`.
+export async function ingestGguf(opts) {
+  try { return await ingest(opts); } catch (e) { throw codedError(e, { signal: opts && opts.signal, what: 'ingest' }); }
+}
+
+async function ingest({ url, key, plan, root = ROOT, format = FORMAT, fetch: fetchFn = fetch, onProgress = () => {}, signal, source = {},
   rangeBytes = 1 << 30, io = { OpfsWriter, readOpfsText, writeOpfsText } }) {
   if (!plan || !plan.layout || !plan.units) throw new Error('ingestGguf: plan { layout, units } is required');
   const t0 = performance.now();
@@ -174,4 +194,41 @@ export function ingestProgress(e) {
   return e && e.status === 'ingest' ? { ...e, status: 'weights', loaded: e.loaded, total: e.total } : e;
 }
 
+// ── The stores on disk: which are usable, which to remove ──
+// A store is usable only when its manifest is complete, in `format`, and every file it names is on disk at its full
+// size. A crash can leave zero-byte or short files behind a complete manifest; those count as invalid, never as a
+// model. Dense files end with up to 255 bytes of alignment padding that is never written, hence the slack.
+// `format` null skips the format check. → { key, state: 'complete' | 'partial' | 'invalid' | 'missing', manifest, bytes, problem }
+const PAD = 255;
+export async function readStore(key, { root = ROOT, format = FORMAT, io = { readOpfsText, opfsFileSize } } = {}) {
+  const dir = `${root}/${key}`;
+  let manifest = null;
+  try { manifest = JSON.parse(await io.readOpfsText(`${dir}/manifest.json`) || 'null'); } catch (_) { manifest = null; }
+  // [file, expected bytes, slack]: the header, then every layout entry the manifest names ({ file, bytes }).
+  const files = manifest
+    ? [['header.bin', manifest.source && manifest.source.dataStart, 0],
+      ...Object.values(manifest).filter((v) => v && typeof v.file === 'string' && typeof v.bytes === 'number').map((v) => [v.file, v.bytes, v.file === 'dense.bin' ? PAD : 0])]
+    : [['header.bin'], ['dense.bin'], ['experts.bin']];
+  const sizes = await Promise.all(files.map(([name]) => io.opfsFileSize(`${dir}/${name}`)));
+  const bytes = sizes.reduce((a, b) => a + (b || 0), 0);
+  const out = (state, problem) => ({ key, state, manifest, bytes, problem });
+  if (!manifest) return out(bytes ? 'invalid' : 'missing', bytes ? 'no readable manifest' : null);
+  if (!manifest.complete) return out('partial', 'ingest not finished');
+  if (format && manifest.format !== format) return out('invalid', `format ${manifest.format}, expected ${format}`);
+  for (let i = 0; i < files.length; i++) {
+    const [name, want, slack] = files[i], have = sizes[i];
+    if (want === 0 && have !== null) continue;                   // a layout entry with no bytes (a dense model's experts.bin)
+    if (!have) return out('invalid', `${name} is ${have === null ? 'missing' : 'empty'}`);
+    if (typeof want === 'number' && have < want - slack) return out('invalid', `${name} is ${have} bytes, expected ${want}`);
+  }
+  return out('complete', null);
+}
+
+// Every store under `root`, for a "models in this browser" list where the user removes one and keeps the rest.
+// `format` null accepts any format (engines write their own; the chat page lists them all).
+export async function listStores({ root = ROOT, format = null, io = { readOpfsText, opfsFileSize, opfsSubdirs } } = {}) {
+  return Promise.all((await io.opfsSubdirs(root)).map((key) => readStore(key, { root, format, io })));
+}
+
+// Removes one store by key; the others under `root` stay.
 export async function removeStore(key, { root = ROOT } = {}) { await removeOpfs(`${root}/${key}`); }

package/src/opfs-reader.js

@@ -256,3 +256,21 @@ export async function removeOpfs(path) {
   const dir = await opfsDir(parts.slice(0, -1).join('/'));
   await dir.removeEntry(parts[parts.length - 1], { recursive: true });
 }
+
+// Size in bytes of an OPFS file, or null when it does not exist.
+export async function opfsFileSize(path) {
+  const parts = path.split('/').filter(Boolean);
+  try {
+    const dir = await opfsDir(parts.slice(0, -1).join('/'));
+    return (await (await dir.getFileHandle(parts[parts.length - 1])).getFile()).size;
+  } catch (_) { return null; }
+}
+
+// Names of the directories directly under an OPFS path; [] when the path does not exist.
+export async function opfsSubdirs(path) {
+  let dir;
+  try { dir = await opfsDir(path); } catch (_) { return []; }
+  const out = [];
+  for await (const [name, h] of dir.entries()) if (h.kind === 'directory') out.push(name);
+  return out.sort();
+}