mlx-bun 0.0.11 → 0.0.13

package/src/eval/tasks/ifeval.ts

@@ -5,13 +5,14 @@
 // 'banana'", "respond in JSON"). Each example carries one or more constraint
 // instructions; we generate a response and run the corresponding verifier.
 //
-// We report prompt-level pass rates (matches the official methodology):
-//   * strict — fraction of examples where ALL of the prompt's instructions
-//     pass on the raw response.
-//   * loose  — same but with response-cleaning preprocessing (strip leading
-//     "Sure, here is…" boilerplate and outer code fences).
-// The primary metric (`accuracy`) is prompt-level strict, headlined by
-// ifeval.py's IFEvalResult.__str__.
+// We report strict and loose metrics at both official granularities:
+//   * prompt — fraction of examples where ALL instructions pass;
+//   * instruction — fraction of supported individual checks that pass.
+// Loose mode first strips leading "Sure, here is…" boilerplate and outer code
+// fences. The primary metric (`accuracy`) remains prompt-level strict, as
+// headlined by ifeval.py's IFEvalResult.__str__. Unknown instruction IDs retain
+// optiq's prompt-pass behavior but are excluded from instruction accuracy and
+// reported through the coverage object.
 //
 // Faithful port note: several verifiers below read kwarg keys that the dataset
 // rows never populate (e.g. _check_capital_words_count / _check_letter_frequency
@@ -21,18 +22,56 @@
 
 import { generateText, loadJsonl, sampleIndices, type TaskModel } from "../runner";
 
-interface IfevalRow {
-  key: number;
+export interface IfevalInstance {
   prompt: string;
   instruction_id_list: string[];
   kwargs: Record<string, unknown>[];
 }
 
+interface IfevalRow extends IfevalInstance {
+  key: number;
+}
+
+export interface IfevalCoverage {
+  /** Prompts for which every instruction ID has a registered verifier. */
+  fullySupportedPrompts: number;
+  promptCoverage: number;
+  /** Registered instruction checks; unknown IDs are excluded from accuracy. */
+  supportedInstructions: number;
+  totalInstructions: number;
+  instructionCoverage: number;
+  unhandledInstructionCounts: Record<string, number>;
+}
+
 export interface IfevalResult {
   nTotal: number;
   strictAcc: number; // 0..1 — prompt-level strict pass rate
   looseAcc: number; // 0..1 — prompt-level loose pass rate
   accuracy: number; // 0..1 — primary metric == strictAcc (ifeval.py headline)
+  strictInstructionAcc: number;
+  looseInstructionAcc: number;
+  coverage: IfevalCoverage;
+}
+
+export interface IfevalVerification {
+  /**
+   * One result per requested instruction. null means the instruction ID is
+   * unhandled and therefore excluded from instruction-level accuracy.
+   */
+  instructionPasses: Array<boolean | null>;
+  /** OptiQ parity: unhandled IDs do not make the prompt fail. */
+  pass: boolean;
+  unhandled: string[];
+}
+
+export interface IfevalInstanceScore {
+  strict: IfevalVerification;
+  loose: IfevalVerification;
+}
+
+export interface IfevalPair {
+  instance: IfevalInstance;
+  response: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,20 +317,24 @@ const VERIFIERS = new Map<string, Verifier>([
   ["detectable_content:postscript", alwaysPass],
 ]);
 
+export const SUPPORTED_INSTRUCTIONS = new Set(VERIFIERS.keys());
+
 /**
  * Verify one response against its instruction list.
- * Returns { pass, unhandled }. An instruction_id with no registered verifier is
- * treated as a PASS (does not affect `pass`) and only recorded in `unhandled` for
- * visibility — matching ifeval.py's `continue` policy EXACTLY, so our strict_acc
- * reproduces optiq's. (Our VERIFIERS map mirrors his `_VERIFIERS` 1:1, so unhandled
- * is empty for the standard IFEval set anyway; this only matters for parity safety.)
+ * `instructionPasses` is aligned with the requested IDs and uses null for
+ * unhandled IDs. An ID with no registered verifier does not affect prompt
+ * `pass` and is recorded in `unhandled` — matching ifeval.py's `continue`
+ * policy exactly, so strict prompt accuracy reproduces OptiQ's. The canonical
+ * aggregate excludes those nulls from instruction accuracy and reports them
+ * through coverage.
  */
 export function verifyResponse(
   response: string,
   instructionIds: string[],
   kwargsList: Kw[],
-): { pass: boolean; unhandled: string[] } {
+): IfevalVerification {
   const unhandled: string[] = [];
+  const instructionPasses: Array<boolean | null> = [];
   let pass = true;
   for (let i = 0; i < instructionIds.length; i++) {
     const iid = instructionIds[i]!;
@@ -299,15 +342,19 @@ export function verifyResponse(
     const verifier = VERIFIERS.get(iid);
     if (verifier === undefined) {
       unhandled.push(iid);
+      instructionPasses.push(null);
       continue; // ifeval.py: treat an unhandled instruction as PASS (don't touch `pass`)
     }
     try {
-      if (!verifier(response, kw)) pass = false;
+      const followed = verifier(response, kw);
+      instructionPasses.push(followed);
+      if (!followed) pass = false;
     } catch {
+      instructionPasses.push(false);
       pass = false;
     }
   }
-  return { pass, unhandled };
+  return { instructionPasses, pass, unhandled };
 }
 
 /** Loose-mode preprocessing — mirrors ifeval.py `_loose_clean`. */
@@ -328,6 +375,92 @@ export function stripThinking(response: string): string {
   return idx === -1 ? response : response.slice(idx + "</think>".length);
 }
 
+/** Score one generated response with the canonical strict + loose contract. */
+export function scoreIfevalInstance(
+  instance: IfevalInstance,
+  rawResponse: string,
+): IfevalInstanceScore {
+  const response = stripThinking(rawResponse);
+  return {
+    strict: verifyResponse(
+      response,
+      instance.instruction_id_list,
+      instance.kwargs,
+    ),
+    loose: verifyResponse(
+      looseClean(response),
+      instance.instruction_id_list,
+      instance.kwargs,
+    ),
+  };
+}
+
+/**
+ * Canonical IFEval aggregation.
+ *
+ * Prompt accuracy follows the OptiQ reference behavior: an unknown instruction
+ * is recorded but does not fail its prompt. Instruction accuracy has a stricter
+ * denominator contract: unknown instructions are excluded and their coverage
+ * is reported explicitly, so an incomplete verifier registry cannot silently
+ * inflate that metric.
+ */
+export function scoreIfevalPairs(pairs: IfevalPair[]): IfevalResult {
+  let strictPrompts = 0;
+  let loosePrompts = 0;
+  let fullySupportedPrompts = 0;
+  let strictInstructions = 0;
+  let looseInstructions = 0;
+  let supportedInstructions = 0;
+  let totalInstructions = 0;
+  const unhandledCounts = new Map<string, number>();
+
+  for (const { instance, response } of pairs) {
+    const score = scoreIfevalInstance(instance, response);
+    if (score.strict.pass) strictPrompts++;
+    if (score.loose.pass) loosePrompts++;
+    if (score.strict.unhandled.length === 0) fullySupportedPrompts++;
+    totalInstructions += instance.instruction_id_list.length;
+
+    for (let i = 0; i < score.strict.instructionPasses.length; i++) {
+      const strict = score.strict.instructionPasses[i];
+      if (strict === null) continue;
+      supportedInstructions++;
+      if (strict) strictInstructions++;
+      if (score.loose.instructionPasses[i]) looseInstructions++;
+    }
+    for (const id of score.strict.unhandled)
+      unhandledCounts.set(id, (unhandledCounts.get(id) ?? 0) + 1);
+  }
+
+  const nTotal = pairs.length;
+  const strictAcc = nTotal ? strictPrompts / nTotal : 0;
+  const looseAcc = nTotal ? loosePrompts / nTotal : 0;
+  return {
+    nTotal,
+    strictAcc,
+    looseAcc,
+    accuracy: strictAcc,
+    strictInstructionAcc: supportedInstructions
+      ? strictInstructions / supportedInstructions
+      : 0,
+    looseInstructionAcc: supportedInstructions
+      ? looseInstructions / supportedInstructions
+      : 0,
+    coverage: {
+      fullySupportedPrompts,
+      promptCoverage: nTotal ? fullySupportedPrompts / nTotal : 0,
+      supportedInstructions,
+      totalInstructions,
+      instructionCoverage: totalInstructions
+        ? supportedInstructions / totalInstructions
+        : 0,
+      unhandledInstructionCounts: Object.fromEntries(
+        [...unhandledCounts.entries()].sort(([a], [b]) => a.localeCompare(b)),
+      ),
+    },
+  };
+}
+
 export async function evaluateIfeval(
   tm: TaskModel,
   opts: { nSamples?: number; maxTokens?: number; seed?: number; frozen?: boolean } = {},
@@ -348,7 +481,7 @@ export async function evaluateIfeval(
 
   let nStrict = 0;
   let nLoose = 0;
-  const unhandledCounts = new Map<string, number>();
+  const pairs: IfevalPair[] = [];
 
   for (let k = 0; k < idx.length; k++) {
     const item = rows[idx[k]!]!;
@@ -356,14 +489,16 @@ export async function evaluateIfeval(
     const kwList = item.kwargs ?? iids.map(() => ({}));
 
     const raw = await generateText(tm, item.prompt, { maxTokens, useChat: true });
-    const response = stripThinking(raw);
-
-    const strict = verifyResponse(response, iids, kwList);
-    const loose = verifyResponse(looseClean(response), iids, kwList);
-    for (const u of strict.unhandled) unhandledCounts.set(u, (unhandledCounts.get(u) ?? 0) + 1);
+    const instance: IfevalInstance = {
+      prompt: item.prompt,
+      instruction_id_list: iids,
+      kwargs: kwList,
+    };
+    const score = scoreIfevalInstance(instance, raw);
+    pairs.push({ instance, response: raw });
 
-    if (strict.pass) nStrict++;
-    if (loose.pass) nLoose++;
+    if (score.strict.pass) nStrict++;
+    if (score.loose.pass) nLoose++;
 
     if ((k + 1) % 10 === 0 || k + 1 === idx.length)
       process.stderr.write(
@@ -372,8 +507,12 @@ export async function evaluateIfeval(
   }
   process.stderr.write("\n");
 
-  if (unhandledCounts.size) {
-    const top = [...unhandledCounts.entries()].sort((a, b) => b[1] - a[1]);
+  const result = scoreIfevalPairs(pairs);
+  const unhandledCounts = Object.entries(
+    result.coverage.unhandledInstructionCounts,
+  );
+  if (unhandledCounts.length) {
+    const top = unhandledCounts.sort((a, b) => b[1] - a[1]);
     process.stderr.write(
       "  ifeval unported instruction ids (treated as PASS, per optiq): " +
         top.map(([k, v]) => `${k}(${v})`).join(", ") +
@@ -381,8 +520,5 @@ export async function evaluateIfeval(
     );
   }
 
-  const nTotal = idx.length;
-  const strictAcc = nTotal ? nStrict / nTotal : 0;
-  const looseAcc = nTotal ? nLoose / nTotal : 0;
-  return { nTotal, strictAcc, looseAcc, accuracy: strictAcc };
+  return result;
 }

package/src/expert-io.ts

@@ -0,0 +1,391 @@
+import { dlopen, FFIType, ptr as ffiPtr, toArrayBuffer } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { nativePackDir } from "./native-pack";
+import type { MlxArray } from "./mlx/array";
+import type { MlxHandle } from "./mlx/ffi";
+
+const { cstring, i32, ptr: pointer, u32, u64 } = FFIType;
+const EBUSY = 16;
+const EAGAIN = 35;
+const MAX_SEGMENTS = 8;
+const HINT_STATS = 8;
+
+type ExpertIOState = "open" | "closing" | "closed";
+
+/**
+ * Poll an asynchronous expert read without letting an await cross the
+ * store's lifetime boundary. Exported only so the race can be tested with a
+ * deterministic fake poller rather than relying on native I/O timing.
+ */
+export async function _pollExpertReadUntilReady(
+  assertOpen: () => void,
+  poll: () => number,
+  sleep: () => Promise<void> = () => Bun.sleep(1),
+): Promise<void> {
+  for (;;) {
+    assertOpen();
+    const status = poll();
+    if (status === 0) return;
+    if (status !== EAGAIN) throw new Error(`expert read failed: errno ${status}`);
+    await sleep();
+  }
+}
+
+export interface ExpertIOOptions {
+  slots: number;
+  slotBytes: number;
+  workers?: number;
+  alignment?: number;
+  noCache?: boolean;
+  /** Keep loaded anonymous slot pages out of the macOS compressor. */
+  wireSlots?: boolean;
+  libraryPath?: string;
+}
+
+export interface ExpertIOSegment {
+  readonly file: number;
+  readonly offset: number;
+  readonly destination: number;
+  readonly length: number;
+}
+
+export interface ExpertIOHintSegment {
+  readonly file: number;
+  readonly offset: number;
+  readonly length: number;
+}
+
+export interface ExpertIOHintSnapshot {
+  readonly submitted: number;
+  readonly completed: number;
+  readonly dropped: number;
+  readonly operations: number;
+  readonly bytes: number;
+  readonly errors: number;
+  readonly queueDepth: number;
+  readonly inFlight: number;
+}
+
+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 candidates = [
+    join(dirname(process.execPath), "libmlx_bun_expert_io.dylib"),
+    join(nativePackDir(), "libmlx_bun_expert_io.dylib"),
+    join(import.meta.dir, "..", "dist-native", "libmlx_bun_expert_io.dylib"),
+  ];
+  return candidates.find(existsSync) ?? candidates[0]!;
+}
+
+export class ExpertIOSlabStore {
+  readonly files: readonly string[];
+  readonly slots: number;
+  readonly slotBytes: number;
+  #lib: any;
+  #handle: bigint;
+  #state: ExpertIOState = "open";
+  readonly #wireSlots: boolean;
+
+  constructor(path: string | readonly string[], options: ExpertIOOptions) {
+    if (!Number.isSafeInteger(options.slots) || options.slots <= 0) throw new Error("slots must be positive");
+    if (!Number.isSafeInteger(options.slotBytes) || options.slotBytes <= 0) throw new Error("slotBytes must be positive");
+    const paths = typeof path === "string" ? [path] : [...path];
+    if (paths.length === 0 || paths.some((entry) => entry.length === 0))
+      throw new Error("expert slab store requires at least one file");
+    this.files = Object.freeze(paths);
+    this.slots = options.slots; this.slotBytes = options.slotBytes;
+    this.#wireSlots = options.wireSlots === true;
+    this.#lib = dlopen(resolveLibrary(options.libraryPath), {
+      mlx_bun_expert_io_open: { args: [cstring, u32, u64, u64, u32, i32], returns: u64 },
+      mlx_bun_expert_io_open_many: {
+        args: [pointer, u64, u32, u32, u64, u64, u32, i32],
+        returns: u64,
+      },
+      mlx_bun_expert_io_submit: { args: [u64, u32, u64, u64, u64], returns: i32 },
+      mlx_bun_expert_io_submitv: {
+        args: [u64, u32, u64, pointer, pointer, pointer, pointer, u32],
+        returns: i32,
+      },
+      mlx_bun_expert_io_hintv: {
+        args: [u64, pointer, pointer, pointer, u32],
+        returns: i32,
+      },
+      mlx_bun_expert_io_hint_stats: {
+        args: [u64, pointer, u32],
+        returns: i32,
+      },
+      mlx_bun_expert_io_wait: { args: [u64, u32, u64], returns: i32 },
+      mlx_bun_expert_io_poll: { args: [u64, u32, u64], returns: i32 },
+      mlx_bun_expert_io_cancel: { args: [u64, u32, u64], returns: i32 },
+      mlx_bun_expert_io_lease: { args: [u64, u32, u64, i32], returns: i32 },
+      mlx_bun_expert_io_release: { args: [u64, u32, u64, i32], returns: i32 },
+      mlx_bun_expert_io_discard: { args: [u64, u32, u64], returns: i32 },
+      mlx_bun_expert_io_set_wiring: { args: [u64, i32], returns: i32 },
+      mlx_bun_process_phys_footprint: { args: [], returns: u64 },
+      mlx_bun_process_compressed: { args: [], returns: u64 },
+      mlx_bun_expert_io_ptr: { args: [u64, u32, u64], returns: u64 },
+      mlx_bun_expert_io_length: { args: [u64, u32, u64], returns: u64 },
+      mlx_bun_expert_io_close: { args: [u64], returns: i32 },
+    });
+    const encoded = Buffer.from(`${paths.join("\0")}\0`);
+    this.#handle = this.#lib.symbols.mlx_bun_expert_io_open_many(
+      ffiPtr(encoded), BigInt(encoded.byteLength), paths.length,
+      options.slots, BigInt(options.slotBytes),
+      BigInt(options.alignment ?? 16 * 1024),
+      options.workers ?? 2, options.noCache === false ? 0 : 1,
+    ) as bigint;
+    if (this.#handle === 0n) {
+      this.#lib.close();
+      throw new Error(`failed to open expert slab store: ${paths.join(", ")}`);
+    }
+    if (this.#wireSlots) {
+      const status = this.#lib.symbols.mlx_bun_expert_io_set_wiring(
+        this.#handle,
+        1,
+      );
+      if (status !== 0) {
+        this.#lib.symbols.mlx_bun_expert_io_close(this.#handle);
+        this.#lib.close();
+        throw new Error(`failed to enable expert slot wiring: errno ${status}`);
+      }
+    }
+  }
+
+  submit(slot: number, generation: bigint, offset: number, length: number): void {
+    this.submitSegments(slot, generation, [{
+      file: 0,
+      offset,
+      destination: 0,
+      length,
+    }]);
+  }
+
+  submitSegments(
+    slot: number,
+    generation: bigint,
+    segments: readonly ExpertIOSegment[],
+  ): void {
+    this.#checkSlot(slot);
+    if (generation <= 0n) throw new RangeError("expert generation must be positive");
+    if (segments.length === 0 || segments.length > MAX_SEGMENTS)
+      throw new RangeError(`expert read requires 1..${MAX_SEGMENTS} segments`);
+    const files = new Uint32Array(segments.length);
+    const offsets = new BigUint64Array(segments.length);
+    const destinations = new BigUint64Array(segments.length);
+    const lengths = new BigUint64Array(segments.length);
+    let extent = 0;
+    for (let index = 0; index < segments.length; index++) {
+      const segment = segments[index]!;
+      if (!Number.isSafeInteger(segment.file) || segment.file < 0 ||
+          segment.file >= this.files.length)
+        throw new RangeError(`expert segment ${index} file is out of range`);
+      if (!Number.isSafeInteger(segment.offset) || segment.offset < 0)
+        throw new RangeError(`expert segment ${index} offset must be non-negative`);
+      if (!Number.isSafeInteger(segment.destination) || segment.destination < 0)
+        throw new RangeError(`expert segment ${index} destination must be non-negative`);
+      if (!Number.isSafeInteger(segment.length) || segment.length <= 0)
+        throw new RangeError(`expert segment ${index} length must be positive`);
+      const end = segment.destination + segment.length;
+      if (!Number.isSafeInteger(end) || end > this.slotBytes)
+        throw new RangeError(`expert segment ${index} exceeds slot capacity`);
+      for (let prior = 0; prior < index; prior++) {
+        const other = segments[prior]!;
+        const otherEnd = other.destination + other.length;
+        if (segment.destination < otherEnd && other.destination < end)
+          throw new RangeError(`expert segment ${index} overlaps segment ${prior}`);
+      }
+      files[index] = segment.file;
+      offsets[index] = BigInt(segment.offset);
+      destinations[index] = BigInt(segment.destination);
+      lengths[index] = BigInt(segment.length);
+      extent = Math.max(extent, end);
+    }
+    if (extent > this.slotBytes)
+      throw new RangeError("expert segmented read exceeds slot capacity");
+    const status = this.#lib.symbols.mlx_bun_expert_io_submitv(
+      this.#handle,
+      slot,
+      generation,
+      ffiPtr(files),
+      ffiPtr(offsets),
+      ffiPtr(destinations),
+      ffiPtr(lengths),
+      segments.length,
+    );
+    if (status !== 0)
+      throw new Error(`expert segmented read submit failed: errno ${status}`);
+  }
+
+  async wait(slot: number, generation: bigint): Promise<void> {
+    await _pollExpertReadUntilReady(
+      () => this.#checkSlot(slot),
+      () => this.#lib.symbols.mlx_bun_expert_io_poll(this.#handle, slot, generation),
+    );
+  }
+
+  /** Queue advisory readahead on the dedicated hint worker. No slab is used. */
+  hintSegments(segments: readonly ExpertIOHintSegment[]): boolean {
+    this.#checkOpen();
+    if (segments.length === 0 || segments.length > MAX_SEGMENTS)
+      throw new RangeError(`expert hint requires 1..${MAX_SEGMENTS} segments`);
+    const files = new Uint32Array(segments.length);
+    const offsets = new BigUint64Array(segments.length);
+    const lengths = new BigUint64Array(segments.length);
+    for (let index = 0; index < segments.length; index++) {
+      const segment = segments[index]!;
+      if (!Number.isSafeInteger(segment.file) || segment.file < 0 ||
+          segment.file >= this.files.length)
+        throw new RangeError(`expert hint ${index} file is out of range`);
+      if (!Number.isSafeInteger(segment.offset) || segment.offset < 0)
+        throw new RangeError(`expert hint ${index} offset must be non-negative`);
+      if (!Number.isSafeInteger(segment.length) || segment.length <= 0)
+        throw new RangeError(`expert hint ${index} length must be positive`);
+      files[index] = segment.file;
+      offsets[index] = BigInt(segment.offset);
+      lengths[index] = BigInt(segment.length);
+    }
+    const status = this.#lib.symbols.mlx_bun_expert_io_hintv(
+      this.#handle,
+      ffiPtr(files),
+      ffiPtr(offsets),
+      ffiPtr(lengths),
+      segments.length,
+    );
+    if (status === 0) return true;
+    if (status === EAGAIN) return false;
+    throw new Error(`expert hint submit failed: errno ${status}`);
+  }
+
+  hintTelemetry(): ExpertIOHintSnapshot {
+    this.#checkOpen();
+    const out = new BigUint64Array(HINT_STATS);
+    const status = this.#lib.symbols.mlx_bun_expert_io_hint_stats(
+      this.#handle,
+      ffiPtr(out),
+      out.length,
+    );
+    if (status !== 0)
+      throw new Error(`expert hint telemetry failed: errno ${status}`);
+    return {
+      submitted: Number(out[0]),
+      completed: Number(out[1]),
+      dropped: Number(out[2]),
+      operations: Number(out[3]),
+      bytes: Number(out[4]),
+      errors: Number(out[5]),
+      queueDepth: Number(out[6]),
+      inFlight: Number(out[7]),
+    };
+  }
+
+  cancel(slot: number, generation: bigint): void {
+    this.#checkSlot(slot);
+    const status = this.#lib.symbols.mlx_bun_expert_io_cancel(this.#handle, slot, generation);
+    if (status !== 0) throw new Error(`expert read cancel failed: errno ${status}`);
+  }
+
+  lease(slot: number, generation: bigint, consumer: "cpu" | "gpu" = "cpu"): void {
+    this.#checkSlot(slot);
+    const status = this.#lib.symbols.mlx_bun_expert_io_lease(this.#handle, slot, generation, consumer === "gpu" ? 1 : 0);
+    if (status !== 0) throw new Error(`expert slot lease failed: errno ${status}`);
+  }
+
+  releaseCpu(slot: number, generation: bigint): void {
+    this.#checkSlot(slot);
+    const status = this.#lib.symbols.mlx_bun_expert_io_release(this.#handle, slot, generation, 0);
+    if (status !== 0) throw new Error(`expert slot release failed: errno ${status}`);
+  }
+
+  releaseGpuFenced(slot: number, generation: bigint): void {
+    this.#checkSlot(slot);
+    const status = this.#lib.symbols.mlx_bun_expert_io_release(this.#handle, slot, generation, 1);
+    if (status !== 0) throw new Error(`expert GPU slot release failed: errno ${status}`);
+  }
+
+  async releaseAfterGpuSync(
+    slot: number, generation: bigint, dependentOutputs: readonly MlxArray[], stream?: MlxHandle,
+  ): Promise<void> {
+    this.#checkSlot(slot);
+    if (dependentOutputs.length === 0) throw new Error("GPU slot release requires dependent outputs to evaluate");
+    const [{ gpuStream }, { synchronize }, ops] = await Promise.all([
+      import("./mlx/array"), import("./mlx/ffi"), import("./mlx/ops"),
+    ]);
+    ops.evalAll([...dependentOutputs]);
+    synchronize(stream ?? gpuStream);
+    this.releaseGpuFenced(slot, generation);
+  }
+
+  discard(slot: number, generation: bigint): void {
+    this.#checkSlot(slot);
+    const status = this.#lib.symbols.mlx_bun_expert_io_discard(this.#handle, slot, generation);
+    if (status !== 0) throw new Error(`expert slot discard failed: errno ${status}`);
+  }
+
+  physicalFootprint(): number {
+    this.#checkOpen();
+    return Number(this.#lib.symbols.mlx_bun_process_phys_footprint());
+  }
+
+  compressedMemory(): number {
+    this.#checkOpen();
+    return Number(this.#lib.symbols.mlx_bun_process_compressed());
+  }
+
+  pointer(slot: number, generation: bigint): number {
+    this.#checkSlot(slot);
+    const result = Number(this.#lib.symbols.mlx_bun_expert_io_ptr(this.#handle, slot, generation));
+    if (!result) throw new Error("expert slot pointer requires the matching active lease");
+    return result;
+  }
+
+  view(slot: number, generation: bigint, length?: number): Uint8Array {
+    this.#checkSlot(slot);
+    const resolvedLength = length ?? Number(this.#lib.symbols.mlx_bun_expert_io_length(this.#handle, slot, generation));
+    if (resolvedLength < 0 || resolvedLength > this.slotBytes) throw new RangeError("expert slot view exceeds capacity");
+    return new Uint8Array(toArrayBuffer(this.pointer(slot, generation) as never, 0, resolvedLength));
+  }
+
+  close(): void {
+    if (this.#state === "closed") return;
+    if (this.#state === "closing") return;
+    this.#state = "closing";
+    let status: number;
+    try {
+      status = this.#lib.symbols.mlx_bun_expert_io_close(this.#handle);
+    } catch (error) {
+      this.#state = "open";
+      throw error;
+    }
+    if (status !== 0) {
+      this.#state = "open";
+      throw new Error(`expert slab close failed: errno ${status}`);
+    }
+    this.#state = "closed";
+    this.#lib.close();
+  }
+
+  #checkSlot(slot: number): void {
+    this.#checkOpen();
+    if (!Number.isInteger(slot) || slot < 0 || slot >= this.slots) throw new RangeError("expert slot out of range");
+  }
+
+  #checkOpen(): void {
+    if (this.#state !== "open") throw new Error("expert slab store is closed");
+  }
+}
+
+export { EBUSY as EXPERT_IO_BUSY_ERRNO };
+
+export interface LruCandidate { slot: number; lastUse: bigint; pinned?: boolean; leased?: boolean }
+
+/** Deterministic eviction primitive: oldest use wins, then lowest slot ID. */
+export function selectExpertLruVictim(candidates: readonly LruCandidate[]): number | null {
+  let best: LruCandidate | null = null;
+  for (const candidate of candidates) {
+    if (candidate.pinned || candidate.leased) continue;
+    if (!best || candidate.lastUse < best.lastUse ||
+        (candidate.lastUse === best.lastUse && candidate.slot < best.slot)) best = candidate;
+  }
+  return best?.slot ?? null;
+}