mlx-bun 0.4.0 → 1.0.0

package/src/eval/ultrafeedback.ts

@@ -1,60 +0,0 @@
-// UltraFeedback (binarized) → mlx-bun preference rows. The binarized schema
-// (HuggingFaceH4/ultrafeedback_binarized) gives each row a `prompt` plus
-// `chosen` / `rejected` as message lists; ORPO wants {prompt, chosen, rejected}
-// where chosen/rejected are the assistant response *strings*. Pure transform so
-// it is unit-testable without downloading the dataset.
-
-export interface PreferenceRow {
-  prompt: string;
-  chosen: string;
-  rejected: string;
-}
-
-type Msg = { role?: string; content?: string };
-
-/** Last assistant message content in a binarized message list (the response). */
-function lastAssistant(messages: unknown): string | null {
-  if (!Array.isArray(messages)) return null;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const m = messages[i] as Msg;
-    if (m && m.role === "assistant" && typeof m.content === "string" && m.content.trim())
-      return m.content;
-  }
-  return null;
-}
-
-/** Convert one binarized UltraFeedback row → a preference row, or null if it is
- *  unusable (missing fields, or chosen == rejected so there is no signal). */
-export function toPreferenceRow(row: Record<string, unknown>): PreferenceRow | null {
-  const prompt = typeof row.prompt === "string" ? row.prompt : null;
-  const chosen = lastAssistant(row.chosen);
-  const rejected = lastAssistant(row.rejected);
-  if (!prompt || !chosen || !rejected) return null;
-  if (chosen.trim() === rejected.trim()) return null;
-  return { prompt, chosen, rejected };
-}
-
-/** Rough token estimate (≈4 chars/token) for a cheap length pre-filter before
- *  tokenization — keeps the curated set within a target context without loading
- *  a tokenizer. */
-export function approxTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-/** Filter + convert a stream of binarized rows. Drops unusable rows and ones
- *  whose prompt+chosen or prompt+rejected approx-exceeds `maxApproxTokens`. */
-export function curate(
-  rows: Record<string, unknown>[],
-  maxApproxTokens = 2048,
-): PreferenceRow[] {
-  const out: PreferenceRow[] = [];
-  for (const row of rows) {
-    const p = toPreferenceRow(row);
-    if (!p) continue;
-    const base = approxTokens(p.prompt);
-    if (base + approxTokens(p.chosen) > maxApproxTokens) continue;
-    if (base + approxTokens(p.rejected) > maxApproxTokens) continue;
-    out.push(p);
-  }
-  return out;
-}

package/src/evaldb.ts

@@ -1,199 +0,0 @@
-// Eval DB: every benchmark run recorded with model + config + commit
-// (bun:sqlite). The fit calculator's predictions are validated against
-// the measured peaks recorded here.
-
-import { Database } from "bun:sqlite";
-import { mkdirSync } from "node:fs";
-
-export const DEFAULT_EVAL_DB = `${process.env.HOME}/.cache/mlx-bun/evals.sqlite`;
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS runs (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts INTEGER NOT NULL,
-  model_path TEXT NOT NULL,
-  commit_sha TEXT,
-  prompt_tokens INTEGER NOT NULL,
-  cached_tokens INTEGER NOT NULL DEFAULT 0,
-  generated_tokens INTEGER NOT NULL,
-  prefill_tps REAL NOT NULL,
-  decode_tps REAL NOT NULL,
-  peak_bytes INTEGER NOT NULL,
-  predicted_peak_bytes INTEGER,
-  predicted_decode_tps REAL,
-  notes TEXT
-);
-
--- Phase 18 P1 — parallel-load harness. ONE row per configuration point
--- (a concurrency level or an arrival-rate target), not per request: the
--- single-stream runs table can't hold p50/p95 distributions or a
--- concurrency axis. Same additive-migration discipline as runs (these
--- are real measurements, never dropped). stack + machine_state mirror the
--- runs columns so cross-stack load rows read the same way.
-CREATE TABLE IF NOT EXISTS load_runs (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts INTEGER NOT NULL,
-  model_id TEXT NOT NULL,
-  base_url TEXT NOT NULL,
-  stack TEXT NOT NULL DEFAULT 'mlx-bun',
-  commit_sha TEXT,
-  mode TEXT NOT NULL,              -- 'closed-loop' | 'open-loop'
-  concurrency INTEGER NOT NULL,    -- in-flight cap (closed) or requester count (open)
-  target_rpm REAL,                 -- open-loop arrival target per requester (null = closed)
-  max_tokens INTEGER NOT NULL,
-  requests_ok INTEGER NOT NULL,
-  requests_err INTEGER NOT NULL,
-  duration_s REAL NOT NULL,        -- wall time of the measured window
-  ttft_p50_ms REAL NOT NULL,
-  ttft_p95_ms REAL NOT NULL,
-  e2e_p50_ms REAL NOT NULL,
-  e2e_p95_ms REAL NOT NULL,
-  e2e_p99_ms REAL NOT NULL,
-  agg_tps REAL NOT NULL,           -- generated tokens/s summed across streams
-  per_req_tps REAL NOT NULL,       -- median per-stream decode tok/s
-  achieved_rpm REAL NOT NULL,      -- completed requests/min over the window
-  peak_bytes INTEGER,              -- from /stats if exposed, else null
-  notes TEXT,
-  machine_state TEXT
-);
-`;
-
-export interface EvalRun {
-  modelPath: string;
-  commitSha?: string | null;
-  promptTokens: number;
-  cachedTokens?: number;
-  generatedTokens: number;
-  prefillTps: number;
-  decodeTps: number;
-  peakBytes: number;
-  predictedPeakBytes?: number | null;
-  predictedDecodeTps?: number | null;
-  notes?: string | null;
-  /** Which engine produced the number: mlx-bun (default) | mlx-lm | optiq. */
-  stack?: string;
-  /** JSON snapshot of preflight machine state (swap, free %, thermal). */
-  machineState?: string | null;
-}
-
-/** One configuration point of a parallel-load sweep (Phase 18 P1). */
-export interface LoadRun {
-  modelId: string;
-  baseUrl: string;
-  stack?: string;
-  commitSha?: string | null;
-  /** 'closed-loop' (fixed in-flight) or 'open-loop' (target arrival rate). */
-  mode: "closed-loop" | "open-loop";
-  /** In-flight cap (closed-loop) or requester count (open-loop). */
-  concurrency: number;
-  /** Per-requester target rpm (open-loop only; null for closed-loop). */
-  targetRpm?: number | null;
-  maxTokens: number;
-  requestsOk: number;
-  requestsErr: number;
-  durationS: number;
-  ttftP50Ms: number;
-  ttftP95Ms: number;
-  e2eP50Ms: number;
-  e2eP95Ms: number;
-  e2eP99Ms: number;
-  /** Generated tokens/s summed across all streams in the window. */
-  aggTps: number;
-  /** Median per-stream decode tok/s. */
-  perReqTps: number;
-  /** Completed requests per minute over the measured window. */
-  achievedRpm: number;
-  /** Peak resident bytes sampled from /stats, if the server exposes it. */
-  peakBytes?: number | null;
-  notes?: string | null;
-  machineState?: string | null;
-}
-
-export class EvalDB {
-  readonly db: Database;
-
-  constructor(dbPath: string = DEFAULT_EVAL_DB) {
-    if (dbPath !== ":memory:") {
-      try { mkdirSync(dbPath.slice(0, dbPath.lastIndexOf("/")), { recursive: true }); } catch {}
-    }
-    this.db = new Database(dbPath);
-    this.db.exec(SCHEMA);
-    // Additive migrations — eval rows are real data, never dropped
-    // (unlike the registry, which is a rebuildable cache).
-    const cols = (this.db.query("PRAGMA table_info(runs)").all() as { name: string }[])
-      .map((c) => c.name);
-    if (!cols.includes("stack"))
-      this.db.exec("ALTER TABLE runs ADD COLUMN stack TEXT NOT NULL DEFAULT 'mlx-bun'");
-    if (!cols.includes("machine_state"))
-      this.db.exec("ALTER TABLE runs ADD COLUMN machine_state TEXT");
-  }
-
-  record(run: EvalRun): void {
-    this.db.prepare(`
-      INSERT INTO runs (ts, model_path, commit_sha, prompt_tokens, cached_tokens,
-        generated_tokens, prefill_tps, decode_tps, peak_bytes,
-        predicted_peak_bytes, predicted_decode_tps, notes, stack, machine_state)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      Date.now(), run.modelPath, run.commitSha ?? null,
-      run.promptTokens, run.cachedTokens ?? 0, run.generatedTokens,
-      run.prefillTps, run.decodeTps, run.peakBytes,
-      run.predictedPeakBytes ?? null, run.predictedDecodeTps ?? null,
-      run.notes ?? null, run.stack ?? "mlx-bun", run.machineState ?? null,
-    );
-  }
-
-  /** Record one parallel-load configuration point (Phase 18 P1). */
-  recordLoad(run: LoadRun): void {
-    this.db.prepare(`
-      INSERT INTO load_runs (ts, model_id, base_url, stack, commit_sha, mode,
-        concurrency, target_rpm, max_tokens, requests_ok, requests_err,
-        duration_s, ttft_p50_ms, ttft_p95_ms, e2e_p50_ms, e2e_p95_ms, e2e_p99_ms,
-        agg_tps, per_req_tps, achieved_rpm, peak_bytes, notes, machine_state)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      Date.now(), run.modelId, run.baseUrl, run.stack ?? "mlx-bun",
-      run.commitSha ?? null, run.mode, run.concurrency, run.targetRpm ?? null,
-      run.maxTokens, run.requestsOk, run.requestsErr, run.durationS,
-      run.ttftP50Ms, run.ttftP95Ms, run.e2eP50Ms, run.e2eP95Ms, run.e2eP99Ms,
-      run.aggTps, run.perReqTps, run.achievedRpm, run.peakBytes ?? null,
-      run.notes ?? null, run.machineState ?? null,
-    );
-  }
-
-  recentLoad(limit = 20): Record<string, unknown>[] {
-    return this.db
-      .query("SELECT * FROM load_runs ORDER BY ts DESC LIMIT ?")
-      .all(limit) as Record<string, unknown>[];
-  }
-
-  /** Latest mlx-bun measurement for a model snapshot (status page:
-   *  measured numbers beat predictions when available). */
-  latestFor(modelPath: string): { decodeTps: number; ts: number; notes: string | null } | null {
-    const r = this.db
-      .query("SELECT decode_tps, ts, notes FROM runs WHERE model_path = ? AND stack = 'mlx-bun' ORDER BY ts DESC LIMIT 1")
-      .get(modelPath) as { decode_tps: number; ts: number; notes: string | null } | null;
-    return r ? { decodeTps: r.decode_tps, ts: r.ts, notes: r.notes } : null;
-  }
-
-  recent(limit = 20): Record<string, unknown>[] {
-    return this.db
-      .query("SELECT * FROM runs ORDER BY ts DESC LIMIT ?")
-      .all(limit) as Record<string, unknown>[];
-  }
-
-  close(): void {
-    this.db.close();
-  }
-}
-
-export function gitCommit(): string | null {
-  try {
-    const r = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
-      cwd: import.meta.dir,
-    });
-    return r.exitCode === 0 ? r.stdout.toString().trim() : null;
-  } catch {
-    return null;
-  }
-}

package/src/expert-io.ts

@@ -1,393 +0,0 @@
-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";
-import { runtimeValue } from "./runtime-config";
-
-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;
-  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"),
-    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;
-}