jev-web 0.8.0 → 0.9.1

package/src/vega.mjs

@@ -24,9 +24,17 @@
  *     vega_config.json; split-conformal prediction sets and an abstain flag
  *     come from the same energies, plus an "unbound particle" OOD signal.
  *
- * Two ONNX graphs (one fused torso -> pooled features, one engine -> logits +
- * physics), mirroring the reference runtime exactly; JS owns the protocol, the
- * packing, the thermal calibration and the answer decoding.
+ * Two ONNX graph layouts ship:
+ *
+ *   fused (warsang/vega-08b-web, the default) — one fused torso that pools
+ *     in-graph + the fp32 engine, 1.5 GB fp16 torso, base engine only;
+ *   split (nvkudva/vega-onnx-q8) — an 8-bit embed graph, a cut decoder that
+ *     emits the residual stream at layers 13/19 (the LM head and layers 20-23
+ *     never run), the fp32 engine with both gated task adapters, and JS
+ *     pooling; 840 MB, wasm-only (8-bit MatMulNBits has no WebGPU kernel).
+ *
+ * JS owns the protocol, the packing, the thermal calibration and the answer
+ * decoding in both.
  */
 import { normalizeQuestions } from "./questions.mjs";
 import { softmaxWithTemperature } from "./answers.mjs";
@@ -40,6 +48,37 @@ export const VEGA_DEFAULT_REVISION = "d2bd4604ed770ca614745f07f623b66e89f406e4";
 export const VEGA_TORSO_FILE = "onnx/torso_fp16.onnx";
 export const VEGA_ENGINE_FILE = "onnx/engine.onnx";
 
+// ---------------------------------------------------------------------------
+// Split export: nvkudva/vega-onnx-q8 (8-bit embed + cut decoder + fp32 engine)
+// ---------------------------------------------------------------------------
+export const VEGA_Q8_DEFAULT_MODEL = "nvkudva/vega-onnx-q8";
+export const VEGA_Q8_DEFAULT_REVISION = "017c096d369ac698087f8c35a6ad8c867a7fe0f4";
+export const VEGA_Q8_DEFAULT_SUBFOLDER = "v2";
+export const VEGA_Q8_EMBED_FILE = "embed_q8.onnx";
+export const VEGA_Q8_DECODER_FILE = "decoder_q8.onnx";
+export const VEGA_Q8_ENGINE_FILE = "engine.onnx";
+
+/**
+ * Named exports. `fp16` is this repo's own fused export (default); `q8` is
+ * nvkudva's split 8-bit export of the same checkpoint, which adds the two
+ * gated task adapters (public_intents / typed_decisions) and is wasm-only.
+ */
+export const VEGA_VARIANTS = {
+  fp16: {
+    model: VEGA_DEFAULT_MODEL,
+    revision: VEGA_DEFAULT_REVISION,
+    format: "fused",
+    description: "fused fp16 torso + fp32 engine, 1.7 GB (the default)",
+  },
+  q8: {
+    model: VEGA_Q8_DEFAULT_MODEL,
+    revision: VEGA_Q8_DEFAULT_REVISION,
+    subfolder: VEGA_Q8_DEFAULT_SUBFOLDER,
+    format: "split",
+    description: "8-bit split embed + cut decoder + fp32 engine with adapters, 840 MB, wasm-only",
+  },
+};
+
 /** Reference prompt template 0 (the inference surface form). */
 const VEGA_HEAD = "Observation:\n";
 const VEGA_QUESTION = "\n\nMeasurement ({t}): {ins}\nPossible outcomes:";
@@ -75,7 +114,10 @@ export const VEGA_DEFAULTS = {
  * Vega's `boolean` is the noul primitive; its slots are fixed [no, yes].
  */
 export function vegaQuestionDef(question) {
-  const ins = renderVegaText(question.instructions);
+  // the reference json.dumps non-string instructions with ensure_ascii=True
+  const ins = typeof question.instructions === "string"
+    ? question.instructions
+    : vegaJsonDumps(question.instructions, true);
   if (question.type === "noul") {
     return { t: "boolean", ins, crit: { ...(question.criteria ?? {}) } };
   }
@@ -90,28 +132,70 @@ export function vegaQuestionDef(question) {
   return { t: "choice", ins, crit };
 }
 
-function flatText(v) {
-  return v === null || v === undefined ? "" : String(v);
+/**
+ * Python `json.dumps(x, ensure_ascii)` — ", " / ": " separators, control
+ * characters escaped, and optionally \uXXXX for everything above ASCII. The
+ * reference runtime serializes dict states, non-string instructions and
+ * non-string criteria values with it, so the prompt stays byte-identical to
+ * the Python original (JSON.stringify uses compact separators and never
+ * escapes non-ASCII).
+ */
+export function vegaJsonDumps(value, ensureAscii = false) {
+  const esc = (s) => {
+    let out = '"';
+    for (const ch of s) {
+      const c = ch.codePointAt(0);
+      if (ch === '"') out += '\\"';
+      else if (ch === "\\") out += "\\\\";
+      else if (ch === "\n") out += "\\n";
+      else if (ch === "\r") out += "\\r";
+      else if (ch === "\t") out += "\\t";
+      else if (c < 0x20) out += "\\u" + c.toString(16).padStart(4, "0");
+      else if (ensureAscii && c > 0x7f) {
+        if (c > 0xffff) {
+          const u = c - 0x10000;
+          out += "\\u" + (0xd800 + (u >> 10)).toString(16).padStart(4, "0");
+          out += "\\u" + (0xdc00 + (u & 0x3ff)).toString(16).padStart(4, "0");
+        } else out += "\\u" + c.toString(16).padStart(4, "0");
+      } else out += ch;
+    }
+    return out + '"';
+  };
+  const go = (x) => {
+    if (x === null || x === undefined) return "null";
+    if (typeof x === "string") return esc(x);
+    if (typeof x === "boolean") return x ? "true" : "false";
+    if (typeof x === "number") return String(x);
+    if (Array.isArray(x)) return "[" + x.map(go).join(", ") + "]";
+    return "{" + Object.entries(x).map(([k, v]) => esc(k) + ": " + go(v)).join(", ") + "}";
+  };
+  return go(value);
+}
+
+/** json.dumps of a non-string criterion value (strings pass through). */
+function vegaCritText(v) {
+  return typeof v === "string" ? v : vegaJsonDumps(v, false);
 }
 
+/** The reference render_text: strings verbatim, anything else json.dumps. */
 export function renderVegaText(content) {
-  return typeof content === "string" ? content : JSON.stringify(content);
+  return typeof content === "string" ? content : vegaJsonDumps(content, false);
 }
 
 /** Option texts in label-index order, exactly as option_texts() renders them. */
 export function vegaOptionTexts(qdef) {
   if (qdef.t === "choice") {
     return Object.entries(qdef.crit).map(([k, v]) => {
-      const d = v === null || v === undefined ? "" : flatText(v);
+      const d = v === null || v === undefined ? "" : vegaCritText(v);
       return d ? `${k} - ${d}` : String(k);
     });
   }
   if (qdef.t === "score") {
-    return qdef.crit.map((c, i) => `level ${i} - ${flatText(c)}`);
+    return qdef.crit.map((c, i) => `level ${i} - ${vegaCritText(c)}`);
   }
   const crit = qdef.crit ?? {};
-  const no = crit.false === null || crit.false === undefined ? "" : flatText(crit.false);
-  const yes = crit.true === null || crit.true === undefined ? "" : flatText(crit.true);
+  const no = crit.false === null || crit.false === undefined ? "" : vegaCritText(crit.false);
+  const yes = crit.true === null || crit.true === undefined ? "" : vegaCritText(crit.true);
   return [
     `no - ${no || "the statement does not hold"}`,
     `yes - ${yes || "the statement holds"}`,
@@ -127,6 +211,10 @@ export function vegaOptionTexts(qdef) {
  * state. Options are capped per option, and an over-long option list is
  * shrunk evenly before the instructions are (mirrors build_prompt).
  *
+ * `truncateState` defaults to the reference's silent truncation; the split
+ * export refuses the decision instead (a cut-off record is worse than none),
+ * so its runtime passes false and gets a RangeError.
+ *
  * @returns {{ids:number[], spans:{state:[number,number], question:[number,number],
  *   options:[number,number][], last:number}}}
  */
@@ -139,6 +227,7 @@ export function buildVegaPrompt({
   queryFirstMaxState = VEGA_DEFAULTS.queryFirstMaxState,
   optMaxTokens = VEGA_DEFAULTS.optMaxTokens,
   insMaxTokens = VEGA_DEFAULTS.insMaxTokens,
+  truncateState = true,
 }) {
   const options = vegaOptionTexts(qdef);
   const enc = (s) => encode(s, false);
@@ -169,6 +258,11 @@ export function buildVegaPrompt({
     fixed += pre.length;
   }
   const room = Math.max(0, maxLen - fixed);
+  if (!truncateState && st.length > room) {
+    throw new RangeError(
+      `vega: state is ${st.length} tokens, only ${room} fit in maxLen=${maxLen}`
+      + " (this export refuses a truncated state; raise maxLen)");
+  }
   st = st.slice(0, room); // truncate_left = false: the head of the state is kept
   const ids = [...bos, ...pre, ...head];
   const s0 = ids.length;
@@ -294,20 +388,26 @@ export const VEGA_DEFAULT_THETA = [[0], [0], [0]];
  * Per-type thermal calibration from the checkpoint's vega_config.json:
  * log_tau = b + w . phys, tau in [0.2, 20]; probs = softmax(logits / tau).
  *
+ * `thetaByRow` overrides the per-type lookup with an explicit theta block per
+ * item (the split export calibrates each question with the routed adapter's
+ * block).
+ *
  * @param {{theta:number[][]}} calibration
  * @param {{logits:ArrayLike<number>, rowWidth:number, qtypes:number[],
- *   phys:ArrayLike<number>, nOpts:number[]}} spec phys is [items, 4]
+ *   phys:ArrayLike<number>, nOpts:number[], thetaByRow?:number[][][]}} spec
+ *   phys is [items, 4]
  * @returns {number[][]} probabilities per item, in prompt order
  */
 export function vegaThermalProbabilities({
   logits, rowWidth, qtypes, phys, nOpts,
   theta = VEGA_DEFAULT_THETA,
+  thetaByRow = null,
 }) {
   const rows = Number(logits.length / rowWidth);
   const out = [];
   for (let b = 0; b < rows; b++) {
     const k = nOpts[b];
-    const t = theta[qtypes[b]] ?? theta[0];
+    const t = thetaByRow ? (thetaByRow[b] ?? theta[0]) : (theta[qtypes[b]] ?? theta[0]);
     let logTau = t[0];
     for (let f = 0; f < 4; f++) logTau += t[1 + f] * phys[b * 4 + f];
     const tau = Math.exp(Math.min(Math.log(20), Math.max(Math.log(0.2), logTau)));
@@ -336,26 +436,31 @@ export function vegaThermalFeatures({ kinetic, nearest, stepsUsed, nOpts, maxSte
 
 /**
  * Vega answers -> jev-web DecideResult answers (additive vega fields:
- * predictionSet / abstain / unbound / settleSteps / energy).
+ * predictionSet / abstain / unbound / settleSteps / energy, and — when the
+ * split export routes per question — adapter / gate).
  *
  * @param {{probs:number[][], qtypes:number[], labels:string[][],
  *   physics:{nearest:ArrayLike<number>, stepsUsed:ArrayLike<number>},
  *   rawLogits:ArrayLike<number>, rowWidth:number,
- *   calibration:object, alpha?:string, risk?:string}} spec
+ *   calibration:object, alpha?:string, risk?:string,
+ *   calibrations?:object[], adapterNames?:string[], gates?:number[][],
+ *   routes?:number[]}} spec calibrations/gates are per row when routed
  */
 export function vegaAnswers({
   probs, qtypes, physics, rawLogits, rowWidth, calibration, questions, labels,
   alpha = VEGA_DEFAULTS.alpha, risk = VEGA_DEFAULTS.risk,
+  calibrations = null, adapterNames = null, gates = null, routes = null,
 }) {
   const answers = [];
   labels.forEach((optionLabels, r) => {
     const p = probs[r];
     const k = optionLabels.length;
     const qtype = VEGA_QTYPE_NAMES[qtypes[r]];
+    const cal = calibrations?.[r] ?? calibration;
     const conf = Math.max(...p);
     const best = p.indexOf(Math.max(...p));
     // LAC prediction set; the top option is always kept so it is never empty.
-    const th = calibration?.conformal?.[qtype]?.[String(alpha)];
+    const th = cal?.conformal?.[qtype]?.[String(alpha)];
     const predictionSet = th === undefined ? null
       : optionLabels.filter((_, i) => i === best || p[i] >= Math.max(1 - th, 1e-12));
     // energy = -max raw logit over the question's real options
@@ -365,11 +470,16 @@ export function vegaAnswers({
       probabilities: Object.fromEntries(optionLabels.map((l, i) => [l, p[i]])),
       confidence: conf,
       predictionSet,
-      abstain: conf < (calibration?.abstain_threshold?.[String(risk)] ?? 0),
-      unbound: physics.nearest[r] > (calibration?.unbound_threshold ?? Infinity),
+      abstain: conf < (cal?.abstain_threshold?.[String(risk)] ?? 0),
+      unbound: physics.nearest[r] > (cal?.unbound_threshold ?? Infinity),
       settleSteps: physics.stepsUsed[r],
       energy: -bestLogit,
     };
+    if (adapterNames) {
+      const rt = routes?.[r] ?? -1;
+      a.adapter = rt >= 0 ? (adapterNames[rt] ?? null) : null;
+      a.gate = gates?.[r]?.length ? Math.max(...gates[r]) : 0;
+    }
     if (qtype === "choice") {
       a.type = "choice";
       a.choice = optionLabels[best];
@@ -396,6 +506,100 @@ export function vegaOptionLabels(questions) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Split export: JS-side perception (positions, past state, pooling, routing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapter routing (reference route_adapters): the most open adapter if its
+ * gate reaches the threshold, else -1 (the base engine calibrates the answer).
+ */
+export function vegaRoute(gates, threshold = 0.5) {
+  if (!gates?.length) return -1;
+  let best = 0;
+  for (let i = 1; i < gates.length; i++) if (gates[i] > gates[best]) best = i;
+  return gates[best] >= threshold ? best : -1;
+}
+
+/** Text M-RoPE positions: 0..L-1 on each of the three rows ([3, 1, L]). */
+export function vegaTextPositions(L) {
+  const out = new BigInt64Array(3 * L);
+  for (let i = 0; i < L; i++) {
+    out[i] = BigInt(i);
+    out[L + i] = BigInt(i);
+    out[2 * L + i] = BigInt(i);
+  }
+  return out;
+}
+
+/**
+ * Zero-filled first-read state for every past_* input the cut decoder keeps
+ * (conv / recurrent / key-value caches). Shapes come from the graph's own
+ * input metadata: batch_size -> 1, any other symbol (past_sequence_length)
+ * -> 0.
+ */
+export function emptyVegaPast(session, Tensor) {
+  const feeds = {};
+  for (const m of session?.inputMetadata ?? []) {
+    if (m?.isTensor === false || !String(m.name).startsWith("past_")) continue;
+    const dims = (m.shape ?? []).map(
+      (d) => (typeof d === "number" ? d : d === "batch_size" ? 1 : 0));
+    feeds[m.name] = new Tensor("float32",
+      new Float32Array(dims.reduce((a, b) => a * b, 1)), dims);
+  }
+  return feeds;
+}
+
+/**
+ * Perception._pooled_batch for one text item, over the hidden states the split
+ * decoder emits: the state/question/final-token span means at every feature
+ * layer, the option span means at the deepest option layer, and the state cut
+ * into up to C equal chunk means for the memory reader (states shorter than
+ * chunkMinTokens get none). Image states get no chunks, as in vega_vision.py.
+ *
+ * @returns {{feats:Float32Array, opts:Float32Array, chunks:Float32Array,
+ *   cmask:Uint8Array}} feats [2, 3, d] (layer, slot, d)
+ */
+export function poolVegaHidden({
+  h13, h19, spans, d,
+  chunks: C = VEGA_DEFAULTS.memoryChunks,
+  chunkMinTokens = VEGA_DEFAULTS.memoryMinTokens,
+  chunkTokens = VEGA_DEFAULTS.memoryChunkTokens,
+  withChunks = true,
+}) {
+  const L = Math.floor(h13.length / d);
+  const mean = (h, a, e, out, off) => {
+    if (e <= a) return;
+    for (let t = a; t < e; t++) {
+      for (let j = 0; j < d; j++) out[off + j] += h[t * d + j];
+    }
+    for (let j = 0; j < d; j++) out[off + j] /= e - a;
+  };
+  const feats = new Float32Array(2 * 3 * d);
+  [h13, h19].forEach((h, l) => {
+    mean(h, spans.state[0], spans.state[1], feats, (l * 3 + 0) * d);
+    mean(h, spans.question[0], spans.question[1], feats, (l * 3 + 1) * d);
+    feats.set(h.subarray((L - 1) * d, L * d), (l * 3 + 2) * d);
+  });
+  const opts = new Float32Array(spans.options.length * d);
+  spans.options.forEach(([a, e], k) => mean(h19, a, e, opts, k * d));
+  const chunks = new Float32Array(C * d);
+  const cmask = new Uint8Array(C);
+  const [s0, s1] = spans.state;
+  const m = s1 - s0;
+  if (withChunks && m >= Math.max(chunkMinTokens, 2)) {
+    const k = Math.max(2, Math.min(C, Math.floor(m / Math.max(1, chunkTokens))));
+    // token t goes to chunk floor(t*k/m): chunk c covers [ceil(c*m/k), ceil((c+1)*m/k))
+    for (let c = 0; c < k; c++) {
+      const a = s0 + Math.ceil((c * m) / k);
+      const e = s0 + (c === k - 1 ? m : Math.ceil(((c + 1) * m) / k));
+      mean(h19, a, e, chunks, c * d);
+    }
+    cmask.fill(1, 0, k);
+  }
+  return { feats, opts, chunks, cmask };
+}
+
 // ---------------------------------------------------------------------------
 // The decider
 // ---------------------------------------------------------------------------
@@ -405,20 +609,87 @@ const now = () => (typeof performance !== "undefined" ? performance.now() : Date
 const hfUrl = (model, revision, file) =>
   `https://huggingface.co/${model}/resolve/${revision ? `${revision}/` : ""}${file}`;
 
+/**
+ * Session opener shared by both Vega formats: graph bytes (plus an external
+ * data sibling when the graph has one) go through the injected fetch and the
+ * Cache API, then ORT creates the session; a WebGPU create failure retries on
+ * wasm. Hosts that load weights differently (local files, bundled, offline
+ * mirrors) replace the whole step with sessionFactory(url, opts).
+ */
+function openVegaSessions({
+  ortMod, fetchImpl, onProgress, sessionFactory, executionProviders, device,
+}) {
+  const create = sessionFactory
+    ?? (async (url, opts) => {
+      const bytes = await fetchCachedBytes(url, {
+        fetchImpl, onProgress: (p) => onProgress?.(p), persist: true,
+      });
+      const external = await fetchOnnxExternalData(url, { fetchImpl });
+      const sessionOpts = external ? { ...opts, externalData: [external] } : opts;
+      return ortMod.InferenceSession.create(bytes, sessionOpts);
+    });
+  return async (url) => {
+    try {
+      return await create(url, { executionProviders, graphOptimizationLevel: "all" });
+    } catch (e) {
+      if (device !== "webgpu") throw e;
+      onProgress?.({ phase: `webgpu unavailable (${e?.message ?? e}) — retrying on wasm` });
+      return create(url, { executionProviders: ["wasm"], graphOptimizationLevel: "all" });
+    }
+  };
+}
+
 /**
  * Create a Vega decider.
  *
  * @param {object} [opts]
- *  model/revision     — browser export repo (torso + engine graphs, tokenizer,
- *                        vega_config.json with the calibration block)
- *  torsoFile/engineFile — graph paths within the repo
- *  calibrationModel   — repo to read vega_config.json from (default: model;
+ *  variant            — "fp16" (default, this repo's fused export) or "q8"
+ *                        (nvkudva/vega-onnx-q8: 8-bit split embed + decoder +
+ *                        fp32 engine with adapters, wasm-only). Sets
+ *                        model/revision/subfolder/format; explicit
+ *                        model/revision/format still win.
+ *  format             — "fused" | "split" (normally derived from the variant)
+ *  model/revision/subfolder — export repo and, for split exports, the
+ *                        version folder that holds the graphs (default "v2")
+ *  torsoFile/engineFile — fused tograph paths within the repo
+ *  embedFile/decoderFile — split graph names within the subfolder
+ *  calibrationModel   — repo to read the config from (default: model;
  *                        point it at the source checkpoint for your own export)
  *  maxLen             — prompt window; null = checkpoint's max_length
- *  alpha / risk       — conformal risk level and abstain risk ("0.1" default)
+ *  alpha / risk       — conformal risk level and abstain risk
+ *                        (default: the calibration block's default_risk)
  *  device, wasmPaths, sessionFactory, onProgress — as in the other families
  */
-export async function createVegaDecider({
+export async function createVegaDecider(opts = {}) {
+  const variant = opts.variant ?? null;
+  const preset = variant === null ? null : VEGA_VARIANTS[variant];
+  if (variant !== null && !preset) {
+    throw new TypeError(
+      `vega: unknown variant "${variant}" (${Object.keys(VEGA_VARIANTS).join(", ")})`);
+  }
+  const format = opts.format ?? preset?.format ?? "fused";
+  if (format !== "fused" && format !== "split") {
+    throw new TypeError(`vega: format must be "fused" or "split" (got ${JSON.stringify(format)})`);
+  }
+  // Like strands: a named variant replaces the *default* model/revision, so
+  // createDecisionRuntime({family: "vega", variant: "q8"}) works even though
+  // the registry passes the default target through; a deliberately different
+  // model/revision still wins.
+  const isDefaultTarget = (opts.model ?? VEGA_DEFAULT_MODEL) === VEGA_DEFAULT_MODEL
+    && (opts.revision ?? VEGA_DEFAULT_REVISION) === VEGA_DEFAULT_REVISION;
+  const usePreset = preset && isDefaultTarget;
+  const resolved = {
+    model: usePreset ? preset.model : (opts.model ?? VEGA_DEFAULT_MODEL),
+    revision: usePreset ? preset.revision : (opts.revision ?? VEGA_DEFAULT_REVISION),
+    subfolder: opts.subfolder ?? preset?.subfolder ?? null,
+  };
+  return format === "split"
+    ? createVegaSplitDecider(opts, resolved)
+    : createVegaFusedDecider({ ...opts, ...resolved });
+}
+
+/** The fused export (one torso graph + the base engine), the default. */
+async function createVegaFusedDecider({
   model = VEGA_DEFAULT_MODEL,
   revision = VEGA_DEFAULT_REVISION,
   torsoFile = VEGA_TORSO_FILE,
@@ -434,7 +705,7 @@ export async function createVegaDecider({
   onProgress = null,
   maxLen = null,
   alpha = VEGA_DEFAULTS.alpha,
-  risk = VEGA_DEFAULTS.risk,
+  risk = null,
   scope = globalThis,
 } = {}) {
   const ortMod = ort ?? (await import("onnxruntime-web"));
@@ -463,6 +734,7 @@ export async function createVegaDecider({
   } catch { /* fall through to the shipped defaults */ }
   const cfg = { ...VEGA_DEFAULTS, ...(config ?? {}) };
   const calibration = config?.calibration ?? {};
+  const effRisk = risk ?? calibration.default_risk ?? cfg.default_risk ?? VEGA_DEFAULTS.risk;
   const cfgMaxLen = config?.max_len ?? cfg.maxLen;
   const effMaxLen = Number.isFinite(maxLen) && maxLen > 0 ? maxLen : cfgMaxLen;
 
@@ -473,29 +745,12 @@ export async function createVegaDecider({
   const encode = (text, addSpecial = false) =>
     Array.from(tok(text, { add_special_tokens: addSpecial }).input_ids.data, Number);
 
-  const createSession = sessionFactory
-    ?? (async (u, opts) => {
-      const bytes = await fetchCachedBytes(u, {
-        fetchImpl, onProgress: (p) => onProgress?.(p), persist: true,
-      });
-      const external = await fetchOnnxExternalData(u, { fetchImpl });
-      const sessionOpts = external ? { ...opts, externalData: [external] } : opts;
-      return ortMod.InferenceSession.create(bytes, sessionOpts);
-    });
-  const makeSession = async (file) => {
-    try {
-      return await createSession(hfUrl(model, revision, file), {
-        executionProviders, graphOptimizationLevel: "all",
-      });
-    } catch (e) {
-      if (resolvedDevice !== "webgpu") throw e;
-      onProgress?.({ phase: `webgpu unavailable (${e?.message ?? e}) — retrying on wasm` });
-      return createSession(hfUrl(model, revision, file),
-        { executionProviders: ["wasm"], graphOptimizationLevel: "all" });
-    }
-  };
-  const torso = await makeSession(torsoFile);
-  const engine = await makeSession(engineFile);
+  const open = openVegaSessions({
+    ortMod, fetchImpl, onProgress, sessionFactory,
+    executionProviders, device: resolvedDevice,
+  });
+  const torso = await open(hfUrl(model, revision, torsoFile));
+  const engine = await open(hfUrl(model, revision, engineFile));
 
   const int64 = (arr, dims) => new ortMod.Tensor("int64", arr, dims);
   const f32 = (arr, dims) => new ortMod.Tensor("float32", arr, dims);
@@ -504,12 +759,13 @@ export async function createVegaDecider({
   return {
     info: {
       family: "vega",
+      format: "fused",
       model,
       revision,
       device: resolvedDevice,
       maxLen: effMaxLen,
       alpha: String(alpha),
-      risk: String(risk ?? cfg.default_risk ?? VEGA_DEFAULTS.risk),
+      risk: String(effRisk),
       calibrationSource: configSource,
       nSteps: cfg.n_steps ?? cfg.nSteps,
       config,
@@ -611,7 +867,7 @@ export async function createVegaDecider({
         probs, qtypes: batch.qtypes, labels,
         physics: { nearest, stepsUsed },
         rawLogits: logits, rowWidth: batch.K,
-        calibration, alpha, risk,
+        calibration, alpha, risk: effRisk,
       });
       const decode = (ids) => {
         try {
@@ -634,3 +890,236 @@ export async function createVegaDecider({
     },
   };
 }
+
+/**
+ * The split export (nvkudva/vega-onnx-q8): an 8-bit embedding graph, a cut
+ * decoder that stops after layer 19 and emits the residual stream at layers
+ * 13/19 (the LM head and layers 20-23 never run), and the fp32 engine with
+ * both gated task adapters. JS pools the hidden states, each question is
+ * calibrated with the theta block of the adapter its gate routes it to, and
+ * the conformal / abstain / unbound machinery reads that block's thresholds.
+ *
+ * Text only in v1: the vision encoder (image as the state) is not wired in.
+ * The 8-bit graphs are wasm-only (MatMulNBits has no WebGPU kernel), so
+ * device "auto" resolves to wasm.
+ */
+async function createVegaSplitDecider({
+  embedFile = VEGA_Q8_EMBED_FILE,
+  decoderFile = VEGA_Q8_DECODER_FILE,
+  engineFile = VEGA_Q8_ENGINE_FILE,
+  calibrationModel = null,
+  calibrationRevision = null,
+  ort = null,
+  transformers = null,
+  fetchImpl = fetch,
+  wasmPaths = null,
+  device = "auto",
+  sessionFactory = null,
+  onProgress = null,
+  maxLen = null,
+  alpha = VEGA_DEFAULTS.alpha,
+  risk = null,
+} = {}, { model, revision, subfolder }) {
+  const ortMod = ort ?? (await import("onnxruntime-web"));
+  const tf = transformers ?? (await import("@huggingface/transformers"));
+  if (wasmPaths) {
+    try { ortMod.env.wasm.wasmPaths = wasmPaths; } catch { /* older runtime */ }
+  }
+  const resolvedDevice = device !== "auto" ? device : "wasm";
+  const executionProviders = resolvedDevice === "webgpu" ? ["webgpu", "wasm"] : ["wasm"];
+
+  const basePath = subfolder ? `${subfolder}/` : "";
+  const configRepo = calibrationModel ?? model;
+  const configRevision = calibrationRevision ?? (calibrationModel ? "main" : revision);
+  const configUrl = hfUrl(configRepo, configRevision, `${basePath}vega_web.json`);
+  let config = null;
+  let configSource = null;
+  try {
+    const res = await fetchImpl(configUrl);
+    if (res?.ok) {
+      config = await res.json();
+      configSource = configUrl;
+    }
+  } catch { /* fall through to the shipped defaults */ }
+  const cfg = { ...VEGA_DEFAULTS, ...(config ?? {}) };
+  const calibration = config?.calibration ?? {};
+  const adapters = Array.isArray(config?.adapters) ? config.adapters : [];
+  const effRisk = risk ?? calibration.default_risk ?? cfg.default_risk ?? VEGA_DEFAULTS.risk;
+  const cfgMaxLen = config?.max_len ?? cfg.maxLen;
+  const effMaxLen = Number.isFinite(maxLen) && maxLen > 0 ? maxLen : cfgMaxLen;
+
+  // The tokenizer (Qwen3.5) ships inside the version folder, and
+  // transformers.js's AutoTokenizer has no subfolder option here, so build
+  // PreTrainedTokenizer from the two files directly -- what the export's own
+  // runtime does. Older transformers falls back to AutoTokenizer.
+  const fetchJson = async (file) => {
+    const url = hfUrl(configRepo, configRevision, `${basePath}${file}`);
+    const res = await fetchImpl(url);
+    if (!res?.ok) throw new Error(`vega: ${url} not found (HTTP ${res?.status ?? "no response"})`);
+    return res.json();
+  };
+  let tok;
+  if (typeof tf.PreTrainedTokenizer === "function") {
+    const [tokenizerJson, tokenizerConfig] = await Promise.all([
+      fetchJson("tokenizer.json"), fetchJson("tokenizer_config.json"),
+    ]);
+    tok = new tf.PreTrainedTokenizer(tokenizerJson, tokenizerConfig);
+  } else {
+    tok = await tf.AutoTokenizer.from_pretrained(configRepo, { revision: configRevision });
+  }
+  const encode = (text, addSpecial = false) => {
+    if (typeof tok.encode === "function") {
+      const ids = tok.encode(text, { add_special_tokens: addSpecial });
+      return Array.isArray(ids) ? ids : Array.from(ids?.input_ids?.data ?? ids, Number);
+    }
+    return Array.from(tok(text, { add_special_tokens: addSpecial }).input_ids.data, Number);
+  };
+  const decode = (ids) => {
+    try {
+      return tok.decode(Array.from(ids), { skip_special_tokens: false });
+    } catch {
+      return Array.from(ids).join(" ");
+    }
+  };
+
+  const open = openVegaSessions({
+    ortMod, fetchImpl, onProgress, sessionFactory, executionProviders,
+    device: resolvedDevice,
+  });
+  const embed = await open(hfUrl(model, revision, `${basePath}${embedFile}`));
+  const decoder = await open(hfUrl(model, revision, `${basePath}${decoderFile}`));
+  const engine = await open(hfUrl(model, revision, `${basePath}${engineFile}`));
+  const past = emptyVegaPast(decoder, ortMod.Tensor);
+
+  const int64 = (arr, dims) => new ortMod.Tensor("int64", arr, dims);
+  const f32 = (arr, dims) => new ortMod.Tensor("float32", arr, dims);
+  const bool = (arr, dims) => new ortMod.Tensor("bool", arr, dims);
+
+  return {
+    info: {
+      family: "vega",
+      format: "split",
+      model,
+      revision,
+      subfolder: subfolder ?? null,
+      device: resolvedDevice,
+      maxLen: effMaxLen,
+      alpha: String(alpha),
+      risk: String(effRisk),
+      calibrationSource: configSource,
+      nSteps: cfg.n_steps ?? cfg.nSteps,
+      adapters: adapters.map((a) => a.name),
+      config,
+    },
+    async decide(state, questions) {
+      const t0 = now();
+      const normalized = normalizeQuestions(questions);
+      const qdefs = normalized.map(vegaQuestionDef);
+      const stateText = renderVegaText(state);
+      const C = Number(cfg.memory_chunks ?? VEGA_DEFAULTS.memoryChunks);
+      const chunkMinTokens = cfg.memory_min_tokens ?? VEGA_DEFAULTS.memoryMinTokens;
+      const chunkTokens = cfg.memory_chunk_tokens ?? VEGA_DEFAULTS.memoryChunkTokens;
+
+      const items = qdefs.map((qdef) => {
+        const { ids, spans } = buildVegaPrompt({
+          encode, stateText, qdef, maxLen: effMaxLen,
+          bosId: null, // the reference adds no BOS for Qwen, and the export never does
+          queryFirstMaxState: cfg.query_first_max_state ?? cfg.queryFirstMaxState,
+          optMaxTokens: cfg.opt_max_tokens ?? cfg.optMaxTokens,
+          insMaxTokens: 256,
+          truncateState: false, // the export refuses a state that does not fit
+        });
+        return { ids, spans, qtype: VEGA_QTYPE[qdef.t], options: vegaOptionTexts(qdef) };
+      });
+
+      // One decoder pass per question (the export's own reading), pooling in JS.
+      const tRun = now();
+      const rows = [];
+      const prompts = [];
+      for (const it of items) {
+        const L = it.ids.length;
+        const embedOut = await embed.run({
+          input_ids: int64(BigInt64Array.from(it.ids, BigInt), [1, L]),
+        });
+        const embeds = embedOut.inputs_embeds.data;
+        const d = embeds.length / L;
+        const decOut = await decoder.run({
+          ...past,
+          inputs_embeds: f32(embeds, [1, L, d]),
+          attention_mask: int64(new BigInt64Array(L).fill(1n), [1, L]),
+          position_ids: int64(vegaTextPositions(L), [3, 1, L]),
+        });
+        const pooled = poolVegaHidden({
+          h13: decOut.h13.data, h19: decOut.h19.data, spans: it.spans, d,
+          chunks: C, chunkMinTokens, chunkTokens,
+        });
+        const K = it.options.length;
+        const eng = await engine.run({
+          feats: f32(pooled.feats, [1, 2, 3, d]),
+          opts: f32(pooled.opts, [1, K, 1, d]),
+          opt_mask: bool(new Uint8Array(K).fill(1), [1, K]),
+          qtype: int64([BigInt(it.qtype)], [1]),
+          chunks: f32(pooled.chunks, [1, C, d]),
+          chunk_mask: bool(pooled.cmask, [1, C]),
+        });
+        rows.push({
+          qtype: it.qtype,
+          K,
+          logits: Array.from(eng.logits.data).slice(0, K),
+          kinetic: eng.kinetic.data[0],
+          nearest: eng.nearest.data[0],
+          stepsUsed: Number(eng.steps_used.data[0]),
+          gates: Array.from(eng.gates.data),
+        });
+        prompts.push(decode(it.ids));
+      }
+
+      const nOpts = rows.map((r) => r.K);
+      const rowWidth = Math.max(...nOpts);
+      const logits = new Float32Array(rows.length * rowWidth);
+      rows.forEach((r, b) => logits.set(r.logits, b * rowWidth));
+      const phys = vegaThermalFeatures({
+        kinetic: rows.map((r) => r.kinetic),
+        nearest: rows.map((r) => r.nearest),
+        stepsUsed: rows.map((r) => r.stepsUsed),
+        nOpts, maxSteps: cfg.n_steps ?? cfg.nSteps,
+      });
+      // Each question is calibrated by the adapter its gate routes it to
+      // (route_adapters: the most open gate, if it reaches the threshold).
+      const gateThreshold = adapters[0]?.gate_threshold ?? 0.5;
+      const gates = rows.map((r) => r.gates);
+      const routes = gates.map((g) => vegaRoute(g, gateThreshold));
+      const calibrations = routes.map(
+        (rt) => (rt >= 0 ? adapters[rt]?.calibration : null) ?? calibration);
+      const thetaByRow = calibrations.map(
+        (cal, b) => cal?.theta?.[rows[b].qtype] ?? VEGA_DEFAULT_THETA[rows[b].qtype]);
+      const probs = vegaThermalProbabilities({
+        logits, rowWidth, qtypes: rows.map((r) => r.qtype),
+        phys: phys.flat(), nOpts, thetaByRow,
+      });
+      const runMs = now() - tRun;
+      const answers = vegaAnswers({
+        probs, qtypes: rows.map((r) => r.qtype), labels: vegaOptionLabels(normalized),
+        physics: {
+          nearest: rows.map((r) => r.nearest),
+          stepsUsed: rows.map((r) => r.stepsUsed),
+        },
+        rawLogits: logits, rowWidth,
+        calibration, calibrations, alpha, risk: effRisk,
+        adapterNames: adapters.map((a) => a.name), gates, routes,
+      });
+      return {
+        answers,
+        truncated: false,
+        length: items.reduce((n, it) => n + it.ids.length, 0),
+        prompts,
+        timings: { totalMs: Math.round(now() - t0), runMs: Math.round(runMs) },
+      };
+    },
+    async dispose() {
+      try { await embed.release?.(); } catch { /* optional */ }
+      try { await decoder.release?.(); } catch { /* optional */ }
+      try { await engine.release?.(); } catch { /* optional */ }
+    },
+  };
+}