mlx-bun 0.0.12 → 0.2.0

package/src/ssd-cache.ts

@@ -22,6 +22,7 @@ import { randomUUID } from "node:crypto";
 import { commonPrefixLength } from "./prompt-cache";
 import {
   saveKvCache, saveKvCacheAsync, loadKvCache, readKvHeader,
+  cacheHeadersTrimmable,
   type KvSaveMeta, type KvLoadExpect, type LoadedKvCache,
 } from "./kv-store";
 import type { Cache } from "./model/gemma4-base";
@@ -40,19 +41,6 @@ export interface SsdIndexEntry {
   trimmable: boolean;
 }
 
-/** Trimmability from a file header alone (mirror of the live caches'
- *  isTrimmable(): kv/qkv/turboquant always trim; rotating kinds only pre-wrap
- *  (offset < maxSize); GLM compressed kinds always trim; ssm never). Keep in
- *  sync with gemma4-base/qwen3-delta/glm52-cache. */
-const headerTrimmable = (caches: { kind: string; offset: number; maxSize?: number }[]): boolean =>
-  caches.every((c) =>
-    c.kind === "kv" || c.kind === "qkv" || c.kind === "turboquant" ||
-      c.kind === "mla" || c.kind === "mla-dsa" || c.kind === "mtp-mla"
-      ? true
-      : c.kind === "rotating" || c.kind === "rotating-qkv"
-        ? c.offset < (c.maxSize ?? 0)
-        : false);
-
 export interface SsdStoreOptions {
   dir: string;
   maxBytes: number;
@@ -91,6 +79,21 @@ export class SsdCacheStore {
     return this.#opts.maxBytes;
   }
 
+  /** Longest token prefix whose atomic cache file is present in the index. */
+  get longestDurablePrefixTokens(): number {
+    return this.#index.reduce((best, entry) => Math.max(best, entry.tokens.length), 0);
+  }
+
+  /** True when the SSD index can seed every token in this prefix. A longer
+   * trimmable descendant is equivalent to an exact boundary snapshot. */
+  hasDurablePrefix(tokens: number[], ns = ""): boolean {
+    return this.#index.some((entry) => {
+      if (entry.ns !== ns || entry.tokens.length < tokens.length) return false;
+      if (commonPrefixLength(entry.tokens, tokens) !== tokens.length) return false;
+      return entry.tokens.length === tokens.length || entry.trimmable;
+    });
+  }
+
   /** Startup recovery: rebuild the in-memory index from disk. Corrupt
    *  headers and metadata mismatches are unlinked; `.tmp` orphans reaped.
    *  Only OUR fingerprint dir is touched. Returns entries indexed. */
@@ -121,7 +124,7 @@ export class SsdCacheStore {
           const st = statSync(path);
           this.#index.push({
             path, ns: h.ns ?? "", tokens: h.tokens, bytes: st.size, mtimeMs: st.mtimeMs,
-            trimmable: headerTrimmable(h.caches),
+            trimmable: cacheHeadersTrimmable(h.caches),
           });
         } catch {
           try { rmSync(path, { force: true }); } catch {}

package/src/ssd-durability.ts

@@ -0,0 +1,195 @@
+import type { Cache } from "./model/gemma4";
+import type { PromptCacheEntry } from "./prompt-cache";
+import type { SpillItem, SpillQueue } from "./kv-store";
+
+export interface DurabilityGateway {
+  readonly busy: boolean;
+  runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+export interface DurabilityPromptCache {
+  findExact(tokens: number[], ns?: string): PromptCacheEntry | null;
+}
+
+export interface DurabilitySnapshotStats {
+  pendingSnapshots: number;
+  pendingSpills: number;
+  pendingSpillBytes: number;
+  droppedSpills: number;
+  failedSpills: number;
+}
+
+export interface DurabilityFlushResult extends DurabilitySnapshotStats {
+  durable: boolean;
+  flushedSnapshots: number;
+  missingSnapshots: number;
+  elapsedMs: number;
+}
+
+interface DirtySnapshot {
+  key: string;
+  tokens: number[];
+  ns: string;
+}
+
+type StoreOutcome = "stored" | "missing" | "failed";
+
+/**
+ * Turns debounced prompt-cache puts into a durability boundary.
+ *
+ * A dirty record stays present until SpillQueue reports that its atomic store
+ * completed. Queue drops and write failures therefore remain retryable during
+ * an explicit flush or graceful shutdown.
+ */
+export class SsdDurabilityCoordinator {
+  readonly #dirty = new Map<string, DirtySnapshot>();
+  readonly #timers = new Map<string, ReturnType<typeof setTimeout>>();
+  readonly #attempts = new Map<string, Promise<StoreOutcome>>();
+  #flush: Promise<DurabilityFlushResult> | null = null;
+
+  constructor(
+    readonly gateway: DurabilityGateway,
+    readonly promptCache: DurabilityPromptCache,
+    readonly spillQueue: SpillQueue,
+    readonly cloneCaches: (caches: Cache[]) => Cache[],
+    readonly isAlreadyDurable: (tokens: number[], ns: string) => boolean = () => false,
+    readonly debounceMs = 1_000,
+    readonly busyRetryMs = 5_000,
+  ) {}
+
+  schedule(tokens: number[], ns = ""): void {
+    if (tokens.length === 0) return;
+    // PromptCache can hold unrelated entries with the same namespace and
+    // length. Include the tokens so one conversation cannot cancel another
+    // conversation's pending durability record.
+    const key = `${ns.length}:${ns}:${tokens.join(",")}`;
+    const rec: DirtySnapshot = { key, tokens: [...tokens], ns };
+    this.#dirty.set(key, rec);
+    this.#arm(key, this.debounceMs);
+  }
+
+  get stats(): DurabilitySnapshotStats {
+    return {
+      pendingSnapshots: this.#dirty.size,
+      pendingSpills: this.spillQueue.pendingCount,
+      pendingSpillBytes: this.spillQueue.pendingBytes,
+      droppedSpills: this.spillQueue.droppedCount,
+      failedSpills: this.spillQueue.failedCount,
+    };
+  }
+
+  /** Force every dirty RAM snapshot through the queue and wait for storage. */
+  flush(): Promise<DurabilityFlushResult> {
+    if (this.#flush) return this.#flush;
+    const started = performance.now();
+    this.#flush = this.#flushInner(started).finally(() => { this.#flush = null; });
+    return this.#flush;
+  }
+
+  #arm(key: string, delayMs: number): void {
+    const old = this.#timers.get(key);
+    if (old) clearTimeout(old);
+    const timer = setTimeout(() => {
+      this.#timers.delete(key);
+      void this.#attempt(key, false);
+    }, delayMs);
+    timer.unref?.();
+    this.#timers.set(key, timer);
+  }
+
+  async #attempt(key: string, force: boolean): Promise<StoreOutcome> {
+    const running = this.#attempts.get(key);
+    if (running) {
+      const outcome = await running;
+      if (!force || !this.#dirty.has(key)) return outcome;
+    }
+
+    const rec = this.#dirty.get(key);
+    if (!rec) return "stored";
+    if (!force && this.gateway.busy) {
+      this.#arm(key, this.busyRetryMs);
+      return "failed";
+    }
+
+    const task = this.#store(rec);
+    this.#attempts.set(key, task);
+    try {
+      const outcome = await task;
+      if (outcome !== "failed" && this.#dirty.get(key) === rec)
+        this.#dirty.delete(key);
+      if (outcome === "failed" && !force && this.#dirty.get(key) === rec)
+        this.#arm(key, this.busyRetryMs);
+      return outcome;
+    } finally {
+      if (this.#attempts.get(key) === task) this.#attempts.delete(key);
+    }
+  }
+
+  async #store(rec: DirtySnapshot): Promise<StoreOutcome> {
+    let snap: SpillItem | null = null;
+    try {
+      snap = await this.gateway.runExclusive(async () => {
+        const entry = this.promptCache.findExact(rec.tokens, rec.ns);
+        if (!entry) return null;
+        return {
+          tokens: [...entry.tokens],
+          caches: this.cloneCaches(entry.caches),
+          ns: rec.ns,
+        };
+      });
+    } catch {
+      return "failed";
+    }
+    if (!snap)
+      return this.isAlreadyDurable(rec.tokens, rec.ns) ? "stored" : "missing";
+    return await this.spillQueue.enqueue(snap) ? "stored" : "failed";
+  }
+
+  async #flushInner(started: number): Promise<DurabilityFlushResult> {
+    for (const timer of this.#timers.values()) clearTimeout(timer);
+    this.#timers.clear();
+
+    let flushedSnapshots = 0;
+    let missingSnapshots = 0;
+    const droppedBefore = this.spillQueue.droppedCount;
+    const failedBefore = this.spillQueue.failedCount;
+
+    if (this.#attempts.size > 0)
+      await Promise.allSettled([...this.#attempts.values()]);
+    await this.spillQueue.drain();
+
+    // Flush one entry at a time. This prevents the queue cap from dropping a
+    // boundary snapshot while a large final snapshot is already in flight.
+    while (this.#dirty.size > 0) {
+      const keys = [...this.#dirty.keys()];
+      let progressed = false;
+      for (const key of keys) {
+        if (!this.#dirty.has(key)) continue;
+        const outcome = await this.#attempt(key, true);
+        await this.spillQueue.drain();
+        if (outcome === "stored") {
+          flushedSnapshots++;
+          progressed = true;
+        } else if (outcome === "missing") {
+          missingSnapshots++;
+          progressed = true;
+        }
+      }
+      if (!progressed) break;
+    }
+
+    const stats = this.stats;
+    return {
+      ...stats,
+      durable:
+        stats.pendingSnapshots === 0 &&
+        stats.pendingSpills === 0 &&
+        stats.droppedSpills === droppedBefore &&
+        stats.failedSpills === failedBefore &&
+        missingSnapshots === 0,
+      flushedSnapshots,
+      missingSnapshots,
+      elapsedMs: performance.now() - started,
+    };
+  }
+}

package/src/train/flash-cce.ts

@@ -37,6 +37,7 @@ import { MlxArray } from "../mlx/array";
 import { Dtype } from "../mlx/ffi";
 import * as ops from "../mlx/ops";
 import { STEEL_QMM_HEADER } from "./steel-qmm-header";
+import { runtimeValue } from "../runtime-config";
 
 /** The quantized head pieces the kernel needs (packed weight + per-group affine
  *  scale/bias + bits/group_size). Mirrors HeadQuant in loss.ts. */
@@ -392,7 +393,7 @@ function fwdSgKernel(): MetalKernel {
       inputNames: ["h", "wp", "scales", "biases", "targets", "shape", "capv"],
       outputNames: ["blockMax_out", "blockSum_out", "blockTgt_out"],
       source: FWD_SG_SOURCE,
-      header: `#include <metal_simdgroup_matrix>\n#define TG ${TG}\n#define BB ${SG_BB}\n#define BV ${SG_BV}\n#define BD ${SG_BD}\n#define BDX ${SG_BD + 4}\n#define BVX ${SG_BV + 4}\n#define CCE_SG_SKIPDQ ${process.env.MLX_BUN_CCE_SG_SKIPDQ === "1" ? 1 : 0}\n`,
+      header: `#include <metal_simdgroup_matrix>\n#define TG ${TG}\n#define BB ${SG_BB}\n#define BV ${SG_BV}\n#define BD ${SG_BD}\n#define BDX ${SG_BD + 4}\n#define BVX ${SG_BV + 4}\n#define CCE_SG_SKIPDQ ${runtimeValue("MLX_BUN_CCE_SG_SKIPDQ") === "1" ? 1 : 0}\n`,
       ensureRowContiguous: true,
     });
   }
@@ -404,7 +405,7 @@ function fwdSgKernel(): MetalKernel {
 // compute-bound regime. Removing the staging redundancy (one thread per packed
 // word; scale/bias once per group) cut it 1629→848 ms, beating the scalar
 // kernel's 1097 ms. Fall back to scalar (MLX_BUN_CCE_SCALAR=1) when H % SG_BD != 0.
-const USE_SIMDGROUP_FWD = process.env.MLX_BUN_CCE_SCALAR !== "1" && process.env.MLX_BUN_CCE_LANE !== "1";
+const USE_SIMDGROUP_FWD = runtimeValue("MLX_BUN_CCE_SCALAR") !== "1" && runtimeValue("MLX_BUN_CCE_LANE") !== "1";
 
 // Backward: dh[t,d] = Σ_v coeff_v · dequant(W_v)[d], coeff_v = g_t·(onehot_v −
 // softmax_v)·sech²_v, softmax_v = exp(softcap(logit_v) − lse_t). Two-phase per
@@ -549,7 +550,7 @@ function bwdKernel(daccN: number): MetalKernel {
       inputNames: ["h", "wp", "scales", "biases", "targets", "lse", "gv", "shape", "capv"],
       outputNames: ["dh"],
       source: BWD_SOURCE,
-      header: `#define TG ${TG}\n#define BLOCK_B ${BLOCK_B_BWD}\n#define DACC_N ${daccN}\n#define CCE_BWD_SKIP_P2DQ ${process.env.MLX_BUN_CCE_BWD_SKIP_P2DQ === "1" ? 1 : 0}\n#define CCE_BWD_SKIP_P2 ${process.env.MLX_BUN_CCE_BWD_SKIP_P2 === "1" ? 1 : 0}\n`,
+      header: `#define TG ${TG}\n#define BLOCK_B ${BLOCK_B_BWD}\n#define DACC_N ${daccN}\n#define CCE_BWD_SKIP_P2DQ ${runtimeValue("MLX_BUN_CCE_BWD_SKIP_P2DQ") === "1" ? 1 : 0}\n#define CCE_BWD_SKIP_P2 ${runtimeValue("MLX_BUN_CCE_BWD_SKIP_P2") === "1" ? 1 : 0}\n`,
       ensureRowContiguous: true,
       atomicOutputs: true, // dh is summed across the NBLK vocab-block programs
     });
@@ -735,7 +736,7 @@ const BWD_SG_SOURCE = String.raw`
 // (The ~3.5× figure floating around older notes was the retired SG kernel, not
 // steel.) MLX_BUN_CCE_BWD_FILTER_EPS=0 restores exact gradients — eps "0"
 // compiles the filter OUT (#if CCE_BWD_FILTER 0), the identical pre-flip kernel.
-const BWD_FILTER_EPS = process.env.MLX_BUN_CCE_BWD_FILTER_EPS ?? "1e-5";
+const BWD_FILTER_EPS = runtimeValue("MLX_BUN_CCE_BWD_FILTER_EPS") ?? "1e-5";
 // blockMax vocab-block early-exit eps (skip whole cold (token-block,vocab-block) programs
 // — attacks BOTH phases). DEFAULT ON at 1e-5 (flipped 2026-07-02). It is ~LOSSLESS when
 // it fires (only skips blocks whose max prob < eps AND which lack the target → ~0
@@ -744,7 +745,7 @@ const BWD_FILTER_EPS = process.env.MLX_BUN_CCE_BWD_FILTER_EPS ?? "1e-5";
 // at ≤0.004% dh; COMBINED with the coeff filter at 1e-5/1e-5 the backward is 1.71×
 // (CPM5) / 3.16× (e4b) vs exact. Fires only when the caller supplies blockMax (the
 // production head does); MLX_BUN_CCE_BWD_BLOCK_EPS=0 disables (compiled out).
-const BWD_BLOCK_EPS = process.env.MLX_BUN_CCE_BWD_BLOCK_EPS ?? "1e-5";
+const BWD_BLOCK_EPS = runtimeValue("MLX_BUN_CCE_BWD_BLOCK_EPS") ?? "1e-5";
 const _bwdSgKernels = new Map<string, MetalKernel>();
 function bwdSgKernel(dimTiles: number, filterEps: string, blockEps: string): MetalKernel {
   const filterOn = Number.parseFloat(filterEps) > 0 ? 1 : 0;
@@ -1061,9 +1062,9 @@ export function flashCceForward(
   // tiling is clean (H,V,blockV all % 32). MLX_BUN_CCE_NOSTEEL=1 falls back to the
   // old kernels (simdgroup / scalar / lane).
   const blockV0 = Math.ceil(V / NBLK);
-  const useSteel = process.env.MLX_BUN_CCE_NOSTEEL !== "1" && H % 32 === 0 && V % 32 === 0 && blockV0 % 32 === 0;
+  const useSteel = runtimeValue("MLX_BUN_CCE_NOSTEEL") !== "1" && H % 32 === 0 && V % 32 === 0 && blockV0 % 32 === 0;
   const useSimd = !useSteel && USE_SIMDGROUP_FWD && H % SG_BD === 0;
-  if (!useSteel && process.env.MLX_BUN_CCE_NOSTEEL !== "1") {
+  if (!useSteel && runtimeValue("MLX_BUN_CCE_NOSTEEL") !== "1") {
     // NOTE blockV0 = ceil(V/NBLK) can violate %32 even when V%32==0 (e.g. V=50304)
     const fails = [
       H % 32 !== 0 ? `H%32!=0 (H=${H})` : null,
@@ -1072,7 +1073,7 @@ export function flashCceForward(
     ].filter(Boolean).join(", ");
     warnSteelFallback("forward", fails, useSimd ? "simdgroup kernel" : "scalar/lane kernel");
   }
-  const useLane = !useSteel && !useSimd && process.env.MLX_BUN_CCE_LANE === "1" && WPR % 32 === 0;
+  const useLane = !useSteel && !useSimd && runtimeValue("MLX_BUN_CCE_LANE") === "1" && WPR % 32 === 0;
   const kernel = useSteel ? fwdSteelKernel(GS, head.bits) : useSimd ? fwdSgKernel() : useLane ? fwdLaneKernel() : fwdKernel();
   const tokTile = useSteel ? STEEL_BM : useSimd ? SG_BB : BLOCK_B;
   // steel + simdgroup read h as [M, H] (M on axis 0); lane + scalar read h TRANSPOSED
@@ -1178,11 +1179,11 @@ export function flashCceBackward(
   const blockV0 = Math.ceil(V / NBLK);
   // HTw == group_size for the phase-2 QuantizedBlockLoader (one group per H-tile); needs
   // H % GS == 0 (always, GR*GS=H) and GS % 32 == 0 (TNv = GS/32 frags per H-tile integral).
-  const useSteel = process.env.MLX_BUN_CCE_BWD_NOSTEEL !== "1" && H % 32 === 0 && V % 32 === 0 && blockV0 % 32 === 0 && H % GS === 0 && GS % 32 === 0;
+  const useSteel = runtimeValue("MLX_BUN_CCE_BWD_NOSTEEL") !== "1" && H % 32 === 0 && V % 32 === 0 && blockV0 % 32 === 0 && H % GS === 0 && GS % 32 === 0;
   // simdgroup_matrix phase-2 GEMM is the next tier (5512→3913 ms, 1.41×) when the H
   // tiling is clean; MLX_BUN_CCE_BWD_SCALAR=1 forces the float4 scalar kernel.
-  const useSg = !useSteel && process.env.MLX_BUN_CCE_BWD_SCALAR !== "1" && H % (SGN * 8) === 0 && H % SG_BD === 0;
-  if (!useSteel && process.env.MLX_BUN_CCE_BWD_NOSTEEL !== "1") {
+  const useSg = !useSteel && runtimeValue("MLX_BUN_CCE_BWD_SCALAR") !== "1" && H % (SGN * 8) === 0 && H % SG_BD === 0;
+  if (!useSteel && runtimeValue("MLX_BUN_CCE_BWD_NOSTEEL") !== "1") {
     // NOTE blockV0 = ceil(V/NBLK) can violate %32 even when V%32==0 (e.g. V=50304)
     const fails = [
       H % 32 !== 0 ? `H%32!=0 (H=${H})` : null,

package/src/train/forward.ts

@@ -20,6 +20,7 @@ import { MlxArray } from "../mlx/array";
 import { Dtype } from "../mlx/ffi";
 import * as ops from "../mlx/ops";
 import { createCausalMask, type Cache, type Mask } from "../model/gemma4-base";
+import { SSMCache } from "../model/qwen3-delta";
 import type { RuntimeModel } from "../model/factory";
 
 /** Stateless cache for the training forward. Training is always a single
@@ -57,6 +58,35 @@ export class TrainingCache implements Cache {
   }
 }
 
+/** Stateless DeltaNet stand-in (same re-runnability contract as
+ *  TrainingCache): state WRITES are discarded immediately, so a gradient-
+ *  checkpoint recompute re-enters with the identical null-state conditions;
+ *  reads always yield null (zeros inside the kernel) — a full-sequence
+ *  forward from t=0, exactly the training/perplexity semantics. Before this
+ *  existed, qwen3_5 routed its DeltaNet layers into plain TrainingCache and
+ *  threw on the missing conv/recurrent/advance surface (the recorded
+ *  "mlx-bun perplexity cannot score qwen3_5" gap). */
+export class TrainingSSMCache implements Cache {
+  offset = 0;
+  specRound: null = null;
+  get conv(): MlxArray | null { return null; }
+  set conv(v: MlxArray | null) { v?.dispose(); }
+  get recurrent(): MlxArray | null { return null; }
+  set recurrent(v: MlxArray | null) { v?.dispose(); }
+  advance(_n: number): void { /* offset pinned at 0 */ }
+  rowOffset(_i: number): number { return 0; }
+  updateAndFetch(): [MlxArray, MlxArray] {
+    throw new Error("TrainingSSMCache: DeltaNet layers do not use the KV path");
+  }
+  makeMask(_N: number, _w: number | null): Mask {
+    return { mode: "", arr: null }; // ssm_mask is None at B=1 (SSMCache parity)
+  }
+  state(): MlxArray[] { return []; }
+  isTrimmable(): boolean { return true; }
+  trim(_n: number): void { /* stateless */ }
+  dispose(): void { /* owns no arrays */ }
+}
+
 /** Run a full-sequence forward for training.
  *  @param ids int32 array [B, L].
  *  @returns logits [B, L, V] (caller owns; dispose when done).
@@ -90,7 +120,8 @@ export function trainForwardHidden(
   // B=1 / no padding: stateless offset-0 caches (one per donor layer), so the
   // forward is pure and safe to recompute under gradient checkpointing.
   const probe = model.makeCache();
-  const cache: Cache[] = probe.map(() => new TrainingCache());
+  const cache: Cache[] = probe.map((c) =>
+    c instanceof SSMCache ? new TrainingSSMCache() : new TrainingCache());
   for (const c of probe) c.dispose();
   try {
     return model.forwardHidden(ids, cache); // [B, L, hidden]

package/src/train/loss.ts

@@ -27,6 +27,7 @@ import { logitSoftcap } from "../model/gemma4-base";
 import { trainForward, trainForwardHidden } from "./forward";
 import { setLoraScale, type TrainableLora } from "./lora-params";
 import { flashCceForward, flashCceBackward, type FlashCceHead } from "./flash-cce";
+import { runtimeValue } from "../runtime-config";
 
 /** The quantized LM-head weights + final-logit softcap, accessed uniformly across
  *  models for the fused linear-CE head: Gemma is tied (`embed.asLinear`, softcap
@@ -1197,7 +1198,7 @@ export function fusedRespLogpMean(
   // e4b time-tie point where flash's memory win takes over) takes the EXACT
   // fused head instead — short rows get the faster exact head for free.
   // MLX_BUN_FLASH_MIN_M=0 always honors flash (the pre-dispatch behavior).
-  const flashMinM = Number(process.env.MLX_BUN_FLASH_MIN_M ?? "1024");
+  const flashMinM = Number(runtimeValue("MLX_BUN_FLASH_MIN_M") ?? "1024");
   const useFlash = flash && (flashMinM <= 0 || M >= flashMinM);
   let op: CustomVjp;
   if (useFlash) {

package/src/train/segmented.ts

@@ -38,6 +38,7 @@ import { MlxArray } from "../mlx/array";
 import * as ops from "../mlx/ops";
 import { peakMemory } from "../mlx/ffi";
 import { Vjp } from "../mlx/autograd";
+import { runtimeValue } from "../runtime-config";
 
 // MLX_BUN_SEG_MEM_LOG=1: log the within-step peak after each phase of the
 // segmented step (forward+boundaries / head vjp / each segment backward).
@@ -46,7 +47,7 @@ import { Vjp } from "../mlx/autograd";
 // (This is how the backlog-#2 refutation below was measured. An inter-segment
 // clearCache was also tried and had NO effect — the watermark is live memory,
 // not allocator cache retention.)
-const SEG_MEM = process.env.MLX_BUN_SEG_MEM_LOG === "1";
+const SEG_MEM = runtimeValue("MLX_BUN_SEG_MEM_LOG") === "1";
 const segMem = (label: string): void => {
   if (SEG_MEM) console.log(`  [seg-mem] ${label}: peak=${(peakMemory() / 1e9).toFixed(2)} GB`);
 };
@@ -68,7 +69,7 @@ import { prefixSharedCaches, prefixGatherIdx, branchLogpMeanGathered, blockSpars
 // memory at the TOP level but not when nested in the segmented mlx_vjp (its
 // per-chunk graph isn't freed incrementally there); Checkpoint does. See
 // docs/design/orpo-training.md.
-const SEG_HEAD = process.env.MLX_BUN_SEG_HEAD ?? "checkpoint";
+const SEG_HEAD = runtimeValue("MLX_BUN_SEG_HEAD") ?? "checkpoint";
 function boundedHeadFromHidden(
   model: MiniCPM5Model | Gemma4Model, h: MlxArray, ids: number[], mask: number[],
   chunkSize: number, sink: Array<{ dispose(): void }>, span?: HeadSpan,
@@ -82,7 +83,7 @@ import { rowLength, type SftBatch, type DpoBatch } from "./dataset";
 
 // Token-chunk size for the bounded SFT head (the ORPO paths take theirs from
 // cfg.orpoChunkSize; SFT has no per-run knob, 512 matches the ORPO default).
-const SFT_HEAD_CHUNK = Number(process.env.MLX_BUN_SEG_HEAD_CHUNK ?? "512");
+const SFT_HEAD_CHUNK = Number(runtimeValue("MLX_BUN_SEG_HEAD_CHUNK") ?? "512");
 
 /** [M,V]-bounded response-only CE from post-finalNorm hidden — the SFT
  *  segmented head (kernel-review backlog #8). Same span arithmetic and

package/src/train/trainer.ts

@@ -10,8 +10,9 @@
 
 import { MlxArray, pinnedBufferCount } from "../mlx/array";
 import { clearCache, peakMemory, activeMemory, cacheMemory, resetPeakMemory } from "../mlx/ffi";
+import { runtimeValue } from "../runtime-config";
 
-const MEM_LOG = process.env.MLX_BUN_MEM_LOG === "1";
+const MEM_LOG = runtimeValue("MLX_BUN_MEM_LOG") === "1";
 const gbStr = (b: number) => `${(b / 1e9).toFixed(2)}GB`;
 import { ValueAndGrad } from "../mlx/autograd";
 import * as ops from "../mlx/ops";
@@ -543,7 +544,7 @@ async function sftLoop(
   // so a stale `export MLX_BUN_TRAIN_ATTN=flash` from a MiniCPM5 experiment
   // would otherwise ride silently into a crash mid-run. Refuse it for Gemma
   // until the >=2K re-validation lands; MiniCPM5 stays allowed.
-  if (process.env.MLX_BUN_TRAIN_ATTN === "flash") {
+  if (runtimeValue("MLX_BUN_TRAIN_ATTN") === "flash") {
     if (model instanceof Gemma4Model)
       throw new Error(
         "MLX_BUN_TRAIN_ATTN=flash is disabled for Gemma models: e4b SIGTRAPs on this " +

package/src/vision/preprocess.ts

@@ -6,7 +6,7 @@
 // 1/255 → patchify into 48×48 patch vectors with 2D grid positions →
 // pad to the 280 soft-token budget.
 //
-// Decode strategy (Bun ≥1.3.14): PNG goes straight through fast-png
+// Decode strategy (Bun ≥1.4.0): PNG goes straight through fast-png
 // (exact, lossless — the parity-golden path). Everything else (JPEG,
 // HEIC, AVIF, WebP, TIFF, GIF, BMP) is transcoded to lossless PNG by
 // Bun.Image — native OS codecs (ImageIO on macOS), EXIF auto-orient,

package/src/vision/prompt.ts

@@ -26,7 +26,7 @@ import type { LoadedTokenizer } from "../tokenizer";
 import type { AudioTower } from "../audio/conformer";
 import { audioSoftTokenCount, decodeAudio } from "../audio/decode";
 import { extractMelFeatures } from "../audio/features";
-import { fetchMediaBytes } from "../media-fetch";
+import { fetchMediaBytes, videoMediaFetchPolicy } from "../media-fetch";
 
 /** Common contract for both vision towers (encoder-free gemma4_unified in
  *  ./embedder.ts and the SigLIP encoder in ./siglip.ts): preprocess image
@@ -117,6 +117,52 @@ export async function extractImages(
   return { messages: out, images };
 }
 
+/** Extract video bytes from content parts, rewriting to the template's
+ *  {type:"video"} form. Accepts {type:"video_url", video_url:{url}} (data:
+ *  or http(s), same SSRF guard as images with the larger video body cap)
+ *  and {type:"video"} with base64 `data`. Decode to frames happens later
+ *  (vision/video-frames.ts — the AVFoundation sidecar). */
+export async function extractVideos(
+  messages: ChatMessage[],
+): Promise<{ messages: ChatMessage[]; videos: Uint8Array[] }> {
+  const videos: Uint8Array[] = [];
+  const out: ChatMessage[] = [];
+  for (const m of messages) {
+    if (!Array.isArray(m.content)) {
+      out.push(m);
+      continue;
+    }
+    const parts: Array<Record<string, unknown>> = [];
+    for (const part of m.content) {
+      if (part.type === "video_url") {
+        const url = (part.video_url as { url: string } | undefined)?.url
+          ?? (part.video_url as unknown as string);
+        if (typeof url !== "string") throw new Error("video_url part missing url");
+        videos.push(await fetchMediaBytes(url, "video"));
+        parts.push({ type: "video" });
+      } else if (part.type === "video") {
+        if (typeof part.data === "string") {
+          // Same cap as fetched/data:-URL video bodies — the inline base64
+          // form must not be the uncapped route.
+          const cap = videoMediaFetchPolicy().maxBytes;
+          if (part.data.length * 0.75 > cap)
+            throw new Error(
+              `video part exceeds the ${Math.round(cap / 1024 / 1024)} MB cap`,
+            );
+          videos.push(Uint8Array.from(Buffer.from(part.data, "base64")));
+          parts.push({ type: "video" });
+        } else {
+          throw new Error("video part requires base64 `data`");
+        }
+      } else {
+        parts.push(part);
+      }
+    }
+    out.push({ ...m, content: parts });
+  }
+  return { messages: out, videos };
+}
+
 /** Extract audio bytes from OpenAI-style content parts, rewriting the parts
  *  to the template's {type:"audio"} form. Accepts the OpenAI-canonical
  *  {type:"input_audio", input_audio:{data:<b64>, format:...}} plus optiq's