mlx-bun 0.5.0 → 1.0.0

package/src/ssd-cache.ts

@@ -1,431 +0,0 @@
-import type { CheckpointAttachment } from "./backends/mlx/checkpoint-state";
-// SSD cold tier for the prompt/KV cache (docs/design/kv-cache.md).
-//
-// Files ARE the database: no sidecar index. Layout
-//   <dir>/<configFingerprint>/<nsHash>/<uuid>.mlxkv
-// so two models (or two kv-quant schemes of one model) share a directory
-// without ever colliding, and an incompatible fingerprint dir is simply
-// ignored (never deleted — it may belong to the user's other model).
-// Startup recovery = a header-only scan of OUR fingerprint dir: header hash
-// verified (cheap), corrupt or metadata-mismatched files unlinked, `.tmp`
-// write orphans reaped. LRU state = file mtime (bumped on hit); the byte
-// cap is enforced at write time by oldest-mtime eviction. A cache is always
-// droppable: every failure path degrades to "no hit" or "not stored" — the
-// tier must never take serving down (oMLX paged_ssd_cache lesson, Apache-2.0
-// idea port; ours spills whole prefix entries, not content-hashed blocks —
-// see the design doc's D1 for why).
-
-import {
-  existsSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync,
-} from "node:fs";
-import { kvWriter, type KvWriteRequest } from "./storage/kv-writer";
-import { join, dirname } from "node:path";
-import { randomUUID } from "node:crypto";
-import { commonPrefixLength } from "./prompt-cache";
-import {
-  saveKvCache, saveKvCacheAsync, loadKvCache, loadKvCacheAsync, readKvHeader,
-  cacheHeadersTrimmable, cacheHeadersMinimumReusableOffset, legacyCacheCodecs, type CacheCodecProvider,
-  type KvSaveMeta, type KvLoadExpect, type LoadedKvCache,
-} from "./kv-store";
-import type { Cache } from "./model/gemma4-base";
-import { minimumReusableOffset } from "./backends/mlx/state-views";
-
-export interface SsdIndexEntry {
-  blocks?: Array<{ hash: string; bytes: number }>;
-  path: string;
-  ns: string;
-  tokens: number[];
-  bytes: number;
-  mtimeMs: number;
-  /** Whether every serialized cache can trim (derived from kinds+state at
-   *  store/scan time). An untrimmable entry (wrapped ring, SSM) can only
-   *  seed prompts it matches WITHOUT a trim — find() must not prefer it
-   *  over a shorter usable one (the 2026-07-06 restart-0 defect: the
-   *  [prompt+gen] file always won, always got rejected after restore). */
-  trimmable: boolean;
-  minimumReusableOffset?: number;
-  generationCheckpoint?: NonNullable<KvSaveMeta["generationCheckpoint"]>;
-}
-
-export interface SsdStoreOptions {
-  storage?: Pick<KvWriteRequest, "layout" | "blockBytes" | "segmented">;
-  codecs?: CacheCodecProvider;
-  dir: string;
-  maxBytes: number;
-  /** Server identity — written into every file, enforced on scan/load. */
-  configFingerprint: string;
-  tokenizerHash: string;
-  modelId: string;
-  /** Verify every tensor hash on load (--ssd-cache-verify). */
-  verify?: boolean;
-}
-
-const nsHash = (ns: string): string =>
-  ns === "" ? "base" : Bun.hash(ns).toString(16);
-
-export class SsdCacheStore {
-  readonly #opts: SsdStoreOptions;
-  readonly #codecs: CacheCodecProvider;
-  readonly #root: string; // <dir>/<configFingerprint>
-  #index: SsdIndexEntry[] = [];
-  #exact = new Map<string, SsdIndexEntry>();
-  #tokenKeys = new WeakMap<number[], string>();
-  #key(tokens: number[], ns: string): string {
-    let hash = this.#tokenKeys.get(tokens);
-    if (!hash) {
-      hash = Bun.hash(new Uint32Array(tokens)).toString(16);
-      this.#tokenKeys.set(tokens, hash);
-    }
-    return JSON.stringify([ns, tokens.length, hash]);
-  }
-  #addIndex(entry: SsdIndexEntry): void {
-    this.#index.push(entry);
-    this.#exact.set(this.#key(entry.tokens, entry.ns), entry);
-  }
-  /** Exact checkpoint selection for a known session, independent of residency. */
-  findExact(tokens: number[], ns = ""): { entry: SsdIndexEntry; prefixLen: number } | null {
-    const entry = this.#exact.get(this.#key(tokens, ns));
-    return entry && commonPrefixLength(entry.tokens, tokens) === tokens.length
-      ? { entry, prefixLen: tokens.length } : null;
-  }
-
-  #warnedWriteFailure = false;
-  stats = { restores: 0, spills: 0, restoreMsLast: 0 };
-
-  constructor(opts: SsdStoreOptions) {
-    this.#opts = opts;
-    this.#codecs = opts.codecs ?? legacyCacheCodecs;
-    this.#root = join(opts.dir, opts.configFingerprint);
-  }
-
-  get entries(): number {
-    return this.#index.length;
-  }
-
-  /** Header-only provenance for the serving tokenizer; no tensor restore. */
-  *tokenPrefixes(): Iterable<readonly number[]> {
-    for (const entry of this.#index) yield entry.tokens;
-  }
-
-  get totalBytes(): number {
-    const blocks = new Map<string, number>();
-    for (const entry of this.#index) for (const block of entry.blocks ?? [])
-      blocks.set(`${dirname(entry.path)}/${block.hash}`, block.bytes);
-    return this.#index.reduce((a, e) => a + e.bytes, 0) + [...blocks.values()].reduce((a, b) => a + b, 0);
-  }
-
-  get maxBytes(): number {
-    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 || tokens.length < (entry.minimumReusableOffset ?? 0)) 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. */
-  scan(): number {
-    this.#index = []; this.#exact.clear();
-    if (!existsSync(this.#root)) return 0;
-    for (const nsDir of readdirSync(this.#root)) {
-      const nsPath = join(this.#root, nsDir);
-      let files: string[];
-      try { files = readdirSync(nsPath); } catch { continue; }
-      for (const f of files) {
-        const path = join(nsPath, f);
-        if (f.endsWith(".tmp")) {
-          // A crash mid-write: the rename never happened. Ours by
-          // construction (uuid names), safe to reap.
-          try { rmSync(path, { force: true }); } catch {}
-          continue;
-        }
-        if (!f.endsWith(".mlxkv")) continue;
-        try {
-          const h = readKvHeader(path); // verifies the header hash
-          if (
-            h.modelId !== this.#opts.modelId ||
-            h.configFingerprint !== this.#opts.configFingerprint ||
-            h.tokenizerHash !== this.#opts.tokenizerHash
-          )
-            throw new Error("metadata mismatch");
-          if ((h.codecProvider ?? legacyCacheCodecs.id) !== this.#codecs.id) continue;
-          const st = statSync(path);
-          this.#addIndex({
-            blocks: [...h.caches, ...(h.attachments ?? [])].flatMap(e => e.tensors.flatMap(t => t.blocks ?? [])),
-            path, ns: h.ns ?? "", tokens: h.tokens, bytes: st.size, mtimeMs: st.mtimeMs,
-            trimmable: !h.attachments?.length && cacheHeadersTrimmable(h.caches, this.#codecs),
-            minimumReusableOffset: cacheHeadersMinimumReusableOffset(h.caches),
-            ...(h.generationCheckpoint
-              ? { generationCheckpoint: h.generationCheckpoint }
-              : {}),
-          });
-        } catch {
-          try { rmSync(path, { force: true }); } catch {}
-        }
-      }
-    }
-    void kvWriter.collect(this.#root).catch(() => {});
-    return this.#index.length;
-  }
-
-  /** Best USABLE stored entry for `prompt` in `ns`: the longest common
-   *  prefix (capped at prompt.length−1 — at least one token must forward).
-   *  An entry LONGER than the matched prefix is returned only when it can
-   *  actually seed the prompt: the divergent tail must be trimmable after
-   *  restore. Untrimmable entries (ring post-wrap, SSM) that would need a
-   *  trim are SKIPPED here — before this gate, the big [prompt+gen] file
-   *  always outranked the usable boundary snapshot, got restored, and was
-   *  thrown away by take()'s backstop (the 2026-07-06 restart-0 + wasted
-   *  84 s restore-then-re-prefill path). Pure index lookup; no I/O. */
-  find(prompt: number[], ns = ""): { entry: SsdIndexEntry; prefixLen: number } | null {
-    let best: SsdIndexEntry | null = null;
-    let bestLen = 0;
-    for (const e of this.#index) {
-      if (e.ns !== ns) continue;
-      const p = Math.min(commonPrefixLength(e.tokens, prompt), prompt.length - 1);
-      if (p === 0 || p <= bestLen || p < (e.minimumReusableOffset ?? 0)) continue;
-      if (e.tokens.length - p > 0 && !e.trimmable) continue;
-      bestLen = p;
-      best = e;
-    }
-    return best ? { entry: best, prefixLen: bestLen } : null;
-  }
-
-  /** Restore an entry via kv-store's STREAMED COPY (bounded host
-   *  transient — live entry + one tensor; no mapping survives the call,
-   *  the caches own their bytes). Bumps LRU mtime. On ANY failure the
-   *  file is dropped and null returned. */
-  restore(entry: SsdIndexEntry, model: { makeCache(): Cache[] }): LoadedKvCache | null {
-    const t0 = performance.now();
-    try {
-      const expect: KvLoadExpect = {
-        modelId: this.#opts.modelId,
-        configFingerprint: this.#opts.configFingerprint,
-        tokenizerHash: this.#opts.tokenizerHash,
-        ns: entry.ns,
-        verify: this.#opts.verify,
-      };
-      const loaded = loadKvCache(entry.path, model, expect, this.#codecs);
-      const now = new Date();
-      try { utimesSync(entry.path, now, now); entry.mtimeMs = now.getTime(); } catch {}
-      this.stats.restores++;
-      this.stats.restoreMsLast = performance.now() - t0;
-      return loaded;
-    } catch (err) {
-      // Loud: a failed restore silently degraded to a full re-prefill for
-      // a month before the 2026-07-06 bench made it observable.
-      console.warn(`[ssd-cache] restore failed, dropping ${entry.path}: ${(err as Error).message}`);
-      this.remove(entry.path);
-      return null;
-    }
-  }
-
-  /** Read on the dedicated CPU queue, then let the model codec adopt state. */
-  async restoreAsync(entry: SsdIndexEntry, model: { makeCache(): Cache[] }): Promise<LoadedKvCache | null> {
-    const t0 = performance.now();
-    try {
-      const loaded = await loadKvCacheAsync(entry.path, model, {
-        ...this.#meta(entry.ns), verify: this.#opts.verify,
-      }, this.#codecs);
-      const now = new Date();
-      try { utimesSync(entry.path, now, now); entry.mtimeMs = now.getTime(); } catch {}
-      this.stats.restores++; this.stats.restoreMsLast = performance.now() - t0;
-      return loaded;
-    } catch (error) {
-      console.warn(`[ssd-cache] restore failed, dropping ${entry.path}: ${error}`);
-      this.remove(entry.path); return null;
-    }
-  }
-
-  /** Persist an entry. Synchronous (the tier calls it on the idle serial
-   *  lane between requests); atomic via kv-store's tmp+fsync+rename. An
-   *  entry bigger than the cap is refused; disk/write failure is a warn-once
-   *  soft-fail — serving never stalls on the cold tier. Existing entries in
-   *  the same ns whose tokens are a PREFIX of the new entry are superseded
-   *  (the agent-conversation pattern: one growing entry, not N generations
-   *  of it). Returns true if stored. */
-  store(tokens: number[], caches: Cache[], ns = "", attachments?: CheckpointAttachment[]): boolean {
-    const dir = join(this.#root, nsHash(ns));
-    const path = join(dir, `${randomUUID()}.mlxkv`);
-    try {
-      mkdirSync(dir, { recursive: true });
-      saveKvCache(path, tokens, caches, { ...this.#meta(ns), attachments }, this.#codecs);
-      return this.#indexStored(path, tokens, caches, ns, undefined, attachments);
-    } catch (err) {
-      return this.#storeFailed(path, err);
-    }
-  }
-
-  /** Non-blocking store (the write-behind persistence path): same file,
-   *  index, and supersede semantics as store(), but the tensor flush
-   *  yields the event loop between tensors so serving interleaves.
-   *  Caller passes zero-copy CLONES it owns (a consistent snapshot no
-   *  matter what the live entry does meanwhile) and disposes them after.
-   *  `runStep` optionally wraps owner-thread snapshot preparation. Hashing,
-   *  packing and disk writes execute on the CPU worker. */
-  async storeAsync(
-    tokens: number[], caches: Cache[], ns = "",
-    runStep?: <T>(step: () => T) => Promise<T>,
-    attachments?: CheckpointAttachment[],
-  ): Promise<boolean> {
-    const dir = join(this.#root, nsHash(ns));
-    const path = join(dir, `${randomUUID()}.mlxkv`);
-    try {
-      await saveKvCacheAsync(path, tokens, caches, { ...this.#meta(ns), attachments }, runStep, this.#codecs, this.#opts.storage);
-      return this.#indexStored(path, tokens, caches, ns, undefined, attachments);
-    } catch (err) {
-      return this.#storeFailed(path, err);
-    }
-  }
-
-  /** Longest durable in-flight generation for an identical request. The
-   *  checkpoint namespace is separate from the ordinary prompt-cache tier,
-   *  so incomplete assistant output can never seed an unrelated prefill. */
-  findGenerationCheckpoint(
-    prompt: number[], key: string, cacheNs = "",
-  ): SsdIndexEntry | null {
-    let best: SsdIndexEntry | null = null;
-    for (const entry of this.#index) {
-      const checkpoint = entry.generationCheckpoint;
-      if (!checkpoint || checkpoint.key !== key || checkpoint.cacheNs !== cacheNs)
-        continue;
-      if (checkpoint.originalPromptTokens !== prompt.length) continue;
-      if (entry.tokens.length <= prompt.length) continue;
-      if (commonPrefixLength(entry.tokens, prompt) !== prompt.length) continue;
-      if (!best || entry.tokens.length > best.tokens.length) best = entry;
-    }
-    return best;
-  }
-
-  /** Persist one in-flight generation atomically. A completed newer
-   *  checkpoint supersedes older checkpoints for the same request only after
-   *  its rename succeeds, so a crash during a write leaves the prior point. */
-  async storeGenerationCheckpoint(
-    tokens: number[], caches: Cache[], checkpoint: NonNullable<KvSaveMeta["generationCheckpoint"]>,
-    runStep?: <T>(step: () => T) => Promise<T>,
-  ): Promise<boolean> {
-    const ns = `__generation_checkpoint__:${checkpoint.key}`;
-    const dir = join(this.#root, nsHash(ns));
-    const path = join(dir, `${randomUUID()}.mlxkv`);
-    try {
-      if (runStep) await runStep(() => mkdirSync(dir, { recursive: true }));
-      else mkdirSync(dir, { recursive: true });
-      await saveKvCacheAsync(path, tokens, caches, {
-        ...this.#meta(ns), generationCheckpoint: checkpoint,
-      }, runStep, this.#codecs, this.#opts.storage);
-      const index = () => {
-        const stored = this.#indexStored(path, tokens, caches, ns, checkpoint);
-        if (stored) {
-          for (const entry of [...this.#index]) {
-            if (entry.path === path) continue;
-            if (entry.generationCheckpoint?.key === checkpoint.key) this.remove(entry.path);
-          }
-        }
-        return stored;
-      };
-      return runStep ? await runStep(index) : index();
-    } catch (err) {
-      return runStep ? await runStep(() => this.#storeFailed(path, err)) : this.#storeFailed(path, err);
-    }
-  }
-
-  removeGenerationCheckpoints(key: string): void {
-    for (const entry of [...this.#index])
-      if (entry.generationCheckpoint?.key === key) this.remove(entry.path);
-  }
-
-  #meta(ns: string): KvSaveMeta {
-    return {
-      modelId: this.#opts.modelId,
-      configFingerprint: this.#opts.configFingerprint,
-      tokenizerHash: this.#opts.tokenizerHash,
-      ns,
-    };
-  }
-
-  #indexStored(
-    path: string, tokens: number[], caches: Cache[], ns: string,
-    generationCheckpoint?: NonNullable<KvSaveMeta["generationCheckpoint"]>,
-    attachments?: CheckpointAttachment[],
-  ): boolean {
-    const st = statSync(path);
-    const header = readKvHeader(path);
-    const blocks = [...header.caches, ...(header.attachments ?? [])].flatMap(e => e.tensors.flatMap(t => t.blocks ?? []));
-    const unique = new Map(blocks.map(block => [block.hash, block.bytes]));
-    const entryBytes = st.size + [...unique.values()].reduce((a, b) => a + b, 0);
-    if (entryBytes > this.#opts.maxBytes) {
-      this.remove(path);
-      console.warn(`[ssd-cache] entry not stored: ${entryBytes} bytes exceeds the ${this.#opts.maxBytes}-byte cap`);
-      return false;
-    }
-    const trimmable = !attachments?.length && caches.every((c) => c.isTrimmable());
-    // Exact duplicates (same tokens) are replaced regardless of
-    // trimmability — the new file serves exactly the old one's matches.
-    for (const e of [...this.#index]) {
-      if (e.ns !== ns || e.tokens.length !== tokens.length) continue;
-      if (commonPrefixLength(e.tokens, tokens) === tokens.length) this.remove(e.path);
-    }
-    // Supersede shadowed ancestors of this prefix (same ns) — ONLY when
-    // the new entry can serve their prefixes (all caches trimmable; the
-    // same guard as PromptCache.put()). An untrimmable [prompt+gen]
-    // entry deleting the boundary snapshot was the gemma restart-0
-    // defect (2026-07-06): the only restorable file died the moment the
-    // unrestorable one landed.
-    if (trimmable) {
-      for (const e of [...this.#index]) {
-        if (e.ns !== ns || e.tokens.length >= tokens.length || e.tokens.length < minimumReusableOffset(caches)) continue;
-        if (commonPrefixLength(e.tokens, tokens) === e.tokens.length) this.remove(e.path);
-      }
-    }
-    this.#addIndex({
-      blocks, path, ns, tokens, bytes: st.size, mtimeMs: Date.now(), trimmable,
-      minimumReusableOffset: minimumReusableOffset(caches),
-      ...(generationCheckpoint ? { generationCheckpoint } : {}),
-    });
-    this.stats.spills++;
-    this.evictToCap();
-    return true;
-  }
-
-  #storeFailed(path: string, err: unknown): boolean {
-    this.remove(path);
-    try { rmSync(`${path}.tmp`, { force: true }); } catch {}
-    if (!this.#warnedWriteFailure) {
-      this.#warnedWriteFailure = true;
-      console.warn(`[ssd-cache] store failed (disk full or unwritable?) — cold tier disabled for this entry: ${(err as Error).message}`);
-    }
-    return false;
-  }
-
-  /** Enforce the byte cap: unlink oldest-mtime entries until under it. */
-  evictToCap(): void {
-    while (this.totalBytes > this.#opts.maxBytes && this.#index.length > 0) {
-      let oldest = 0;
-      for (let i = 1; i < this.#index.length; i++)
-        if (this.#index[i]!.mtimeMs < this.#index[oldest]!.mtimeMs) oldest = i;
-      this.remove(this.#index[oldest]!.path);
-    }
-  }
-
-  remove(path: string): void {
-    try { rmSync(path, { force: true }); } catch {}
-    for (const entry of this.#index) if (entry.path === path) {
-      const key = this.#key(entry.tokens, entry.ns);
-      if (this.#exact.get(key) === entry) this.#exact.delete(key);
-    }
-    this.#index = this.#index.filter((e) => e.path !== path);
-    void kvWriter.collect(this.#root).catch(() => {});
-  }
-}

package/src/ssd-durability.ts

@@ -1,209 +0,0 @@
-import { cloneAttachments } from "./backends/mlx/checkpoint-state";
-import { cleanupFailure, disposeResources } from "./engine/resources";
-import type { Cache } from "./model/gemma4";
-import type { PromptCacheEntry } from "./prompt-cache";
-import type { SpillItem, SpillQueue } from "./kv-store";
-
-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 promptCache: DurabilityPromptCache,
-    readonly spillQueue: SpillQueue,
-    readonly cloneCaches: (caches: Cache[]) => Cache[],
-    readonly isAlreadyDurable: (tokens: number[], ns: string) => boolean = () => false,
-    readonly debounceMs = 0,
-    readonly retryMs = 5_000,
-    readonly onStored: () => void = () => {},
-  ) {}
-
-  schedule(tokens: number[], ns = "", replace = true): void {
-    // Exact tensor objects use an empty history and still need persistence.
-    if (tokens.length === 0 && !this.promptCache.findExact(tokens, ns)?.attachments?.length) 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(",")}`;
-    if (!replace && this.#dirty.has(key)) return;
-    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";
-
-    const task = this.#store(rec);
-    this.#attempts.set(key, task);
-    try {
-      const outcome = await task;
-      if (outcome === "stored" && this.#dirty.get(key) === rec)
-        this.#dirty.delete(key);
-      if (outcome !== "stored" && !force && this.#dirty.get(key) === rec)
-        this.#arm(key, this.retryMs);
-      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 = (() => {
-        if (this.isAlreadyDurable(rec.tokens, rec.ns)) return null;
-        const entry = this.promptCache.findExact(rec.tokens, rec.ns);
-        if (!entry) return null;
-        const caches = this.cloneCaches(entry.caches);
-        try {
-          return { tokens: [...entry.tokens], caches, ns: rec.ns,
-            attachments: cloneAttachments(entry.attachments) };
-        } catch (error) {
-          return cleanupFailure(error, () => disposeResources(caches));
-        }
-      })();
-    } catch {
-      return "failed";
-    }
-    if (!snap)
-      return this.isAlreadyDurable(rec.tokens, rec.ns) ? "stored" : "missing";
-    const stored = await this.spillQueue.enqueue(snap);
-    // The queue releases its views before this continuation runs. Residency
-    // policy now sees memory without the completed writer's ownership.
-    if (stored) this.onStored();
-    return stored ? "stored" : "failed";
-  }
-
-  async #flushInner(started: number): Promise<DurabilityFlushResult> {
-    for (const timer of this.#timers.values()) clearTimeout(timer);
-    this.#timers.clear();
-
-    let flushedSnapshots = 0;
-    const missing = new Map<string, DirtySnapshot>();
-    const droppedBefore = this.spillQueue.droppedCount;
-    const failedBefore = this.spillQueue.failedCount;
-
-    if (this.#attempts.size > 0) {
-      const results = await Promise.allSettled([...this.#attempts.values()]);
-      flushedSnapshots += results.filter(result => result.status === "fulfilled" && result.value === "stored").length;
-    }
-    await this.spillQueue.drain();
-
-    // Flush dirty entries serially without a second queue of snapshots.
-    // Attempt each record version once. Missing state stays dirty, so a
-    // second flush cannot report success without a real durable snapshot.
-    const attempted = new Set<DirtySnapshot>();
-    while (this.#dirty.size > 0) {
-      const records = [...this.#dirty.entries()].filter(([, rec]) => !attempted.has(rec));
-      if (records.length === 0) break;
-      for (const [key, rec] of records) {
-        if (this.#dirty.get(key) !== rec) continue;
-        attempted.add(rec);
-        const outcome = await this.#attempt(key, true);
-        await this.spillQueue.drain();
-        if (outcome === "stored") {
-          flushedSnapshots++;
-        } else if (outcome === "missing") {
-          missing.set(key, rec);
-        }
-      }
-    }
-
-    // A later trimmable snapshot may now cover a superseded RAM ancestor.
-    // Reconcile against committed SSD coverage after all writes settle;
-    // never clear a missing prefix merely because another write succeeded.
-    for (const [key, rec] of missing) {
-      if (!this.isAlreadyDurable(rec.tokens, rec.ns)) continue;
-      if (this.#dirty.get(key) === rec) this.#dirty.delete(key);
-      missing.delete(key);
-      flushedSnapshots++;
-    }
-
-    const stats = this.stats;
-    return {
-      ...stats,
-      durable:
-        stats.pendingSnapshots === 0 &&
-        stats.pendingSpills === 0 &&
-        stats.droppedSpills === droppedBefore &&
-        stats.failedSpills === failedBefore &&
-        missing.size === 0,
-      flushedSnapshots,
-      missingSnapshots: missing.size,
-      elapsedMs: performance.now() - started,
-    };
-  }
-}

package/src/storage/host-buffer.ts

@@ -1,24 +0,0 @@
-import { dlopen, ptr, read, type Pointer } from "bun:ffi";
-
-// Page alignment permits Metal to use the restored allocation directly.
-// The destructor is native free, so final release may occur on any thread.
-const libc = dlopen("/usr/lib/libSystem.B.dylib", {
-  posix_memalign: { args: ["ptr", "u64", "u64"], returns: "i32" },
-  free: { args: ["ptr"], returns: "void" },
-});
-export const hostBufferDestructor = Number(Reflect.get(libc.symbols.free, "ptr"));
-
-/** Unpublished CPU storage. A reader fills it before ownership moves to MLX. */
-export class HostBuffer {
-  #pointer: number;
-  constructor(readonly bytes: number) {
-    const slot = new BigUint64Array(1), address = ptr(slot);
-    const status = libc.symbols.posix_memalign(address, 16384n, BigInt(Math.max(16384, Math.ceil(bytes / 16384) * 16384)));
-    if (status) throw new Error(`KV restore allocation failed (${status})`);
-    this.#pointer = Number(read.u64(address));
-  }
-  get pointer(): number { return this.#pointer; }
-  transfer(): number { const p = this.#pointer; this.#pointer = 0; return p; }
-  dispose(): void { if (this.#pointer) libc.symbols.free(this.transfer() as Pointer); }
-  [Symbol.dispose](): void { this.dispose(); }
-}