mlx-bun 0.4.0 → 0.5.0

package/src/spec/qwen-mtp-source.ts

@@ -47,6 +47,8 @@ const DRAFT_PREFILL_CHUNK = 2048;
 
 export class QwenMtpProvider implements DraftProvider {
   readonly grouped: GroupedDraftProvider = {
+    supportsExternalTokens: true,
+    checkpointNamespace: () => this.#checkpointNamespace,
     open: options => this.#openRows(options.target, options.sampling, options.checkpoints),
     openPrefill: options => this.#openRows(options.target, null, options.checkpoints),
   };
@@ -132,6 +134,7 @@ export class QwenMtpProvider implements DraftProvider {
       append, prepareAppend, prefill: (tokens, context) => rows.prefill(tokens, context!), materialize: rows.materialize.bind(rows),
       filterRows: rows.filterRows.bind(rows),
       draft: rows.draft.bind(rows), commit: rows.commit.bind(rows),
+      consume: rows.consume.bind(rows),
       capture(row) {
         const state = rows.extractRow(row);
         try { return captureQwenMtpState(state); }

package/src/spec/serve-loop.ts

@@ -133,7 +133,9 @@ async function specRunInner(
     sampler,
   });
   const gamma = Math.max(1, numDraftTokens);
+  const trace = runtimeConfig().value("MLX_BUN_SPEC_TRACE") === "1";
   const prefillChunk = options.prefillChunkSize ??
+    binding.prefillPolicy?.chunkSize(promptIds.length) ??
     runtimeConfig().number("MLX_BUN_RD_PREFILL_CHUNK", PREFILL_CHUNK);
 
   // Allocated INSIDE the try below (2026-07-07 review): provider.open()
@@ -216,7 +218,7 @@ async function specRunInner(
       kvGroupSize: options.kvGroupSize ?? 64, quantizedKvStart: options.quantizedKvStart ?? null,
       turboQuant: options.turboQuant ?? null });
     let cached = 0;
-    const hit = prefixCache?.take(promptIds, prefixNamespace);
+    const hit = prefixCache?.take(promptIds, prefixNamespace, options.cacheSessionId);
     if (hit) {
       try {
         disposeResources(caches);
@@ -237,7 +239,7 @@ async function specRunInner(
       try {
         state = (services.cloneState ?? cloneKvCaches)(caches);
         attachments.push(checkpoint!.capture(tokens.length));
-        prefixCache!.put(tokens, state, prefixNamespace, undefined, attachments);
+        prefixCache!.put(tokens, state, prefixNamespace, undefined, attachments, options.cacheSessionId);
         state = []; attachments = [];
       } finally {
         disposeResources([...state, { dispose: () => disposeAttachments(attachments) }]);
@@ -445,7 +447,7 @@ async function specRunInner(
       );
       const d = drafts.length;
       if (d < 0 || d > n) throw new Error(`DraftSource returned ${d} drafts (contract: 0..${n})`);
-      if (Bun.env.MLX_BUN_SPEC_TRACE === "1") {
+      if (trace) {
         console.error(
           `[SPEC_TRACE] round=${extras.rounds + 1} ` +
           `feed=${feed.join(",")} drafts=${drafts.join(",")}`,

package/src/spec/source.ts

@@ -145,6 +145,12 @@ export interface DraftRowSampling {
   sample(logprobs: MlxArray, steps: readonly number[]): MlxArray;
 }
 
+/** Request-owned constraints can propose known continuations without changing
+ * their committed state. The target verifier still decides every output. */
+export interface DraftRowConstraints {
+  propose(row: number, maxTokens: number): Promise<number[]>;
+}
+
 export interface DraftRowCheckpoint {
   readonly processedTokens: number;
   readonly attachment: CheckpointAttachment;
@@ -155,6 +161,10 @@ export interface DraftRowCheckpoint {
  * Membership changes and capture occur only between committed rounds.
  * The caller retains the provider's residency lease for the group's lifetime. */
 export interface DraftRowGroup extends MlxDraftRows {
+  /** Consume externally chosen target inputs at a committed round boundary.
+   * Context and tokens are borrowed rectangular windows; lengths retain each
+   * row's consumed prefix, excluding right padding and the pending output. */
+  consume?(tokens: MlxArray, context: MlxArray, lengths: readonly number[]): void | Promise<void>;
   readonly namespace: string;
   readonly tapLayers: readonly number[];
   readonly rowCount: number;
@@ -187,12 +197,15 @@ export interface DraftPrefillGroup {
 }
 
 export interface GroupedDraftProvider {
+  readonly supportsExternalTokens?: boolean;
+  /** Resolve persistence identity without allocating a draft row. */
+  checkpointNamespace?(): string;
   /** Draft state remains valid when target forwards run under a mounted
    * adapter context. Unqualified learned draft graphs leave this absent. */
   readonly supportsTargetAdapters?: boolean;
   openPrefill(options: { target: TargetView;
     checkpoints: readonly (DraftRowCheckpoint | null)[] }): DraftPrefillGroup;
-  open(options: { target: TargetView; sampling: DraftRowSampling;
+  open(options: { target: TargetView; sampling: DraftRowSampling; constraints?: DraftRowConstraints;
     checkpoints: readonly DraftRowCheckpoint[] }): DraftRowGroup;
 }
 

package/src/spec/two-model-rows.ts

@@ -55,6 +55,7 @@ export function openStandaloneDraftRows(binding: MlxAutoregressiveBinding, names
 
 export function standaloneDraftGroups(binding: MlxAutoregressiveBinding, namespace: string): GroupedDraftProvider {
   return {
+    checkpointNamespace: () => namespace,
     open: options => openStandaloneDraftRows(binding, namespace, options.sampling, options.checkpoints),
     openPrefill: options => openStandaloneDraftRows(binding, namespace, null, options.checkpoints),
   };

package/src/spec/two-model.ts

@@ -16,7 +16,7 @@
 import { MlxArray } from "../mlx/array";
 import * as ops from "../mlx/ops";
 import { clearCache } from "../mlx/ffi";
-import { flagOn } from "../runtime-config";
+import { runtimeFlag } from "../runtime-config";
 import { loadModelConfig } from "../config";
 import { Weights } from "../weights";
 import { createModel, type RuntimeModel } from "../model/factory";
@@ -93,7 +93,7 @@ class TwoModelSource implements DraftSource {
       { sample: (logprobs, steps) => sampler(logprobs, steps[0]!) }, [null]);
   }
   async prefill(promptIds: number[]): Promise<void> {
-    const tailSplit = flagOn("MLX_BUN_PREFILL_TAIL_SPLIT", true);
+    const tailSplit = runtimeFlag("MLX_BUN_PREFILL_TAIL_SPLIT", true);
     const upTo = tailSplit && promptIds.length > 1 ? promptIds.length - 1 : promptIds.length;
     for (let at = this.processed; at < upTo; at += PREFILL_CHUNK) {
       const end = Math.min(at + PREFILL_CHUNK, upTo);

package/src/ssd-cache.ts

@@ -18,11 +18,12 @@ import type { CheckpointAttachment } from "./backends/mlx/checkpoint-state";
 import {
   existsSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync,
 } from "node:fs";
-import { join } from "node:path";
+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, readKvHeader,
+  saveKvCache, saveKvCacheAsync, loadKvCache, loadKvCacheAsync, readKvHeader,
   cacheHeadersTrimmable, cacheHeadersMinimumReusableOffset, legacyCacheCodecs, type CacheCodecProvider,
   type KvSaveMeta, type KvLoadExpect, type LoadedKvCache,
 } from "./kv-store";
@@ -30,6 +31,7 @@ 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[];
@@ -46,6 +48,7 @@ export interface SsdIndexEntry {
 }
 
 export interface SsdStoreOptions {
+  storage?: Pick<KvWriteRequest, "layout" | "blockBytes" | "segmented">;
   codecs?: CacheCodecProvider;
   dir: string;
   maxBytes: number;
@@ -65,6 +68,27 @@ export class SsdCacheStore {
   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 };
 
@@ -78,8 +102,16 @@ export class SsdCacheStore {
     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 {
-    return this.#index.reduce((a, e) => a + e.bytes, 0);
+    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 {
@@ -105,7 +137,7 @@ export class SsdCacheStore {
    *  headers and metadata mismatches are unlinked; `.tmp` orphans reaped.
    *  Only OUR fingerprint dir is touched. Returns entries indexed. */
   scan(): number {
-    this.#index = [];
+    this.#index = []; this.#exact.clear();
     if (!existsSync(this.#root)) return 0;
     for (const nsDir of readdirSync(this.#root)) {
       const nsPath = join(this.#root, nsDir);
@@ -130,7 +162,8 @@ export class SsdCacheStore {
             throw new Error("metadata mismatch");
           if ((h.codecProvider ?? legacyCacheCodecs.id) !== this.#codecs.id) continue;
           const st = statSync(path);
-          this.#index.push({
+          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),
@@ -143,6 +176,7 @@ export class SsdCacheStore {
         }
       }
     }
+    void kvWriter.collect(this.#root).catch(() => {});
     return this.#index.length;
   }
 
@@ -198,6 +232,23 @@ export class SsdCacheStore {
     }
   }
 
+  /** 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
@@ -222,9 +273,8 @@ export class SsdCacheStore {
    *  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` owns every per-tensor step (see saveKvCacheAsync) — the
-   *  server passes the gateway's exclusive runner so a request cannot start
-   *  between an idle check and the blocking MLX readback. */
+   *  `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>,
@@ -233,8 +283,7 @@ export class SsdCacheStore {
     const dir = join(this.#root, nsHash(ns));
     const path = join(dir, `${randomUUID()}.mlxkv`);
     try {
-      mkdirSync(dir, { recursive: true });
-      await saveKvCacheAsync(path, tokens, caches, { ...this.#meta(ns), attachments }, runStep, this.#codecs);
+      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);
@@ -275,7 +324,7 @@ export class SsdCacheStore {
       else mkdirSync(dir, { recursive: true });
       await saveKvCacheAsync(path, tokens, caches, {
         ...this.#meta(ns), generationCheckpoint: checkpoint,
-      }, runStep, this.#codecs);
+      }, runStep, this.#codecs, this.#opts.storage);
       const index = () => {
         const stored = this.#indexStored(path, tokens, caches, ns, checkpoint);
         if (stored) {
@@ -312,9 +361,13 @@ export class SsdCacheStore {
     attachments?: CheckpointAttachment[],
   ): boolean {
     const st = statSync(path);
-    if (st.size > this.#opts.maxBytes) {
-      rmSync(path, { force: true });
-      console.warn(`[ssd-cache] entry not stored: ${st.size} bytes exceeds the ${this.#opts.maxBytes}-byte cap`);
+    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());
@@ -336,8 +389,8 @@ export class SsdCacheStore {
         if (commonPrefixLength(e.tokens, tokens) === e.tokens.length) this.remove(e.path);
       }
     }
-    this.#index.push({
-      path, ns, tokens, bytes: st.size, mtimeMs: Date.now(), trimmable,
+    this.#addIndex({
+      blocks, path, ns, tokens, bytes: st.size, mtimeMs: Date.now(), trimmable,
       minimumReusableOffset: minimumReusableOffset(caches),
       ...(generationCheckpoint ? { generationCheckpoint } : {}),
     });
@@ -347,7 +400,8 @@ export class SsdCacheStore {
   }
 
   #storeFailed(path: string, err: unknown): boolean {
-    try { rmSync(path, { force: true }); rmSync(`${path}.tmp`, { force: true }); } catch {}
+    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}`);
@@ -367,6 +421,11 @@ export class SsdCacheStore {
 
   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

@@ -4,11 +4,6 @@ import type { Cache } from "./model/gemma4";
 import type { PromptCacheEntry } from "./prompt-cache";
 import type { SpillItem, SpillQueue } from "./kv-store";
 
-export interface DurabilityGateway {
-  readonly busy: boolean;
-  runWhenIdle<T>(fn: () => Promise<T>): Promise<T>;
-}
-
 export interface DurabilityPromptCache {
   findExact(tokens: number[], ns?: string): PromptCacheEntry | null;
 }
@@ -50,21 +45,23 @@ export class SsdDurabilityCoordinator {
   #flush: Promise<DurabilityFlushResult> | null = null;
 
   constructor(
-    readonly gateway: DurabilityGateway,
     readonly promptCache: DurabilityPromptCache,
     readonly spillQueue: SpillQueue,
     readonly cloneCaches: (caches: Cache[]) => Cache[],
     readonly isAlreadyDurable: (tokens: number[], ns: string) => boolean = () => false,
-    readonly debounceMs = 1_000,
-    readonly busyRetryMs = 5_000,
+    readonly debounceMs = 0,
+    readonly retryMs = 5_000,
+    readonly onStored: () => void = () => {},
   ) {}
 
-  schedule(tokens: number[], ns = ""): void {
-    if (tokens.length === 0) return;
+  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);
@@ -108,10 +105,6 @@ export class SsdDurabilityCoordinator {
 
     const rec = this.#dirty.get(key);
     if (!rec) return "stored";
-    if (!force && this.gateway.busy) {
-      this.#arm(key, this.busyRetryMs);
-      return "failed";
-    }
 
     const task = this.#store(rec);
     this.#attempts.set(key, task);
@@ -120,7 +113,7 @@ export class SsdDurabilityCoordinator {
       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.busyRetryMs);
+        this.#arm(key, this.retryMs);
       return outcome;
     } finally {
       if (this.#attempts.get(key) === task) this.#attempts.delete(key);
@@ -130,7 +123,7 @@ export class SsdDurabilityCoordinator {
   async #store(rec: DirtySnapshot): Promise<StoreOutcome> {
     let snap: SpillItem | null = null;
     try {
-      snap = await this.gateway.runWhenIdle(async () => {
+      snap = (() => {
         if (this.isAlreadyDurable(rec.tokens, rec.ns)) return null;
         const entry = this.promptCache.findExact(rec.tokens, rec.ns);
         if (!entry) return null;
@@ -141,13 +134,17 @@ export class SsdDurabilityCoordinator {
         } catch (error) {
           return cleanupFailure(error, () => disposeResources(caches));
         }
-      });
+      })();
     } catch {
       return "failed";
     }
     if (!snap)
       return this.isAlreadyDurable(rec.tokens, rec.ns) ? "stored" : "missing";
-    return await this.spillQueue.enqueue(snap) ? "stored" : "failed";
+    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> {
@@ -159,12 +156,13 @@ export class SsdDurabilityCoordinator {
     const droppedBefore = this.spillQueue.droppedCount;
     const failedBefore = this.spillQueue.failedCount;
 
-    if (this.#attempts.size > 0)
-      await Promise.allSettled([...this.#attempts.values()]);
+    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 one entry at a time. This prevents the queue cap from dropping a
-    // boundary snapshot while a large final snapshot is already in flight.
+    // 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>();

package/src/storage/host-buffer.ts

@@ -0,0 +1,24 @@
+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(); }
+}

package/src/storage/kv-writer.ts

@@ -0,0 +1,83 @@
+import { Worker } from "node:worker_threads";
+import workerSource from "./kv-writer.worker.js" with { type: "text" };
+import type { KvFileHeader } from "../kv-store";
+
+/** Immutable, evaluated host-visible storage. The owner retains the native
+ * buffers until write() settles. No MLX handles cross the worker boundary. */
+export interface StoredTensorView {
+  pointer: number;
+  shape: number[];
+  strides: number[];
+  itemSize: number;
+}
+
+export interface KvWriteRequest {
+  layout?: "whole" | "blocks";
+  blockBytes?: number;
+  segmented?: boolean;
+  path: string;
+  header: KvFileHeader;
+  tensors: StoredTensorView[];
+}
+
+/** Hashing, layout packing and atomic disk writes run on a dedicated CPU
+ * worker. Only metadata and pointers are posted; tensor bytes are not copied
+ * through structured clone. The RAM cache remains an independent owner. */
+export class KvWriter {
+  #worker: Worker | null = null;
+  #next = 0;
+  #pending = new Map<number, { resolve(): void; reject(error: Error): void }>();
+
+  lastMetrics: { elapsedMs: number; writtenBytes?: number; reusedBytes?: number; copiedBytes?: number; scratchPeak?: number } | null = null;
+
+  write(request: KvWriteRequest): Promise<void> { return this.#send(request); }
+
+  read(request: { path: string; header: KvFileHeader & { dataStart: number }; pointers: number[]; verify?: boolean }): Promise<void> {
+    return this.#send({ ...request, operation: "read" });
+  }
+
+  collect(root: string): Promise<void> { return this.#send({ root, operation: "collect" }); }
+
+  #send(request: object): Promise<void> {
+    const worker = this.#worker ?? this.#start();
+    worker.ref();
+    const id = ++this.#next;
+    return new Promise<void>((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      try { worker.postMessage({ id, ...request }); }
+      catch (error) {
+        this.#pending.delete(id);
+        if (!this.#pending.size) worker.unref();
+        reject(error);
+      }
+    });
+  }
+
+  #start(): Worker {
+    // Embed the worker in the single-file executable as well as source runs.
+    const worker = new Worker(workerSource, { eval: true });
+    worker.on("message", (message: { id: number; error?: string; metrics?: KvWriter["lastMetrics"] }) => {
+      const result = this.#pending.get(message.id);
+      if (!result) return;
+      this.#pending.delete(message.id);
+      if (message.error) result.reject(new Error(message.error));
+      else { this.lastMetrics = message.metrics ?? null; result.resolve(); }
+      if (!this.#pending.size) worker.unref();
+    });
+    // Job failures are acknowledged by the worker. A worker-level failure
+    // settles only at exit, after it can no longer read borrowed buffers.
+    worker.on("error", () => {});
+    worker.on("exit", () => {
+      for (const job of this.#pending.values()) job.reject(new Error("KV persistence worker exited"));
+      this.#pending.clear();
+      this.#worker = null;
+    });
+    this.#worker = worker;
+    return worker;
+  }
+}
+
+export const kvWriter = new KvWriter();
+
+/** Reads have their own queue: a restore never waits behind persistence. */
+export const kvReader = new KvWriter();