mlx-bun 0.0.13 → 0.3.0

package/src/eval/tasks/bfcl.ts

@@ -16,6 +16,7 @@
 
 import { generateText, loadJsonl, sampleIndices, type TaskModel } from "../runner";
 import { type ToolDefinition } from "../../chat-template";
+import { runtimeValue } from "../../runtime-config";
 
 // ---------------------------------------------------------------------------
 // Data shapes (the merged jsonl: each line = {query, answer}).
@@ -465,7 +466,7 @@ export async function evaluateBfcl(
 
   // Optiq-parity mode (DEFAULT): optiq's EXACT 200 BFCL-simple questions, scored
   // through OUR pipeline. MLX_BUN_BFCL_FROZEN=0 reverts to our copy + sampling.
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_BFCL_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_BFCL_FROZEN") !== "0");
   let items: BfclItem[];
   if (useFrozen) {
     items = loadJsonl<BfclFrozenRow>("bfcl_optiq_frozen").map((r) => ({

package/src/eval/tasks/gsm8k.ts

@@ -2,6 +2,7 @@
 // 3-shot CoT, greedy decode, extract the numeric answer, compare.
 
 import { generateText, loadJsonl, sampleIndices, type TaskModel } from "../runner";
+import { runtimeValue } from "../../runtime-config";
 
 // 3-shot exemplars (verbatim from gsm8k.py).
 const FEW_SHOT: { question: string; answer: string }[] = [
@@ -73,7 +74,7 @@ export async function evaluateGsm8k(
   // his published GSM8K used) but through OUR OWN pipeline — our few-shot builder,
   // our chat template, our scorer. If our number reproduces his, our runtime is
   // faithful. MLX_BUN_GSM8K_FROZEN=0 falls back to our own sampling of the full set.
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_GSM8K_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_GSM8K_FROZEN") !== "0");
   let rows: Gsm8kRow[];
   if (useFrozen) {
     rows = loadJsonl<Gsm8kRow>("gsm8k_optiq_frozen"); // optiq's exact draw; we use {question, answer}

package/src/eval/tasks/hashhop.ts

@@ -10,6 +10,7 @@
 // fused-attention kernel (opportunity A) has the most to prove.
 
 import { generateText, loadJsonl, type TaskModel } from "../runner";
+import { runtimeValue } from "../../runtime-config";
 
 const INSTR =
   "You will be given a list of hash assignments and a starting hash. " +
@@ -96,7 +97,7 @@ export async function evaluateHashhop(
   // RECONSTRUCTION producing DIFFERENT problems, so it cannot reproduce optiq's
   // number — the frozen problems are the only way to match. MLX_BUN_HASHHOP_FROZEN=0
   // uses our generator.
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_HASHHOP_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_HASHHOP_FROZEN") !== "0");
   if (useFrozen) {
     const rows = loadJsonl<HashhopFrozen>("hashhop_optiq_frozen");
     const hopCorrect: Record<number, number> = {};

package/src/eval/tasks/humaneval.ts

@@ -16,11 +16,12 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { generateText, loadJsonl, sampleIndices, type TaskModel } from "../runner";
+import { runtimeValue } from "../../runtime-config";
 
 // Oracle venv python — the same interpreter the Python reference uses.
 // Machine-specific: overridable via MLX_BUN_ORACLE_PYTHON (the committed default is
 // the reference box; other laptops set the env, never re-commit the path).
-const ORACLE_PYTHON = process.env.MLX_BUN_ORACLE_PYTHON ?? "/Users/joshrossi/Code/mlx-lm/.venv/bin/python";
+const ORACLE_PYTHON = runtimeValue("MLX_BUN_ORACLE_PYTHON") ?? "/Users/joshrossi/Code/mlx-lm/.venv/bin/python";
 
 interface HumanevalRow {
   task_id: string;
@@ -185,7 +186,7 @@ function runProgram(program: string, timeoutSec: number, memoryMb: number): RunR
       env,
       timeout: timeoutSec * 1000, // hard wall-clock kill
       killSignal: "SIGKILL",
-      stdio: ["ignore", "ignore", process.env.MLX_BUN_EVAL_DEBUG === "1" ? "pipe" : "ignore"],
+      stdio: ["ignore", "ignore", runtimeValue("MLX_BUN_EVAL_DEBUG") === "1" ? "pipe" : "ignore"],
       encoding: "utf8",
     });
 
@@ -219,7 +220,7 @@ export async function evaluateHumaneval(
   // Optiq-parity mode (DEFAULT): optiq's EXACT 164-problem set (he runs the full
   // HumanEval test split), scored through OUR pipeline. MLX_BUN_HUMANEVAL_FROZEN=0
   // reverts to our own copy + optional sampling.
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_HUMANEVAL_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_HUMANEVAL_FROZEN") !== "0");
   const rows = loadJsonl<HumanevalRow>(useFrozen ? "humaneval_optiq_frozen" : "humaneval");
   const idx = useFrozen
     ? Array.from({ length: rows.length }, (_, i) => i)
@@ -252,7 +253,7 @@ export async function evaluateHumaneval(
 
     const rr = runProgram(program, timeoutSec, memoryMb);
     if (rr.ok) nPass++;
-    else if (process.env.MLX_BUN_EVAL_DEBUG === "1") {
+    else if (runtimeValue("MLX_BUN_EVAL_DEBUG") === "1") {
       const err = rr.stderr ?? "";
       const reason = rr.timedOut ? "TIMEOUT"
         : completion.trim() === "" ? "EMPTY"

package/src/eval/tasks/ifeval.ts

@@ -21,6 +21,7 @@
 // default in both implementations, so behavior is identical.
 
 import { generateText, loadJsonl, sampleIndices, type TaskModel } from "../runner";
+import { runtimeValue } from "../../runtime-config";
 
 export interface IfevalInstance {
   prompt: string;
@@ -472,7 +473,7 @@ export async function evaluateIfeval(
   // Optiq-parity mode (DEFAULT): score optiq's EXACT prompt set (he runs the full
   // IFEval split — 541 prompts) through OUR verifiers + OUR chat template.
   // MLX_BUN_IFEVAL_FROZEN=0 reverts to our own copy + optional sampling.
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_IFEVAL_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_IFEVAL_FROZEN") !== "0");
   const rows = loadJsonl<IfevalRow>(useFrozen ? "ifeval_optiq_frozen" : "ifeval");
   const nSamples = opts.nSamples ?? rows.length;
   const idx = (!useFrozen && nSamples < rows.length)

package/src/eval/tasks/mmlu.ts

@@ -10,6 +10,7 @@
 // table. MLX_BUN_MMLU_FROZEN=0 falls back to our own sampling of the full 14k set.
 
 import { loadJsonl, sampleIndices, type TaskModel } from "../runner";
+import { runtimeValue } from "../../runtime-config";
 
 interface MmluRow {
   question: string;
@@ -85,7 +86,7 @@ export async function evaluateMmlu(
   // parity, not sampling. Set MLX_BUN_MMLU_FROZEN=0 (or frozen:false) to fall back to
   // our own stratified sampling of the full 14k test set (a DIFFERENT subset: JS RNG
   // ≠ numpy RandomState, so it does not match optiq's questions even at the same seed).
-  const useFrozen = opts.frozen ?? (process.env.MLX_BUN_MMLU_FROZEN !== "0");
+  const useFrozen = opts.frozen ?? (runtimeValue("MLX_BUN_MMLU_FROZEN") !== "0");
 
   const testRows = loadJsonl<MmluRow>(useFrozen ? "mmlu_optiq_frozen" : "mmlu_test");
   const devRows = loadJsonl<MmluRow>(useFrozen ? "mmlu_optiq_dev" : "mmlu_dev");

package/src/expert-io.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { nativePackDir } from "./native-pack";
 import type { MlxArray } from "./mlx/array";
 import type { MlxHandle } from "./mlx/ffi";
+import { runtimeValue } from "./runtime-config";
 
 const { cstring, i32, ptr: pointer, u32, u64 } = FFIType;
 const EBUSY = 16;
@@ -69,7 +70,8 @@ export interface ExpertIOHintSnapshot {
 
 function resolveLibrary(explicit?: string): string {
   if (explicit) return explicit;
-  if (process.env.MLX_BUN_EXPERT_IO_DYLIB) return process.env.MLX_BUN_EXPERT_IO_DYLIB;
+  const configured = runtimeValue("MLX_BUN_EXPERT_IO_DYLIB");
+  if (configured) return configured;
   const candidates = [
     join(dirname(process.execPath), "libmlx_bun_expert_io.dylib"),
     join(nativePackDir(), "libmlx_bun_expert_io.dylib"),

package/src/expert-offload.ts

@@ -16,6 +16,7 @@ import { readFileSync } from "node:fs";
 import { MmapFile } from "./mmap";
 import { MlxArray, SAFETENSORS_TO_MLX } from "./mlx/array";
 import type { SafetensorsDtype } from "./safetensors";
+import { runtimeValue } from "./runtime-config";
 
 export interface OffloadEntry {
   name: string;
@@ -71,4 +72,5 @@ export function expertOffloadArray(name: string): MlxArray | null {
   return MlxArray.fromPointer(mm.pointer(e.offset), e.shape, SAFETENSORS_TO_MLX[e.dtype]);
 }
 
-if (process.env.MLX_BUN_EXPERT_OFFLOAD) activateExpertOffload(process.env.MLX_BUN_EXPERT_OFFLOAD);
+const expertOffloadPath = runtimeValue("MLX_BUN_EXPERT_OFFLOAD");
+if (expertOffloadPath) activateExpertOffload(expertOffloadPath);

package/src/fill/echo-index.ts

@@ -0,0 +1,188 @@
+// The echo source (K3c, Lab tier) — a growing per-request k-gram index over
+// the session's own tokens, and the branch-point rule that decides how far a
+// copied span may run.
+//
+// PORT. The index is the TS port of `GrowingMatcher` from the corpus study
+// (reports/k3-replication/analyze.py): a sequence plus a k-gram → [start
+// positions] map, appended incrementally so a lookup never rescans the prefix,
+// with the bucket scan capped at the NEAREST candidates. The corpus tool ran
+// it offline over recorded turns to measure how much of an agent's output is
+// copy-determined; this runs the same structure online, over promptIds plus
+// everything emitted (injected tokens included — the model cannot tell them
+// apart, so neither does the index).
+//
+// THE INTERESTING PART is not the lookup, it is the STOPPING RULE. A match
+// tells you where this exact k-gram occurred before; it does not tell you how
+// far the future agrees with the past. So the span extends only while EVERY
+// nearby occurrence continues the same way. The moment two occurrences
+// disagree — the session history forks — the span stops. That is where
+// old-query-vs-new-query divergence lives, and delimiters fall out of it for
+// free: a closing quote is where histories fork.
+//
+// DOCTRINE. An echo span is a GUESS, unlike the schema rows. It ships under
+// policy "verify" unless it is unambiguous all the way to a delimiter-class
+// token — the engine then keeps only the prefix the model itself agrees with.
+// Lab tier: default off, and a paired A/B decides whether it ever becomes a
+// default (PLAN K3).
+import type { Proposal, ProposalSource, TokenView } from "./proposal";
+
+export interface EchoConfig {
+  /** Anchor length: the k-gram that has to match for a span to be proposed. */
+  k: number;
+  /** Longest span the source will propose (the session clamps again). */
+  maxSpan: number;
+  /** Bucket scan cap — the NEAREST occurrences win (recency is the signal;
+   *  an unbounded scan is also the only quadratic risk here). */
+  maxCandidates: number;
+  /** Stop growing the index past this many tokens (memory cap). */
+  indexMax: number;
+  /** Token ids that legitimately END a copied span (a closing quote, the
+   *  markup that follows an argument value). Derived from the template by the
+   *  strict-row compiler; empty means "no span can be asserted". */
+  delimiters: ReadonlySet<number>;
+}
+
+/** Growing k-gram index over one request's token sequence. */
+export class EchoIndex {
+  readonly #k: number;
+  readonly #indexMax: number;
+  readonly #seq: number[] = [];
+  /** hash(k-gram) → start positions, oldest first. Hash collisions are
+   *  harmless: every candidate's gram is compared id-for-id before use. */
+  readonly #buckets = new Map<number, number[]>();
+  #frozen = false;
+
+  constructor(k: number, indexMax: number) {
+    this.#k = Math.max(1, Math.floor(k));
+    this.#indexMax = Math.max(this.#k, Math.floor(indexMax));
+  }
+
+  get length(): number { return this.#seq.length; }
+  /** True once the memory cap stopped the index from growing. */
+  get frozen(): boolean { return this.#frozen; }
+
+  append(ids: readonly number[]): void {
+    for (const id of ids) {
+      if (this.#seq.length >= this.#indexMax) { this.#frozen = true; return; }
+      this.#seq.push(id);
+      const start = this.#seq.length - this.#k;
+      if (start < 0) continue;
+      const h = this.#hash(start);
+      const bucket = this.#buckets.get(h);
+      if (bucket) bucket.push(start);
+      else this.#buckets.set(h, [start]);
+    }
+  }
+
+  /** Start positions whose k-gram equals `gram` AND which have at least one
+   *  token after it, nearest (most recent) first. */
+  candidates(gram: readonly number[], cap: number): number[] {
+    if (gram.length !== this.#k) return [];
+    let h = 0x811c9dc5;
+    for (const id of gram) h = this.#mix(h, id);
+    const bucket = this.#buckets.get(h >>> 0);
+    if (!bucket) return [];
+    const out: number[] = [];
+    for (let i = bucket.length - 1; i >= 0 && out.length < cap; i--) {
+      const pos = bucket[i]!;
+      if (pos + this.#k >= this.#seq.length) continue; // no continuation yet
+      let ok = true;
+      for (let j = 0; j < this.#k; j++) {
+        if (this.#seq[pos + j] !== gram[j]) { ok = false; break; } // collision
+      }
+      if (ok) out.push(pos);
+    }
+    return out;
+  }
+
+  /** Extend forward from the given anchors while EVERY anchor agrees.
+   *  Returns the agreed continuation, whether it stopped at a fork, and how
+   *  many occurrences corroborated the WHOLE span (survivors at the last
+   *  accepted token) — one occurrence is a copy, several are a pattern. */
+  extend(
+    anchors: readonly number[], maxSpan: number, delimiters: ReadonlySet<number>,
+  ): { ids: number[]; branchStop: boolean; agreed: number } {
+    const ids: number[] = [];
+    let agreed = 0;
+    let live = anchors.map((p) => p + this.#k);
+    while (ids.length < maxSpan) {
+      let next: number | undefined;
+      let forked = false;
+      const stillLive: number[] = [];
+      for (const p of live) {
+        const v = this.#seq[p];
+        // An occurrence that ran out of history simply drops out: a prefix
+        // that ends is not evidence of disagreement.
+        if (v === undefined) continue;
+        if (next === undefined) next = v;
+        else if (v !== next) { forked = true; break; }
+        stillLive.push(p + 1);
+      }
+      // A fork means the session's own history disagrees about what comes
+      // next. That is exactly the position the model must decide for itself.
+      if (forked) return { ids, branchStop: true, agreed };
+      if (next === undefined) break; // every occurrence exhausted
+      ids.push(next);
+      agreed = stillLive.length;
+      live = stillLive;
+      // A delimiter is a legitimate END: injecting the closing quote is the
+      // point, continuing past it is not.
+      if (delimiters.has(next)) break;
+    }
+    return { ids, branchStop: false, agreed };
+  }
+
+  #hash(start: number): number {
+    let h = 0x811c9dc5;
+    for (let j = 0; j < this.#k; j++) h = this.#mix(h, this.#seq[start + j]!);
+    return h >>> 0;
+  }
+
+  #mix(h: number, id: number): number {
+    let x = h ^ id;
+    x = Math.imul(x, 0x01000193);
+    return x >>> 0;
+  }
+}
+
+/** ProposalSource over the echo index. */
+export class EchoSource implements ProposalSource {
+  readonly name = "echo";
+  readonly windowNeeded: number;
+  readonly index: EchoIndex;
+
+  constructor(private readonly config: EchoConfig, promptIds: readonly number[]) {
+    this.windowNeeded = config.k;
+    this.index = new EchoIndex(config.k, config.indexMax);
+    this.index.append(promptIds);
+  }
+
+  observe(ids: readonly number[]): void {
+    this.index.append(ids);
+  }
+
+  propose(view: TokenView): Proposal | null {
+    const { k, maxSpan, maxCandidates, delimiters } = this.config;
+    const gram = view.tail(k);
+    if (gram.length < k) return null;
+    const anchors = this.index.candidates(gram, maxCandidates);
+    if (anchors.length === 0) return null;
+    const { ids, branchStop, agreed } = this.index.extend(anchors, maxSpan, delimiters);
+    if (ids.length < 2) return null;
+    // POLICY. Assert only with CORROBORATION: several occurrences of this
+    // context all continued the same way, nothing forked, and the span stops
+    // at a delimiter-class token. A single occurrence is just a copy — and a
+    // copy will happily replay whatever followed it in the transcript,
+    // including another role's turn, so it has to be the model's call.
+    // Everything else rides policy "verify", where a wrong guess costs a
+    // rewound forward, never a wrong token.
+    const endsAtDelimiter = delimiters.has(ids[ids.length - 1]!);
+    const corroborated = agreed >= 2;
+    return {
+      ids,
+      policy: !branchStop && endsAtDelimiter && corroborated ? "assert" : "verify",
+      origin: "echo",
+      branchStop,
+    };
+  }
+}