llama-cpp-pro 0.2.2

package/dist/wasm/llama_engine.js

@@ -0,0 +1,1829 @@
+/* @ts-self-types="./llama_engine.d.ts" */
+/* Auto-generated by package-embed-wasm.mjs — do not edit */
+import createLlamaModule from './llama_engine_emscripten.mjs';
+
+let _mod = null;
+let _lastWasmStderr = '';
+const LLAMA_WASM_JSPI = true;
+const LLAMA_WASM_PTHREAD = false;
+
+// JSPI polyfill for token streaming only (generate_stream). Model load uses sync EM_JS fread.
+if (LLAMA_WASM_JSPI && typeof WebAssembly !== 'undefined' && !WebAssembly.Suspending) {
+  WebAssembly.Suspending = function (fn) { return fn; };
+  WebAssembly.promising = function (fn) {
+    return function (...args) {
+      try { return Promise.resolve(fn(...args)); }
+      catch (e) { return Promise.reject(e); }
+    };
+  };
+}
+
+function wasmHasAsyncFileBridge(mod) {
+  if (!mod) return false;
+  if (typeof mod._cap_wasm_set_use_async_file === 'function') return true;
+  try {
+    if (typeof mod.cwrap === 'function') {
+      return typeof mod.cwrap('cap_wasm_set_use_async_file', null, ['number']) === 'function';
+    }
+  } catch (_) {}
+  return false;
+}
+
+/** External file read (OPFS/JS handler → sync fread hook). Does not require native JSPI. */
+export function can_use_async_file() {
+  if (_mod && wasmHasAsyncFileBridge(_mod)) return true;
+  return LLAMA_WASM_JSPI;
+}
+
+/** Most recent llama stderr (error messages must use tail — head is stale load_tensors lines). */
+function tailWasmStderr(maxLen = 1200) {
+  if (!_lastWasmStderr) return '';
+  return _lastWasmStderr.length > maxLen
+    ? _lastWasmStderr.slice(-maxLen)
+    : _lastWasmStderr;
+}
+
+/** Shared WASM memory for pthread builds (wllama getWasmMemory). Requires COOP/COEP. */
+function trySharedWasmMemory() {
+  if (!LLAMA_WASM_PTHREAD) return null;
+  if (globalThis.crossOriginIsolated !== true || typeof SharedArrayBuffer === 'undefined') {
+    return null;
+  }
+  // wllama-style: 20 MB initial, step down max (4096 → 20 MB) on iOS OOM
+  const minBytes = 20 * 1024 * 1024;
+  let maxBytes = 4096 * 1024 * 1024;
+  const stepBytes = 128 * 1024 * 1024;
+  while (maxBytes >= minBytes) {
+    try {
+      return new WebAssembly.Memory({
+        initial: minBytes / 65536,
+        maximum: maxBytes / 65536,
+        shared: true,
+      });
+    } catch {
+      maxBytes -= stepBytes;
+    }
+  }
+  return null;
+}
+
+/** Single-thread: Emscripten owns memory (wllama passes wasmMemory: null). */
+function tryWasmMemory() {
+  return null;
+}
+
+/** Raw Emscripten Module — used by HeapFS helpers in wasm.engine.ts. */
+export function getEmscriptenModule() {
+  return _mod;
+}
+
+// ── Default export: loads and instantiates the WebAssembly module ─────────────
+// wasm.engine.ts calls: await mod.default()
+// Named "initWasm" internally so the "init" named export (below) can remain
+// unambiguously the Rust-level engine initialiser (mod.init).
+export default async function initWasm(_pathHint) {
+  if (_mod) return _mod;
+
+  // Emscripten's instantiateWasm hook has no failure callback — if instantiation
+  // fails we must reject this outer promise via Promise.race (never throw from
+  // the async chain inside instantiateWasm or the module hangs forever).
+  let rejectWasmInstantiate;
+  const wasmInstantiateFailed = new Promise((_, reject) => {
+    rejectWasmInstantiate = reject;
+  });
+
+  const sharedMem = trySharedWasmMemory();
+  if (LLAMA_WASM_PTHREAD && !sharedMem) {
+    throw new Error(
+      'Cannot allocate shared WebAssembly.Memory for llama pthread build. ' +
+        'Ensure COOP/COEP headers (crossOriginIsolated) or disable pthreads.',
+    );
+  }
+  const importedMem = sharedMem;
+  const pthreadPoolSize = sharedMem && navigator.hardwareConcurrency
+    ? Math.max(2, Math.floor(navigator.hardwareConcurrency / 2))
+    : 4;
+
+  const modulePromise = createLlamaModule({
+    preRun: [() => {
+      if (can_use_async_file()) {
+        if (typeof Module !== 'undefined') {
+          Module.ENV = Module.ENV || {};
+          Module.ENV['USE_ASYNC_FILE'] = '1';
+        }
+      }
+    }],
+    printErr: (text) => {
+      const line = String(text);
+      _lastWasmStderr = (_lastWasmStderr ? _lastWasmStderr + '\n' : '') + line;
+      if (_lastWasmStderr.length > 4096) _lastWasmStderr = _lastWasmStderr.slice(-4096);
+      if (typeof console !== 'undefined') {
+        if (line.includes('@@WASM_LOAD@@') || line.includes('@@WASM_GEN@@')) {
+          console.error('[llama-wasm-load]', line);
+        } else {
+          console.error('[llama.cpp]', line);
+        }
+      }
+    },
+    onAbort: (reason) => {
+      _lastWasmStderr = 'Aborted: ' + String(reason);
+      if (typeof console !== 'undefined') console.error('[llama.cpp]', _lastWasmStderr);
+    },
+    ...(importedMem ? { wasmMemory: importedMem } : {}),
+    ...(sharedMem ? {
+      pthreadPoolSize,
+      mainScriptUrlOrBlob: new URL('./llama_engine_emscripten.mjs', import.meta.url).href,
+    } : {}),
+    // Resolve assets relative to this JS file so the module works regardless
+    // of where the dist/wasm/ directory is served from.
+    // Emscripten requests 'llama_engine_emscripten.wasm' but we ship the
+    // MAIN_MODULE binary under the stable name 'llama_engine.wasm'.
+    locateFile: (filename) => {
+      const name = filename === 'llama_engine_emscripten.wasm' ? 'llama_engine.wasm' : filename;
+      return new URL(name, import.meta.url).href;
+    },
+    // The WASM binary imports wasm-bindgen helpers from "__wbindgen_placeholder__"
+    // but Emscripten's addToLibrary places them all under the "env" key.
+    // Alias the module so WebAssembly.instantiate receives the expected key.
+    instantiateWasm: (imports, successCallback) => {
+      const wasmUrl = new URL('llama_engine.wasm', import.meta.url).href;
+      // wasm-bindgen externref xform: manages a growable JS-side index space
+      // for externref table slots. Indices are tracked with a monotonic counter;
+      // the Emscripten runtime's heap handles actual JS object storage.
+      let _extRefNextIdx = 128; // skip wasm-bindgen's pre-filled reserved slots
+      const extRefXform = {
+        __wbindgen_externref_table_grow: (delta) => {
+          const prev = _extRefNextIdx;
+          _extRefNextIdx += delta;
+          return prev;
+        },
+        __wbindgen_externref_table_set_null: (_idx) => {},
+      };
+
+      // The MAIN_MODULE binary was originally a SIDE_MODULE: it imports ggml
+      // quantisation functions via GOT.func even though those functions are
+      // compiled into the same binary (as "_generic" suffixed exports).
+      // Emscripten's reportUndefinedSymbols crashes when GOT entries that are
+      // marked "required" cannot be resolved.  We fix this in two steps:
+      //
+      // 1. Wrap GOT.func/GOT.mem so every entry is marked weak (required=false).
+      //    This stops the GL/AL/console stubs (never called by llama inference)
+      //    from crashing reportUndefinedSymbols.
+      //
+      // 2. After instantiation, grow __indirect_function_table by one slot per
+      //    ggml symbol, store the "_generic" function there, and write that slot
+      //    index into the GOT global before calling successCallback.
+      //    Emscripten's updateGOT sees value != -1 and leaves them untouched.
+      const gotGlobals = {};
+      const weakenGOT = (proxy) => new Proxy({}, {
+        get(_, symName) {
+          if (typeof symName !== 'string') return undefined;
+          const global = proxy[symName];
+          if (global instanceof WebAssembly.Global) {
+            global.required = false;
+            gotGlobals[symName] = global;
+          }
+          return global;
+        },
+      });
+
+      // GOT.func symbol → exported "_generic" implementation present in the binary.
+      const FUNC_ALIASES = {
+        'lm_ggml_vec_dot_q4_0_q8_0': 'lm_ggml_vec_dot_q4_0_q8_0_generic',
+        'lm_ggml_vec_dot_q5_0_q8_0': 'lm_ggml_vec_dot_q5_0_q8_0_generic',
+        'lm_ggml_vec_dot_q5_1_q8_1': 'lm_ggml_vec_dot_q5_1_q8_1_generic',
+        'quantize_row_q8_0':          'quantize_row_q8_0_generic',
+        'lm_ggml_vec_dot_q8_0_q8_0': 'lm_ggml_vec_dot_q8_0_q8_0_generic',
+        'quantize_row_q8_1':          'quantize_row_q8_1_generic',
+        'lm_ggml_vec_dot_q2_K_q8_K': 'lm_ggml_vec_dot_q2_K_q8_K_generic',
+        'lm_ggml_vec_dot_q3_K_q8_K': 'lm_ggml_vec_dot_q3_K_q8_K_generic',
+        'lm_ggml_vec_dot_q4_K_q8_K': 'lm_ggml_vec_dot_q4_K_q8_K_generic',
+        'lm_ggml_vec_dot_q5_K_q8_K': 'lm_ggml_vec_dot_q5_K_q8_K_generic',
+        'lm_ggml_vec_dot_q6_K_q8_K': 'lm_ggml_vec_dot_q6_K_q8_K_generic',
+        'quantize_row_q8_K':          'quantize_row_q8_K_generic',
+      };
+
+      const patchedImports = {
+        ...imports,
+        '__wbindgen_placeholder__': imports['env'] ?? {},
+        '__wbindgen_externref_xform__': extRefXform,
+        'GOT.func': weakenGOT(imports['GOT.func']),
+        'GOT.mem':  weakenGOT(imports['GOT.mem']),
+      };
+
+      const patchGOTAndCall = (result) => {
+        const exports = result.instance.exports;
+        const table = exports.__indirect_function_table;
+        if (table) {
+          for (const [gotSym, exportSym] of Object.entries(FUNC_ALIASES)) {
+            const fn = exports[exportSym];
+            if (fn && gotGlobals[gotSym]) {
+              const idx = table.grow(1);
+              table.set(idx, fn);
+              gotGlobals[gotSym].value = idx;
+            }
+          }
+        }
+
+        // Pass the real Instance — updateGOT(origExports) requires authentic WASM
+        // export objects. wasm-bindgen shims are injected in llama_engine_emscripten.mjs
+        // after Asyncify.instrumentWasmExports (see package-embed-wasm Stage 1b).
+        successCallback(result.instance, result.module);
+      };
+
+      const reportInstantiateFailure = (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        rejectWasmInstantiate(error);
+      };
+      WebAssembly.instantiateStreaming(fetch(wasmUrl), patchedImports)
+        .catch(() =>
+          fetch(wasmUrl)
+            .then((r) => {
+              if (!r.ok) {
+                throw new Error(`Failed to fetch wasm: ${r.status} ${r.statusText}`);
+              }
+              return r.arrayBuffer();
+            })
+            .then((bytes) => WebAssembly.instantiate(bytes, patchedImports))
+        )
+        .then(patchGOTAndCall)
+        .catch(reportInstantiateFailure);
+      return {}; // Emscripten requires a synchronous {} return
+    },
+  });
+
+  _mod = await Promise.race([modulePromise, wasmInstantiateFailed]);
+  installAsyncFileBridge(_mod);
+  ensureMemfsTmp();
+  patchHeapFS();
+  _mod.__llamaWasmJspi = LLAMA_WASM_JSPI;
+  _mod.__llamaWasmAsyncFile = can_use_async_file();
+  _mod.__llamaWasmPthread = LLAMA_WASM_PTHREAD && !!sharedMem;
+  return _mod;
+}
+
+/**
+ * wasm-bindgen + JSPI: Rust load_model_from_path reads wasm ptr2 as vfs_path (not ptr1).
+ * JS glue still maps arg2→ptr1, arg3→ptr2 — pass (model_id, opts_json, vfs_path).
+ */
+function wasmBindgenLoadModelFromPath(model_id, vfs_path, opts_json) {
+  const fn = _mod?.load_model_from_path;
+  if (!fn) throw new Error('load_model_from_path not on Emscripten module');
+  fn(model_id, opts_json, vfs_path);
+}
+
+// ── Named exports (synchronous; safe to call after await initWasm()) ─────────
+// These match the wasm-bindgen function names that initBindgen assigns to Module.*
+
+/** Rust-level engine init — must be called once after the default export resolves. */
+export function init() {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.init();
+}
+
+/** Load a GGUF model from bytes. */
+export function load_model(model_id, bytes, opts_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.load_model(model_id, bytes, opts_json);
+}
+
+/** Unload a loaded model and release resources. */
+export function unload_model(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  _modelContextIds.delete(String(model_id));
+  _loadedModelBytes.delete(String(model_id));
+  _loadedModelOpts.delete(String(model_id));
+  _embedGraphWarmed.delete(String(model_id));
+  _measuredFootprintBytes.delete(String(model_id));
+  _linearAtLoadStart.delete(String(model_id));
+  _mod.unload_model(model_id);
+  const kept = _loadedHeapfsModels.get(model_id);
+  if (kept) {
+    heapfsReleaseEntry(kept.path, { mode: 'heapfs', basename: kept.basename, heapId: kept.heapId });
+    _loadedHeapfsModels.delete(model_id);
+  }
+  const asyncPath = _loadedAsyncModels.get(model_id);
+  if (asyncPath) {
+    asyncFileRelease(asyncPath);
+    _loadedAsyncModels.delete(model_id);
+  }
+}
+
+/** Select which resident model receives inference when model_id is omitted. */
+export function set_active_model(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.set_active_model(model_id);
+}
+
+/** Return the active model id, or throw if none. */
+export function get_active_model() {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.get_active_model();
+}
+
+/** List resident models (registry snapshot JSON). */
+export function list_loaded_models() {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.list_loaded_models();
+}
+
+/** model_id → C++ context id (cwrap path — same pattern as llama_load_context_from_path). */
+const _modelContextIds = new Map();
+let _cwrapCompletion = null;
+let _cwrapEmbeddingJson = null;
+
+/** Emscripten 3.x / WASM i64 — cwrap and wasm-bindgen expect bigint for int64_t. */
+function wasmI64Arg(value) {
+  const n = typeof value === 'bigint' ? value : BigInt(Math.trunc(Number(value)));
+  return n;
+}
+
+function wasmI64ToNumber(value) {
+  if (typeof value === 'bigint') return Number(value);
+  return Number(value);
+}
+
+function registerModelContext(model_id, context_id) {
+  const id = wasmI64ToNumber(context_id);
+  if (model_id && id > 0) {
+    _modelContextIds.set(String(model_id), id);
+  }
+  const reg = _mod?.register_model_context;
+  if (typeof reg === 'function') {
+    try {
+      try {
+        reg(model_id, wasmI64Arg(id));
+      } catch (_) {
+        reg(model_id, id);
+      }
+    } catch (err) {
+      if (typeof console !== 'undefined') {
+        console.error('[llama-wasm] register_model_context failed (JS context map still set):', err);
+      }
+    }
+  }
+}
+
+function buildCompletionParamsJson(req_json) {
+  let req = {};
+  try {
+    req = JSON.parse(req_json || '{}');
+  } catch (e) {
+    throw new Error('Invalid generate request JSON: ' + (e && e.message ? e.message : String(e)));
+  }
+  const prompt = req.prompt != null
+    ? String(req.prompt)
+    : Array.isArray(req.messages)
+      ? req.messages.map((m) => m.role + ': ' + m.content).join('\n')
+      : '';
+  if (!prompt.trim()) {
+    throw new Error('No prompt or messages provided');
+  }
+  const out = {
+    prompt,
+    n_predict: req.max_tokens ?? req.n_predict ?? 128,
+    temperature: req.temperature ?? 0.7,
+    top_p: req.top_p ?? 0.95,
+    top_k: req.top_k ?? 40,
+    stop: req.stop ?? [],
+  };
+  const repeat =
+    req.repeat_penalty ?? req.penalty_repeat ?? req.repeatPenalty;
+  if (typeof repeat === 'number' && Number.isFinite(repeat)) {
+    out.penalty_repeat = repeat;
+  }
+  return JSON.stringify(out);
+}
+
+function resolveCompletionFn() {
+  if (_cwrapCompletion) return _cwrapCompletion;
+  const name = 'llama_completion';
+  const wrapCall = (raw, useBigintArg) => (ctxId, paramsJson) =>
+    raw(useBigintArg ? wasmI64Arg(ctxId) : Number(ctxId), paramsJson);
+  if (typeof _mod.cwrap === 'function') {
+    for (const argType of ['bigint', 'number']) {
+      try {
+        const raw = _mod.cwrap(name, 'string', [argType, 'string']);
+        if (typeof raw === 'function') {
+          _cwrapCompletion = wrapCall(raw, argType === 'bigint');
+          return _cwrapCompletion;
+        }
+      } catch (_) {}
+    }
+  }
+  const rawFn = _mod['_' + name] ?? _mod.wasmExports?.[name];
+  if (typeof rawFn === 'function') {
+    _cwrapCompletion = (ctxId, paramsJson) => {
+      try {
+        return rawFn(wasmI64Arg(ctxId), paramsJson);
+      } catch (e1) {
+        return rawFn(Number(ctxId), paramsJson);
+      }
+    };
+    return _cwrapCompletion;
+  }
+  throw new Error('llama_completion not exported — rebuild wasm (EXPORTED_FUNCTIONS)');
+}
+
+/** Inference via C cwrap (avoids wasm-bindgen trap/undefined throw on llama_decode). */
+function wasmGenerateViaCwrap(model_id, req_json) {
+  const ctxId = _modelContextIds.get(String(model_id));
+  if (!ctxId || ctxId <= 0) {
+    throw new Error('Model not loaded (no WASM context id for ' + model_id + ')');
+  }
+  const t0 = typeof performance !== 'undefined' ? performance.now() : Date.now();
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] cwrap generate: model=' + model_id + ' ctxId=' + ctxId +
+      ' wasmMB=' + wasmLinearMb(),
+    );
+  }
+  const compJson = buildCompletionParamsJson(req_json);
+  const raw = resolveCompletionFn()(ctxId, compJson);
+  const elapsedMs = Math.round(
+    (typeof performance !== 'undefined' ? performance.now() : Date.now()) - t0,
+  );
+  if (typeof raw !== 'string') {
+    throw new TypeError('llama_completion returned ' + typeof raw + ' (' + String(raw) + ')');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_) {
+    throw new Error('llama_completion returned non-JSON: ' + raw.slice(0, 160));
+  }
+  if (parsed && typeof parsed.error === 'string' && parsed.error.length > 0) {
+    throw new Error(parsed.error);
+  }
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] cwrap generate ok chars=' + (parsed.text?.length ?? 0) +
+      ' ms=' + elapsedMs + ' tokens=' + (parsed.tokens_predicted ?? '?'),
+    );
+  }
+  return raw;
+}
+
+function resolveEmbeddingFn() {
+  if (_cwrapEmbeddingJson) return _cwrapEmbeddingJson;
+  const name = 'llama_embedding_json';
+  const wrapCall = (raw, useBigintArg) => (ctxId, text, paramsJson) =>
+    raw(useBigintArg ? wasmI64Arg(ctxId) : Number(ctxId), text, paramsJson ?? '{}');
+  if (typeof _mod.cwrap === 'function') {
+    for (const argType of ['bigint', 'number']) {
+      try {
+        const raw = _mod.cwrap(name, 'string', [argType, 'string', 'string']);
+        if (typeof raw === 'function') {
+          _cwrapEmbeddingJson = wrapCall(raw, argType === 'bigint');
+          return _cwrapEmbeddingJson;
+        }
+      } catch (_) {}
+    }
+  }
+  const rawFn = _mod['_' + name] ?? _mod.wasmExports?.[name];
+  if (typeof rawFn === 'function') {
+    _cwrapEmbeddingJson = (ctxId, text, paramsJson) => {
+      try {
+        return rawFn(wasmI64Arg(ctxId), text, paramsJson ?? '{}');
+      } catch (e1) {
+        return rawFn(Number(ctxId), text, paramsJson ?? '{}');
+      }
+    };
+    return _cwrapEmbeddingJson;
+  }
+  throw new Error('llama_embedding_json not exported — rebuild wasm (EXPORTED_FUNCTIONS)');
+}
+
+function parseEmbedRequest(req_json) {
+  let req = {};
+  try {
+    req = JSON.parse(req_json || '{}');
+  } catch (e) {
+    throw new Error('Invalid embed request JSON: ' + (e && e.message ? e.message : String(e)));
+  }
+  let inputs;
+  if (typeof req.input === 'string') {
+    inputs = [req.input];
+  } else if (Array.isArray(req.input)) {
+    inputs = req.input.map((v) => String(v));
+  } else {
+    throw new Error('Embed request missing input (string or string[])');
+  }
+  if (inputs.length === 0 || inputs.every((t) => !String(t).trim())) {
+    throw new Error('Embed request input is empty');
+  }
+  const paramsJson = req.normalize != null
+    ? JSON.stringify({ embd_normalize: req.normalize ? 2 : -1 })
+    : '{}';
+  return { inputs, paramsJson };
+}
+
+/** Inference via C cwrap (avoids wasm-bindgen malloc abort after heap grow). */
+function wasmEmbedViaCwrap(model_id, req_json) {
+  const ctxId = _modelContextIds.get(String(model_id));
+  if (!ctxId || ctxId <= 0) {
+    throw new Error('Model not loaded (no WASM context id for ' + model_id + ')');
+  }
+  const { inputs, paramsJson } = parseEmbedRequest(req_json);
+  const embedFn = resolveEmbeddingFn();
+  const t0 = typeof performance !== 'undefined' ? performance.now() : Date.now();
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] cwrap embed: model=' + model_id + ' ctxId=' + ctxId +
+      ' n=' + inputs.length + ' wasmMB=' + wasmLinearMb(),
+    );
+  }
+  const vectors = [];
+  for (const text of inputs) {
+    const raw = embedFn(ctxId, text, paramsJson);
+    if (typeof raw !== 'string') {
+      throw new TypeError('llama_embedding_json returned ' + typeof raw);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (_) {
+      throw new Error('llama_embedding_json returned non-JSON: ' + raw.slice(0, 160));
+    }
+    if (parsed && typeof parsed.error === 'string' && parsed.error.length > 0) {
+      throw new Error(parsed.error);
+    }
+    if (!Array.isArray(parsed?.embedding) || parsed.embedding.length === 0) {
+      throw new Error('llama_embedding_json returned empty embedding');
+    }
+    vectors.push(parsed.embedding);
+  }
+  const elapsedMs = Math.round(
+    (typeof performance !== 'undefined' ? performance.now() : Date.now()) - t0,
+  );
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] cwrap embed ok n=' + vectors.length + ' dim=' + (vectors[0]?.length ?? 0) +
+      ' ms=' + elapsedMs,
+    );
+  }
+  return JSON.stringify({ vectors });
+}
+
+/** Run text generation. Returns JSON GenerateResponse. */
+export function generate(model_id, req_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  try {
+    return wasmGenerateViaCwrap(model_id, req_json);
+  } catch (err) {
+    throw wasmThrowToError(err, 'generate failed');
+  }
+}
+
+/** Streaming generation — calls on_token(token, index) per token (JSPI when available). */
+export function generate_stream(model_id, req_json, on_token) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.generate_stream;
+  if (typeof fn !== 'function') {
+    throw new Error('generate_stream not exported — rebuild with LLAMA_WASM_JSPI=1');
+  }
+  try {
+    return fn(model_id, req_json, on_token);
+  } catch (err) {
+    throw wasmThrowToError(err, 'generate_stream failed');
+  }
+}
+
+function growWasmLinearTo(targetBytes) {
+  if (!_mod) return;
+  const current = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  if (current >= targetBytes) return;
+  let grown = false;
+  if (typeof _mod.growMemory === 'function') {
+    grown = _mod.growMemory(targetBytes) === 1;
+  } else if (typeof _mod.emscripten_resize_heap === 'function') {
+    grown = !!_mod.emscripten_resize_heap(targetBytes);
+  }
+  if (!grown) {
+    throw new Error(
+      '[llama-wasm] failed to grow wasm memory to ' + targetBytes + ' bytes (have ' + current + ')',
+    );
+  }
+  heapfsResyncViews();
+  const after = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] embed memory grow: ' + (current / 1048576).toFixed(0) + 'MB -> ' +
+      (after / 1048576).toFixed(0) + 'MB',
+    );
+  }
+}
+
+/** Reserve slack for lazy encoder-graph alloc on first embed (BERT / pooling models). */
+function ensureEmbedInferenceHeadroom(model_id) {
+  if (!_mod) return;
+  const id = String(model_id);
+  if (_embedGraphWarmed.has(id)) return;
+  const opts = _loadedModelOpts.get(id) ?? {};
+  if (!opts.embedding) {
+    _embedGraphWarmed.add(id);
+    return;
+  }
+  const current = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  const target = Math.min(current + 64 * 1024 * 1024, WASM_MAX_BYTES);
+  if (current < target) {
+    growWasmLinearTo(target);
+  }
+  _embedGraphWarmed.add(id);
+}
+
+/** Generate embeddings. Returns JSON EmbedResponse. */
+export function embed(model_id, req_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  try {
+    ensureEmbedInferenceHeadroom(model_id);
+    return wasmEmbedViaCwrap(model_id, req_json);
+  } catch (err) {
+    throw wasmThrowToError(err, 'embed failed');
+  }
+}
+
+/** Rank documents by relevance (rank-pooling embed models). Returns JSON array. */
+export function rerank(model_id, query, documents_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.rerank;
+  if (typeof fn !== 'function') throw new Error('rerank not exported — rebuild WASM');
+  return fn(model_id, query, documents_json);
+}
+
+/** Benchmark prompt/tg throughput. Returns JSON-ish bench string. */
+export function bench(model_id, pp, tg, pl, nr) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.bench;
+  if (typeof fn !== 'function') throw new Error('bench not exported — rebuild WASM');
+  return fn(model_id, pp, tg, pl, nr);
+}
+
+export function save_session(model_id, filepath, token_size) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.save_session;
+  if (typeof fn !== 'function') throw new Error('save_session not exported — rebuild WASM');
+  return fn(model_id, filepath, token_size);
+}
+
+export function load_session(model_id, filepath) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.load_session;
+  if (typeof fn !== 'function') throw new Error('load_session not exported — rebuild WASM');
+  return fn(model_id, filepath);
+}
+
+export function apply_lora_adapters(model_id, lora_list_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.apply_lora_adapters;
+  if (typeof fn !== 'function') throw new Error('apply_lora_adapters not exported — rebuild WASM');
+  return fn(model_id, lora_list_json);
+}
+
+export function remove_lora_adapters(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  _mod.remove_lora_adapters?.(model_id);
+}
+
+export function get_loaded_lora_adapters(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.get_loaded_lora_adapters;
+  if (typeof fn !== 'function') return '[]';
+  return fn(model_id);
+}
+
+export function init_multimodal(model_id, path, use_gpu) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.init_multimodal;
+  if (typeof fn !== 'function') throw new Error('init_multimodal not exported — rebuild WASM');
+  return fn(model_id, path, !!use_gpu);
+}
+
+export function multimodal_status(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.multimodal_status;
+  if (typeof fn !== 'function') return '{"enabled":false,"vision":false,"audio":false}';
+  return fn(model_id);
+}
+
+export function release_multimodal(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  _mod.release_multimodal?.(model_id);
+}
+
+export function init_vocoder(model_id, path, n_batch) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.init_vocoder;
+  if (typeof fn !== 'function') throw new Error('init_vocoder not exported — rebuild WASM');
+  return fn(model_id, path, n_batch ?? 512);
+}
+
+export function vocoder_enabled(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.vocoder_enabled;
+  if (typeof fn !== 'function') return '{"enabled":false}';
+  return fn(model_id);
+}
+
+export function release_vocoder(model_id) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  _mod.release_vocoder?.(model_id);
+}
+
+export function formatted_audio_completion(model_id, speaker_json, text_to_speak) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.formatted_audio_completion;
+  if (typeof fn !== 'function') throw new Error('formatted_audio_completion not exported — rebuild WASM');
+  return fn(model_id, speaker_json ?? '', text_to_speak ?? '');
+}
+
+export function audio_guide_tokens(model_id, text_to_speak) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.audio_guide_tokens;
+  if (typeof fn !== 'function') throw new Error('audio_guide_tokens not exported — rebuild WASM');
+  return fn(model_id, text_to_speak ?? '');
+}
+
+export function decode_audio_tokens(model_id, tokens_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const fn = _mod.decode_audio_tokens;
+  if (typeof fn !== 'function') throw new Error('decode_audio_tokens not exported — rebuild WASM');
+  return fn(model_id, tokens_json);
+}
+
+/** Return engine health as a JSON string. */
+export function health() {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return _mod.health();
+}
+
+/** Return memory usage as a JSON string (JS-only — never call Rust memory_snapshot; it can abort WASM). */
+export function memory_snapshot() {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const linear = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  const loadedModels = [];
+  for (const [modelId, fileBytes] of _loadedModelBytes) {
+    const opts = _loadedModelOpts.get(modelId) ?? {};
+    const estimatedFootprintBytes = estimateModelWasmFootprint(fileBytes, opts);
+    const measuredFootprintBytes = _measuredFootprintBytes.get(modelId);
+    loadedModels.push({
+      modelId,
+      fileBytes,
+      estimatedFootprintBytes,
+      measuredFootprintBytes: measuredFootprintBytes ?? null,
+      footprintBytes: getModelFootprintBytes(modelId),
+      calibrated: typeof measuredFootprintBytes === 'number' && measuredFootprintBytes > 0,
+    });
+  }
+  return JSON.stringify({
+    pressure: 'unknown',
+    wasmLinearBytes: linear,
+    wasmLinearMb: linear ? +(linear / 1048576).toFixed(1) : 0,
+    wasmPoolCeilingBytes: WASM_POOL_CEILING_BYTES,
+    wasmHeadroomBytes: Math.max(0, WASM_POOL_CEILING_BYTES - linear),
+    maxModels: WASM_MAX_CONCURRENT_MODELS,
+    loadedModelCount: _loadedModelBytes.size,
+    loadedModels,
+    loadedFootprintBytes: loadedModelsFootprintBytes(null),
+    measuredFootprintBytes: loadedModelsFootprintBytes(null),
+  });
+}
+
+// ── JSPI async file read (wllama USE_ASYNC_FILE / cap-wasm-fs.cpp) ───────────
+// Model bytes stay in JS (Blob / OPFS reader). C++ fread → _cap_js_file_read.
+const _asyncFileHandlers = new Map();
+const _loadedAsyncModels = new Map();
+/** Bytes per loaded model — cumulative sizing when chat + embed share one worker. */
+const _loadedModelBytes = new Map();
+/** Load opts per model — for accurate footprint when summing resident models. */
+const _loadedModelOpts = new Map();
+/** First embed per model may lazily allocate encoder graph — one-time heap bump. */
+const _embedGraphWarmed = new Set();
+/** Post-load measured WASM bytes per model (calibrated from linear heap delta). */
+const _measuredFootprintBytes = new Map();
+/** Linear heap bytes captured immediately before each model load. */
+const _linearAtLoadStart = new Map();
+
+function wasmLinearBytesNow() {
+  return _mod?.HEAPU8?.length ?? _mod?.wasmMemory?.buffer?.byteLength ?? 0;
+}
+
+function getModelFootprintBytes(modelId) {
+  const id = String(modelId);
+  if (_measuredFootprintBytes.has(id)) {
+    return _measuredFootprintBytes.get(id);
+  }
+  const fileBytes = _loadedModelBytes.get(id) ?? 0;
+  const opts = _loadedModelOpts.get(id) ?? {};
+  return estimateModelWasmFootprint(fileBytes, opts);
+}
+
+function calibrateModelFootprintAfterLoad(model_id) {
+  const id = String(model_id);
+  const after = wasmLinearBytesNow();
+  const before = _linearAtLoadStart.get(id) ?? 0;
+  const fileBytes = _loadedModelBytes.get(id) ?? 0;
+  const opts = _loadedModelOpts.get(id) ?? {};
+  const estimated = estimateModelWasmFootprint(fileBytes, opts);
+  const firstModel = _loadedModelBytes.size <= 1;
+  let measured = Math.max(0, after - before);
+  if (firstModel && after > 64 * 1024 * 1024) {
+    measured = after;
+  } else if (measured <= 0) {
+    measured = estimated;
+  }
+  _measuredFootprintBytes.set(id, measured);
+  _linearAtLoadStart.delete(id);
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] footprint calibrated: model=' + id +
+      ' measuredMB=' + (measured / 1048576).toFixed(1) +
+      ' estimatedMB=' + (estimated / 1048576).toFixed(1) +
+      ' heapMB=' + (after / 1048576).toFixed(1),
+    );
+  }
+  return measured;
+}
+
+function stripModelsPrefix(path) {
+  return String(path).replace(/^\/?models\//, '');
+}
+
+function enableAsyncFileEnv() {
+  if (!_mod) return;
+  _mod.ENV = _mod.ENV || {};
+  _mod.ENV['USE_ASYNC_FILE'] = '1';
+  try {
+    if (typeof _mod._cap_wasm_set_use_async_file === 'function') {
+      _mod._cap_wasm_set_use_async_file(1);
+    } else if (typeof _mod.cwrap === 'function') {
+      const setFn = _mod.cwrap('cap_wasm_set_use_async_file', null, ['number']);
+      if (typeof setFn === 'function') setFn(1);
+    }
+  } catch (_) {}
+}
+
+function disableAsyncFileEnv() {
+  if (!_mod) return;
+  if (_mod.ENV) delete _mod.ENV['USE_ASYNC_FILE'];
+  try {
+    if (typeof _mod._cap_wasm_set_use_async_file === 'function') {
+      _mod._cap_wasm_set_use_async_file(0);
+    } else if (typeof _mod.cwrap === 'function') {
+      const setFn = _mod.cwrap('cap_wasm_set_use_async_file', null, ['number']);
+      if (typeof setFn === 'function') setFn(0);
+    }
+  } catch (_) {}
+}
+
+function installAsyncFileBridge(mod) {
+  const bridge = (path, offset, req_size, out_ptr) => {
+    const name = stripModelsPrefix(path);
+    const handler = _asyncFileHandlers.get(name);
+    if (!handler) {
+      throw new Error('async file handler missing for ' + name);
+    }
+    const off = Number(offset);
+    const req = Number(req_size);
+    const raw = handler.readSync(off, req);
+    if (raw != null && typeof raw.then === 'function') {
+      throw new Error(
+        'async file readFn returned a Promise — use synchronous OPFS SyncAccessHandle reads',
+      );
+    }
+    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    getHeapU8().set(bytes.subarray(0, Math.min(bytes.byteLength, req)), Number(out_ptr));
+    return bytes.byteLength;
+  };
+  globalThis._cap_js_file_read = bridge;
+  if (mod) mod._cap_js_file_read = bridge;
+}
+
+function asyncFilePlaceholder(vfs_path, sizeBytes) {
+  patchHeapFS();
+  enableAsyncFileEnv();
+  const basename = stripModelsPrefix(vfs_path);
+  if (!_mod.FS.analyzePath(vfs_path).exists) {
+    _mod.FS.createDataFile('/models', basename, new ArrayBuffer(0), true, true, true);
+  }
+  try {
+    const node = _mod.FS.lookupPath(vfs_path).node;
+    node.usedBytes = sizeBytes;
+  } catch (_) {}
+}
+
+function asyncFileRegister(vfs_path, sizeBytes, readFn) {
+  const basename = stripModelsPrefix(vfs_path);
+  asyncFilePlaceholder(vfs_path, sizeBytes);
+  _asyncFileHandlers.set(basename, {
+    size: sizeBytes,
+    readSync: (offset, len) => readFn(Number(offset), Number(len)),
+  });
+}
+
+function asyncFileRelease(vfs_path) {
+  const basename = stripModelsPrefix(vfs_path);
+  _asyncFileHandlers.delete(basename);
+  try { _mod.FS.unlink(vfs_path); } catch (_) {}
+}
+
+/**
+ * Bind a JS-side reader for an async VFS path (no WASM heap copy of the full GGUF).
+ * readFn(offset, length) must return Uint8Array (may be shorter at EOF).
+ */
+export function async_model_bind(vfs_path, size_bytes, readFn) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const entry = _jsVfsStreams.get(vfs_path);
+  if (entry?.mode === 'heapfs') {
+    if (!(size_bytes > 0)) {
+      throw new Error('async_model_bind(heapfs): size_bytes must be positive');
+    }
+    const CHUNK = 1024 * 1024;
+    for (let off = 0; off < size_bytes; off += CHUNK) {
+      const raw = readFn(off, Math.min(CHUNK, size_bytes - off));
+      if (raw != null && typeof raw.then === 'function') {
+        throw new Error('async_model_bind readFn must be synchronous (use OPFS SyncAccessHandle)');
+      }
+      const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+      heapfsWrite(entry.heapId, bytes, off);
+    }
+    entry.bound = true;
+    if (typeof console !== 'undefined') {
+      console.error(
+        '[llama-wasm] heapfs_model_bind: copied modelMB=' + (size_bytes / 1048576).toFixed(1) +
+        ' wasmMB=' + wasmLinearMb() + ' (use_mmap=true zero-copy tensors)',
+      );
+    }
+    return;
+  }
+  if (!can_use_async_file()) {
+    throw new Error(
+      'async_model_bind requires cap_wasm async file bridge — rebuild with npm run build:wasm',
+    );
+  }
+  asyncFileRegister(vfs_path, size_bytes, readFn);
+  try {
+    const probe = readFn(0, 4);
+    if (probe != null && typeof probe.then === 'function') {
+      throw new Error('async_model_bind readFn must be synchronous (use OPFS SyncAccessHandle)');
+    }
+    const b = probe instanceof Uint8Array ? probe : new Uint8Array(probe);
+    const magic = b.byteLength >= 4
+      ? String.fromCharCode(b[0], b[1], b[2], b[3])
+      : '';
+    if (magic !== 'GGUF' && typeof console !== 'undefined') {
+      console.error(
+        '[llama-wasm] async_model_bind: GGUF magic mismatch at offset 0 for ' +
+        vfs_path + ': ' + JSON.stringify(magic) + ' (check OPFS reader)',
+      );
+    }
+  } catch (err) {
+    if (typeof console !== 'undefined') {
+      console.error('[llama-wasm] async_model_bind: probe read failed for ' + vfs_path, err);
+    }
+    throw err;
+  }
+}
+
+// ── VFS streaming API (wllama HeapFS pattern) ─────────────────────────────────
+// Ref: ref-code/wllama/src/workers-code/llama-cpp.js
+// - mmapAlloc places GGUF bytes in WASM linear memory (not JS heap MEMFS)
+// - patchHeapFS redirects MEMFS mmap/read to those bytes (zero-copy for llama)
+// - Targeted mem.grow() before model init: 20 MB at boot, then model size + headroom (BGE and LFM same policy)
+
+let _heapfsPatched = false;
+const _heapfsNameToFile = {};
+const _heapfsIdToFile = {};
+let _heapfsFileId = 0;
+
+/** Fresh HEAP view after mmapAlloc growth (wllama getHeapU8). */
+function getHeapU8() {
+  const buf = _mod.wasmMemory?.buffer ?? _mod.HEAPU8?.buffer;
+  if (!buf) throw new Error('WASM heap not ready');
+  return new Uint8Array(buf);
+}
+
+function supportsHeapFS() {
+  return typeof _mod?.mmapAlloc === 'function' && _mod?.MEMFS && _mod?.FS;
+}
+
+function patchHeapFS() {
+  if (_heapfsPatched || !supportsHeapFS()) return;
+  _heapfsPatched = true;
+  const m = _mod;
+  const ops = m.MEMFS.stream_ops;
+  ops._read = ops._read ?? ops.read;
+  ops._write = ops._write ?? ops.write;
+  ops._llseek = ops._llseek ?? ops.llseek;
+  ops._allocate = ops._allocate ?? ops.allocate;
+  ops._mmap = ops._mmap ?? ops.mmap;
+  ops._msync = ops._msync ?? ops.msync;
+
+  const patchStream = (stream) => {
+    const name = stream.node.name;
+    const f = _heapfsNameToFile[name];
+    if (!f) return;
+    const ptr = Number(f.ptr);
+    stream.node.contents = getHeapU8().subarray(ptr, ptr + f.size);
+    stream.node.usedBytes = f.size;
+  };
+
+  ops.read = function (stream, buffer, offset, length, position) {
+    patchStream(stream);
+    return ops._read(stream, buffer, offset, length, position);
+  };
+  m.MEMFS.ops_table.file.stream.read = ops.read;
+
+  ops.llseek = function (stream, off, whence) {
+    patchStream(stream);
+    return ops._llseek(stream, off, whence);
+  };
+  m.MEMFS.ops_table.file.stream.llseek = ops.llseek;
+
+  ops.mmap = function (stream, length, position, prot, flags) {
+    patchStream(stream);
+    const name = stream.node.name;
+    const f = _heapfsNameToFile[name];
+    if (f) {
+      return { ptr: Number(f.ptr) + Number(position), allocated: false };
+    }
+    return ops._mmap(stream, length, position, prot, flags);
+  };
+  m.MEMFS.ops_table.file.stream.mmap = ops.mmap;
+
+  try {
+    if (!m.FS.analyzePath('/models').exists) {
+      if (m.FS.createPath) {
+        m.FS.createPath('/', 'models', true, true);
+      } else {
+        m.FS.mkdir('/models');
+      }
+    }
+    m.FS.mount(m.MEMFS, { root: '.' }, '/models');
+  } catch (_) {}
+}
+
+function heapfsAlloc(name, size) {
+  const ptr = _mod.mmapAlloc(size);
+  const file = { ptr: Number(ptr), size, id: _heapfsFileId++ };
+  _heapfsIdToFile[file.id] = file;
+  _heapfsNameToFile[name] = file;
+  return file.id;
+}
+
+function heapfsWrite(id, buffer, offset) {
+  const f = _heapfsIdToFile[id];
+  if (!f) throw new Error('HeapFS file id ' + id + ' not found');
+  const after = offset + buffer.byteLength;
+  if (after > f.size) {
+    throw new Error('HeapFS write out of bounds: ' + after + ' > ' + f.size);
+  }
+  getHeapU8().set(buffer, Number(f.ptr) + offset);
+  return buffer.byteLength;
+}
+
+/** Ensure MEMFS /tmp exists (legacy fallback path). */
+function ensureMemfsTmp() {
+  const fs = _mod?.FS;
+  if (!fs) {
+    throw new Error('Emscripten FS not ready — cannot create /tmp for model streaming');
+  }
+  if (!fs.analyzePath('/tmp').exists) {
+    if (typeof fs.createPath === 'function') {
+      fs.createPath('/', 'tmp', true, true);
+    } else {
+      fs.mkdir('/tmp');
+    }
+  }
+  if (!fs.analyzePath('/tmp').exists) {
+    throw new Error('Failed to create MEMFS /tmp for model VFS streaming');
+  }
+}
+
+const _jsVfsStreams = new Map();
+/** Keep HeapFS mmap alive for loaded models (wllama never unlinks until exit). */
+const _loadedHeapfsModels = new Map();
+let _jsVfsCounter = 0;
+
+function effectiveNctx(modelBytes, opts_json) {
+  let n_ctx = 1024;
+  try {
+    const opts = JSON.parse(opts_json || '{}');
+    if (typeof opts.n_ctx === 'number' && opts.n_ctx > 0) n_ctx = opts.n_ctx;
+  } catch (_) {}
+  if (modelBytes > 500 * 1024 * 1024) {
+    n_ctx = Math.min(n_ctx, 512);
+  }
+  if (modelBytes > 600 * 1024 * 1024) {
+    // Recurrent/hybrid models (e.g. LFM2) use tiny KV — keep n_ctx high enough for chat templates.
+    n_ctx = Math.min(n_ctx, 512);
+  } else if (modelBytes > 500 * 1024 * 1024) {
+    n_ctx = Math.min(n_ctx, 256);
+  }
+  return n_ctx;
+}
+
+function heapfsReleaseEntry(vfs_path, entry) {
+  if (!entry || entry.mode !== 'heapfs') return;
+  if (entry.basename) {
+    delete _heapfsNameToFile[entry.basename];
+    if (entry.heapId != null) delete _heapfsIdToFile[entry.heapId];
+  }
+  try {
+    _mod.FS.unlink(vfs_path);
+  } catch (_) {}
+}
+
+/** Re-attach MEMFS node views after wasmMemory.grow() (old TypedArrays are detached). */
+function heapfsResyncViews() {
+  if (!supportsHeapFS()) return;
+  patchHeapFS();
+  const heap = getHeapU8();
+  for (const name in _heapfsNameToFile) {
+    const f = _heapfsNameToFile[name];
+    if (!f) continue;
+    const ptr = Number(f.ptr);
+    const slice = heap.subarray(ptr, ptr + f.size);
+    try {
+      const node = _mod.FS.lookupPath('/models/' + name).node;
+      node.contents = slice;
+      node.usedBytes = f.size;
+    } catch (_) {}
+  }
+}
+
+/** Sync MEMFS node size + verify GGUF magic before C++ fopen/mmap (wllama pattern). */
+function heapfsFinalizeForLoad(vfs_path, basename, expectedBytes) {
+  const f = _heapfsNameToFile[basename];
+  if (!f) {
+    throw new Error('heapfs finalize: missing entry for ' + basename);
+  }
+  patchHeapFS();
+  const ptr = Number(f.ptr);
+  const heap = getHeapU8();
+  if (heap.byteLength < ptr + 4) {
+    throw new Error('heapfs finalize: ptr out of heap bounds ' + ptr);
+  }
+  const magic = String.fromCharCode(heap[ptr], heap[ptr + 1], heap[ptr + 2], heap[ptr + 3]);
+  if (magic !== 'GGUF') {
+    throw new Error('heapfs GGUF magic mismatch at ' + vfs_path + ': ' + JSON.stringify(magic));
+  }
+  const node = _mod.FS.lookupPath(vfs_path).node;
+  node.contents = heap.subarray(ptr, ptr + f.size);
+  node.usedBytes = f.size;
+  const st = _mod.FS.stat(vfs_path);
+  const fd = _mod.FS.open(vfs_path, 'r');
+  const endPos = _mod.FS.llseek(fd, 0, 2);
+  _mod.FS.close(fd);
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] heapfs finalize: path=' + vfs_path +
+      ' stat=' + st.size + ' llseek=' + endPos +
+      ' expected=' + expectedBytes,
+    );
+  }
+  if (endPos !== expectedBytes) {
+    throw new Error(
+      'heapfs file size mismatch at ' + vfs_path + ': llseek=' + endPos + ' expected=' + expectedBytes,
+    );
+  }
+}
+
+let _cwrapLoadContextFromPath = null;
+
+function resolveLoadContextFromPathFn() {
+  if (_cwrapLoadContextFromPath) return _cwrapLoadContextFromPath;
+  const name = 'llama_load_context_from_path';
+  const tryFns = [];
+  if (typeof _mod.cwrap === 'function') {
+    tryFns.push(() => _mod.cwrap(name, 'bigint', ['string', 'string']));
+    tryFns.push(() => _mod.cwrap(name, 'number', ['string', 'string']));
+  }
+  if (_mod.wasmExports?.[name]) {
+    tryFns.push(() => _mod.wasmExports[name]);
+  }
+  if (typeof _mod['_' + name] === 'function') {
+    tryFns.push(() => _mod['_' + name]);
+  }
+  for (const get of tryFns) {
+    try {
+      const raw = get();
+      if (typeof raw === 'function') {
+        _cwrapLoadContextFromPath = (path, opts) => wasmI64ToNumber(raw(path, opts));
+        return _cwrapLoadContextFromPath;
+      }
+    } catch (_) {}
+  }
+  throw new Error('llama_load_context_from_path not exported (cwrap/wasmExports)');
+}
+
+/** Load via C bridge (avoids bindgen throw on trap) + register context in Rust. */
+function wasmLoadContextFromPath(model_id, vfs_path, opts_json, mode) {
+  if (mode === 'async') {
+    enableAsyncFileEnv();
+  } else {
+    disableAsyncFileEnv();
+  }
+  const loadFn = resolveLoadContextFromPathFn();
+  if (typeof console !== 'undefined') {
+    console.error('[llama-wasm] cwrap load: path=' + vfs_path + ' wasmMB=' + wasmLinearMb());
+  }
+  const ctxId = loadFn(vfs_path, opts_json);
+  if (typeof console !== 'undefined') {
+    console.error('[llama-wasm] cwrap load result: ctxId=' + ctxId + ' wasmMB=' + wasmLinearMb());
+  }
+  if (ctxId <= 0) {
+    throw new Error(
+      'llama_load_context_from_path returned ' + ctxId + ' for ' + vfs_path +
+      ' wasmMB=' + wasmLinearMb() +
+      (tailWasmStderr() ? ' | llama: ' + tailWasmStderr() : ''),
+    );
+  }
+  registerModelContext(model_id, ctxId);
+  return;
+}
+
+function wasmThrowToError(err, context) {
+  const WasmException = typeof WebAssembly !== 'undefined' && WebAssembly.Exception;
+  const stderrTail = tailWasmStderr();
+  const memNote = ' wasmMB=' + wasmLinearMb();
+  if (WasmException && err instanceof WasmException) {
+    let msg = 'WebAssembly.Exception (likely OOM during model/context init — try closing other tabs)';
+    try {
+      if (err.message) msg = String(err.message);
+    } catch (_) {}
+    if (stderrTail) msg += ' | llama: ' + stderrTail;
+    return new Error(context + ': ' + msg + memNote);
+  }
+  if (err instanceof WebAssembly.RuntimeError) {
+    const msg = err.message || 'WebAssembly runtime error (likely OOM during model load)';
+    let suffix = msg;
+    if (stderrTail) suffix += ' | llama: ' + stderrTail;
+    return new Error(context + ': ' + suffix + memNote);
+  }
+  if (err instanceof Error && err.message && err.message !== 'undefined') {
+    if (stderrTail) err.message += ' | llama: ' + stderrTail;
+    err.message += memNote;
+    return err;
+  }
+  const detail =
+    typeof err === 'string' ? err :
+    err instanceof Error ? err.message :
+    err == null ? '' : String(err);
+  let suffix = detail && detail !== 'undefined' ? detail :
+    'WASM trap during inference (OOM/stack in llama_decode — close other tabs and reload model)';
+  if (stderrTail) suffix += ' | llama: ' + stderrTail;
+  return new Error(context + ': ' + suffix + memNote);
+}
+
+function vfsStatBytes(path) {
+  try {
+    const st = _mod.FS.stat(path);
+    return typeof st.size === 'number' ? st.size : 0;
+  } catch (_) {
+    return -1;
+  }
+}
+
+function wasmLinearMb() {
+  try {
+    const buf = _mod.wasmMemory?.buffer ?? _mod.HEAPU8?.buffer;
+    return buf ? +(buf.byteLength / 1024 / 1024).toFixed(1) : 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
+const WASM_INITIAL_BYTES = 20 * 1024 * 1024;
+const WASM_MAX_BYTES = 2147483648;
+/** WASM pool cap — aligned with Emscripten MAXIMUM_MEMORY (2 GiB). */
+const WASM_POOL_CEILING_BYTES = WASM_MAX_BYTES;
+const WASM_POOL_RESERVE_BYTES = 64 * 1024 * 1024;
+const WASM_MAX_CONCURRENT_MODELS = 5;
+const WASM_MIN_HEADROOM_BYTES = 128 * 1024 * 1024;
+
+function totalLoadedModelBytes() {
+  let sum = 0;
+  for (const b of _loadedModelBytes.values()) sum += b;
+  return sum;
+}
+
+function loadOptsForMemory(opts_json, mode, modelBytes) {
+  let opts = {};
+  try {
+    opts = JSON.parse(opts_json || '{}');
+  } catch (_) {}
+  const embedding = opts.embedding === true || opts.embedding === 'true';
+  const n_ctx = typeof opts.n_ctx === 'number' && opts.n_ctx > 0
+    ? opts.n_ctx
+    : embedding ? 128 : effectiveNctx(modelBytes, opts_json);
+  // BERT/encoder: llama_encode() asserts n_ubatch >= n_tokens — always match n_batch to n_ctx.
+  const n_batch = embedding
+    ? n_ctx
+    : (typeof opts.n_batch === 'number' && opts.n_batch > 0 ? opts.n_batch : 16);
+  return {
+    mode,
+    n_ctx,
+    n_batch,
+    embedding,
+  };
+}
+
+/** Estimate WASM bytes for one model (weights + COPY path + KV/context headroom). */
+function estimateModelWasmFootprint(fileBytes, memOpts = {}, mode) {
+  if (!(fileBytes > 0)) return 20 * 1024 * 1024;
+  const embedding = memOpts.embedding === true;
+  const heapfsMmap = mode === 'heapfs' && embedding;
+  const heapfsCopy = (mode === 'heapfs' && !embedding) || (mode !== 'async' && embedding && mode !== 'heapfs');
+  const n_ctx = typeof memOpts.n_ctx === 'number' && memOpts.n_ctx > 0
+    ? memOpts.n_ctx
+    : embedding ? 128 : 512;
+  const n_batch = typeof memOpts.n_batch === 'number' && memOpts.n_batch > 0
+    ? memOpts.n_batch
+    : embedding ? n_ctx : 16;
+  // Async OPFS (use_mmap=false) and HeapFS COPY duplicate weights during tensor init (~2× file size).
+  const weightMultiplier = embedding
+    ? (heapfsMmap ? 1.15 : heapfsCopy ? 2.2 : 2.0)
+    : fileBytes > 200 * 1024 * 1024 ? 1.32 : 1.2;
+  // Encoder-only (BERT): n_ubatch = min(n_batch, …) and must cover the full prompt.
+  const effectiveBatch = embedding ? Math.max(n_batch, n_ctx) : n_batch;
+  const ctxBytes = n_ctx * effectiveBatch * 4096;
+  const graphReserve = embedding
+    ? (heapfsMmap ? 64 * 1024 * 1024 : heapfsCopy ? 48 * 1024 * 1024 : (mode === 'async' ? 96 * 1024 * 1024 : 32 * 1024 * 1024))
+    : 0;
+  const proportional = Math.ceil(fileBytes * (embedding ? 0.25 : 0.12));
+  const minHeadroom = embedding ? 72 * 1024 * 1024 : WASM_MIN_HEADROOM_BYTES;
+  const headroom = Math.max(minHeadroom, proportional, ctxBytes) + graphReserve;
+  return Math.ceil(fileBytes * weightMultiplier + headroom);
+}
+
+function loadedModelsFootprintBytes(excludeModelId) {
+  let sum = 0;
+  for (const [id] of _loadedModelBytes) {
+    if (excludeModelId != null && String(id) === String(excludeModelId)) continue;
+    sum += getModelFootprintBytes(id);
+  }
+  return sum;
+}
+
+function isModelResidentInWasm(model_id) {
+  const id = String(model_id);
+  return _loadedModelBytes.has(id) || _modelContextIds.has(id);
+}
+
+/** Projected pool usage after loading one more model (footprint-based — no double-count). */
+function projectedWasmAfterLoad(model_id, fileBytes, memOpts) {
+  const id = String(model_id);
+  const linear = _mod?.HEAPU8?.length ?? _mod?.wasmMemory?.buffer?.byteLength ?? 0;
+  if (isModelResidentInWasm(id)) {
+    return linear;
+  }
+  const estimated = estimateModelWasmFootprint(fileBytes, memOpts);
+  const residentCount = _loadedModelBytes.size;
+  const residentFootprint = loadedModelsFootprintBytes(id);
+  // Prefer calibrated footprints over linear heap size. Linear may already include
+  // unused pre-grown headroom (or a prior failed grow to MAXIMUM_MEMORY), so
+  // linear+estimated falsely rejects BGE+LFM2 co-residence inside 2 GiB.
+  if (residentCount > 0) {
+    return residentFootprint + estimated;
+  }
+  if (linear > 64 * 1024 * 1024) {
+    return estimated;
+  }
+  return Math.max(linear, estimated);
+}
+
+/** Reject load before grow when pool ceiling or slot limit would be exceeded. */
+function checkWasmLoadAdmission(model_id, fileBytes, opts_json, mode) {
+  const id = String(model_id);
+  if (isModelResidentInWasm(id)) {
+    return;
+  }
+
+  if (_loadedModelBytes.size >= WASM_MAX_CONCURRENT_MODELS) {
+    throw new Error(
+      '[llama-wasm] model slot limit reached (' + WASM_MAX_CONCURRENT_MODELS +
+      ' concurrent contexts) — unload a model first',
+    );
+  }
+  const memOpts = loadOptsForMemory(opts_json, mode, fileBytes);
+  const estimated = estimateModelWasmFootprint(fileBytes, memOpts);
+  const projected = projectedWasmAfterLoad(id, fileBytes, memOpts);
+  const linear = _mod?.HEAPU8?.length ?? _mod?.wasmMemory?.buffer?.byteLength ?? 0;
+  const admitLimit = WASM_MAX_BYTES - WASM_POOL_RESERVE_BYTES;
+  if (projected > admitLimit) {
+    const ggufMb = (fileBytes / 1048576).toFixed(0);
+    const linearMb = (linear / 1048576).toFixed(0);
+    throw new Error(
+      '[llama-wasm] WASM pool would exceed ' + (WASM_MAX_BYTES / 1048576).toFixed(0) +
+      ' MB (projected ' + (projected / 1048576).toFixed(0) +
+      ' MB, heap now ' + linearMb + ' MB, GGUF ' + ggufMb + ' MB → est. +~' +
+      (estimated / 1048576).toFixed(0) + ' MB for ' + id + ')',
+    );
+  }
+}
+
+/** Same growth policy for BGE and LFM: 20 MB at init, then model size + headroom (max 2 GB). */
+function wasmMemoryTarget(modelBytes, memOpts = {}) {
+  if (!(modelBytes > 0)) return WASM_INITIAL_BYTES;
+  const n_ctx = memOpts.n_ctx ?? 512;
+  const n_batch = memOpts.n_batch ?? 16;
+  const ctxBytes = n_ctx * n_batch * 4096;
+  const proportional = Math.ceil(modelBytes * 0.35);
+  const headroom = Math.max(WASM_MIN_HEADROOM_BYTES, proportional, ctxBytes);
+  const target = modelBytes + headroom;
+  return Math.min(Math.max(WASM_INITIAL_BYTES, target), WASM_MAX_BYTES);
+}
+
+/** Reserve headroom for vocab, BPE ranks, and KV cache before model init. */
+function ensureWasmMemoryHeadroom(modelBytes, opts_json, mode, model_id) {
+  if (!_mod || !(modelBytes > 0)) return;
+  if (model_id != null && isModelResidentInWasm(model_id)) return;
+
+  const current = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  const memOpts = loadOptsForMemory(opts_json, mode, modelBytes);
+  const modelsBytes = totalLoadedModelBytes() + modelBytes;
+  const estimate = estimateModelWasmFootprint(modelBytes, memOpts, mode);
+  const warmHeap = current > 64 * 1024 * 1024;
+  let target;
+  if (memOpts.embedding) {
+    // Embed graph + sched reserve — budget extra headroom; heapfs mmap still needs graph slack.
+    const graphSlack = mode === 'heapfs'
+      ? 128 * 1024 * 1024
+      : mode === 'async'
+        ? 128 * 1024 * 1024
+        : 48 * 1024 * 1024;
+    const embedFloor = mode === 'heapfs' ? 256 * 1024 * 1024 : 224 * 1024 * 1024;
+    target = Math.min(Math.max(current, estimate + graphSlack, embedFloor), WASM_MAX_BYTES);
+  } else if (warmHeap || _loadedModelBytes.size > 0) {
+    if (_loadedModelBytes.size > 0) {
+      // Second+ resident model — incremental footprint plus COPY tensor headroom (use_mmap=0).
+      const memOpts = loadOptsForMemory(opts_json, mode, modelBytes);
+      const embedCopy = memOpts.embedding
+        ? Math.max(96 * 1024 * 1024, Math.ceil(modelBytes * 3))
+        : Math.max(32 * 1024 * 1024, Math.ceil(modelBytes * 1.5));
+      const copyHeadroom = embedCopy;
+      target = Math.min(current + estimate + copyHeadroom, WASM_MAX_BYTES);
+    } else {
+      // Async stream begin may have pre-grown; do not add estimate again.
+      target = Math.min(Math.max(current, estimate), WASM_MAX_BYTES);
+    }
+  } else {
+    target = wasmMemoryTarget(modelsBytes, memOpts);
+  }
+  if (target > WASM_MAX_BYTES) {
+    throw new Error(
+      '[llama-wasm] WASM grow target exceeds Emscripten max ' + (WASM_MAX_BYTES / 1048576).toFixed(0) +
+      ' MB (requested ' + (target / 1048576).toFixed(0) + ' MB, heap now ' +
+      (current / 1048576).toFixed(0) + ' MB)',
+    );
+  }
+  if (current >= target) return;
+
+  let grown = false;
+  if (typeof _mod.growMemory === 'function') {
+    grown = _mod.growMemory(target) === 1;
+  } else if (typeof _mod.emscripten_resize_heap === 'function') {
+    grown = !!_mod.emscripten_resize_heap(target);
+  }
+  if (!grown) {
+    throw new Error('[llama-wasm] failed to grow wasm memory to ' + target + ' bytes (have ' + current + ')');
+  }
+  heapfsResyncViews();
+  const after = _mod.HEAPU8?.length ?? _mod.wasmMemory?.buffer?.byteLength ?? 0;
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] memory grow: ' + (current / 1048576).toFixed(0) + 'MB -> ' +
+      (after / 1048576).toFixed(0) + 'MB (models=' + (modelsBytes / 1048576).toFixed(0) +
+      'MB target=' + (target / 1048576).toFixed(0) + 'MB mode=' + (mode || 'async') + ')',
+    );
+  }
+}
+
+/** Begin HeapFS stream — mmapAlloc grows Emscripten memory (wllama fs.alloc). */
+function heapfsStreamBegin(totalBytes, opts_json) {
+  patchHeapFS();
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] HeapFS begin: modelMB=' + (totalBytes / 1048576).toFixed(1) +
+      ' wasmMB=' + wasmLinearMb() + ' (mmapAlloc will grow as needed)',
+    );
+  }
+  const basename = 'wasm_stream_' + (_jsVfsCounter++) + '.gguf';
+  _mod.FS.createDataFile('/models', basename, new ArrayBuffer(0), true, true, true);
+  const heapId = heapfsAlloc(basename, totalBytes);
+  const path = '/models/' + basename;
+  _jsVfsStreams.set(path, { mode: 'heapfs', heapId, basename, offset: 0, size: totalBytes });
+  return path;
+}
+
+/** Begin streaming a model into WASM VFS. Pass total_bytes + opts_json for HeapFS pre-grow. */
+function asyncFileStreamBegin(totalBytes, opts_json) {
+  patchHeapFS();
+  enableAsyncFileEnv();
+  // Cold load only: pre-grow here. When another model is resident, admission + grow
+  // run in load_model_from_vfs (after checkWasmLoadAdmission) so we do not inflate
+  // linear to MAXIMUM_MEMORY and then reject with linear+estimated.
+  if (typeof totalBytes === 'number' && totalBytes > 0 && _loadedModelBytes.size === 0) {
+    const loadOpts = vfsLoadOptsJson(opts_json ?? '{}', 'async', totalBytes);
+    ensureWasmMemoryHeadroom(totalBytes, loadOpts, 'async');
+  }
+  const basename = 'wasm_async_' + (_jsVfsCounter++) + '.gguf';
+  const path = '/models/' + basename;
+  asyncFilePlaceholder(path, totalBytes);
+  _jsVfsStreams.set(path, { mode: 'async', basename, size: totalBytes, bound: false });
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] JSPI async begin: modelMB=' + (totalBytes / 1048576).toFixed(1) +
+      ' wasmMB=' + wasmLinearMb() + ' (no full-model heap copy)',
+    );
+  }
+  return path;
+}
+
+function vfsOptsEmbedding(opts_json) {
+  try {
+    const o = JSON.parse(opts_json || '{}');
+    return o.embedding === true || o.embedding === 'true';
+  } catch (_) {
+    return false;
+  }
+}
+
+/** Small embed (≤32MB): HeapFS + use_mmap zero-copy; larger embed falls back to async OPFS fread. */
+const EMBED_HEAPFS_MAX_BYTES = 32 * 1024 * 1024;
+
+function preferHeapFsVfs(totalBytes, opts_json) {
+  if (!supportsHeapFS() || !(totalBytes > 0)) return false;
+  if (vfsOptsEmbedding(opts_json)) {
+    if (totalBytes <= EMBED_HEAPFS_MAX_BYTES) return true;
+    if (can_use_async_file()) return false;
+    return true;
+  }
+  if (totalBytes < 100 * 1024 * 1024) return true;
+  return false;
+}
+
+function jsModelVfsBegin(totalBytes, opts_json) {
+  if (preferHeapFsVfs(totalBytes, opts_json)) {
+    return heapfsStreamBegin(totalBytes, opts_json);
+  }
+  if (can_use_async_file() && typeof totalBytes === 'number' && totalBytes > 0) {
+    return asyncFileStreamBegin(totalBytes, opts_json);
+  }
+  if (typeof totalBytes === 'number' && totalBytes > 0 && supportsHeapFS()) {
+    return heapfsStreamBegin(totalBytes, opts_json);
+  }
+  ensureMemfsTmp();
+  const path = '/tmp/wasm_stream_' + (_jsVfsCounter++) + '.gguf';
+  const stream = _mod.FS.open(path, 'w');
+  _jsVfsStreams.set(path, { mode: 'memfs', stream, offset: 0 });
+  return path;
+}
+
+function jsModelVfsWrite(path, chunk) {
+  const entry = _jsVfsStreams.get(path);
+  if (!entry) {
+    throw new Error('model_vfs_write: no open stream for ' + path);
+  }
+  if (!chunk || chunk.byteLength === 0) return;
+  const buf = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+  if (entry.mode === 'async') {
+    throw new Error(
+      'model_vfs_write on async path: use async_model_bind() instead of streaming into WASM heap',
+    );
+  }
+  try {
+    if (entry.mode === 'heapfs') {
+      heapfsWrite(entry.heapId, buf, entry.offset);
+    } else {
+      _mod.FS.write(entry.stream, buf, 0, buf.byteLength, entry.offset);
+    }
+    entry.offset += buf.byteLength;
+  } catch (err) {
+    throw wasmThrowToError(err, 'VFS write failed at offset ' + entry.offset + ' for ' + path);
+  }
+}
+
+function jsModelVfsClose(path) {
+  const entry = _jsVfsStreams.get(path);
+  if (!entry) return;
+  if (entry.mode === 'memfs' && entry.stream) {
+    _mod.FS.close(entry.stream);
+  }
+}
+
+function jsModelVfsAbort(path) {
+  const entry = _jsVfsStreams.get(path);
+  jsModelVfsClose(path);
+  _jsVfsStreams.delete(path);
+  if (entry?.mode === 'heapfs' && entry.basename) {
+    delete _heapfsNameToFile[entry.basename];
+    if (entry.heapId != null) delete _heapfsIdToFile[entry.heapId];
+  } else if (entry?.mode === 'async') {
+    asyncFileRelease(path);
+  }
+  try {
+    _mod.FS.unlink(path);
+  } catch (_) {}
+}
+
+function vfsLoadOptsJson(opts_json, mode, modelBytes) {
+  let opts = {};
+  try {
+    opts = JSON.parse(opts_json || '{}');
+  } catch (_) {}
+  opts.n_threads = 1;
+  const embedding = opts.embedding === true || opts.embedding === 'true';
+  if (embedding) {
+    if (opts.n_ctx == null || opts.n_ctx > 128) {
+      opts.n_ctx = 128;
+    }
+    // BERT encode: n_ubatch must be >= token count; match n_batch to n_ctx.
+    const encBatch = opts.n_ctx;
+    if (opts.n_batch == null || opts.n_batch < encBatch) {
+      opts.n_batch = encBatch;
+    } else if (opts.n_batch > encBatch) {
+      opts.n_batch = encBatch;
+    }
+  } else if (modelBytes < 100 * 1024 * 1024) {
+    if (opts.n_ctx == null || opts.n_ctx > 256) {
+      opts.n_ctx = 256;
+    }
+    if (opts.n_batch == null || opts.n_batch > 32) {
+      opts.n_batch = 32;
+    }
+  }
+  if (mode === 'heapfs') {
+    // Small embed: GGUF lives in mmapAlloc heap — buffer_from_host_ptr avoids a second COPY.
+    opts.use_mmap = embedding;
+    if (!embedding) {
+      opts.n_ctx = effectiveNctx(modelBytes, opts_json);
+      if (opts.n_batch == null || opts.n_batch > 128) {
+        opts.n_batch = 128;
+      }
+    }
+    if (modelBytes > 600 * 1024 * 1024 && (opts.n_batch == null || opts.n_batch > 64)) {
+      opts.n_batch = 64;
+    }
+  } else if (mode === 'async') {
+    opts.use_mmap = false;
+    if (!embedding) {
+      opts.n_ctx = effectiveNctx(modelBytes, opts_json);
+    }
+    if (modelBytes > 600 * 1024 * 1024) {
+      // 65536 vocab × n_batch logits buffer — keep small at 2GB heap after full weight copy.
+      if (opts.n_batch == null || opts.n_batch > 16) {
+        opts.n_batch = 16;
+      }
+    } else if (!embedding && (opts.n_batch == null || opts.n_batch > 128)) {
+      opts.n_batch = 128;
+    }
+    if (!embedding && modelBytes > 500 * 1024 * 1024 && modelBytes <= 600 * 1024 * 1024 &&
+        (opts.n_batch == null || opts.n_batch > 64)) {
+      opts.n_batch = 64;
+    }
+  } else if (opts.use_mmap == null) {
+    opts.use_mmap = false;
+  }
+  return JSON.stringify(opts);
+}
+
+/** Begin streaming a model into WASM VFS. Pass total_bytes + opts_json for HeapFS pre-grow. */
+export function model_vfs_begin(total_bytes, opts_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  return jsModelVfsBegin(total_bytes, opts_json);
+}
+
+/** Append a chunk to an in-progress VFS model write. */
+export function model_vfs_write(vfs_path, chunk) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  jsModelVfsWrite(vfs_path, chunk);
+}
+
+/** Abort a partial VFS write and remove the temp file. */
+export function model_vfs_abort(vfs_path) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  jsModelVfsAbort(vfs_path);
+}
+
+/** Finish a streamed VFS write and load the model. HeapFS mmap stays alive until unload. */
+export function load_model_from_vfs(model_id, vfs_path, opts_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  const entry = _jsVfsStreams.get(vfs_path);
+  const mode = entry?.mode ?? 'memfs';
+  jsModelVfsClose(vfs_path);
+  const bytes = mode === 'heapfs' || mode === 'async'
+    ? (entry?.size ?? 0)
+    : vfsStatBytes(vfs_path);
+  if (bytes <= 0) {
+    throw new Error('VFS model file missing or empty after stream: ' + vfs_path + ' (bytes=' + bytes + ')');
+  }
+  if (mode === 'async') {
+    const basename = entry?.basename ?? stripModelsPrefix(vfs_path);
+    if (!_asyncFileHandlers.has(basename)) {
+      throw new Error(
+        'async VFS path not bound — call async_model_bind() before load_model_from_vfs: ' + vfs_path,
+      );
+    }
+  }
+  const loadOpts = vfsLoadOptsJson(opts_json, mode, bytes);
+  if (typeof console !== 'undefined') {
+    console.error(
+      '[llama-wasm] load_model_from_vfs: mode=' + mode +
+      ' wasmMB=' + wasmLinearMb() + ' opts=' + loadOpts,
+    );
+  }
+  _jsVfsStreams.delete(vfs_path);
+  if (isModelResidentInWasm(model_id)) {
+    if (typeof console !== 'undefined') {
+      console.error(
+        '[llama-wasm] load_model_from_vfs: skip — already loaded model_id=' + model_id +
+        ' wasmMB=' + wasmLinearMb(),
+      );
+    }
+    return;
+  }
+  try {
+    checkWasmLoadAdmission(model_id, bytes, loadOpts, mode);
+    if (mode === 'heapfs') {
+      ensureWasmMemoryHeadroom(bytes, loadOpts, 'heapfs', model_id);
+      heapfsFinalizeForLoad(vfs_path, entry.basename, bytes);
+    } else if (mode === 'async') {
+      enableAsyncFileEnv();
+      // asyncFileStreamBegin grows for cold load; re-run when another model is already resident.
+      if (_loadedModelBytes.size > 0) {
+        ensureWasmMemoryHeadroom(bytes, loadOpts, 'async', model_id);
+      }
+    } else {
+      ensureWasmMemoryHeadroom(bytes, loadOpts, 'memfs', model_id);
+    }
+    _linearAtLoadStart.set(String(model_id), wasmLinearBytesNow());
+    // COPY tensor path + llm_graph_result reserve can exceed pre-stream grow — top up before cwrap.
+    const embedLoad = vfsOptsEmbedding(loadOpts);
+    if (mode === 'heapfs' || mode === 'memfs' || (mode === 'async' && embedLoad)) {
+      ensureWasmMemoryHeadroom(bytes, loadOpts, mode, model_id);
+    }
+    // P2 diagnostics: Log memory state before and after load
+    if (embedLoad && (mode === 'async' || mode === 'heapfs')) {
+      console.error('[llama-wasm] P2-diag: pre-tensor wasmMB=' + wasmLinearMb() + ' model=' + model_id + ' mode=' + mode);
+    }
+
+    wasmLoadContextFromPath(model_id, vfs_path, loadOpts, mode);
+
+    if (embedLoad && (mode === 'async' || mode === 'heapfs')) {
+      console.error('[llama-wasm] P2-diag: post-load wasmMB=' + wasmLinearMb() + ' model=' + model_id + ' mode=' + mode);
+    }
+    
+    _loadedModelBytes.set(String(model_id), bytes);
+    try {
+      _loadedModelOpts.set(String(model_id), JSON.parse(loadOpts || '{}'));
+    } catch (_) {
+      _loadedModelOpts.set(String(model_id), {});
+    }
+    calibrateModelFootprintAfterLoad(model_id);
+    if (mode === 'heapfs' && entry?.basename) {
+      _loadedHeapfsModels.set(model_id, {
+        path: vfs_path,
+        basename: entry.basename,
+        heapId: entry.heapId,
+      });
+    } else if (mode === 'async') {
+      _loadedAsyncModels.set(model_id, vfs_path);
+    }
+  } catch (err) {
+    // P2: Capture comprehensive diagnostics on error
+    const wasmMbAfterFail = wasmLinearMb();
+    const stderrTail = tailWasmStderr(1200); // capture last 1200 chars of stderr
+    const errorMsg = '[llama-wasm] load_model_from_vfs FAILED: model=' + model_id +
+      ' mode=' + mode + ' wasmMbAfterFail=' + wasmMbAfterFail +
+      ' err=' + (err instanceof Error ? err.message : String(err));
+    
+    if (typeof console !== 'undefined') {
+      console.error(errorMsg);
+      if (stderrTail) {
+        console.error('[llama-wasm] stderr tail (last 1200 chars):\n' + stderrTail);
+      }
+    }
+    
+    if (mode === 'heapfs') {
+      heapfsReleaseEntry(vfs_path, entry);
+    } else if (mode === 'async') {
+      asyncFileRelease(vfs_path);
+    } else {
+      try {
+        _mod.FS.unlink(vfs_path);
+      } catch (_) {}
+    }
+    throw wasmThrowToError(
+      err,
+      'load_model_from_vfs failed for ' + vfs_path + ' (' + bytes + ' bytes, mode=' + mode + ', wasmMb=' + wasmLinearMb() + ')',
+    );
+  }
+}
+
+/** Load from an existing VFS path (HeapFS — zero-copy mmap). */
+export function load_model_from_path(model_id, vfs_path, opts_json) {
+  if (!_mod) throw new Error('llama_engine not ready — await init() first');
+  wasmBindgenLoadModelFromPath(model_id, vfs_path, opts_json);
+}