mlx-bun 0.0.10 → 0.0.12

package/src/config.ts

@@ -2,6 +2,11 @@
 // Parses HF config.json (Gemma 4 unified layout: text_config nested),
 // the OptiQ per-layer quantization map, and kv_config.json when present.
 
+import {
+  parseGlm52Config,
+  type Glm52Config,
+} from "./model/glm52-config";
+
 export interface RopeParams {
   ropeTheta: number;
   ropeType: string;
@@ -38,6 +43,13 @@ export interface TextConfig {
   numExperts: number;
   topKExperts: number;
   moeIntermediateSize: number;
+  /** Qwen3-MoE sparse-block gating (qwen3_moe): a layer is MoE unless it is
+   *  in `mlpOnlyLayers` and `(idx+1) % decoderSparseStep == 0` selects it.
+   *  `normTopkProb` renormalizes the top-k gate weights. Defaults are inert
+   *  for non-qwen3_moe families. */
+  decoderSparseStep: number;
+  mlpOnlyLayers: number[];
+  normTopkProb: boolean;
   /** Qwen3.5 hybrid (gated-DeltaNet) geometry; 0/false for other families. */
   linearNumValueHeads: number;
   linearNumKeyHeads: number;
@@ -77,6 +89,37 @@ export interface KvQuantSpec {
   groupSize: number;
 }
 
+/** TurboQuant scheme (docs/design/turboquant-kv.md): rotation-based KV
+ *  quantization, a distinct axis from the uniform/per-layer affine kvQuant
+ *  above (composes with it in principle; v1 ships as a standalone CLI-only
+ *  runtime lever, same class as uniform kvBits — see
+ *  src/generate.ts maybeQuantizeKv). Valid kBits: {2,4,5,8}; vBits:
+ *  {2,3,4,5,8} (docs/design/turboquant-kv.md's supported Lloyd-Max tables). */
+export interface TurboQuantScheme {
+  kBits: number;
+  vBits: number;
+}
+
+export const TURBOQUANT_VALID_KBITS = [2, 4, 5, 8] as const;
+export const TURBOQUANT_VALID_VBITS = [2, 3, 4, 5, 8] as const;
+
+/** Parse `turbo` / `turbo:k<bits>v<bits>` (default k8v3). Returns null for
+ *  non-turbo strings (caller falls through to the uniform/config parser);
+ *  throws Error with a user-facing message for a malformed turbo spec. */
+export function parseTurboQuantScheme(raw: string): TurboQuantScheme | null {
+  if (raw !== "turbo" && !raw.startsWith("turbo:")) return null;
+  if (raw === "turbo") return { kBits: 8, vBits: 3 };
+  const m = /^turbo:k(\d+)v(\d+)$/.exec(raw);
+  if (!m) throw new Error(`--kv-quant turbo spec must look like "turbo:k<bits>v<bits>" (got "${raw}")`);
+  const kBits = Number(m[1]);
+  const vBits = Number(m[2]);
+  if (!(TURBOQUANT_VALID_KBITS as readonly number[]).includes(kBits))
+    throw new Error(`--kv-quant turbo: kBits must be one of ${TURBOQUANT_VALID_KBITS.join(",")} (got ${kBits})`);
+  if (!(TURBOQUANT_VALID_VBITS as readonly number[]).includes(vBits))
+    throw new Error(`--kv-quant turbo: vBits must be one of ${TURBOQUANT_VALID_VBITS.join(",")} (got ${vBits})`);
+  return { kBits, vBits };
+}
+
 export interface ModelConfig {
   modelDir: string;
   modelType: string;
@@ -93,6 +136,11 @@ export interface ModelConfig {
 function parseRope(raw: Record<string, any>): Record<string, RopeParams> {
   const out: Record<string, RopeParams> = {};
   for (const [kind, p] of Object.entries(raw ?? {})) {
+    // transformers ≥5.10 configs mix flat scalars into the per-attention-type
+    // map (`rope_parameters: { full_attention: {...}, rope_theta: null,
+    // rope_type: "default", ... }` — the DeepSpec drafter ships this shape);
+    // only object entries are attention-type params.
+    if (!p || typeof p !== "object") continue;
     out[kind] = {
       ropeTheta: p.rope_theta,
       ropeType: p.rope_type ?? "default",
@@ -103,7 +151,7 @@ function parseRope(raw: Record<string, any>): Record<string, RopeParams> {
   return out;
 }
 
-function parseQuantization(raw: Record<string, any> | undefined): QuantizationConfig | null {
+export function parseQuantization(raw: Record<string, any> | undefined): QuantizationConfig | null {
   if (!raw) return null;
   const def: QuantSpec = {
     bits: raw.bits,
@@ -180,6 +228,18 @@ export async function loadModelConfig(modelDir: string): Promise<ModelConfig> {
   const raw = (await Bun.file(`${modelDir}/config.json`).json()) as Record<string, any>;
   const modelType = raw.model_type;
   const isDiffusion = modelType === "diffusion_gemma";
+  const isGlm52 = modelType === "glm_moe_dsa";
+  // The converted Colibri artifact keeps stop metadata split across the two
+  // HF files. Preserve the old config-only behavior for every other family;
+  // GLM-5.2 explicitly unions both lists through its dedicated parser.
+  let glm52: Glm52Config | null = null;
+  if (isGlm52) {
+    const generationFile = Bun.file(`${modelDir}/generation_config.json`);
+    const generation = await generationFile.exists()
+      ? await generationFile.json() as Record<string, any>
+      : null;
+    glm52 = parseGlm52Config(modelDir, raw, generation);
+  }
   // Gemma 4 unified nests the LM config; plain text models keep it at top level.
   // DiffusionGemma keeps it flat too, but omits all dims — backfill from defaults.
   const baseT = (raw.text_config ?? raw) as Record<string, any>;
@@ -195,28 +255,44 @@ export async function loadModelConfig(modelDir: string): Promise<ModelConfig> {
   const qwenRope = (t.rope_parameters ?? {}) as Record<string, any>;
 
   const text: TextConfig = {
-    hiddenSize: t.hidden_size,
-    numHiddenLayers: t.num_hidden_layers,
-    numAttentionHeads: t.num_attention_heads,
-    numKeyValueHeads: t.num_key_value_heads,
-    headDim: t.head_dim ?? Math.floor(t.hidden_size / t.num_attention_heads),
-    numGlobalKeyValueHeads: t.num_global_key_value_heads ?? t.num_key_value_heads,
-    globalHeadDim: t.global_head_dim ?? t.head_dim ?? Math.floor(t.hidden_size / t.num_attention_heads),
+    hiddenSize: glm52?.hiddenSize ?? t.hidden_size,
+    numHiddenLayers: glm52?.numHiddenLayers ?? t.num_hidden_layers,
+    numAttentionHeads: glm52?.numAttentionHeads ?? t.num_attention_heads,
+    numKeyValueHeads: glm52?.numKeyValueHeads ?? t.num_key_value_heads,
+    headDim: glm52?.qkHeadDim ?? t.head_dim ?? Math.floor(t.hidden_size / t.num_attention_heads),
+    numGlobalKeyValueHeads:
+      glm52?.numKeyValueHeads ?? t.num_global_key_value_heads ?? t.num_key_value_heads,
+    globalHeadDim:
+      glm52?.qkHeadDim ??
+      t.global_head_dim ??
+      t.head_dim ??
+      Math.floor(t.hidden_size / t.num_attention_heads),
     attentionKEqV: t.attention_k_eq_v ?? false,
-    intermediateSize: t.intermediate_size,
+    intermediateSize: glm52?.intermediateSize ?? t.intermediate_size,
     hiddenActivation: t.hidden_activation ?? t.hidden_act ?? "gelu_pytorch_tanh",
-    rmsNormEps: t.rms_norm_eps,
-    vocabSize: t.vocab_size,
-    maxPositionEmbeddings: t.max_position_embeddings,
+    rmsNormEps: glm52?.rmsNormEps ?? t.rms_norm_eps,
+    vocabSize: glm52?.vocabSize ?? t.vocab_size,
+    maxPositionEmbeddings:
+      glm52?.maxPositionEmbeddings ?? t.max_position_embeddings,
     slidingWindow: t.sliding_window ?? 0,
-    layerTypes: t.layer_types ?? (isLlama ? Array(t.num_hidden_layers).fill("full_attention") : []),
+    layerTypes: glm52
+      ? Array(glm52.numHiddenLayers).fill("full_attention")
+      : t.layer_types ?? (isLlama ? Array(t.num_hidden_layers).fill("full_attention") : []),
     hiddenSizePerLayerInput: t.hidden_size_per_layer_input ?? 0,
-    vocabSizePerLayerInput: t.vocab_size_per_layer_input ?? t.vocab_size,
+    vocabSizePerLayerInput:
+      t.vocab_size_per_layer_input ?? glm52?.vocabSize ?? t.vocab_size,
     numKvSharedLayers: t.num_kv_shared_layers ?? 0,
-    enableMoeBlock: t.enable_moe_block ?? false,
-    numExperts: t.num_experts ?? 0,
-    topKExperts: t.top_k_experts ?? 0,
-    moeIntermediateSize: t.moe_intermediate_size ?? 0,
+    enableMoeBlock: glm52 ? true : t.enable_moe_block ?? false,
+    numExperts: glm52?.numRoutedExperts ?? t.num_experts ?? 0,
+    // gemma4 uses `top_k_experts`; qwen3_moe uses `num_experts_per_tok`.
+    topKExperts:
+      glm52?.numExpertsPerToken ?? t.top_k_experts ?? t.num_experts_per_tok ?? 0,
+    moeIntermediateSize: glm52?.moeIntermediateSize ?? t.moe_intermediate_size ?? 0,
+    decoderSparseStep: glm52 ? 1 : t.decoder_sparse_step ?? 1,
+    mlpOnlyLayers: glm52
+      ? Array.from({ length: glm52.firstKDenseReplace }, (_, layer) => layer)
+      : t.mlp_only_layers ?? [],
+    normTopkProb: glm52?.normTopkProb ?? t.norm_topk_prob ?? false,
     linearNumValueHeads: t.linear_num_value_heads ?? 0,
     linearNumKeyHeads: t.linear_num_key_heads ?? 0,
     linearKeyHeadDim: t.linear_key_head_dim ?? 0,
@@ -224,9 +300,19 @@ export async function loadModelConfig(modelDir: string): Promise<ModelConfig> {
     linearConvKernelDim: t.linear_conv_kernel_dim ?? 0,
     fullAttentionInterval: t.full_attention_interval ?? 0,
     attnOutputGate: t.attn_output_gate ?? false,
-    partialRotaryFactor:
-      qwenRope.partial_rotary_factor ?? t.partial_rotary_factor ?? 1.0,
-    ropeParameters: isQwen35
+    partialRotaryFactor: glm52
+      ? glm52.qkRopeHeadDim / glm52.qkHeadDim
+      : qwenRope.partial_rotary_factor ?? t.partial_rotary_factor ?? 1.0,
+    ropeParameters: glm52
+      ? {
+          full_attention: {
+            ropeTheta: glm52.ropeTheta,
+            ropeType: "default",
+            partialRotaryFactor: glm52.qkRopeHeadDim / glm52.qkHeadDim,
+            factor: 1.0,
+          },
+        }
+      : isQwen35
       ? {
           full_attention: {
             ropeTheta: qwenRope.rope_theta ?? t.rope_theta ?? 10000,
@@ -250,7 +336,7 @@ export async function loadModelConfig(modelDir: string): Promise<ModelConfig> {
     finalLogitSoftcapping: t.final_logit_softcapping ?? null,
     tieWordEmbeddings: t.tie_word_embeddings ?? raw.tie_word_embeddings ?? false,
     bosTokenId: t.bos_token_id ?? raw.bos_token_id,
-    eosTokenId: t.eos_token_id ?? raw.eos_token_id,
+    eosTokenId: glm52?.eosTokenIds ?? t.eos_token_id ?? raw.eos_token_id,
     canvasLength: raw.canvas_length ?? t.canvas_length,
   };
 
@@ -264,14 +350,20 @@ export async function loadModelConfig(modelDir: string): Promise<ModelConfig> {
     }));
   }
 
-  const eos = raw.eos_token_id ?? text.eosTokenId;
+  const eos = glm52?.eosTokenIds ?? raw.eos_token_id ?? text.eosTokenId;
   return {
     modelDir,
     modelType,
     architectures: raw.architectures ?? [],
     dtype: raw.dtype ?? "bfloat16",
     text,
-    quantization: parseQuantization(raw.quantization ?? raw.quantization_config),
+    // Colibri's config retains the SOURCE FP8 quantization_config, while the
+    // serving shards are converted U8 + `.qs` tensors whose int4/int8/group
+    // geometry is inferred and validated by Glm52Container. Advertising the
+    // source FP8 block as mlx affine quantization would be actively wrong.
+    quantization: glm52
+      ? null
+      : parseQuantization(raw.quantization ?? raw.quantization_config),
     kvQuant,
     hasVisionSidecar: await Bun.file(`${modelDir}/optiq_vision.safetensors`).exists(),
     eosTokenIds: Array.isArray(eos) ? eos : [eos],

package/src/diffusion/diffusion-generate.ts

@@ -245,9 +245,7 @@ export function diffusionGenerate(
 
       let currentCanvas = ops.randint(0, vocab, [1, canvasLength], I32); // RNG: init
       let draftReveal = ops.zeros([1, canvasLength], Dtype.bool);
-      let draftCanvas: MlxArray = ops.logicalNot(ops.logicalNot(draftReveal)); // placeholder, replaced below
-      draftCanvas.dispose();
-      draftCanvas = ops.reshape(currentCanvas, [1, canvasLength]); // alias copy
+      let draftCanvas = ops.reshape(currentCanvas, [1, canvasLength]); // alias copy
       let argmaxCanvas = ops.reshape(currentCanvas, [1, canvasLength]);
       let scEmbeddings: MlxArray | null = null;
       const history: MlxArray[] = [];
@@ -266,7 +264,9 @@ export function diffusionGenerate(
         logits.dispose();
 
         argmaxCanvas.dispose();
-        argmaxCanvas = ops.argmaxAxis(processed, -1).astype(I32); // [1, L]
+        const argmax = ops.argmaxAxis(processed, -1);
+        argmaxCanvas = argmax.astype(I32); // [1, L]
+        argmax.dispose();
 
         if (curStep === 1) {
           processed.dispose();
@@ -296,7 +296,9 @@ export function diffusionGenerate(
           currentCanvas.dispose();
           currentCanvas = newCurrent;
           draftReveal.dispose();
-          draftReveal = ops.logicalNot(ops.logicalNot(acceptance)); // = acceptance
+          const notAcceptance = ops.logicalNot(acceptance);
+          draftReveal = ops.logicalNot(notAcceptance); // = acceptance
+          notAcceptance.dispose();
           draftCanvas.dispose();
           draftCanvas = ops.reshape(argmaxCanvas, [1, canvasLength]);
           accepted.dispose();
@@ -341,6 +343,10 @@ export function diffusionGenerate(
           stableStop &&
           stableAndConfident(argmaxCanvas, processed, history, stabilityThreshold, stopConfidence)
         ) {
+          // Entropy sampling precomputes the next step's self-conditioning
+          // tensor before evaluating this stop. The break means ownership is
+          // never transferred to scEmbeddings, so release the pending value.
+          nextSc?.dispose();
           processed.dispose();
           break;
         }
@@ -361,9 +367,9 @@ export function diffusionGenerate(
       draftCanvas.dispose();
 
       // Emit from the final argmax canvas.
-      const blockTokens = [...argmaxCanvas.astype(Dtype.float32).toFloat32()].map((x) =>
-        Math.round(x),
-      );
+      const argmaxFloat = argmaxCanvas.astype(Dtype.float32);
+      const blockTokens = [...argmaxFloat.toFloat32()].map((x) => Math.round(x));
+      argmaxFloat.dispose();
       argmaxCanvas.dispose();
       blocks.push(blockTokens);
       totalSteps += stepsThisCanvas;

package/src/download.ts

@@ -4,7 +4,7 @@
 // lore"): Xet stalls (we speak plain HTTPS resolve/CDN), no resume on
 // flaky links (we Range-resume partial blobs), and silent corruption
 // (every blob is verified — sha256 for LFS files against the API's
-// oid, git-blob sha1 for small files against blobId).
+// normalized LFS digest, git-blob sha1 for small files against blobId).
 //
 // Writes the exact huggingface_hub cache layout so the registry and
 // loaders find the result with zero changes:
@@ -18,6 +18,7 @@
 import {
   mkdirSync, existsSync, statSync, createWriteStream, renameSync, rmSync,
   symlinkSync, readFileSync, openSync, closeSync, readSync, writeSync,
+  statfsSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { DEFAULT_HUB } from "./registry";
@@ -29,8 +30,8 @@ export interface RepoFile {
   size: number;
   /** git blob sha1 (non-LFS identity, and the blob filename for non-LFS). */
   blobId: string;
-  /** LFS sha256 + size; present for large files. oid is the blob filename. */
-  lfs?: { oid: string; size: number };
+  /** LFS sha256 + size; present for large files. sha256 is the blob filename. */
+  lfs?: { sha256: string; size: number };
 }
 
 export interface RepoListing {
@@ -47,6 +48,56 @@ export interface DownloadOptions {
   onProgress?: (file: string, received: number, total: number) => void;
 }
 
+export interface DownloadSpacePlan {
+  /** Bytes still absent after crediting verified blobs and resumable prefixes. */
+  remainingBytes: number;
+  /** Files that still need at least one byte. */
+  remainingFiles: number;
+  /** Files already complete in the shared HF blob store. */
+  completeFiles: number;
+  /** Existing `.incomplete` bytes that will be rehashed and resumed. */
+  resumableBytes: number;
+}
+
+/** One GiB for filesystem metadata, the final refs write, and normal host
+ * operation. The artifact bytes themselves are exact; this is deliberately a
+ * small fixed guard rather than a percentage that would add tens of GiB to a
+ * Colibri download. */
+export const DOWNLOAD_DISK_RESERVE_BYTES = 2 ** 30;
+
+/** Compute the exact remaining payload without opening or hashing any blob.
+ * A valid-size final blob is already complete; an in-range `.incomplete`
+ * prefix is credited because downloadOneLocked resumes it in place. */
+export function planDownloadSpace(
+  files: readonly RepoFile[],
+  blobsDir: string,
+): DownloadSpacePlan {
+  let remainingBytes = 0;
+  let remainingFiles = 0;
+  let completeFiles = 0;
+  let resumableBytes = 0;
+  for (const file of files) {
+    const blobId = file.lfs?.sha256 ?? file.blobId;
+    if (!blobId) throw new Error(`no blob id for ${file.rfilename}`);
+    const blobPath = join(blobsDir, blobId);
+    if (existsSync(blobPath) && statSync(blobPath).size === file.size) {
+      completeFiles++;
+      continue;
+    }
+    const partPath = `${blobPath}.incomplete`;
+    const partBytes = existsSync(partPath) ? statSync(partPath).size : 0;
+    const credited = partBytes >= 0 && partBytes <= file.size ? partBytes : 0;
+    resumableBytes += credited;
+    remainingBytes += file.size - credited;
+    remainingFiles++;
+  }
+  return { remainingBytes, remainingFiles, completeFiles, resumableBytes };
+}
+
+function formatGib(bytes: number): string {
+  return `${(bytes / 2 ** 30).toFixed(2)} GiB`;
+}
+
 /** HF auth: explicit > env > the file `hf auth login` writes. */
 export function hfToken(): string | null {
   if (process.env.HF_TOKEN) return process.env.HF_TOKEN;
@@ -114,6 +165,28 @@ function acquireLock(blobPath: string, name: string): () => void {
   throw new Error(`could not acquire ${lockPath}`);
 }
 
+/** Reject a repo file path that could escape the snapshot directory once
+ *  joined onto it. `rfilename` comes verbatim from the remote HF API's
+ *  `siblings[].rfilename` (listRepoFiles) — for a repo the caller doesn't
+ *  control (attacker-owned/attacker-referenced), that string is untrusted
+ *  input reaching a path-join + symlink write (downloadModel's
+ *  `join(snapDir, f.rfilename)` + `symlinkSync`). node:path's `join()`
+ *  normalizes `..` segments, so an rfilename like
+ *  `../../../../home/x/.ssh/authorized_keys` would otherwise resolve
+ *  OUTSIDE the intended snapshots dir and write a symlink at an arbitrary
+ *  filesystem path. Reachable over HTTP via POST /api/hub/download
+ *  (src/hub-rest.ts), which passes any caller-supplied `repo` straight
+ *  through with no allowlist — this check is the actual gate, not that
+ *  route. A leading `/` (absolute path) is equally rejected: join() would
+ *  otherwise treat it as relative to snapDir and still normalize safely,
+ *  but there's no legitimate reason a repo file entry needs one, and
+ *  rejecting it removes any doubt. */
+export function isSafeRepoFilename(rfilename: string): boolean {
+  if (!rfilename || rfilename.startsWith("/") || rfilename.includes("\0")) return false;
+  const parts = rfilename.split("/");
+  return parts.every((p) => p !== "" && p !== "." && p !== "..");
+}
+
 /** git blob identity: sha1("blob <size>\0" + content) — what blobId is. */
 export function gitBlobSha1(bytes: Uint8Array): string {
   const hasher = new Bun.CryptoHasher("sha1");
@@ -139,16 +212,34 @@ export async function listRepoFiles(
     );
   const body = (await res.json()) as {
     sha: string;
-    siblings: { rfilename: string; size?: number; blobId?: string; lfs?: { oid: string; size: number } }[];
+    siblings: {
+      rfilename: string;
+      size?: number;
+      blobId?: string;
+      // The current HF API calls this field `sha256`. Accept the older `oid`
+      // spelling too, but normalize it before the download path sees it.
+      lfs?: { sha256?: string; oid?: string; size: number };
+    }[];
   };
   return {
     sha: body.sha,
-    files: body.siblings.map((s) => ({
-      rfilename: s.rfilename,
-      size: s.lfs?.size ?? s.size ?? 0,
-      blobId: s.blobId ?? "",
-      lfs: s.lfs,
-    })),
+    files: body.siblings.map((s) => {
+      let lfs: RepoFile["lfs"];
+      if (s.lfs) {
+        const sha256 = s.lfs.sha256 ?? s.lfs.oid;
+        if (!sha256 || !/^[0-9a-f]{64}$/i.test(sha256))
+          throw new Error(`HF API returned an invalid LFS sha256 for ${s.rfilename}`);
+        lfs = { sha256: sha256.toLowerCase(), size: s.lfs.size };
+      }
+      if (!lfs && (!s.blobId || !/^[0-9a-f]{40}$/.test(s.blobId)))
+        throw new Error(`HF API returned an invalid git blob SHA-1 for ${s.rfilename}`);
+      return {
+        rfilename: s.rfilename,
+        size: lfs?.size ?? s.size ?? 0,
+        blobId: s.blobId ?? "",
+        lfs,
+      };
+    }),
   };
 }
 
@@ -294,6 +385,14 @@ export function downloadsSnapshot(): DownloadStatus[] {
   return downloadLog.slice(-5);
 }
 
+/** True when a download for this exact repoId is currently "active" in this
+ *  process's tracker (used by the Hub's POST /api/hub/download to refuse a
+ *  duplicate kick-off — same repoId, still running — rather than starting a
+ *  second writer that would race the first on the same blob lockfile). */
+export function isDownloadActive(repoId: string): boolean {
+  return downloadLog.some((d) => d.repoId === repoId && d.state === "active");
+}
+
 export async function downloadModel(
   repoId: string, opts: DownloadOptions = {},
 ): Promise<string> {
@@ -303,12 +402,44 @@ export async function downloadModel(
   const hub = opts.cacheDir ?? DEFAULT_HUB;
 
   const listing = await listRepoFiles(repoId, { ...opts, token });
+  // Fail the whole download closed (not skip-and-continue) if the repo's
+  // file listing contains a path-traversal rfilename — see
+  // isSafeRepoFilename's doc comment. This gates BOTH the CLI and the web
+  // Hub's POST /api/hub/download (src/hub-rest.ts), which accepts any
+  // caller-supplied repo string with no allowlist of its own.
+  for (const f of listing.files) {
+    if (!isSafeRepoFilename(f.rfilename)) {
+      throw new Error(`${repoId}: refusing unsafe file path in repo listing: ${JSON.stringify(f.rfilename)}`);
+    }
+  }
   const repoDir = join(hub, `models--${repoId.replaceAll("/", "--")}`);
   const blobsDir = join(repoDir, "blobs");
   const snapDir = join(repoDir, "snapshots", listing.sha);
   mkdirSync(blobsDir, { recursive: true });
   mkdirSync(join(repoDir, "refs"), { recursive: true });
 
+  // Preflight before the first network payload. This matters for direct
+  // Colibri artifacts (hundreds of GiB): discovering a full volume after the
+  // 140th shard is not a usable failure mode. Existing verified blobs and
+  // partial prefixes are credited exactly, so rerunning after interruption is
+  // both resumable and progressively cheaper.
+  const space = planDownloadSpace(listing.files, blobsDir);
+  if (space.remainingBytes > 0) {
+    const fs = statfsSync(blobsDir);
+    const availableBytes = fs.bavail * fs.bsize;
+    const requiredBytes = space.remainingBytes + DOWNLOAD_DISK_RESERVE_BYTES;
+    if (requiredBytes > availableBytes) {
+      throw new Error(
+        `insufficient disk space for ${repoId}: ${formatGib(space.remainingBytes)} ` +
+        `remains across ${space.remainingFiles} files, but only ` +
+        `${formatGib(availableBytes)} is available in ${hub} ` +
+        `(${formatGib(DOWNLOAD_DISK_RESERVE_BYTES)} safety reserve). ` +
+        `Free space or choose another cache directory, then rerun; ` +
+        `${formatGib(space.resumableBytes)} of partial data will resume.`,
+      );
+    }
+  }
+
   const status: DownloadStatus = {
     repoId, state: "active", currentFile: null,
     receivedBytes: 0, totalBytes: listing.files.reduce((a, f) => a + f.size, 0),
@@ -329,7 +460,7 @@ export async function downloadModel(
 
   try {
     for (const f of listing.files) {
-      const blobId = f.lfs?.oid ?? f.blobId;
+      const blobId = f.lfs?.sha256 ?? f.blobId;
       if (!blobId) throw new Error(`no blob id for ${f.rfilename} (API response missing ?blobs=true data)`);
       const blobPath = join(blobsDir, blobId);
 
@@ -338,7 +469,7 @@ export async function downloadModel(
         status.currentFile = f.rfilename;
         await downloadOne(url, token, blobPath, {
           size: f.size, name: f.rfilename,
-          ...(f.lfs ? { sha256: f.lfs.oid } : { sha1: f.blobId }),
+          ...(f.lfs ? { sha256: f.lfs.sha256 } : { sha1: f.blobId }),
         }, (file, received, total) => {
           status.receivedBytes = doneBytes + received;
           sampleRate(status.receivedBytes);

package/src/eval/README.md

@@ -36,8 +36,8 @@ repo rule: free-running greedy "measures chaos").
 # drift gate on an existing non-bit-exact lever (validates the harness today):
 bun scripts/eval.ts kl --candidate e4b
 
-# once a fused kernel is wired for e4b, its drift vs compat:
-bun scripts/eval.ts kl --candidate e4b --self MLX_BUN_PERF_KERNEL --ref-value 0 --cand-value 1
+# self-arm A/B on an output-affecting lever (fused-sdpa on vs off):
+bun scripts/eval.ts kl --candidate e4b --self MLX_BUN_NO_FUSED_SDPA --ref-value 1 --cand-value 0
 
 # optiq-style absolute drift vs a reference model:
 bun scripts/eval.ts kl --candidate e4b --reference <bf16-or-4bit-id>
@@ -55,9 +55,10 @@ the throughput `runs` table). Each row records the active perf levers
 
 - **M0 (done):** KL drift gate + capability score + `quality_runs` DB + CLI.
 - **M0b (done):** *serving-path* KL (`evaluateKlServingDecode` in `kl.ts`,
-  `bun scripts/eval.ts kl --decode`). Validated: identical arms → KL 0;
-  `MLX_BUN_FUSED_DECODE` tiled-decode → KL 0.27 (real drift on the quantized
-  path). Motivation below — the compat KL couldn't see it:
+  `bun scripts/eval.ts kl --decode`). Validated at the time: identical arms →
+  KL 0; the since-deleted `MLX_BUN_FUSED_DECODE` tiled-decode → KL 0.27 (real
+  drift on the quantized path — the lever was removed 2026-07-05, but the
+  validation stands). Motivation below — the compat KL couldn't see it:
   The compat `forward()` path with `makeCache()` uses **plain bf16 caches**. That is wrong
   twice over: (1) e4b's KV is **per-layer mixed 4-bit/8-bit** (group 64, from
   `kv_config.json` → `config.kvQuant`; 8-bit layers 3,4,9,10,11,14, 4-bit
@@ -67,7 +68,7 @@ the throughput `runs` table). Each row records the active perf levers
   caches, then `cache[i] = c.toQuantized(e.groupSize, e.bits)` per
   `config.kvQuant` (the logic already at `generate.ts:68-86`), so the
   teacher-forced prefill runs the real mixed-4/8-bit quantized path and the
-  perf levers (NO_FUSED_SDPA, perf-kernel) actually bite.
+  perf levers (NO_FUSED_SDPA) actually bite.
 - **M1 (done):** all six capability tasks ported + runtime-validated, plus
   `capability` aggregation and the `smoketest` (KL + GSM8K-50) gate. Datasets
   exported by `scripts/eval/export-datasets.py` → `~/.cache/mlx-bun/eval-data/`.