diskformer 0.0.1 → 0.3.0

package/src/measure.js

@@ -0,0 +1,61 @@
+/* measure.js — how fast this machine reads an OPFS file the way a disk tier does. Run it where the tier will run
+ * (a page or a worker); OPFS speed varies a lot between machines and browsers.
+ *
+ *   const r = await measure();                         // writes a 256 MB probe, measures, removes it
+ *   const r = await measure({ path: 'diskformer/<key>/experts.bin', recordBytes: 3345408 });   // an existing store
+ *   // → { bytes, sequentialMBps, random: { recordBytes, reads, p50Ms, p90Ms, MBps }, burst8: { p50Ms, MBps } }
+ *
+ * A probe the call just wrote is likely in the OS page cache, so its numbers are an upper bound; point `path` at a
+ * store larger than RAM to see the disk itself.
+ */
+import { OpfsReaderPool, OpfsWriter, removeOpfs } from './opfs-reader.js';
+
+const pct = (a, q) => { const s = [...a].sort((x, y) => x - y); return s[Math.min(s.length - 1, Math.floor(q * s.length))]; };
+
+export async function measure({ path = null, bytes = 256 << 20, recordBytes = 3 << 20, reads = 64, workers = 4, chunkBytes = 64 << 20 } = {}) {
+  const probe = !path;
+  if (probe) {
+    path = 'diskformer/.measure/probe.bin';
+    const w = await OpfsWriter.open(path, { truncate: true });
+    const chunk = new Uint8Array(Math.min(chunkBytes, bytes));
+    for (let i = 0; i < chunk.length; i += 4096) chunk[i] = i & 255;
+    for (let at = 0; at < bytes; at += chunk.length) await w.write(chunk.subarray(0, Math.min(chunk.length, bytes - at)), at);
+    await w.close();
+  }
+  const pool = await OpfsReaderPool.open(path, { workers });
+  try {
+    const size = pool.size;
+    // Sequential: the load pattern (64 MB chunks, one at a time per worker).
+    let t0 = performance.now(), done = 0, inflight = [];
+    for (let at = 0; at < size; at += chunkBytes) {
+      inflight.push(pool.read(at, Math.min(chunkBytes, size - at)).then((r) => { done += r.got; }));
+      if (inflight.length >= workers) { await Promise.all(inflight); inflight = []; }
+    }
+    await Promise.all(inflight);
+    const sequentialMBps = done / 1e6 / ((performance.now() - t0) / 1000);
+    // Random whole records: the per-token pattern, one at a time, then bursts of 8 (one MoE layer's misses).
+    const n = Math.max(1, Math.floor(size / recordBytes));
+    const at = () => Math.floor(Math.random() * n) * recordBytes;
+    // Throughput comes from the total time: browsers coarsen performance.now() (0.1 ms in a worker without
+    // cross-origin isolation), which rounds a single small read to zero.
+    const one = []; let t1 = performance.now();
+    for (let i = 0; i < reads; i++) { const s = performance.now(); await pool.read(at(), recordBytes); one.push(performance.now() - s); }
+    const oneMs = performance.now() - t1;
+    const burst = [], bursts = Math.max(1, Math.round(reads / 8)); t1 = performance.now();
+    for (let i = 0; i < bursts; i++) {
+      const s = performance.now();
+      await Promise.all(Array.from({ length: 8 }, () => pool.read(at(), recordBytes)));
+      burst.push(performance.now() - s);
+    }
+    const burstMs = performance.now() - t1;
+    const mbps = (count, ms) => Math.round((count * recordBytes) / 1e6 / (Math.max(ms, 0.1) / 1000));
+    return {
+      path, bytes: size, workers, sequentialMBps: Math.round(sequentialMBps),
+      random: { recordBytes, reads, p50Ms: +pct(one, 0.5).toFixed(2), p90Ms: +pct(one, 0.9).toFixed(2), MBps: mbps(reads, oneMs) },
+      burst8: { bursts, p50Ms: +pct(burst, 0.5).toFixed(2), MBps: mbps(8 * bursts, burstMs) },
+    };
+  } finally {
+    await pool.close();
+    if (probe) await removeOpfs('diskformer/.measure').catch(() => {});
+  }
+}

package/src/opfs-reader.js

@@ -0,0 +1,258 @@
+/* opfs-reader.js — read model weights from the Origin Private File System (OPFS) fast.
+ *
+ * Only OPFS has the fast path: FileSystemSyncAccessHandle, which exists only in dedicated
+ * workers. Measured 2026-10-02 on an M4 Pro, Chrome 153: 1.51 GB/s per worker for 1.3 MB
+ * random reads, 4.3–5.9 GB/s with 4 read-only workers; File.slice().arrayBuffer() reached
+ * only 0.39 GB/s. (~/Code/knowledge/notes/browser-tab-can-stream-weights-from-ssd.md)
+ *
+ * Shared by the SSD-streaming engines (Qwen3-MoE experts, Gemma 4 PLE rows). No engine
+ * dependencies. Works from a page or from inside an engine worker: the reader and writer
+ * workers are spawned from inlined Blob URLs, so there is no extra file to vendor.
+ *
+ *   const pool = await OpfsReaderPool.open('localmind-ssd/<model>/experts.bin', { workers: 4 });
+ *   const { buf } = await pool.read(offset, length, recycled);      // one contiguous range
+ *   const { buf } = await pool.readv([{ offset, length }, …], into); // many small ranges, packed
+ *   pool.close();
+ *
+ *   const w = await OpfsWriter.open('localmind-ssd/<model>/experts.bin', { truncate: true });
+ *   await w.write(u8, at); await w.close();   // a read-write handle is exclusive: close it first
+ *
+ * Buffers move by transfer, never by copy; pass a previously returned buffer back in to
+ * recycle it.
+ *
+ * Inside a dedicated worker, `{ inline: true }` (see canInline()) skips the worker hop: the
+ * sync handle lives in the calling thread, and the pool gains readSync() for a per-token
+ * critical path where a postMessage round trip would cost more than the read.
+ */
+
+// The file operations, shared by the worker and the inline (same-thread) mode. Kept
+// self-contained: it is stringified into the worker's Blob source.
+function makeOps() {
+  let handle = null;
+  const openFile = async (path, create) => {
+    const parts = path.split('/').filter(Boolean);
+    let dir = await navigator.storage.getDirectory();
+    for (const p of parts.slice(0, -1)) dir = await dir.getDirectoryHandle(p, { create });
+    return dir.getFileHandle(parts[parts.length - 1], { create });
+  };
+  const readFull = (u8, at) => {
+    let got = 0;
+    while (got < u8.byteLength) {
+      const n = handle.read(u8.subarray(got), { at: at + got });
+      if (n <= 0) break;
+      got += n;
+    }
+    return got;
+  };
+  // → [reply, transferList]
+  const run = async (m) => {
+    try {
+      if (m.op === 'open') {
+        const fh = await openFile(m.path, !!m.create);
+        handle = await fh.createSyncAccessHandle(m.mode === 'readwrite' ? {} : { mode: 'read-only' });
+        if (m.truncate) handle.truncate(0);
+        return [{ id: m.id, size: handle.getSize() }, []];
+      }
+      if (m.op === 'read') {
+        const t0 = performance.now();
+        const got = readFull(new Uint8Array(m.buf, 0, m.length), m.at);
+        return [{ id: m.id, buf: m.buf, got, ms: performance.now() - t0 }, [m.buf]];
+      }
+      if (m.op === 'readv') {
+        const t0 = performance.now();
+        let pos = 0, got = 0;
+        for (let i = 0; i < m.ranges.length; i += 2) {
+          const len = m.ranges[i + 1];
+          got += readFull(new Uint8Array(m.buf, pos, len), m.ranges[i]);
+          pos += len;
+        }
+        return [{ id: m.id, buf: m.buf, got, ms: performance.now() - t0 }, [m.buf]];
+      }
+      if (m.op === 'write') {
+        const u8 = new Uint8Array(m.buf, 0, m.length);
+        let put = 0;
+        while (put < u8.byteLength) put += handle.write(u8.subarray(put), { at: m.at + put });
+        return [{ id: m.id, buf: m.buf, put }, [m.buf]];
+      }
+      if (m.op === 'truncate') { handle.truncate(m.size); return [{ id: m.id, size: handle.getSize() }, []]; }
+      if (m.op === 'flush') { handle.flush(); return [{ id: m.id, size: handle.getSize() }, []]; }
+      if (m.op === 'close') {
+        if (handle) { if (m.flush) handle.flush(); handle.close(); }
+        handle = null;
+        return [{ id: m.id, closed: true }, []];
+      }
+      return [{ id: m.id, error: `unknown op ${m.op}` }, []];
+    } catch (err) {
+      return [{ id: m.id, error: `${(err && err.name) || 'Error'}: ${(err && err.message) || err}`, buf: m.buf }, m.buf ? [m.buf] : []];
+    }
+  };
+  run.sync = {
+    read: (buf, length, at) => readFull(new Uint8Array(buf, 0, length), at),
+    write: (u8, at) => { let put = 0; while (put < u8.byteLength) put += handle.write(u8.subarray(put), { at: at + put }); return put; },
+  };
+  return run;
+}
+
+let workerUrl = null;
+const spawn = () => {
+  if (!workerUrl) {
+    const src = `const run = (${makeOps.toString()})();\nself.onmessage = async (e) => { const [r, t] = await run(e.data); self.postMessage(r, t); };`;
+    workerUrl = URL.createObjectURL(new Blob([src], { type: 'text/javascript' }));
+  }
+  return new Worker(workerUrl);
+};
+
+// Inline mode needs a sync access handle in this thread: only a dedicated worker has one.
+export const canInline = () => typeof FileSystemSyncAccessHandle !== 'undefined'
+  && typeof DedicatedWorkerGlobalScope !== 'undefined' && self instanceof DedicatedWorkerGlobalScope;
+
+// Same interface as Channel, but the file operations run in this thread.
+class InlineChannel {
+  constructor() { this.run = makeOps(); this.inflight = 0; this.nextId = 1; }
+  async call(msg) {
+    this.inflight++;
+    try {
+      const [r] = await this.run({ ...msg, id: this.nextId++ });
+      if (r.error) { const err = new Error(r.error); err.buf = r.buf; throw err; }
+      return r;
+    } finally { this.inflight--; }
+  }
+  terminate() {}
+}
+
+// One worker, request/response matched by id; requests run in arrival order.
+class Channel {
+  constructor() {
+    this.worker = spawn();
+    this.pending = new Map();
+    this.nextId = 1;
+    this.inflight = 0;
+    this.worker.onmessage = (e) => {
+      const m = e.data, p = this.pending.get(m.id);
+      if (!p) return;
+      this.pending.delete(m.id);
+      this.inflight--;
+      if (m.error) { const err = new Error(m.error); err.buf = m.buf; p.reject(err); } else p.resolve(m);
+    };
+    this.worker.onerror = (e) => {
+      for (const p of this.pending.values()) p.reject(new Error(`OPFS worker failed: ${e.message || e}`));
+      this.pending.clear();
+    };
+  }
+  call(msg, transfer = []) {
+    const id = this.nextId++;
+    this.inflight++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.worker.postMessage({ ...msg, id }, transfer);
+    });
+  }
+  terminate() { this.worker.terminate(); }
+}
+
+const bufferFor = (into, length) => (into && into.byteLength >= length ? into : new ArrayBuffer(length));
+
+export class OpfsReaderPool {
+  // inline: true → no workers; reads run on this thread's own sync handle (dedicated
+  // worker only, see canInline()), and readSync() is available for a critical path.
+  static async open(path, { workers = 4, inline = false } = {}) {
+    const pool = new OpfsReaderPool();
+    pool.path = path;
+    pool.inline = inline;
+    pool.channels = [];
+    if (inline) pool.channels.push(new InlineChannel());
+    else for (let i = 0; i < workers; i++) pool.channels.push(new Channel());
+    const sizes = await Promise.all(pool.channels.map((c) => c.call({ op: 'open', path })));
+    pool.size = sizes[0].size;
+    return pool;
+  }
+  pick() {
+    let best = this.channels[0];
+    for (const c of this.channels) if (c.inflight < best.inflight) best = c;
+    return best;
+  }
+  // → { buf, got, ms }; `buf` is `into` when it was large enough, else a new ArrayBuffer.
+  read(offset, length, into) {
+    const buf = bufferFor(into, length);
+    return this.pick().call({ op: 'read', at: offset, length, buf }, [buf]);
+  }
+  // Inline mode only: a synchronous read, no promise. → bytes read.
+  readSync(offset, length, into) {
+    if (!this.inline) throw new Error('readSync needs OpfsReaderPool.open(path, { inline: true })');
+    return this.channels[0].run.sync.read(into, length, offset);
+  }
+  // ranges: [{ offset, length }]. The bytes land back-to-back in `buf`, in order.
+  readv(ranges, into) {
+    let total = 0;
+    const flat = new Array(ranges.length * 2);
+    ranges.forEach((r, i) => { flat[2 * i] = r.offset; flat[2 * i + 1] = r.length; total += r.length; });
+    const buf = bufferFor(into, total);
+    return this.pick().call({ op: 'readv', ranges: flat, buf }, [buf]);
+  }
+  async close() {
+    await Promise.all(this.channels.map((c) => c.call({ op: 'close' }).catch(() => {})));
+    for (const c of this.channels) c.terminate();
+    this.channels = [];
+  }
+}
+
+export class OpfsWriter {
+  // inline: true → the read-write sync handle lives in this thread (dedicated worker only).
+  static async open(path, { truncate = false, inline = false } = {}) {
+    const w = new OpfsWriter();
+    w.path = path;
+    w.ch = inline ? new InlineChannel() : new Channel();
+    w.size = (await w.ch.call({ op: 'open', path, create: true, mode: 'readwrite', truncate })).size;
+    return w;
+  }
+  // Copies `u8` into a transferable buffer only when it is a view on part of a larger one.
+  // Resolves with the (recycled) ArrayBuffer once the bytes are written.
+  async write(u8, at) {
+    let buf = u8.buffer, length = u8.byteLength;
+    if (this.ch instanceof InlineChannel) { this.ch.run.sync.write(u8, at); return buf; }
+    if (u8.byteOffset !== 0 || buf.byteLength !== length || (typeof SharedArrayBuffer !== 'undefined' && buf instanceof SharedArrayBuffer)) {
+      buf = new ArrayBuffer(length);
+      new Uint8Array(buf).set(u8);
+    }
+    const r = await this.ch.call({ op: 'write', at, length, buf }, [buf]);
+    return r.buf;
+  }
+  // Like write(), but takes ownership of `buf` (no copy) — the caller gets it back when done.
+  async writeOwned(buf, length, at) {
+    const r = await this.ch.call({ op: 'write', at, length, buf }, [buf]);
+    return r.buf;
+  }
+  async truncate(size) { return (await this.ch.call({ op: 'truncate', size })).size; }
+  async flush() { return (await this.ch.call({ op: 'flush' })).size; }
+  async close() { await this.ch.call({ op: 'close', flush: true }); this.ch.terminate(); }
+}
+
+export async function opfsDir(path, { create = false } = {}) {
+  let dir = await navigator.storage.getDirectory();
+  for (const p of path.split('/').filter(Boolean)) dir = await dir.getDirectoryHandle(p, { create });
+  return dir;
+}
+
+export async function readOpfsText(path) {
+  const parts = path.split('/').filter(Boolean);
+  try {
+    const dir = await opfsDir(parts.slice(0, -1).join('/'));
+    const f = await (await dir.getFileHandle(parts[parts.length - 1])).getFile();
+    return await f.text();
+  } catch (_) { return null; }
+}
+
+export async function writeOpfsText(path, text) {
+  const parts = path.split('/').filter(Boolean);
+  const dir = await opfsDir(parts.slice(0, -1).join('/'), { create: true });
+  const fh = await dir.getFileHandle(parts[parts.length - 1], { create: true });
+  const w = await fh.createWritable();
+  await w.write(text);
+  await w.close();
+}
+
+export async function removeOpfs(path) {
+  const parts = path.split('/').filter(Boolean);
+  const dir = await opfsDir(parts.slice(0, -1).join('/'));
+  await dir.removeEntry(parts[parts.length - 1], { recursive: true });
+}

package/src/rows.js

@@ -0,0 +1,230 @@
+/* rows.js — rows of a large lookup table (an embedding-style table) served from OPFS into a small GPU-resident
+ * cache. Extracted from LocalMind's ple-opfs.js (2026-10-05), where it serves Gemma 4 E2B/E4B's per-layer embedding
+ * table from disk; the Gemma-specific helpers stay in LocalMind. `root` is a new option (LocalMind passes
+ * 'localmind-ssd').
+ *
+ *   RowFile   fixed-size rows in one OPFS file plus manifest.json; synchronous reads through opfs-reader.js in
+ *             inline mode, so it must live in a dedicated worker.
+ *   RowCache  `slots` rows on the GPU, split into planes (byte ranges of a row that live in separate GPU buffers),
+ *             an O(1) LRU, and a CPU id→slot mirror (optionally a GPU u32 map). lookup(ids) makes every id
+ *             resident and returns its slot, writing missing rows with queue.writeBuffer.
+ */
+
+import { OpfsReaderPool, OpfsWriter, canInline, readOpfsText, writeOpfsText, removeOpfs } from './opfs-reader.js';
+
+export const ROOT = 'diskformer';
+const FORMAT = 'localmind-rows/1';   // unchanged from LocalMind, so a store it wrote stays valid
+
+// FNV-1a over a few samples of each source buffer and their lengths: cheap enough to run on every
+// load, and it changes when the model's weights change.
+export function fingerprint(buffers, sample = 1 << 16) {
+  let h = 0x811c9dc5;
+  const mix = (b) => { h ^= b; h = Math.imul(h, 0x01000193) >>> 0; };
+  for (const u8 of buffers) {
+    for (const v of [u8.length & 0xff, (u8.length >>> 8) & 0xff, (u8.length >>> 16) & 0xff, (u8.length >>> 24) & 0xff]) mix(v);
+    const starts = [0, Math.max(0, (u8.length >> 1) - (sample >> 1)), Math.max(0, u8.length - sample)];
+    for (const s of starts) for (let i = s, e = Math.min(u8.length, s + sample); i < e; i++) mix(u8[i]);
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+// Fixed-size rows in one OPFS file, <root>/<key>/<name>, with manifest.json beside it.
+// The file I/O is opfs-reader.js in inline mode: the sync handle lives in this dedicated worker,
+// so a row read is a plain synchronous call with no worker hop.
+export class RowFile {
+  #reader = null;
+
+  constructor({ key, name, rowBytes, rows, root = ROOT }) {
+    this.path = `${root}/${key}/${name}`;
+    this.manifestPath = `${root}/${key}/manifest.json`;
+    this.name = name;
+    this.rowBytes = rowBytes;
+    this.rows = rows;
+    this.manifest = null;
+  }
+
+  static async open({ key, name = 'rows.bin', rowBytes, rows, root = ROOT }) {
+    if (!canInline()) throw new Error('RowFile needs a dedicated worker (FileSystemSyncAccessHandle)');
+    const f = new RowFile({ key, name, rowBytes, rows, root });
+    try { f.manifest = JSON.parse(await readOpfsText(f.manifestPath)); } catch (_) { f.manifest = null; }
+    return f;
+  }
+
+  matches(fp) {
+    const m = this.manifest;
+    return !!m && m.format === FORMAT && m.complete === true && m.name === this.name &&
+      m.rowBytes === this.rowBytes && m.rows === this.rows && m.fingerprint === fp;
+  }
+
+  // fill(row0, count, dst) writes `count` rows starting at `row0` into dst (count * rowBytes bytes).
+  // The manifest is removed first and written last, so an interrupted write is never taken as valid.
+  async write(fp, fill, { batchRows = 8192, extra = {} } = {}) {
+    this.close();
+    await removeOpfs(this.manifestPath).catch(() => {});
+    this.manifest = null;
+    const total = this.rows * this.rowBytes;
+    const t0 = performance.now();
+    const w = await OpfsWriter.open(this.path, { truncate: true, inline: true });
+    try {
+      const buf = new Uint8Array(batchRows * this.rowBytes);
+      for (let row0 = 0; row0 < this.rows; row0 += batchRows) {
+        const n = Math.min(batchRows, this.rows - row0);
+        const view = buf.subarray(0, n * this.rowBytes);
+        fill(row0, n, view);
+        await w.write(view, row0 * this.rowBytes);
+      }
+    } finally { await w.close(); }
+    const writeMs = performance.now() - t0;
+    this.manifest = { format: FORMAT, name: this.name, rowBytes: this.rowBytes, rows: this.rows, bytes: total,
+      fingerprint: fp, complete: true, writtenAt: new Date().toISOString(), writeMs: Math.round(writeMs), ...extra };
+    await writeOpfsText(this.manifestPath, JSON.stringify(this.manifest, null, 1));
+    return writeMs;
+  }
+
+  async openRead() {
+    if (this.#reader) return;
+    const r = await OpfsReaderPool.open(this.path, { inline: true });
+    if (r.size !== this.rows * this.rowBytes) {
+      await r.close();
+      throw new Error(`RowFile ${this.name}: size ${r.size} != ${this.rows * this.rowBytes}`);
+    }
+    this.#reader = r;
+  }
+
+  // Reads rows [row, row + count) to the start of dst (a Uint8Array that starts its buffer).
+  readRows(row, count, dst) {
+    if (dst.byteOffset !== 0) throw new Error('RowFile.readRows: dst must start at offset 0 of its buffer');
+    const len = count * this.rowBytes;
+    const got = this.#reader.readSync(row * this.rowBytes, len, dst.buffer);
+    if (got !== len) throw new Error(`RowFile ${this.name}: read ${got} of ${len} bytes at row ${row}`);
+  }
+
+  // Closes the read handle. In inline mode the handle closes synchronously inside this call.
+  close() {
+    if (this.#reader) { this.#reader.close(); this.#reader = null; }
+  }
+}
+
+export class RowCache {
+  // file: an open RowFile. slots: rows held on the GPU. planes: [{ offset, bytes, buffer }], each
+  // row byte range [offset, offset + bytes) is stored at buffer[slot * bytes]. queue: GPUQueue.
+  // mapBuffer (optional): a GPU u32[file.rows] copy of the id->slot map, 0xFFFFFFFF when absent.
+  constructor({ file, slots, planes, queue, mapBuffer = null }) {
+    this.file = file;
+    this.slots = slots;
+    this.planes = planes;
+    this.queue = queue;
+    this.mapBuffer = mapBuffer;
+    this.slotOf = new Int32Array(file.rows).fill(-1);
+    this.idOf = new Int32Array(slots).fill(-1);
+    // LRU as a doubly linked list over slots; head = least recently used. Starts as 0..slots-1.
+    this.prev = new Int32Array(slots);
+    this.next = new Int32Array(slots);
+    for (let s = 0; s < slots; s++) { this.prev[s] = s - 1; this.next[s] = s + 1 < slots ? s + 1 : -1; }
+    this.head = 0;
+    this.tail = slots - 1;
+    this.stamp = new Uint32Array(slots);
+    this.clock = 0;
+    this.row = new Uint8Array(file.rowBytes);
+    this.u32 = new Uint32Array(1);
+    this.stats = { lookups: 0, ids: 0, misses: 0, readMs: 0, replays: 0 };
+    this.missLog = []; // the first 4,096 ids installed after load, for analysis
+  }
+
+  #touch(s) {
+    if (s === this.tail) return;
+    const p = this.prev[s], n = this.next[s];
+    if (p >= 0) this.next[p] = n; else this.head = n;
+    this.prev[n] = p;
+    this.prev[s] = this.tail;
+    this.next[s] = -1;
+    this.next[this.tail] = s;
+    this.tail = s;
+  }
+
+  #mapWrite(id, slot) {
+    if (!this.mapBuffer) return;
+    this.u32[0] = slot >>> 0;
+    this.queue.writeBuffer(this.mapBuffer, id * 4, this.u32);
+  }
+
+  #install(id, s) {
+    const old = this.idOf[s];
+    if (old >= 0) { this.slotOf[old] = -1; this.#mapWrite(old, 0xffffffff); }
+    const t0 = performance.now();
+    this.file.readRows(id, 1, this.row);
+    this.stats.readMs += performance.now() - t0;
+    for (const p of this.planes) this.queue.writeBuffer(p.buffer, s * p.bytes, this.row, p.offset, p.bytes);
+    this.idOf[s] = id;
+    this.slotOf[id] = s;
+    this.#mapWrite(id, s);
+    this.stats.misses++;
+    if (this.missLog.length < 4096) this.missLog.push(id);
+  }
+
+  // Makes every id resident and returns its slot. Rows one call uses are never evicted by the same
+  // call, so a call may name at most `slots` distinct ids.
+  lookup(ids, out = new Uint32Array(ids.length)) {
+    const call = ++this.clock;
+    this.stats.lookups++;
+    this.stats.ids += ids.length;
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      let s = this.slotOf[id];
+      if (s < 0) {
+        s = this.head;
+        if (this.stamp[s] === call) throw new Error(`RowCache: one lookup needs more than ${this.slots} rows`);
+        this.#install(id, s);
+      }
+      this.stamp[s] = call;
+      this.#touch(s);
+      out[i] = s;
+    }
+    return out;
+  }
+
+  has(id) { return this.slotOf[id] >= 0; }
+
+  // Loads rows [row0, row0 + count) into the least recently used slots in large reads (for a warm
+  // set at load), then uploads the whole id->slot map once. Returns the milliseconds spent.
+  warm(row0, count, batch = 4096) {
+    const t0 = performance.now();
+    count = Math.min(count, this.slots);
+    const rb = this.file.rowBytes;
+    const buf = new Uint8Array(batch * rb);
+    const planeBufs = this.planes.map((p) => new Uint8Array(batch * p.bytes));
+    for (let r = row0; r < row0 + count; r += batch) {
+      const n = Math.min(batch, row0 + count - r);
+      this.file.readRows(r, n, buf);
+      // Fresh slots come from the LRU head in order; collect them and write contiguous runs.
+      const slots = new Int32Array(n);
+      for (let i = 0; i < n; i++) {
+        const id = r + i;
+        let s = this.slotOf[id];
+        if (s < 0) {
+          s = this.head;
+          const old = this.idOf[s];
+          if (old >= 0) this.slotOf[old] = -1;
+          this.idOf[s] = id;
+          this.slotOf[id] = s;
+        }
+        this.#touch(s);
+        slots[i] = s;
+      }
+      for (let pi = 0; pi < this.planes.length; pi++) {
+        const p = this.planes[pi], dst = planeBufs[pi];
+        for (let i = 0; i < n; i++) dst.set(buf.subarray(i * rb + p.offset, i * rb + p.offset + p.bytes), i * p.bytes);
+        let i = 0;
+        while (i < n) {
+          let j = i + 1;
+          while (j < n && slots[j] === slots[j - 1] + 1) j++;
+          this.queue.writeBuffer(p.buffer, slots[i] * p.bytes, dst, i * p.bytes, (j - i) * p.bytes);
+          i = j;
+        }
+      }
+    }
+    // slotOf's bytes are the GPU map: -1 as an Int32 is 0xFFFFFFFF as a u32.
+    if (this.mapBuffer) this.queue.writeBuffer(this.mapBuffer, 0, this.slotOf);
+    return performance.now() - t0;
+  }
+}