diskformer 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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

@@ -15,12 +15,12 @@ Plain ES modules, no dependencies, no build step. Chromium with WebGPU. Weights
 | 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.
+Open [diskformer.naklitechie.com](https://diskformer.naklitechie.com/) (also on a [Hugging Face Space](https://huggingface.co/spaces/naklitechie/diskformer-chat)), or serve `examples/chat` yourself.
 Pick a model and a GPU memory budget. The page downloads the model once into OPFS, resumably, then chats.
 
 ```bash
@@ -83,14 +83,14 @@ 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.
 
-`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
 

package/engines/qwen3_moe_ssd.js

@@ -24,7 +24,7 @@ import { OpfsReaderPool, readOpfsText } 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, removeStore } from '../src/ingest.js';
 export { GGML, Q4_BLOCK, Q6K_BLOCK, parseGguf, tensorBytes, splitQ4 } from '../src/gguf.js';
 export { ingestProgress } from '../src/ingest.js';
 
@@ -542,8 +542,14 @@ export class Qwen3MoeSsd {
   static tokenizerFrom(kv) { return new BpeTokenizer(kv); }
 
   static async load(modelId = QWEN3_30B_A3B.repo, opts = {}) {
-    const { fetch: fetchFn = (u, i) => fetch(u, i), onProgress = () => {}, signal } = 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
@@ -567,7 +573,7 @@ export class Qwen3MoeSsd {
     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 },
+        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,
       });

package/index.js

@@ -4,5 +4,5 @@ export { OpfsReaderPool, OpfsWriter, canInline, opfsDir, readOpfsText, writeOpfs
 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, removeStore } from './src/ingest.js';
 export { measure } from './src/measure.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diskformer",
-  "version": "0.2.0",
+  "version": "0.3.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/ingest.js

@@ -17,7 +17,7 @@ import { parseGguf, splitQ8, splitQ4, Q8_BLOCK, Q4_BLOCK } from './gguf.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 +33,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);