mlx-bun 0.0.9 → 0.0.11

package/src/server.ts

@@ -16,22 +16,56 @@ import type { Server } from "bun";
 // the runtime value a string — hence the double cast.
 import appHtml from "./web/app.html" with { type: "text" };
 import curveDesignerHtml from "./assets/curve-designer.html" with { type: "text" };
+// Vendored, no-CDN static assets referenced by app.html (convention: any
+// self-contained JS/CSS too big to inline gets `with { type: "text" }`
+// imported here and served under /assets/<name>; see src/web/vendor/README
+// for how hljs.js was built). Add new vendored assets the same way.
+import hljsJs from "./web/vendor/hljs.js" with { type: "text" };
+import hljsCss from "./web/vendor/hljs-theme.css" with { type: "text" };
+// The frontend bundle (plan §7/§9 Phase 2 module split): GENERATED from
+// src/web/src/*.ts by `bun scripts/build-web.ts` — see that file's header
+// and tests/web-build.test.ts (the freshness gate). Same
+// with { type: "text" } + /assets/<name> pattern as the vendored assets
+// above; app.html's <script defer src="/assets/app.js"> loads it.
+import appJs from "./web/app.js" with { type: "text" };
+// PWA installability (plan §9 Phase 3, beat-matrix Axis 10): a manifest +
+// a single inline SVG icon (no binary PNGs — the hygiene gate forbids
+// tracked binary files; some browsers won't show an SVG app icon, which is
+// an accepted tradeoff, see docs/reference/features-matrix.md) + a shell-
+// only service worker. Same with { type: "text" } + /assets/<name>-shaped
+// pattern as the vendored assets above; see src/web/sw.js's header for why
+// it deliberately does NOT cache API/WS traffic.
+import manifestWebmanifest from "./web/manifest.webmanifest" with { type: "text" };
+import iconSvg from "./web/icon.svg" with { type: "text" };
+import swJs from "./web/sw.js" with { type: "text" };
 import pkgJson from "../package.json" with { type: "json" };
 import { readFileSync } from "node:fs";
 const APP_PAGE = appHtml as unknown as string;
+const HLJS_JS = hljsJs as unknown as string;
+const HLJS_CSS = hljsCss as unknown as string;
+const APP_JS = appJs as unknown as string;
+const MANIFEST_WEBMANIFEST = manifestWebmanifest as unknown as string;
+const ICON_SVG = iconSvg as unknown as string;
+const SW_JS = swJs as unknown as string;
 const pkgVersion = (pkgJson as { version: string }).version;
-import { loadModelConfig, type KvQuantSpec, type ModelConfig } from "./config";
+import { loadModelConfig, type KvQuantSpec, type ModelConfig, type TurboQuantScheme } from "./config";
 import { Weights } from "./weights";
 import { Gemma4Model } from "./model/gemma4";
 import { DiffusionGemmaModel } from "./model/diffusion-gemma";
 import { spliceImageTokens } from "./vision/diffusion-vision";
 import { createModel, type RuntimeModel } from "./model/factory";
-import { isMiniCPM5Config, isSupportedModelRecord } from "./model/support";
+import { isMiniCPM5Config } from "./model/support";
 import { generate, type GenerateOptions, type TokenLogprobs } from "./generate";
+import { cloneKvCaches, SpillQueue } from "./kv-store";
+import { TURBOQUANT_HEAD_DIMS } from "./mlx/turboquant-tables";
+import {
+  compileGrammarRequest, grammarEnabled, type GrammarRequest,
+} from "./grammar";
 import type { HlgConfig } from "./sampler";
 import { isMonotone, CURVE_UMIN, type CurveParams } from "./curve-sampler";
 const CURVE_PAGE = curveDesignerHtml as unknown as string;
 import { GenerationGateway } from "./serve/generation-gateway";
+import { recordLane, type Lane } from "./serve/lane-registry";
 import {
   ChatTemplate, type ChatMessage, type ToolDefinition,
 } from "./chat-template";
@@ -40,7 +74,9 @@ import {
   CHANNEL_END, CHANNEL_START, parseGeneratedToolCalls, parseToolCalls,
   TOOL_CALL_END, TOOL_CALL_START,
 } from "./tool-call";
-import { PromptCache } from "./prompt-cache";
+import { PromptCache, cacheBytes } from "./prompt-cache";
+import { SsdCacheStore } from "./ssd-cache";
+import { configFingerprint } from "./model/fingerprint";
 import {
   anthropicToChatBody, chatJsonToAnthropic, translateOpenAiSse,
   type AnthropicRequest,
@@ -57,14 +93,23 @@ import { setMemoryLimit } from "./mlx/ffi";
 import { VisionTower } from "./vision/embedder";
 import { SiglipVisionTower, parseSiglipConfig } from "./vision/siglip";
 import {
-  buildVisionPrompt, extractImages,
-  type VisionTokenIds, type VisionEncoder,
+  buildMultimodalPrompt, buildVisionPrompt, extractAudio, extractImages,
+  type AudioTokenIds, type VisionTokenIds, type VisionEncoder,
 } from "./vision/prompt";
+import { AudioTower, parseAudioConfig } from "./audio/conformer";
+import { ensureWav } from "./audio/transcode";
+import { sidecarShipsAudioTower } from "./registry";
 import { makePiWsHandler, type PiWsData } from "./pi-web";
 
 export interface ServerOptions {
-  /** Byte cap for the prompt (KV) cache. Default 2 GB. */
+  /** Byte cap for the prompt (KV) cache. Default 8 GB. */
   promptCacheBytes?: number;
+  /** Aggregate KV-byte budget across concurrently-admitted batch rows
+   *  (`--kv-budget`, batching-perf-path P3). Joiners whose projected KV
+   *  (prompt + max_tokens, window-capped) would exceed it QUEUE until rows
+   *  evict; a request over the budget alone is rejected. Unset = no
+   *  aggregate cap (per-request admission via memoryBudget still applies). */
+  kvBudgetBytes?: number;
   /** KV quantization override. When unset: apply ctx.kvConfig (mixed
    *  per-layer) for serial serving, but bf16 under `--batch N` (the batched
    *  engine is bf16-only — a mode switch, see `batch` below). "config" forces
@@ -72,6 +117,19 @@ export interface ServerOptions {
    *  the serial path); "off" forces bf16; a number forces uniform bits
    *  (group size 64, start 0) ignoring the config file. */
   kvQuant?: "off" | "config" | number;
+  /** TurboQuant scheme (docs/design/turboquant-kv.md): a separate axis from
+   *  kvQuant above, mutually exclusive with it (`--kv-quant turbo[:k<bits>v
+   *  <bits>]` sets this instead of kvQuant). Solo-only in v1 — see
+   *  GenerationGateway's explicit refusal. */
+  turboQuant?: TurboQuantScheme;
+  /** OPTIONAL paged KV cache (`--paged-kv`, docs/design/paged-kv-cache.md):
+   *  vLLM-style block-pool storage for full-attention layers,
+   *  gather-to-contiguous before the stock SDPA. Default off (unset = the
+   *  plain KVCache path, byte-identical). v1 scope: serial batch=1,
+   *  Gemma4-family, bf16 — startup refuses `--batch N>1`, `--kv-quant`,
+   *  turbo, and `--draft-model` combinations; paged requests bypass the
+   *  prompt cache and run uncompiled. Gated bit-exact vs the plain path. */
+  pagedKv?: { blockSize?: number };
   /** Memory budget for the serving process (admission control — Phase 5).
    *  Requests whose prompt + max_tokens exceed the budget's max safe
    *  context are rejected with 400 instead of crashing the GPU: the OOM
@@ -86,6 +144,11 @@ export interface ServerOptions {
    *  it). Exposed at /stats.server so other mlx-bun processes can
    *  warn before attaching to a server that may vanish. */
   owner?: "serve" | "pi-session" | "embedded";
+  /** Listen on a UNIX DOMAIN SOCKET instead of a TCP port — the engine-
+   *  child mode of the isolation architecture (runtime-isolation.md): the
+   *  parent process reverse-proxies HTTP to this socket. Stale socket
+   *  files are unlinked before bind. When set, `hostname`/port are ignored. */
+  unixSocket?: string;
   /** Interface to bind (Bun.serve hostname). Unset ⇒ Bun's default
    *  (all interfaces) — embedded/library use. The CLI always passes one:
    *  "127.0.0.1" (loopback, mlx_lm.server parity) unless --host says
@@ -109,9 +172,9 @@ export interface ServerOptions {
    *  thinking traces never truncate. `--max-tokens 512` = mlx-lm behavior. */
   defaultMaxTokens?: number;
   /** Max concurrent requests batched through the mlx-lm-parity engine
-   *  (`--batch N`). Default 1 = today's serialized single-queue path. >1 opts
-   *  the WHOLE server into the batched engine (continuous batching, B floats
-   *  1..N, bit-parity with mlx-lm B=N) — a mode switch, not a load-dependent
+   *  (`--batch N`). Default 8 (continuous batching, B floats 1..N,
+   *  bit-parity with mlx-lm B=N); `--batch 1` pins the serialized
+   *  single-queue path — a mode switch, not a load-dependent
    *  fallback. See docs/design/parallel-slots.md. NOTE: the batched executor
    *  is mid-build; until it lands, >1 warns and runs serially. */
   batch?: number;
@@ -123,6 +186,21 @@ export interface ServerOptions {
    *  request's explicit `adapter` (including "none") always wins. Hot-swap
    *  via /v1/adapters is unchanged. */
   defaultAdapter?: string;
+  /** SSD cold tier for the prompt/KV cache (`--ssd-cache <dir>`): prefix
+   *  KV survives RAM eviction AND server restarts — the coding-agent
+   *  long-context TTFT win (docs/design/ssd-kv-cold-tier.md). Off unless
+   *  a directory is given. Serial lane only (where the prompt cache lives). */
+  ssdCacheDir?: string;
+  /** Byte cap for the SSD tier (default 32 GiB). */
+  ssdCacheMaxBytes?: number;
+  /** Idle-demotion threshold in seconds (`--ssd-demote-idle`): prompt-cache
+   *  entries unused this long spill to the SSD tier and free their GPU
+   *  memory (Layer 0 — RAM drains between bursts, prefixes stay reachable
+   *  via zero-copy restore). Default 300 when the tier is on; 0 disables. */
+  ssdDemoteIdleSec?: number;
+  /** Verify every tensor hash on restore (`--ssd-cache-verify`) — reads all
+   *  bytes eagerly, defeating lazy fault-in; integrity paranoia only. */
+  ssdCacheVerify?: boolean;
 }
 
 export interface ServerContext {
@@ -139,6 +217,17 @@ export interface ServerContext {
    *  `vision`. */
   loadVision: (() => VisionEncoder) | null;
   visionTokenIds: VisionTokenIds;
+  /** Lazily-loaded Conformer audio tower — null until the first audio
+   *  request (see `getAudioTower`). Same sidecar file as vision
+   *  (optiq_vision.safetensors), separate tower; text-only sessions never
+   *  pay for it. */
+  audio: AudioTower | null;
+  /** Loads the audio tower on demand; null when the model can't do audio
+   *  (no `audio_config` in config.json or no sidecar). No flags — audio
+   *  auto-enables exactly like vision. */
+  loadAudio: (() => AudioTower) | null;
+  /** null when the model has no `audio_config` (audio-incapable). */
+  audioTokenIds: AudioTokenIds | null;
   adapters: AdapterManager;
   /** Per-layer KV quantization from the repo's kv_config.json (null if
    *  absent). Applied by default — optiq serve's headline behavior;
@@ -148,6 +237,14 @@ export interface ServerContext {
    *  optiq serve injects these as server defaults (gen_config.py);
    *  explicit request fields always win. */
   genDefaults: GenSamplingDefaults;
+  /** Speculative decoding (`serve --draft-model`, mlx_lm.server parity).
+   *  Server-level: when set, EVERY request routes to the serial lane
+   *  (upstream: is_batchable = draft is None) and spec-eligible ones decode
+   *  through src/spec/serve-loop.ts. null = no draft configured. */
+  draft?: {
+    provider: import("./spec/source").DraftProvider;
+    numDraftTokens: number;
+  } | null;
 }
 
 export interface GenSamplingDefaults {
@@ -157,6 +254,30 @@ export interface GenSamplingDefaults {
   repetitionPenalty?: number;
 }
 
+export type DraftKind = "dspark" | "deepspec" | "assistant" | "two-model" | "ngram";
+
+/** Detect the draft artifact's kind so the right provider is loaded. All
+ *  providers share ONE serve loop (src/spec/serve-loop.ts). Exported for the
+ *  bench harness (scripts/bench-feature-matrix.ts) — one detection, no drift.
+ *  "ngram" is never detected — it has no artifact (model-free prompt lookup,
+ *  src/spec/ngram-source.ts) and mounts via an explicit `--draft-kind ngram`. */
+export async function detectDraftKind(dir: string): Promise<DraftKind> {
+  if (await Bun.file(`${dir}/dspark.json`).exists()) return "dspark"; // our trained module
+  try {
+    const cfg = (await Bun.file(`${dir}/config.json`).json()) as {
+      model_type?: string;
+      architectures?: string[];
+    };
+    // DeepSeek's released DSpark drafters (DeepSpec reference): no
+    // dspark.json, plain HF config stamped Gemma4DSparkModel.
+    if (cfg.architectures?.[0] === "Gemma4DSparkModel") return "deepspec";
+    if (String(cfg.model_type ?? "").includes("assistant")) return "assistant";
+  } catch {
+    // no/unreadable config → fall through to a full second model
+  }
+  return "two-model";
+}
+
 async function loadGenSamplingDefaults(modelDir: string): Promise<GenSamplingDefaults> {
   const file = Bun.file(`${modelDir}/generation_config.json`);
   if (!(await file.exists())) return {};
@@ -176,7 +297,24 @@ async function loadGenSamplingDefaults(modelDir: string): Promise<GenSamplingDef
 
 export async function loadContext(
   modelDir: string, modelId?: string,
-  opts: { memoryBudgetBytes?: number } = {},
+  opts: {
+    memoryBudgetBytes?: number;
+    /** Snapshot dir of a draft model for speculative decoding
+     *  (`--draft-model`). Loaded alongside the target; the pair must share
+     *  a tokenizer family (hard check below — upstream's silent-garbage
+     *  mode on mismatched tokenizers isn't worth inheriting). */
+    draftModelDir?: string;
+    /** Drafts per round (`--num-draft-tokens`, mlx_lm.server default 3). */
+    numDraftTokens?: number;
+    /** Draft-provider kind override (`--draft-kind`); auto-detected from the
+     *  draft artifact when absent (dspark.json → dspark; *_assistant config →
+     *  assistant; otherwise two-model). "ngram" mounts WITHOUT a draft dir. */
+    draftKind?: DraftKind;
+    /** Prompt-lookup window bounds (`--ngram-max` / `--ngram-min`), ngram
+     *  kind only. Defaults 3 / 1 (Saxena's reference values). */
+    ngramMax?: number;
+    ngramMin?: number;
+  } = {},
 ): Promise<ServerContext> {
   const config = await loadModelConfig(modelDir);
   const weights = await Weights.open(modelDir);
@@ -207,7 +345,116 @@ export async function loadContext(
   // the tokenizer eos; union it in. No-op when already present (Gemma, 27B).
   if (tokenizer.eosTokenId != null && !config.eosTokenIds.includes(tokenizer.eosTokenId))
     config.eosTokenIds = [...config.eosTokenIds, tokenizer.eosTokenId];
+
+  // Speculative decoding: load the draft (mlx_lm.server --draft-model). The
+  // draft artifact's KIND selects the provider — all three share ONE serve
+  // loop (src/spec/serve-loop.ts): dspark.json → DSpark (KV-injected), a
+  // *_assistant config → the optiq KV-borrowing Gemma drafter, otherwise a
+  // full second model (mlx-lm parity). `--draft-kind` overrides the detect.
+  let draft: ServerContext["draft"] = null;
+  if (opts.draftKind === "ngram") {
+    // Model-free prompt lookup: no artifact, no dir, no probe/budget concerns
+    // (weightsBytes 0, open() never throws). Default γ=10 per the reference
+    // implementation — drafting is free, so wide blocks cost only verify-window
+    // width when wrong.
+    if (opts.draftModelDir)
+      throw new Error(
+        "--draft-kind ngram is model-free — drop --draft-model (it would be ignored)",
+      );
+    const { NgramProvider } = await import("./spec/ngram-source");
+    draft = {
+      provider: new NgramProvider({ max: opts.ngramMax, min: opts.ngramMin }),
+      numDraftTokens: Math.max(1, opts.numDraftTokens ?? 10),
+    };
+  } else if (opts.draftModelDir) {
+    const dir = opts.draftModelDir;
+    const kind = opts.draftKind ?? (await detectDraftKind(dir));
+    let provider: import("./spec/source").DraftProvider;
+    let numDraftTokens = Math.max(1, opts.numDraftTokens ?? 3);
+    if (kind === "dspark") {
+      const { DflashProvider } = await import("./spec/dflash-source");
+      const p = await DflashProvider.load(dir);
+      provider = p;
+      // Pin to the trained block width — the serve loop must never ask for
+      // more positions than the DSpark block was trained for (n ≤ cfg.gamma).
+      numDraftTokens = Math.max(1, Math.min(opts.numDraftTokens ?? p.gamma, p.gamma));
+    } else if (kind === "deepspec") {
+      const { DeepspecProvider } = await import("./spec/deepspec-source");
+      const p = await DeepspecProvider.load(dir);
+      provider = p;
+      // Same pin, from their config's block_size (e.g. 7 for the released
+      // dspark_gemma4_12b_block7).
+      numDraftTokens = Math.max(1, Math.min(opts.numDraftTokens ?? p.gamma, p.gamma));
+    } else if (kind === "assistant") {
+      const { AssistantProvider } = await import("./spec/assistant-source");
+      provider = await AssistantProvider.load(dir);
+    } else {
+      const { TwoModelProvider } = await import("./spec/two-model");
+      provider = await TwoModelProvider.load(dir, config.text.vocabSize);
+      // Tokenizer-family hard check — two-model ONLY (it ships its own
+      // tokenizer). Exact-token-match acceptance is meaningful only when both
+      // models tokenize identically; a probe that ENCODES differently means
+      // different families — refuse instead of silently accepting ~0% of
+      // drafts. The KV-borrowing drafters share the target's tokenization by
+      // construction, so this check does not apply to them.
+      const draftTok = await loadTokenizer(dir);
+      const probe = "The 3 quick brown foxes jumped över the lazy dog?! 🦊";
+      if (JSON.stringify(tokenizer.encode(probe)) !== JSON.stringify(draftTok.encode(probe))) {
+        provider.dispose();
+        throw new Error(
+          `--draft-model tokenizer differs from the target's (probe string encodes ` +
+            `differently) — speculation needs the same tokenizer family`,
+        );
+      }
+    }
+    // Fail-fast pairing validation (2026-07-07 review): the KV-borrowing
+    // sources validate the (target, drafter) pairing in open() — non-Gemma4
+    // target, DeepSpec target-layer-count mismatch — which used to surface
+    // as a 500 from inside specServeRun on EVERY text request. Probe-open
+    // once with throwaway caches here so a mismatch refuses at load; open()
+    // allocates no per-request tensors before prefill/draft, so this is
+    // free. The probe sampler is never called during open().
+    {
+      const probeCaches = model.makeCache();
+      try {
+        provider
+          .open({
+            sampler: () => { throw new Error("probe sampler never samples"); },
+            target: { model, caches: probeCaches },
+          })
+          .dispose();
+      } catch (err) {
+        provider.dispose();
+        throw new Error(
+          `--draft-model is incompatible with this target: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      } finally {
+        for (const c of probeCaches) c.dispose();
+      }
+    }
+    if (opts.memoryBudgetBytes) {
+      const targetBytes = [...weights.shards.files.values()].reduce((a, f) => a + f.mmap.size, 0);
+      // Draft weights shrink the target's envelope. Draft KV is not modeled
+      // (small relative to its weights at serve contexts); admission stays
+      // approximately conservative via the combined-weights term.
+      const report = fit(config, targetBytes + provider.weightsBytes, 1, undefined, undefined, 0, opts.memoryBudgetBytes);
+      if (report.maxSafeContext < 1) {
+        provider.dispose();
+        throw new Error(
+          `target + draft do not fit the memory budget (draft adds ` +
+            `${(provider.weightsBytes / 1e9).toFixed(2)} GB)`,
+        );
+      }
+    }
+    draft = { provider, numDraftTokens };
+  } else if (opts.draftKind) {
+    // Every other kind names an artifact to load — refuse instead of silently
+    // serving without speculation.
+    throw new Error(`--draft-kind ${opts.draftKind} requires --draft-model`);
+  }
+
   return {
+    draft,
     model,
     adapters: new AdapterManager(model),
     kvConfig: config.kvQuant,
@@ -227,6 +474,17 @@ export async function loadContext(
       boiTokenId: (config.raw.boi_token_id as number) ?? 255999,
       eoiTokenId: (config.raw.eoi_token_id as number) ?? 258882,
     },
+    // Audio mirrors vision: lazy tower from the same sidecar, loaded on the
+    // first audio request only (docs/design/audio-input-plan.md A4).
+    audio: null,
+    loadAudio: makeAudioLoader(modelDir, model, config),
+    audioTokenIds: config.raw.audio_config
+      ? {
+          audioTokenId: (config.raw.audio_token_id as number) ?? 258881,
+          boaTokenId: (config.raw.boa_token_id as number) ?? 256000,
+          eoaTokenId: (config.raw.eoa_token_id as number) ?? 258883,
+        }
+      : null,
   };
 }
 
@@ -264,6 +522,46 @@ function getVisionTower(ctx: ServerContext): VisionEncoder | null {
   }
 }
 
+/** Build the on-demand audio-tower loader (gemma-4 Conformer, A4 of
+ *  docs/design/audio-input-plan.md). Auto-enables — no flags — when
+ *  config.json carries an `audio_config` AND the optiq_vision.safetensors
+ *  sidecar exists (the audio tensors ship in the same sidecar as vision).
+ *  Returns null when the model can't do audio (no audio_config: 26B-A4B,
+ *  DiffusionGemma, bf16 assistants — architectural, not a porting gap). */
+function makeAudioLoader(
+  modelDir: string, model: RuntimeModel, config: ModelConfig,
+): (() => AudioTower) | null {
+  if (!(config.hasVisionSidecar && config.raw.audio_config && model instanceof Gemma4Model))
+    return null;
+  // The sidecar header must actually name the Conformer tensors: the local
+  // 12B snapshot pairs audio_config with a STUB sidecar (embed_audio only),
+  // and a non-null loader here is what advertises `audio: true` on every
+  // capability surface (ws handshake, /v1/models). Header-only read.
+  if (!sidecarShipsAudioTower(`${modelDir}/optiq_vision.safetensors`)) return null;
+  const audioCfg = parseAudioConfig(config.raw.audio_config as Record<string, any>);
+  return () => AudioTower.load(modelDir, audioCfg, model.embedScale);
+}
+
+/** Lazily load + cache the audio tower on first use. Unlike vision's
+ *  warn-and-continue (text-only degrade is correct for requests WITHOUT
+ *  images), this is only ever consulted for requests WITH audio — the
+ *  caller turns null into an explicit 400, never a silent text-only
+ *  degrade. A failed load is not retried every request. (The stub-sidecar
+ *  case — the local 12B state — never gets here: makeAudioLoader checks the
+ *  sidecar header and returns a null loader.) */
+function getAudioTower(ctx: ServerContext): AudioTower | null {
+  if (ctx.audio) return ctx.audio;
+  if (!ctx.loadAudio) return null;
+  try {
+    ctx.audio = ctx.loadAudio();
+    return ctx.audio;
+  } catch (e) {
+    console.warn(`audio sidecar not loadable (${(e as Error).message})`);
+    ctx.loadAudio = null;
+    return null;
+  }
+}
+
 interface ChatRequest {
   messages: ChatMessage[];
   stream?: boolean;
@@ -328,6 +626,20 @@ interface ChatRequest {
     toe?: number;
     pivot_offset?: number;
   };
+  /** OpenAI structured output: {type:"json_object"} | {type:"json_schema",
+   *  json_schema:{name,schema,strict?}} | {type:"text"}. Enforced at the
+   *  sampler via xgrammar token-bitmasks (src/grammar.ts). L2-class (oMLX
+   *  oracle). On compile failure, degrades to a system-prompt injection +
+   *  Warning header (oMLX parity), never 500. */
+  response_format?: unknown;
+  /** vLLM/oMLX grammar aliases (all compiled via xgrammar): raw EBNF/LARK
+   *  grammar, regex, enum choice, and a bare JSON-schema object. Precedence
+   *  (guided_grammar > json_schema > json_object > structured_outputs >
+   *  guided_regex > guided_choice) mirrors oMLX _effective_guided_grammar. */
+  guided_grammar?: string;
+  guided_regex?: string;
+  guided_choice?: string[];
+  structured_outputs?: unknown;
 }
 
 /** POST /v1/completions body (mlx_lm.server's raw text completion — no chat
@@ -407,9 +719,9 @@ export class ToolAwareStream {
    *  chain-of-thought as `<|channel>thought\n…<channel|>` using special tokens
    *  100/101 that the content decoder strips, so reasoning is captured here at
    *  the token level. A SEPARATE decoder keeps the reasoning byte-stream's
-   *  incremental state independent of content's. The `thought\n` channel-name
-   *  line is stripped before the reasoning text (per the model's parser spec,
-   *  it sits outside the captured thought). */
+   *  incremental state independent of content's. The `thought` channel-name
+   *  word is stripped before the reasoning text (mlx-lm's think-start marker
+   *  is `<|channel>thought`; the "\n" after it is reasoning content). */
   readonly #channelDecoder: StreamDecoder;
   #inChannel = false;
   #channelNamePending = "";
@@ -430,15 +742,20 @@ export class ToolAwareStream {
     this.#channelDecoder = new StreamDecoder(tokenizer, true);
   }
 
-  /** Feed decoded channel text, stripping the leading `thought\n` name line
-   *  (which may arrive across tokens). Returns the reasoning delta. */
+  /** Feed decoded channel text, stripping the leading `thought` channel-name
+   *  word (which may arrive across tokens). Returns the reasoning delta.
+   *  mlx-lm parity: its think-start marker is exactly `<|channel>thought`
+   *  (tokenizer_utils.py `_infer_thinking`) and only the MARKER tokens get
+   *  their text blanked (server.py `_process_control_tokens`) — the "\n"
+   *  after the name is an ordinary generated token, so it is the FIRST byte
+   *  of the reasoning stream and must be kept, not swallowed with the name. */
   #feedChannel(text: string): string {
     if (this.#channelNameDone) return text;
     this.#channelNamePending += text;
     const nl = this.#channelNamePending.indexOf("\n");
-    if (nl === -1) return ""; // still inside the channel-name line
+    if (nl === -1) return ""; // still inside the channel-name word
     this.#channelNameDone = true;
-    const rest = this.#channelNamePending.slice(nl + 1);
+    const rest = this.#channelNamePending.slice(nl); // keep the "\n" (mlx-lm does)
     this.#channelNamePending = "";
     return rest;
   }
@@ -503,7 +820,8 @@ export class ToolAwareStream {
     // Reasoning channel: tokens between <|channel> and <channel|> are thought,
     // captured to #reasoning (drained via takeReasoning), never content. An
     // empty block (<|channel>thought\n<channel|>, emitted by larger Gemmas even
-    // with thinking off) yields no reasoning and leaks nothing.
+    // with thinking off) yields only the "\n" as reasoning (mlx-lm parity) and
+    // leaks nothing into content.
     if (this.#inChannel) {
       if (token === CHANNEL_END) {
         this.#inChannel = false;
@@ -744,10 +1062,15 @@ function contentPartsToText(parts: Array<Record<string, unknown>>): string {
     .join("");
 }
 
-/** True if any content part is an image (so the vision path must keep the
- *  array form for extractImages). */
-function hasImagePart(parts: Array<Record<string, unknown>>): boolean {
-  return parts.some((p) => p && (p.type === "image" || p.type === "image_url"));
+/** True if any content part is media — image OR audio — so the multimodal
+ *  path must keep the array form for extractImages/extractAudio. */
+function hasMediaPart(parts: Array<Record<string, unknown>>): boolean {
+  return parts.some(
+    (p) =>
+      p &&
+      (p.type === "image" || p.type === "image_url" ||
+        p.type === "audio" || p.type === "input_audio" || p.type === "audio_url"),
+  );
 }
 
 /** OpenAI sends assistant tool_call arguments as JSON strings; the
@@ -768,13 +1091,14 @@ function hasImagePart(parts: Array<Record<string, unknown>>): boolean {
  *     OpenAI multimodal client) sends user content as `[{type:"text",text}]`,
  *     but non-vision chat templates expect `content` to be a STRING and render
  *     nothing for an array — so the user's turn silently vanishes and the model
- *     replies "I don't see any message." Arrays that carry an image part are
- *     left intact for the vision path (extractImages); only text-only arrays
- *     are collapsed here, which is a no-op for the vision templates too. */
+ *     replies "I don't see any message." Arrays that carry a media part
+ *     (image or audio) are left intact for the multimodal path
+ *     (extractImages/extractAudio); only text-only arrays are collapsed
+ *     here, which is a no-op for the vision templates too. */
 export function normalizeMessages(messages: ChatMessage[]): ChatMessage[] {
   return messages.map((raw) => {
     let m = raw.role === "developer" ? { ...raw, role: "system" } : raw;
-    if (Array.isArray(m.content) && !hasImagePart(m.content)) {
+    if (Array.isArray(m.content) && !hasMediaPart(m.content)) {
       m = { ...m, content: contentPartsToText(m.content) };
     }
     if (!m.tool_calls) return m;
@@ -838,6 +1162,33 @@ export function nextDefaultSeed(): number {
  *  with defaults logprobs=False / top_logprobs=-1). Returns the reference's
  *  error message (→ 400) or null when valid. Note mlx-lm caps top_logprobs
  *  at 11, not OpenAI's 20 — we mirror the reference. */
+/** Build a degrade-path system-prompt instruction for JSON output, mirroring
+ *  oMLX's api.tool_calling.build_json_system_prompt (used when xgrammar
+ *  compile fails — the response_format degrades to prompt injection rather
+ *  than a 500, oMLX parity). Returns null for {type:"text"} / unset. */
+export function degradeJsonSystemPrompt(body: ChatRequest): string | null {
+  const rf = body.response_format as { type?: string; json_schema?: { name?: string; description?: string; schema?: unknown } } | undefined;
+  if (!rf || typeof rf !== "object") return null;
+  const type = rf.type ?? "text";
+  if (type === "text") return null;
+  if (type === "json_object") {
+    return "You must respond with valid JSON only. " +
+      "Do not include any explanation or text outside the JSON object.";
+  }
+  if (type === "json_schema") {
+    const spec = rf.json_schema ?? {};
+    const schema = spec.schema ?? body.structured_outputs ?? {};
+    const name = spec.name ?? "response";
+    const description = spec.description ?? "";
+    let prompt = `You must respond with valid JSON matching the '${name}' schema.`;
+    if (description) prompt += ` ${description}`;
+    prompt += `\n\nJSON Schema:\n\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\`\n\n` +
+      "Respond with only the JSON object, no additional text or explanation.";
+    return prompt;
+  }
+  return null;
+}
+
 export function validateLogprobsParams(body: {
   logprobs?: unknown;
   top_logprobs?: unknown;
@@ -917,24 +1268,79 @@ class LogprobsCollector {
   }
 }
 
-/** Incremental detokenizer: emits the longest stable decoded prefix. */
-class StreamDecoder {
+/** Incremental detokenizer: emits the longest stable decoded prefix.
+ *
+ *  Byte parity with mlx-lm's streaming detokenizers (the drop-in contract is
+ *  rendered BYTES, not just token ids). For BPE/ByteLevel tokenizers, two
+ *  mlx-lm 0.31.3 BPEStreamingDetokenizer behaviors our full-sequence decode
+ *  lacks (tokenizer_utils.py:195-226):
+ *
+ *  1. `trimsLeadingSpace` — mlx-lm drops ONE leading " " at the start of the
+ *     generated sequence (`_maybe_trim_space`); trim it here. SPM decode
+ *     already matches (see LoadedTokenizer.trimsLeadingSpace).
+ *  2. `bareSpaceTokenId` — add_token WITHHOLDS a single-char byte-32 token
+ *     ("Ġ") in `_unflushed` ("For single spaces wait until the next token"),
+ *     flushing it together with the NEXT token — and mlx_lm.server NEVER
+ *     calls detokenizer.finalize() (zero hits in server.py 0.31.3), so a
+ *     generation ENDING on bare-space token(s) silently drops their spaces
+ *     from the served bytes. push() withholds those spaces; flush() drops a
+ *     trailing bare-space run (the held text dies with the request, exactly
+ *     like mlx-lm serve). Re-check both if upstream ever adds a finalize()
+ *     call. LATENT HAZARD (deliberately not emulated): models with
+ *     clean_up_tokenization_spaces=true get an ADDITIONAL mid-stream rule
+ *     (`_space_matches`: held space dropped before "." "," "'s" …) — both
+ *     current BPE targets have it false (MiniCPM5), so it never fires here.
+ *
+ *  Exported for unit tests (serve-detok mlx-lm byte parity). */
+export class StreamDecoder {
   #ids: number[] = [];
   #emitted = "";
+  #warnedRevision = false;
+  readonly #trimLeadingSpace: boolean;
+  readonly #bareSpaceId: number | undefined;
 
   constructor(
     readonly tokenizer: LoadedTokenizer,
     readonly skipSpecialTokens = true,
-  ) {}
+  ) {
+    this.#trimLeadingSpace = tokenizer.trimsLeadingSpace === true;
+    this.#bareSpaceId = tokenizer.bareSpaceTokenId;
+  }
+
+  #decode(ids: number[]): string {
+    const full = this.tokenizer.decode(ids, this.skipSpecialTokens);
+    return this.#trimLeadingSpace && full.startsWith(" ") ? full.slice(1) : full;
+  }
 
   push(token: number): string {
     this.#ids.push(token);
-    const full = this.tokenizer.decode(this.#ids, this.skipSpecialTokens);
+    // Bare-space hold-back (mlx-lm add_token keeps "Ġ" in _unflushed): don't
+    // advance #emitted; the held space(s) flush as part of the next
+    // non-bare-space token's delta — consecutive bare spaces accumulate.
+    if (token === this.#bareSpaceId) return "";
+    const full = this.#decode(this.#ids);
     // hold back a trailing replacement char (partial multi-byte sequence)
     const stable = full.endsWith("�") ? full.slice(0, -1) : full;
     if (!stable.startsWith(this.#emitted)) {
-      // decoder revised earlier text (rare); re-emit from scratch
-      const out = stable;
+      // The decoder revised already-streamed text (cleanup rules — never
+      // fires for the shipped tokenizers, which all have
+      // clean_up_tokenization_spaces=false; see the LATENT HAZARD note in
+      // the class doc). An SSE client cannot un-receive bytes, so the old
+      // "re-emit from scratch" answer DUPLICATED the whole stream
+      // (2026-07-07 review). Truncate-safe resync instead: emit only the
+      // length-extension and keep the emitted watermark monotone — byte
+      // drift is confined to the revised span, and the once-per-stream
+      // warning makes the tokenizer that needs real _space_matches
+      // emulation loud instead of silently wrong.
+      if (!this.#warnedRevision) {
+        this.#warnedRevision = true;
+        console.warn(
+          "[detok] decoder revised already-streamed text (clean_up_tokenization_spaces?) — " +
+            "resyncing without re-emit; add mlx-lm's cleanup-rule emulation for this tokenizer",
+        );
+      }
+      if (stable.length <= this.#emitted.length) return "";
+      const out = stable.slice(this.#emitted.length);
       this.#emitted = stable;
       return out;
     }
@@ -944,7 +1350,15 @@ class StreamDecoder {
   }
 
   flush(): string {
-    const full = this.tokenizer.decode(this.#ids, this.skipSpecialTokens);
+    // mlx_lm.server never finalize()s: a trailing bare-space run stays
+    // withheld forever, so its text is dropped from the served bytes.
+    let ids = this.#ids;
+    if (this.#bareSpaceId !== undefined) {
+      let n = ids.length;
+      while (n > 0 && ids[n - 1] === this.#bareSpaceId) n--;
+      if (n < ids.length) ids = ids.slice(0, n);
+    }
+    const full = this.#decode(ids);
     const delta = full.slice(this.#emitted.length);
     this.#emitted = full;
     return delta;
@@ -974,9 +1388,203 @@ export function createServer(
   // cache by attention type. Non-batchable requests (vision / adapters /
   // repetition penalty / user seed / explicit kv-quant) drain to the serial
   // lane (see GenerationGateway.willBatch).
-  const batch = Math.max(1, Math.floor(serverOptions.batch ?? 1));
+  // DEFAULT 8 (flipped 2026-07-05, Josh's call, after GATE-B1-SPEED): a
+  // lone request through the batch lane IS the serial engine (adopted
+  // serial-class caches, compiled decode, prompt cache + SSD restore;
+  // 0.992-0.996 paired decode ratios, byte-identical output), so the cap
+  // only changes behavior when concurrent requests actually arrive — the
+  // agentic sub-agent workload. --batch 1 pins strict serial for
+  // arrival-independent numerics. 8 = optiq's Mac-safe concurrency.
+  const batch = Math.max(1, Math.floor(serverOptions.batch ?? 8));
+
+  // KV-quant scheme, resolved once. UNSET now means bf16 (flipped
+  // 2026-07-05 with the naked-=-L1 default): quantized KV measured 5–20%
+  // SLOWER decode than bf16 at ≤16k on every model — on mlx-lm too (its
+  // kv8 oracle trails its own bf16) — so it pays only in memory headroom
+  // and must be an explicit opt-in (--kv-quant config|4|8, or --l2
+  // whose presets pass it explicitly). The CLI always passes kvQuant now;
+  // this fallback is the library-user default and matches the CLI's.
+  const configScheme = ctx.kvConfig?.length ? { kvConfig: ctx.kvConfig } : {};
+  // Mutually exclusive by contract (GenerateOptions.turboQuant doc): a
+  // programmatic caller setting both gets turboQuant — say so, like the
+  // other risky-combination warnings below.
+  if (serverOptions.turboQuant && serverOptions.kvQuant && serverOptions.kvQuant !== "off")
+    console.warn(
+      `[kv-quant] both turboQuant and --kv-quant ${serverOptions.kvQuant} are set; ` +
+        `turboQuant wins (they are mutually exclusive).`,
+    );
+  const kvScheme: Pick<GenerateOptions, "kvBits" | "kvConfig" | "quantizedKvStart" | "turboQuant"> =
+    serverOptions.turboQuant ? { turboQuant: serverOptions.turboQuant, quantizedKvStart: 0 }
+    : serverOptions.kvQuant === "off" ? {}
+    : serverOptions.kvQuant === "config" ? configScheme
+    : typeof serverOptions.kvQuant === "number"
+      ? { kvBits: serverOptions.kvQuant, quantizedKvStart: 0 }
+    : {}; // unset → bf16 (L1 default; quantized KV is opt-in)
+  // Phase 3.1: kvConfig whose layers are all full-attention BATCHES (the
+  // scheduler applies the mixed scheme per row); uniform kvBits and configs
+  // touching rotating layers still route those requests serial. The warning
+  // only fires for the still-serial compositions.
+  if (batch > 1 && kvScheme.kvBits)
+    console.warn(
+      `[batch] --batch ${batch} with uniform --kv-quant ${kvScheme.kvBits}: uniform ` +
+        `quantized KV is serial-only (it touches rotating layers) — those requests ` +
+        `won't batch. Use --kv-quant config for batched mixed-precision KV, or omit ` +
+        `--kv-quant to batch in bf16. (docs/design/unified-engine-frontier-plan.md)`,
+    );
+  // TurboQuant is solo-only in v1 (novel cache class, not batchable by
+  // construction — see GenerationGateway#modelCachesBatchable/willBatch).
+  if (batch > 1 && kvScheme.turboQuant)
+    console.warn(
+      `[batch] --batch ${batch} with --kv-quant turbo: TurboQuant is serial-only in v1 ` +
+        `— those requests won't batch. Omit --kv-quant to batch in bf16. ` +
+        `(docs/design/turboquant-kv.md)`,
+    );
+  // Quantized KV (any axis) excludes the spec lane: drafted requests fall to
+  // the normal serial path WITH the KV scheme applied rather than losing it
+  // silently (mirrors the affine kvBits/kvConfig exclusion; the spec loop is
+  // bf16-KV-only in v1).
+  if (ctx.draft && (kvScheme.turboQuant || kvScheme.kvBits || kvScheme.kvConfig?.length))
+    console.warn(
+      `[spec] --draft-model with quantized KV (--kv-quant ${serverOptions.turboQuant ? "turbo" : String(serverOptions.kvQuant)}): ` +
+        `the speculative lane is bf16-KV-only in v1 — requests keep the KV scheme and ` +
+        `decode serially WITHOUT speculation. Omit --kv-quant to speculate. ` +
+        `(docs/design/dspark-serving-program.md Phase 4)`,
+    );
+  // TurboQuant head-dim fail-fast (2026-07-07 review): the cache class only
+  // supports {64,128,256,512} (sign-vector + Lloyd-Max table coverage) and
+  // used to validate LAZILY on the first append — an unsupported model
+  // (e.g. a 72/80/96 head dim) accepted --kv-quant turbo at startup and
+  // then 500'd EVERY request from inside prefill. The config knows the
+  // full-attention head dim (the only kind that converts; sliding layers
+  // stay bf16) — refuse at createServer instead.
+  if (kvScheme.turboQuant) {
+    const dim = ctx.model.config.text.globalHeadDim;
+    if (!(TURBOQUANT_HEAD_DIMS as readonly number[]).includes(dim))
+      throw new Error(
+        `--kv-quant turbo: this model's full-attention head_dim is ${dim}; ` +
+          `TurboQuant supports {${TURBOQUANT_HEAD_DIMS.join(",")}} ` +
+          `(docs/design/turboquant-kv.md) — use --kv-quant config|4|8 or omit it`,
+      );
+  }
+  // Paged KV v1 (docs/design/paged-kv-cache.md): explicit refusals, not
+  // silent downgrades — the incompatible combos would otherwise degrade
+  // quietly (batch: paged caches can't merge; kv-quant: the swap would
+  // drop the scheme, the exact composition bug the kvQuant gate above
+  // exists to prevent; draft: the spec lane assumes serial-class caches).
+  if (serverOptions.pagedKv) {
+    if (batch > 1)
+      throw new Error(
+        `--paged-kv is serial-only in v1 — add --batch 1 (got --batch ${batch}). ` +
+          `Batched paging is the follow-up PR (docs/design/paged-kv-cache.md).`,
+      );
+    if (kvScheme.kvBits || kvScheme.kvConfig?.length || kvScheme.turboQuant)
+      throw new Error(
+        `--paged-kv is bf16-only in v1 — omit --kv-quant (quantized paged ` +
+          `blocks are a documented follow-up, docs/design/paged-kv-cache.md).`,
+      );
+    if (ctx.draft)
+      throw new Error(
+        `--paged-kv cannot combine with --draft-model in v1 ` +
+          `(docs/design/paged-kv-cache.md non-goals).`,
+      );
+    if (!ctx.model.config.modelType.startsWith("gemma4"))
+      throw new Error(
+        `--paged-kv v1 supports Gemma4-family models only ` +
+          `(this model: ${ctx.model.config.modelType}) — docs/design/paged-kv-cache.md.`,
+      );
+    const bs = serverOptions.pagedKv.blockSize;
+    if (bs !== undefined && (!Number.isInteger(bs) || bs <= 0))
+      throw new Error(`--paged-kv-block-size must be a positive integer (got ${bs})`);
+    if (serverOptions.ssdCacheDir)
+      console.warn(
+        "[paged-kv] --ssd-cache has no effect: paged requests bypass the prompt " +
+          "cache (v1 non-goal), so nothing reaches the SSD tier.",
+      );
+  }
 
-  const promptCache = new PromptCache(serverOptions.promptCacheBytes ?? 2e9);
+  // SSD cold tier (docs/design/ssd-kv-cold-tier.md): prefix KV survives RAM
+  // eviction and restarts. Compatibility key = configFingerprint (graph
+  // shape) + the EFFECTIVE kv scheme (flags pick bf16 vs config vs uniform
+  // on the same model — restored caches must match what serving produces) +
+  // tokenizer hash (ids must keep meaning the same text).
+  // RAM prompt-cache cap: 8 GB default (Josh's call, 2026-07-06). The old
+  // flat 2e9 was an anti-OOM reflex sized for a 1B model in 24 GB — a
+  // single full-context 12B entry is ~0.6 GB, so it silently shrank to
+  // "three entries" on big models. 8 GB holds a dozen 12B contexts; idle
+  // entries still demote to SSD and LRU eviction bounds pressure.
+  // --prompt-cache <GB> overrides; 0 disables.
+  const promptCacheCap = serverOptions.promptCacheBytes ?? 8e9;
+  let ssdStore: SsdCacheStore | null = null;
+  if (serverOptions.ssdCacheDir) {
+    if (promptCacheCap <= 0)
+      throw new Error("--ssd-cache requires the RAM prompt cache (--prompt-cache 0 disables it)");
+    const schemeKey = kvScheme.turboQuant
+      ? `turbo-k${kvScheme.turboQuant.kBits}v${kvScheme.turboQuant.vBits}`
+      : kvScheme.kvBits
+      ? `kv${kvScheme.kvBits}`
+      : kvScheme.kvConfig?.length ? "config" : "bf16";
+    const tokJson = readFileSync(`${ctx.model.config.modelDir}/tokenizer.json`);
+    ssdStore = new SsdCacheStore({
+      dir: serverOptions.ssdCacheDir,
+      maxBytes: serverOptions.ssdCacheMaxBytes ?? 32 * 2 ** 30,
+      configFingerprint: `${configFingerprint(ctx.model.config)}-${schemeKey}`,
+      tokenizerHash: Bun.hash(tokJson).toString(16),
+      modelId: ctx.modelId,
+      verify: serverOptions.ssdCacheVerify,
+    });
+    const recovered = ssdStore.scan();
+    console.log(
+      `[ssd-cache] ${serverOptions.ssdCacheDir} — ${recovered} entr${recovered === 1 ? "y" : "ies"} recovered, ` +
+      `${(ssdStore.totalBytes / 2 ** 30).toFixed(2)} GiB of ${(ssdStore.maxBytes / 2 ** 30).toFixed(0)} GiB cap`,
+    );
+  }
+
+  // Layer 0 (unified-engine plan): the cold tier is bound INTO the prompt
+  // cache — take() itself tiers over it, so the batch scheduler and every
+  // other consumer get SSD restores through the same API; eviction AND
+  // idle demotion spill into it.
+  const coldTier = ssdStore
+    ? {
+        find: (prompt: number[], ns: string) => {
+          const h = ssdStore!.find(prompt, ns);
+          return h ? { prefixLen: h.prefixLen, handle: h.entry } : null;
+        },
+        restore: (handle: unknown) => {
+          const loaded = ssdStore!.restore(handle as import("./ssd-cache").SsdIndexEntry, ctx.model);
+          if (!loaded) return null;
+          // Restore is a STREAMED COPY (2026-07-07 A7-restore): the caches
+          // own their bytes and no mapping outlives loadKvCache — nothing
+          // to pin, nothing to unmap. retain stays in the entry contract
+          // as a no-op so callers' dispose ordering is unchanged.
+          return { tokens: loaded.tokens, caches: loaded.caches, retain: () => {} };
+        },
+        store: (tokens: number[], caches: import("./model/gemma4").Cache[], ns: string) => {
+          ssdStore!.store(tokens, caches, ns);
+        },
+      }
+    : null;
+  const promptCache = new PromptCache(
+    promptCacheCap,
+    // RAM eviction AND idle demotion spill to the cold tier NON-BLOCKING
+    // (2026-07-06, same contract as the write-behind snapshot below): the
+    // cache hands us OWNED zero-copy clones + copied tokens (made under
+    // the generation lock — microseconds; entries are immutable so the
+    // clones stay consistent), and the flush goes through the BOUNDED
+    // SpillQueue -> storeAsync (idle-gated per tensor, see below) ->
+    // clone disposal on every settle/drop path (that dispose is what
+    // actually frees the demoted GPU memory; the queue's byte cap keeps
+    // starved-gate retention bounded — 2026-07-07 review fix). spillQueue
+    // is declared with the snapshot scheduler below; safe to close over
+    // here because spills only fire at put()/demoteIdle time, long after
+    // init.
+    ssdStore
+      ? {
+          spillOwned: (entry) =>
+            spillQueue!.enqueue({ tokens: entry.tokens, caches: entry.caches, ns: entry.ns }),
+        }
+      : null,
+    coldTier,
+  );
   // Responses-API store for previous_response_id resumption (Phase 11):
   // TTL + byte-capped LRU, port of optiq/response_store.py. Pairs with
   // the prompt cache: a resumed conversation re-renders the same prefix,
@@ -989,50 +1597,284 @@ export function createServer(
    *  `enqueue` promise queue is gone; the gateway's AsyncMutex is THE lock.)
    *  onToken returning `false` halts generation early (stop
    *  sequence fired); the cache snapshot stays valid and is still kept.
-   *  Vision requests bypass the prompt cache: image tokens are
-   *  identical placeholder ids, so prefix matching across different
-   *  images would false-hit. */
+   *  Media (vision/audio embeddings-prefill) requests bypass the prompt
+   *  cache: soft tokens are identical placeholder ids, so prefix matching
+   *  across different images/clips would false-hit. */
   const runGeneration = async (
     promptIds: number[],
     options: GenerateOptions,
     onToken: (token: number, logprobs?: TokenLogprobs) => void | boolean | Promise<void | boolean>,
-    vision?: { embeddings: import("./mlx/array").MlxArray; imageMask: import("./mlx/array").MlxArray },
+    vision?: {
+      embeddings: import("./mlx/array").MlxArray;
+      imageMask?: import("./mlx/array").MlxArray;
+      multimodalMask?: import("./mlx/array").MlxArray;
+    },
   ) => {
+    // Speculative decoding (serve --draft-model): spec-ELIGIBLE requests
+    // decode through the verify loop; the rest fall through to the normal
+    // serial path (never wrong results, just no speedup — logged once per
+    // combination class would be noise, so silent). Eligibility v1:
+    // text-only, base weights, no logprobs capture, bf16 KV — ALL quantized
+    // KV axes excluded (affine kvBits/kvConfig AND turboQuant; the spec loop
+    // builds fresh bf16 caches and never calls maybeQuantizeKv, so routing a
+    // turbo request here would silently drop the operator's KV scheme —
+    // 2026-07-07 review). Grammar COMPOSES (Phase C constrained verify walk
+    // — see the serve-loop.ts header). Prompt-cache reuse is bypassed on
+    // the spec path v1.
+    if (
+      ctx.draft &&
+      !vision &&
+      !options.adapters?.length &&
+      !options.logprobs &&
+      !options.kvBits &&
+      !options.kvConfig &&
+      !options.turboQuant &&
+      // Belt: --paged-kv + --draft-model is refused at createServer; this
+      // keeps the spec lane paged-free even for programmatic callers.
+      !options.pagedKv
+    ) {
+      const { specServeRun } = await import("./spec/serve-loop");
+      return specServeRun(
+        ctx.model, ctx.draft.provider, ctx.draft.numDraftTokens,
+        promptIds, options, onToken,
+      );
+    }
     // Cache entries are adapter-specific: KV computed under one adapter
     // must never seed another's (or the base's) prefill.
     const cacheNs = options.adapters?.join("+") ?? "";
-    const entry = vision ? null : promptCache.take(promptIds, cacheNs);
+    // Paged-KV request scope (docs/design/paged-kv-cache.md): media
+    // prompts (bidir overlay) and LoRA-adapter requests are v1 non-goals —
+    // they run the PLAIN cache path even under --paged-kv (scope the flag
+    // per request, never 400). Effective value computed ONCE so the
+    // prompt-cache bypass below and the generate() options can't disagree.
+    const pagedKv = vision || options.adapters?.length ? undefined : options.pagedKv;
+    // Paged requests bypass the prompt cache entirely (v1 non-goal:
+    // PagedKVCache has no cloneKvCaches/restore path — the vision
+    // precedent). Fresh caches per request, disposed on completion.
+    const skipPromptCache = Boolean(vision || pagedKv);
+    // Both tiers in one call (Layer 0): take() prefers a strictly-longer
+    // SSD prefix, restores it zero-copy, and trims — see PromptCache.take.
+    const entry = skipPromptCache ? null : promptCache.take(promptIds, cacheNs);
     const caches = entry?.caches ?? ctx.model.makeCache();
+    // Prompt-boundary snapshot (the multi-turn agent fix, 2026-07-04): the
+    // prompt+gen entry put() below is UNTRIMMABLE at context > sliding
+    // window (wrapped rings) and under quantized KV (mid-group), so any
+    // decode→encode roundtrip drift in the reply the client sends back
+    // turns the next turn into a total miss (measured: 12B turn-2 TTFT
+    // 8.9 s instead of ~0.2 s). A prompt-ONLY entry is always an exact
+    // prefix of the next turn's rendering regardless of reply drift.
+    // Zero-copy (cloneKvCaches = slice views); only for substantial cold
+    // prefills, where the re-prefill it saves is worth an extra entry.
+    // The oracle invariant (mlx-lm insert_segments): a trim-free STRICT
+    // prefix of the prompt exists for EVERY substantial request — cap the
+    // boundary at len-1 so even a stableLen == len prompt (e4b: the
+    // template tail survives the probe render) snapshots prompt[:-1]. An
+    // exact repeat then matches with trimNeeded == 0, bypassing
+    // isTrimmable() entirely — the only reuse path a wrapped ring has.
+    const boundary = Math.min(options.snapshotAt ?? promptIds.length, promptIds.length - 1);
+    // Re-snapshot on EVERY substantial request whose stable boundary extends
+    // past the cached prefix; the clone is zero-copy views, so re-putting
+    // is ~free.
+    const snapshotBoundary =
+      !skipPromptCache && boundary >= 256 && boundary > (entry?.tokens.length ?? 0);
     try {
       const gen = generate(ctx.model, promptIds, {
         ...options,
+        pagedKv, // request-scoped (undefined strips the server-wide flag)
         cache: caches,
-        ...(vision ? { promptEmbeddings: vision.embeddings, imageMask: vision.imageMask } : {}),
+        ...(snapshotBoundary
+          ? {
+              // snapshotAt MUST travel with the hook: generate() splits the
+              // prefill at exactly this many tokens and fires the hook while
+              // the caches hold exactly that prefix — putting boundary
+              // tokens against caches at any other offset is silent KV
+              // corruption.
+              snapshotAt: boundary,
+              onPrefillDone: () => {
+                try {
+                  promptCache.put(promptIds.slice(0, boundary), cloneKvCaches(caches), cacheNs);
+                } catch (e) {
+                  console.warn(`prompt-boundary snapshot skipped: ${(e as Error).message}`);
+                }
+              },
+            }
+          : {}),
+        ...(vision
+          ? {
+              promptEmbeddings: vision.embeddings,
+              ...(vision.imageMask ? { imageMask: vision.imageMask } : {}),
+              ...(vision.multimodalMask ? { multimodalMask: vision.multimodalMask } : {}),
+            }
+          : {}),
       });
       for await (const t of gen) {
         if ((await onToken(t.token, t.logprobs)) === false) break;
       }
       const s = gen.stats!; // set on completion AND on early break
-      if (vision) {
+      if (skipPromptCache) {
+        // Vision and paged-KV requests own their caches for exactly one
+        // generation (paged: v1 non-goal — no PromptCache integration).
         for (const c of caches) c.dispose();
       } else {
-        promptCache.put(s.cacheTokens, caches, cacheNs);
+        // put() fires onPut → the debounced write-behind SSD snapshot
+        // (wired below), covering the batch lane's puts too.
+        promptCache.put(s.cacheTokens, caches, cacheNs, entry?.retain);
       }
       return s;
     } catch (e) {
       for (const c of caches) c.dispose();
+      entry?.retain?.();
+      // A throw BEFORE generate()/the gateway took ownership (promptCache
+      // take / makeCache) would leak the grammar's WASM matcher; dispose()
+      // is idempotent, so this is safe when the throw came from inside run
+      // (whose finally already disposed it).
+      options.grammar?.dispose();
       throw e;
     } finally {
       vision?.embeddings.dispose();
-      vision?.imageMask.dispose();
+      vision?.imageMask?.dispose();
+      vision?.multimodalMask?.dispose();
       options.visionPixels?.dispose();
     }
   };
 
+  // Write-behind persistence (restart survival — the oMLX boundary-snapshot
+  // idea at whole-entry granularity, spill-on-evict alone can't survive a
+  // clean exit): after a request completes, snapshot its still-RAM-resident
+  // entry to SSD off the request path. Debounced + coalesced per namespace —
+  // an agent hammering one conversation persists the settled state once
+  // things go quiet, not every turn. Runs under the gateway lock (byte
+  // extraction must not race a generation mutating the entry); if the entry
+  // was evicted (already spilled) or extended (a newer schedule pending)
+  // meanwhile, findExact misses and nothing is written.
+  // Keyed by ns AND entry length: a sub-second final [prompt+gen] put must
+  // not cancel the pending boundary-snapshot write (they are DIFFERENT
+  // entries; for wrapped-ring models the boundary file is the only one a
+  // restart can use). Same-length reschedules still coalesce; stale keys
+  // self-clean at fire time (findExact misses once the RAM tier superseded
+  // the entry, so nothing extra is written).
+  //
+  // NON-BLOCKING (2026-07-06, the write-behind persistence contract): the
+  // gateway lock is held only for a zero-copy SNAPSHOT (findExact +
+  // cloneKvCaches — microseconds; entries are immutable so the clones are
+  // consistent forever). The flush itself runs OFF the lock via
+  // storeAsync, and writes chain serially so two multi-hundred-MB flushes
+  // never overlap.
+  //
+  // IDLE-GATED (2026-07-07, the decode@ctx fix): "off the lock" was not
+  // enough — every per-tensor flush step is a blocking GPU sync on the
+  // SAME stream decode uses (ops.contiguous enqueues a kernel, rawBytesView
+  // evals) plus a synchronous multi-MB writeSync, and the setImmediate
+  // pacing interleaved those slices exactly between decode tokens. A ~16k
+  // entry's flush overlapping the bench's ctx repeats depressed decode@ctx
+  // ~9% on e4b (mlx-lm runs no equivalent background work). Now every step
+  // — including the first — awaits gateway.onIdle() (ssdFlushGate), so the
+  // flush only progresses while NOTHING is generating and pauses when a
+  // request arrives mid-flush. Tradeoffs, accepted: durability waits for a
+  // quiet moment (single-user serving quiesces constantly; sustained
+  // hammering defers the flush AND the spill clones' GPU-memory release —
+  // bounded by the chain), and one in-flight tensor step (~10-15 MB) can
+  // still land ahead of a just-arrived request. MLX_BUN_SSD_WRITEBEHIND=0
+  // disables write-behind snapshots entirely — the paired-A/B lever + kill
+  // switch (restart survival then degrades to spill-on-evict only).
+  const writeBehindOn = process.env.MLX_BUN_SSD_WRITEBEHIND !== "0";
+  const ssdFlushGate = (): Promise<void> => gateway.onIdle();
+  const ssdPending = new Map<string, ReturnType<typeof setTimeout>>();
+  // Bounded write-behind queue (2026-07-07 review fix — see SpillQueue in
+  // kv-store.ts): pending clones pin their entries' GPU buffers while the
+  // idle gate starves under sustained traffic, so QUEUED bytes are capped —
+  // over cap the oldest queued spill drops (clone disposed immediately, a
+  // future cache miss, never a wrong result) instead of accumulating past
+  // the prompt-cache cap. Default 2 GB (a quarter of the 8 GB RAM-cache
+  // default); MLX_BUN_SSD_SPILL_QUEUE_GB overrides. There is deliberately
+  // NO shutdown flush: exiting under traffic loses queued write-behind
+  // entries (restart survival degrades to whatever flushed) — accepted for
+  // a best-effort cache tier; drops/pending are visible in /stats.
+  // `|| 2` would coerce an explicit "0" back to 2 GB — parse so 0 works
+  // (cap 0 = keep only the newest + in-flight clone pinned; the soft cap
+  // never drops the item just enqueued).
+  const spillQueueGbRaw = Number(process.env.MLX_BUN_SSD_SPILL_QUEUE_GB);
+  const spillQueueCapBytes =
+    (Number.isFinite(spillQueueGbRaw) && spillQueueGbRaw >= 0 ? spillQueueGbRaw : 2) * 1024 ** 3;
+  const spillQueue = ssdStore
+    ? new SpillQueue(
+        spillQueueCapBytes,
+        cacheBytes,
+        (item) => ssdStore!.storeAsync(item.tokens, item.caches, item.ns, ssdFlushGate),
+        (caches) => { for (const c of caches) c.dispose(); },
+      )
+    : null;
+  const scheduleSsdSnapshot = (tokens: number[], ns: string): void => {
+    if (!ssdStore || !writeBehindOn || tokens.length === 0) return;
+    const key = `${ns}|${tokens.length}`;
+    const prev = ssdPending.get(key);
+    if (prev) clearTimeout(prev);
+    const fire = (): void => {
+      ssdPending.delete(key);
+      // Same guard as demoteIdle below (2026-07-07 review fix): the
+      // runExclusive registers a serial waiter, which HOLDS BATCH ADMISSION
+      // until every running row drains — a background durability timer must
+      // never do that. Busy → re-arm and try again in 5 s (entries are
+      // immutable; a late snapshot is just as valid).
+      if (gateway.activeRows > 0 || gateway.pendingRows > 0) {
+        const t = setTimeout(fire, 5000);
+        t.unref?.();
+        ssdPending.set(key, t);
+        return;
+      }
+      void gateway.runExclusive(async () => {
+        const e = promptCache.findExact(tokens, ns);
+        if (!e) return null;
+        return { tokens: e.tokens, caches: cloneKvCaches(e.caches) };
+      }).then((snap) => {
+        if (!snap) return;
+        spillQueue!.enqueue({ tokens: snap.tokens, caches: snap.caches, ns });
+      }).catch(() => { /* cold tier is best-effort */ });
+    };
+    ssdPending.set(key, setTimeout(fire, 1000));
+  };
+  // Every put() — serial lane AND batch scheduler — schedules the snapshot
+  // (Layer 0: batch-lane entries survive restarts too, not just evictions).
+  promptCache.onPut = (tokens, ns) => scheduleSsdSnapshot(tokens, ns);
+
+  // Idle demotion (Layer 0): entries unused for --ssd-demote-idle seconds
+  // spill to SSD and free their GPU memory — the RAM tier drains between
+  // bursts while every prefix stays reachable (take() restores via
+  // zero-copy mmap). The exclusive section below covers only the sweep's
+  // zero-copy clone + dispose (spillOwned above); the SSD write itself
+  // runs off-lock on ssdWriteChain. Swept only when the engine is TRULY idle: the
+  // runExclusive below registers as a serial waiter, which would DRAIN a
+  // running batch, so the activity check guards it (a momentary exclusive
+  // grab of an idle engine is free). 0 disables.
+  const demoteIdleMs = (serverOptions.ssdDemoteIdleSec ?? (ssdStore ? 300 : 0)) * 1000;
+  let demoteTimer: ReturnType<typeof setInterval> | null = null;
+  if (ssdStore && demoteIdleMs > 0) {
+    demoteTimer = setInterval(() => {
+      if (gateway.activeRows > 0 || gateway.pendingRows > 0) return;
+      void gateway.runExclusive(async () => {
+        const n = promptCache.demoteIdle(demoteIdleMs);
+        if (n > 0) console.log(`[ssd-cache] demoted ${n} idle entr${n === 1 ? "y" : "ies"} to disk`);
+      }).catch(() => {});
+    }, Math.max(30_000, demoteIdleMs / 4));
+    demoteTimer.unref?.();
+  }
+
   // The lane picker: routes each request to the serial path (runGeneration,
   // above) or the continuous-batching scheduler, keeping the two off the GPU
   // (and shared loraState) at the same time. See src/serve/generation-gateway.ts.
-  const gateway = new GenerationGateway(ctx.model, batch, runGeneration);
+  const gateway = new GenerationGateway(ctx.model, batch, runGeneration, {
+    kvBudgetBytes: serverOptions.kvBudgetBytes,
+    // Phase 3.1: the server-wide scheme travels to the gateway once; the
+    // gateway batches kv-quant requests when the scheme is the batchable
+    // kvConfig/full-attention composition (see #kvBatchable) and the
+    // scheduler applies it — otherwise those requests route serial as before.
+    kvScheme,
+    // Phase 3.2: batch-lane prompt-cache reuse — joiners take() the longest
+    // usable prefix (multi-turn chat TTFT under --batch N); never-merged
+    // lone rows put() back on finish. Vision/adapter requests never batch,
+    // so the serial lane's bypass rules are preserved by routing.
+    promptCache,
+  });
 
   // Admission ceiling, resolved once (Phase 5 memoryBudget enforcement).
   // fit() solves max safe context from weights + KV growth + prefill
@@ -1075,28 +1917,8 @@ export function createServer(
     return jobStore;
   };
 
-  // KV-quant scheme, resolved once: kv_config.json by default (optiq
-  // serve's headline behavior), overridable to uniform bits or off.
-  // KV quant scheme. The serial default is the model's mixed-precision config
-  // (optiq parity). But `--batch N` is a bf16 continuous-batching MODE (= mlx-lm
-  // B=N parity), so when KV quant is left UNSET under `--batch N` it defaults to
-  // bf16 — the batch path engages out of the box. An EXPLICIT --kv-quant
-  // (config / bits) is still honored, but those requests then route to the
-  // serial path (batched quantized KV is the L2 follow-up); warned below.
-  const configScheme = ctx.kvConfig?.length ? { kvConfig: ctx.kvConfig } : {};
-  const kvScheme: Pick<GenerateOptions, "kvBits" | "kvConfig" | "quantizedKvStart"> =
-    serverOptions.kvQuant === "off" ? {}
-    : serverOptions.kvQuant === "config" ? configScheme
-    : typeof serverOptions.kvQuant === "number"
-      ? { kvBits: serverOptions.kvQuant, quantizedKvStart: 0 }
-    : batch > 1 ? {} // unset + batching → bf16 mode (Option B)
-    : configScheme; // unset + serial → optiq-parity mixed-precision default
-  if (batch > 1 && (kvScheme.kvConfig?.length || kvScheme.kvBits))
-    console.warn(
-      `[batch] --batch ${batch} with explicit --kv-quant: batched serving (v1) is ` +
-        `bf16-only, so kv-quant requests route to the serial path (no batching for them). ` +
-        `Omit --kv-quant to batch in bf16. (docs/design/parallel-slots.md)`,
-    );
+  // (kvScheme is resolved earlier, above the prompt-cache construction —
+  // the SSD tier's compatibility fingerprint folds the effective scheme in.)
 
   // XTC never removes EOS or the newline token: mlx_lm.server passes
   // [tokenizer.eos_token_id, tokenizer.encode("\n")] as xtc_special_tokens.
@@ -1168,9 +1990,30 @@ export function createServer(
       stopSequences: (typeof req.stop === "string" ? [req.stop] : req.stop ?? [])
         .filter((s) => typeof s === "string" && s.length > 0),
       ...kvScheme,
+      // Paged KV is a server-wide mode like the kv scheme above (v1:
+      // serial bf16 gemma4 — the createServer refusals hold the invariants).
+      ...(serverOptions.pagedKv ? { pagedKv: serverOptions.pagedKv } : {}),
     };
   };
 
+  /** Compile a grammar controller from the request's structured-output fields
+   *  (response_format / guided_* / structured_outputs). Returns null when no
+   *  constraint is requested OR when compile failed (degrade path). On degrade,
+   *  `degradeHint` carries a human description for the system-prompt injection
+   *  + Warning header (oMLX parity — never 500). Honors MLX_BUN_GRAMMAR=0. */
+  const compileGrammarForRequest = async (
+    req: ChatRequest,
+  ): Promise<{ controller: import("./grammar").GrammarController | null; degradeHint: string | null }> => {
+    if (!grammarEnabled()) return { controller: null, degradeHint: null };
+    const r = await compileGrammarRequest(
+      req as GrammarRequest,
+      ctx.tokenizer,
+      ctx.model.config.text.vocabSize,
+    );
+    if (!r) return { controller: null, degradeHint: null };
+    return { controller: r.controller, degradeHint: r.degradeHint };
+  };
+
   const templateOptionsFor = (req: ChatRequest, tools: ToolDefinition[] | null) => {
     // enableThinking resolution (and its precedence) lives in
     // resolveEnableThinking so template rendering and sampling stay in sync.
@@ -1181,13 +2024,60 @@ export function createServer(
     req: ChatRequest,
     tools: ToolDefinition[] | null,
   ): { ids: number[]; startInThinking: boolean } => {
-    const rendered = ctx.template.render(normalizeMessages(req.messages), templateOptionsFor(req, tools));
+    const opts = templateOptionsFor(req, tools);
+    const rendered = ctx.template.render(normalizeMessages(req.messages), opts);
     const ids = ctx.tokenizer.encode(rendered);
     // template includes <bos>; tokenizer post-processor also prepends one
     const trimmed = ids[0] === ids[1] && ids[0] === ctx.tokenizer.bosTokenId ? ids.slice(1) : ids;
     return { ids: trimmed, startInThinking: promptEndsInOpenThink(rendered) };
   };
 
+  /** STABLE cache boundary: the prompt's tail is a generation primer (e.g.
+   *  12B's `<|channel>thought` tokens) that the NEXT turn's re-render does
+   *  not contain — a cache entry ending there can never prefix-match again
+   *  once the rings wrap. Probe by rendering this conversation as if a
+   *  reply existed; the common prefix is what every future turn preserves.
+   *  The probe is EXPENSIVE (a second full render + encode — ~150 ms at
+   *  16k with our tokenizer; 30-50% of the 12B ctx-repeat TTFT,
+   *  2026-07-06b), but the PRIMER LENGTH it measures is constant per
+   *  template mode: the divergence sits after a special-token turn
+   *  delimiter, and special tokens break BPE merges, so message content
+   *  can't shift it. So the full probe runs ONCE per mode and later
+   *  requests pay a subtraction. (A wrong boundary is a QUALITY knob, not
+   *  a correctness one — any prefix ≤ len-1 is a valid snapshot point.) */
+  const primerLenByMode = new Map<string, number>();
+  const stableLenFor = (
+    req: ChatRequest,
+    tools: ToolDefinition[] | null,
+    trimmed: number[],
+  ): number => {
+    const opts = templateOptionsFor(req, tools);
+    const mode = `${opts.enableThinking}|${!!tools?.length}`;
+    const primer = primerLenByMode.get(mode);
+    if (primer !== undefined) return Math.max(0, trimmed.length - primer);
+    let stableLen = trimmed.length;
+    try {
+      const probe = ctx.tokenizer.encode(
+        ctx.template.render(
+          [...normalizeMessages(req.messages), { role: "assistant", content: "x" }],
+          opts,
+        ),
+      );
+      const probeTrimmed =
+        probe[0] === probe[1] && probe[0] === ctx.tokenizer.bosTokenId ? probe.slice(1) : probe;
+      let i = 0;
+      const n = Math.min(trimmed.length, probeTrimmed.length);
+      while (i < n && trimmed[i] === probeTrimmed[i]) i++;
+      stableLen = i;
+      // Memoize the mode's primer length (sanity-capped: a "primer" longer
+      // than 64 tokens means the probe diverged for content reasons —
+      // don't generalize that).
+      const p = trimmed.length - stableLen;
+      if (p >= 0 && p <= 64) primerLenByMode.set(mode, p);
+    } catch { /* probe is best-effort; full boundary is the fallback */ }
+    return stableLen;
+  };
+
   const toolStreamMode = (tools: ToolDefinition[] | null): ToolStreamMode =>
     // Gemma-4 keeps the token-level sentinel path; every other family
     // (MiniCPM5, Qwen3/3.5, Tier-0 generics) emits tool calls as DECODED TEXT
@@ -1197,9 +2087,18 @@ export function createServer(
   const toolRouter = (tools: ToolDefinition[] | null): ToolAwareStream =>
     new ToolAwareStream(ctx.tokenizer, toolStreamMode(tools), tools);
 
+  if (serverOptions.unixSocket) {
+    try { require("node:fs").unlinkSync(serverOptions.unixSocket); } catch {}
+  }
+  // Bun's types make unix/port mutually exclusive variants that a spread
+  // union can't prove — runtime accepts either; cast once at the call.
   serverRef = Bun.serve({
-    port,
-    ...(serverOptions.hostname ? { hostname: serverOptions.hostname } : {}),
+    ...(serverOptions.unixSocket
+      ? ({ unix: serverOptions.unixSocket } as unknown as Record<string, never>)
+      : {
+          port,
+          ...(serverOptions.hostname ? { hostname: serverOptions.hostname } : {}),
+        }),
     idleTimeout: 0,
     // Web chat rides pi's AgentSession events over a WebSocket; the embedded
     // pi provider points back at THIS server's own loopback /v1 (port
@@ -1208,9 +2107,21 @@ export function createServer(
       port: () => serverRef.port ?? port,
       modelId: ctx.modelId,
       contextWindow: ctx.model.config.text.maxPositionEmbeddings,
-      // capability flag — true if a tower is loaded or loadable (lazy)
+      // capability flags — true if a tower is loaded or loadable (lazy)
       vision: !!(ctx.vision || ctx.loadVision),
+      audio: !!(ctx.audio || ctx.loadAudio),
       thinking: ctx.template.supportsThinking,
+      // Model-author sampling defaults (generation_config.json, server-CLI
+      // overrides applied) for the sampling popover's per-model recommended
+      // values (web-ui-pass-plan.md #14 groundwork) — same resolution
+      // /v1/models' gen_defaults uses, so the two surfaces agree. The
+      // think-mode-vs-not distinction lives in toOptions (per-request); this
+      // is the single "model's own defaults" snapshot sent once at ready.
+      genDefaults: {
+        temperature: serverOptions.defaultTemperature ?? ctx.genDefaults.temperature ?? null,
+        topP: serverOptions.defaultTopP ?? ctx.genDefaults.topP ?? null,
+        topK: serverOptions.defaultTopK ?? ctx.genDefaults.topK ?? null,
+      },
     }),
     async fetch(request, server) {
       const url = new URL(request.url);
@@ -1221,6 +2132,81 @@ export function createServer(
         return new Response("expected websocket", { status: 426 });
       }
 
+      // Memory REST wrappers (web-chat-redesign.md §2.3/§9 Phase 2): thin
+      // loopback JSON routes over src/memory/vault.ts for the web chat's
+      // Memory panel. Handlers live in src/memory/rest.ts (pure functions,
+      // no `ctx` dependency) so they're unit-testable without a loaded
+      // model; dispatch here just matches path+method. The agent-tool
+      // surface (src/memory/tools.ts) is untouched by this block.
+      if (url.pathname === "/api/memory/status" && request.method === "GET") {
+        const { handleMemoryStatus } = await import("./memory/rest");
+        return handleMemoryStatus();
+      }
+      if (url.pathname === "/api/memory/list" && request.method === "GET") {
+        const { handleMemoryList } = await import("./memory/rest");
+        return handleMemoryList();
+      }
+      if (url.pathname === "/api/memory/search" && request.method === "GET") {
+        const { handleMemorySearch } = await import("./memory/rest");
+        return handleMemorySearch(url);
+      }
+      if (url.pathname === "/api/memory/article" && request.method === "GET") {
+        const { handleMemoryArticle } = await import("./memory/rest");
+        return handleMemoryArticle(url);
+      }
+      if (url.pathname === "/api/memory/links" && request.method === "GET") {
+        const { handleMemoryLinks } = await import("./memory/rest");
+        return handleMemoryLinks(url);
+      }
+      if (url.pathname === "/api/memory/history" && request.method === "GET") {
+        const { handleMemoryHistory } = await import("./memory/rest");
+        return handleMemoryHistory(url);
+      }
+      if (url.pathname === "/api/memory/diff" && request.method === "GET") {
+        const { handleMemoryDiff } = await import("./memory/rest");
+        return handleMemoryDiff(url);
+      }
+      if (url.pathname === "/api/memory/init" && request.method === "POST") {
+        const { handleMemoryInit } = await import("./memory/rest");
+        return handleMemoryInit(request);
+      }
+
+      // Model Hub (web-chat-redesign.md §9 Phase 3, beat-matrix Axis 3):
+      // thin loopback JSON routes over the registry/download/fit machinery
+      // for the web chat's Hub panel. Handlers live in src/hub-rest.ts
+      // (pure functions, no `ctx` dependency); dispatch here just matches
+      // path+method, same convention as the memory wrappers above.
+      if (url.pathname === "/api/hub/local" && request.method === "GET") {
+        const { handleHubLocal } = await import("./hub-rest");
+        return handleHubLocal();
+      }
+      if (url.pathname === "/api/hub/search" && request.method === "GET") {
+        const { handleHubSearch } = await import("./hub-rest");
+        return handleHubSearch(url);
+      }
+      if (url.pathname === "/api/hub/download" && request.method === "POST") {
+        const { handleHubDownload } = await import("./hub-rest");
+        return handleHubDownload(request);
+      }
+      if (url.pathname === "/api/hub/serve" && request.method === "POST") {
+        const { handleHubServe } = await import("./hub-rest");
+        return handleHubServe(request);
+      }
+
+      // Session full-text search + export (docs/design/web-chat-redesign.md
+      // §9 Phase 3, beat-matrix Axis 10/11 — the full-text-search BEAT and
+      // Markdown/JSON chat export). Handlers live in src/serve/session-search.ts
+      // (pure, read-only, no `ctx` dependency), dispatched here by
+      // path+method, same convention as the memory/hub blocks above.
+      if (url.pathname === "/api/sessions/search" && request.method === "GET") {
+        const { handleSessionsSearch } = await import("./serve/session-search");
+        return handleSessionsSearch(url);
+      }
+      if (url.pathname === "/api/sessions/export" && request.method === "GET") {
+        const { handleSessionsExport } = await import("./serve/session-search");
+        return handleSessionsExport(url);
+      }
+
       // The unified SPA is served at "/"; legacy deep links redirect into
       // the hash router so old bookmarks still land on the right section.
       if (url.pathname === "/" && request.method === "GET") {
@@ -1228,6 +2214,50 @@ export function createServer(
           headers: { "content-type": "text/html; charset=utf-8" },
         });
       }
+      // Vendored syntax-highlighting assets (src/web/vendor/*, no CDN — see
+      // that dir's README). Long cache: content is versioned by the vendor
+      // rebuild step, not by URL, but a hard reload always wins during dev.
+      if (url.pathname === "/assets/hljs.js" && request.method === "GET") {
+        return new Response(HLJS_JS, {
+          headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+      }
+      if (url.pathname === "/assets/hljs.css" && request.method === "GET") {
+        return new Response(HLJS_CSS, {
+          headers: { "content-type": "text/css; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+      }
+      // The frontend bundle (see the import comment above) — cache header
+      // matches the other /assets/* entries; content is versioned by the
+      // build step, not the URL, and a hard reload always wins during dev.
+      if (url.pathname === "/assets/app.js" && request.method === "GET") {
+        return new Response(APP_JS, {
+          headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+      }
+      // PWA manifest + icon (plan §9 Phase 3): linked from app.html's
+      // <link rel="manifest">. Same versioned-by-content cache posture as
+      // the other /assets/* entries above.
+      if (url.pathname === "/manifest.webmanifest" && request.method === "GET") {
+        return new Response(MANIFEST_WEBMANIFEST, {
+          headers: { "content-type": "application/manifest+json; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+      }
+      if (url.pathname === "/assets/icon.svg" && request.method === "GET") {
+        return new Response(ICON_SVG, {
+          headers: { "content-type": "image/svg+xml; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+      }
+      // Service worker MUST be served at the root scope (/sw.js, not
+      // /assets/sw.js) — a worker's default scope is the directory it's
+      // served from, and the shell it manages includes "/" itself.
+      // no-store: the browser's own update check needs a fresh byte
+      // comparison every time to notice a new worker, not a cached 304.
+      if (url.pathname === "/sw.js" && request.method === "GET") {
+        return new Response(SW_JS, {
+          headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" },
+        });
+      }
       // v2 HLG Curve Designer — served same-origin so /generate + /signal need no CORS.
       // Read fresh from disk in dev (edits show on reload, no restart); fall back to the
       // embedded copy when running as the compiled single binary.
@@ -1271,7 +2301,7 @@ export function createServer(
           // surface on their own. (scan() is INSERT-OR-REPLACE + prunes deleted,
           // so it's idempotent and cheap for a local cache.)
           await reg.scan();
-          const { visionCapable } = await import("./registry");
+          const { visionCapable, audioCapable } = await import("./registry");
           const { supportTier } = await import("./model/support");
           const rows = [];
           // listCanonical: one row per repo (refs/main) — duplicate snapshots
@@ -1292,7 +2322,8 @@ export function createServer(
             rows.push({
               repo_id: m.repoId, model_type: m.modelType,
               size_bytes: m.sizeBytes, quant_bits: m.quantBits,
-              vision: visionCapable(m), supported, support_tier: tier,
+              vision: visionCapable(m), audio: audioCapable(m),
+              supported, support_tier: tier,
               serving: m.repoId === ctx.modelId,
               assessment,
             });
@@ -1419,7 +2450,13 @@ export function createServer(
         const layerTypes = ctx.model.config.text.layerTypes;
         const kvLayers: Record<string, number> = {};
         let kvMode = "bf16";
-        if (kvScheme.kvBits) {
+        if (kvScheme.turboQuant) {
+          // v1: full-attention layers only (sliding-window stays bf16 —
+          // docs/design/turboquant-kv.md non-goal).
+          const fullAttn = layerTypes.filter((l) => l !== "sliding_attention").length;
+          kvMode = `turbo k${kvScheme.turboQuant.kBits}v${kvScheme.turboQuant.vBits}`;
+          kvLayers[`turbo-k${kvScheme.turboQuant.kBits}v${kvScheme.turboQuant.vBits}`] = fullAttn;
+        } else if (kvScheme.kvBits) {
           kvMode = `uniform-kv${kvScheme.kvBits}`;
           kvLayers[`kv${kvScheme.kvBits}`] = layerTypes.length;
         } else if (kvScheme.kvConfig) {
@@ -1442,6 +2479,24 @@ export function createServer(
             hits: promptCache.hits,
             misses: promptCache.misses,
           },
+          ...(ssdStore ? {
+            ssd_cache: {
+              dir: serverOptions.ssdCacheDir,
+              entries: ssdStore.entries,
+              bytes: ssdStore.totalBytes,
+              max_bytes: ssdStore.maxBytes,
+              restores: ssdStore.stats.restores,
+              spills: ssdStore.stats.spills,
+              restore_ms_last: Math.round(ssdStore.stats.restoreMsLast),
+              demotions: promptCache.demotions,
+              // Bounded write-behind queue (2026-07-07): clones waiting for
+              // the idle-gated flush, and spills the byte cap dropped
+              // (each = one future cache miss, never a wrong result).
+              pending_spills: spillQueue?.pendingCount ?? 0,
+              pending_spill_bytes: spillQueue?.pendingBytes ?? 0,
+              dropped_spills: spillQueue?.droppedCount ?? 0,
+            },
+          } : {}),
           response_store: {
             entries: responseStore.size,
             bytes: responseStore.totalBytes,
@@ -1468,12 +2523,31 @@ export function createServer(
             configured: batch,
             batched: gateway.batchingEnabled,
             active_rows: gateway.activeRows,
+            pending_rows: gateway.pendingRows,
+            submitted_rows: gateway.submittedRows,
+            kv_bytes: gateway.kvBytes.projected,
+            kv_budget_bytes: gateway.kvBytes.budget,
           },
         });
       }
 
       // mlx_lm.server parity: GET /health → the exact body it writes
       // ('{"status": "ok"}', note the space) so byte-for-byte health checks pass.
+      // Engine-mode admin (unix-socket children only — never exposed on
+      // TCP): drain = quiesce the gateway + demote the whole prompt cache
+      // to the SSD tier. The pool calls this before evicting a model
+      // child, so its state survives the eviction losslessly.
+      if (
+        serverOptions.unixSocket &&
+        url.pathname === "/admin/drain" &&
+        request.method === "POST"
+      ) {
+        await gateway.runExclusive(async () => {
+          promptCache.demoteIdle(0);
+        });
+        return Response.json({ drained: true, demotions: promptCache.demotions });
+      }
+
       if (url.pathname === "/health" && request.method === "GET") {
         return new Response('{"status": "ok"}', {
           headers: { "content-type": "application/json" },
@@ -1493,26 +2567,43 @@ export function createServer(
           ? decodeURIComponent(url.pathname.slice("/v1/models/".length))
           : null;
         const created = Math.floor(startedAt / 1000);
+        // Model-author sampling defaults (generation_config.json), resolved once
+        // at load (web-ui-pass-plan.md #14 groundwork): lets a client (the web
+        // chat's sampling popover, external pi) show the SERVED model's actual
+        // recommended values instead of one hardcoded shape.
+        const genDefaultsOut = {
+          temperature: ctx.genDefaults.temperature ?? null,
+          top_p: ctx.genDefaults.topP ?? null,
+          top_k: ctx.genDefaults.topK ?? null,
+        };
         const data: Array<Record<string, unknown>> = [{
           id: ctx.modelId, object: "model", created, owned_by: "mlx-bun",
           context_window: ctx.model.config.text.maxPositionEmbeddings,
           // Capability flags for clients (CLI/external pi) that build a
           // provider from discovery — `reasoning` gates the thinking toggle,
-          // `vision` the image input declaration (tower loaded or lazily
-          // loadable; same signal the web embed uses).
+          // `vision` the image input declaration, `audio` whether
+          // `input_audio` content parts are accepted (tower loaded or lazily
+          // loadable; same signals the web embed uses).
           reasoning: ctx.template.supportsThinking,
           vision: !!(ctx.vision || ctx.loadVision),
+          audio: !!(ctx.audio || ctx.loadAudio),
+          gen_defaults: genDefaultsOut,
         }];
         try {
-          const { Registry } = await import("./registry");
+          const { Registry, visionCapable } = await import("./registry");
+          const { supportTier } = await import("./model/support");
           const reg = new Registry();
           try {
             if (reg.list().length === 0) await reg.scan();
             // Canonical rows only — a repo with N snapshots is ONE model id.
             for (const m of reg.listCanonical()) {
               if (m.repoId === ctx.modelId) continue;
-              if (!isSupportedModelRecord(m.modelType, m.repoId)) continue;
-              data.push({ id: m.repoId, object: "model", created });
+              const tier = supportTier(m.modelType, m.repoId);
+              if (tier === null) continue;
+              data.push({
+                id: m.repoId, object: "model", created,
+                vision: visionCapable(m), tier,
+              });
             }
           } finally {
             reg.close();
@@ -1568,13 +2659,16 @@ export function createServer(
       // unmount. Mount and unmount go through the generation queue so
       // they never race an in-flight forward pass.
       if (url.pathname === "/v1/adapters/available" && request.method === "GET") {
-        // On-disk adapters that can be mounted (the chat selector's source),
-        // FILTERED to ones compatible with the currently-served model — a
-        // MiniCPM5 adapter can't mount on Gemma, so it must not appear in the
-        // picker. Compatibility = the adapter's recorded base repo id matches the
-        // served model (compared on the bare name, lenient about the org); an
-        // adapter with no recorded base is kept (mount validates it). `mounted`
-        // flags ones already loaded so the UI auto-loads on select only if needed.
+        // On-disk adapters that can be mounted (the chat selector's source).
+        // Every on-disk adapter is returned — the web chat routing chip (§5.2)
+        // needs incompatible entries visible-but-grayed, not silently dropped,
+        // so a user understands "10 adapters exist, 2 apply here" rather than
+        // seeing a shorter list with no explanation. `compatible` = the
+        // adapter's recorded base repo id matches the served model (compared
+        // on the bare name, lenient about the org); an adapter with no
+        // recorded base is treated as compatible (mount validates it for
+        // real). `mounted` flags ones already loaded so the UI auto-loads on
+        // select only if needed.
         const { homedir } = await import("node:os");
         const stores = [
           `${homedir()}/.cache/mlx-bun-finetunes`,
@@ -1584,10 +2678,10 @@ export function createServer(
         const bareName = (s: string) => s.split("/").pop()!.toLowerCase();
         const servedName = bareName(ctx.modelId);
         const adapters = (await listAvailableAdapters(stores))
-          .filter((a) => a.baseModel == null || bareName(a.baseModel) === servedName)
           .map((a) => ({
             id: a.id, path: a.path, rank: a.rank, scale: a.scale,
             base_model: a.baseModel, mounted: mounted.has(a.id),
+            compatible: a.baseModel == null || bareName(a.baseModel) === servedName,
           }));
         return Response.json({ adapters });
       }
@@ -1596,6 +2690,7 @@ export function createServer(
           adapters: ctx.adapters.list().map((a) => ({
             id: a.id, path: a.path, rank: a.rank, scale: a.scale,
             size_bytes: a.sizeBytes, mounted_layers: a.mountedLayers,
+            ram_bytes: a.ramBytes,
           })),
         });
       }
@@ -1615,7 +2710,7 @@ export function createServer(
           const info = await gateway.runExclusive(() => ctx.adapters.mount(body.id!, body.path!));
           return Response.json({
             id: info.id, mounted_layers: info.mountedLayers,
-            rank: info.rank, scale: info.scale,
+            rank: info.rank, scale: info.scale, ram_bytes: info.ramBytes,
           });
         } catch (e) {
           return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
@@ -1733,29 +2828,140 @@ export function createServer(
           (m) => Array.isArray(m.content) &&
             m.content.some((p: any) => p.type === "image_url" || p.type === "image"),
         );
+        // Same shapes extractAudio accepts: OpenAI-canonical input_audio plus
+        // optiq's audio / audio_url aliases (audio-input-plan.md §3.2).
+        const hasAudio = body.messages.some(
+          (m) => Array.isArray(m.content) &&
+            m.content.some(
+              (p: any) => p.type === "input_audio" || p.type === "audio" || p.type === "audio_url",
+            ),
+        );
         let promptIds: number[];
+        let stableLen: number | null = null;
         // Whether the prompt primed an open <think> (Qwen3.5/MiniCPM5 thinking
         // on) so the model's output starts mid-reasoning — seeds the splitter.
         // Vision is Gemma4-only (no switchable thinking channel), so it's false.
         let startInThinking = false;
         let vision: Parameters<typeof runGeneration>[3];
         let diffusionPixels: import("./mlx/array").MlxArray | null = null;
+        // Grammar-constrained decoding (src/grammar.ts). Compile BEFORE prompt
+        // rendering: on the degrade path (compile failed but a constraint was
+        // requested) inject a system message instructing valid JSON so the
+        // model still best-efforts schema-conformant output (oMLX parity —
+        // _compile_grammar_for_request returning None + build_json_system_prompt).
+        let grammarCtrl: import("./grammar").GrammarController | null = null;
+        let grammarWarning: string | null = null;
+        const grammarReq =
+          body.response_format != null || !!body.guided_grammar ||
+          !!body.guided_regex || !!body.guided_choice?.length ||
+          body.structured_outputs != null;
+        if (grammarReq) {
+          const g = await compileGrammarForRequest(body);
+          grammarCtrl = g.controller;
+          if (!g.controller && g.degradeHint) {
+            grammarWarning = `grammar not enforced: ${g.degradeHint} — falling back to prompt injection`;
+            body = {
+              ...body,
+              messages: [
+                { role: "system", content: degradeJsonSystemPrompt(body) },
+                ...body.messages,
+              ],
+            };
+          }
+        }
+        // Free what a rejected request has already allocated (grammar WASM
+        // matcher/compiled-grammar, vision embeddings, diffusion pixels).
+        // Every early return between here and gateway.run() must call this —
+        // generate()/the gateway only take disposal ownership once running
+        // (leaked one matcher per SSRF-blocked-media + response_format
+        // request before the 2026-07-07 sweep).
+        const disposeRejected = () => {
+          grammarCtrl?.dispose();
+          vision?.embeddings.dispose();
+          vision?.imageMask?.dispose();
+          vision?.multimodalMask?.dispose();
+          diffusionPixels?.dispose();
+        };
         try {
-          if (hasImages && ctx.model instanceof DiffusionGemmaModel) {
+          if (hasAudio) {
+            // Audio (and MIXED image+audio) input — A4 of
+            // docs/design/audio-input-plan.md. One buildMultimodalPrompt call
+            // splices both media kinds in document order. A request WITH
+            // audio on a model whose tower is unavailable is an explicit 400
+            // — never a silent text-only degrade (that leniency is only for
+            // requests without the media, getVisionTower's contract).
+            const audioTower = getAudioTower(ctx);
+            if (!audioTower || !ctx.audioTokenIds) {
+              disposeRejected();
+              return Response.json(
+                {
+                  error: {
+                    message:
+                      `model ${ctx.modelId} has no audio tower — audio input needs ` +
+                      `a model whose config.json carries audio_config and whose ` +
+                      `sidecar ships the audio tensors (e.g. gemma-4 e4b OptiQ)`,
+                  },
+                },
+                { status: 400 },
+              );
+            }
+            let visionSide:
+              | { tower: VisionEncoder; tokenIds: VisionTokenIds }
+              | undefined;
+            if (hasImages) {
+              const tower = getVisionTower(ctx);
+              if (!tower) {
+                disposeRejected();
+                return Response.json(
+                  { error: { message: "model has no vision sidecar" } }, { status: 400 },
+                );
+              }
+              visionSide = { tower, tokenIds: ctx.visionTokenIds };
+            }
+            const { messages: withAudioParts, images } =
+              await extractImages(normalizeMessages(body.messages));
+            const { messages, audio } = await extractAudio(withAudioParts);
+            // Non-WAV containers (mp3/m4a/flac/ogg/aiff/…) transcode to
+            // 16 kHz WAV via CoreAudio; RIFF bytes pass through untouched.
+            // Failures throw into the prompt-build 400 below.
+            const wavs = await Promise.all(audio.map(ensureWav));
+            // The towers are only ever non-null for Gemma4 (loader gates).
+            const mp = await buildMultimodalPrompt(
+              ctx.model as Gemma4Model,
+              {
+                ...(visionSide ? { vision: visionSide } : {}),
+                audio: { tower: audioTower, tokenIds: ctx.audioTokenIds },
+              },
+              ctx.tokenizer, ctx.template, messages, images, wavs, tools,
+            );
+            promptIds = mp.ids;
+            // bidirMask is null whenever audio is present (§3.3 Q1: mixed
+            // prompts run fully causal); the union mask does the per-layer
+            // id zeroing either way.
+            vision = {
+              embeddings: mp.embeddings,
+              ...(mp.bidirMask ? { imageMask: mp.bidirMask } : {}),
+              multimodalMask: mp.multimodalMask,
+            };
+          } else if (hasImages && ctx.model instanceof DiffusionGemmaModel) {
             // DiffusionGemma image-text-to-text: its OWN dedicated SigLIP tower +
             // encoder vision merge feed the denoising engine (NOT the AR
             // forwardEmbeddings path). v1 supports a single image.
             const dm = ctx.model;
-            if (!dm.visionTower)
+            if (!dm.visionTower) {
+              disposeRejected();
               return Response.json(
                 { error: { message: "this checkpoint has no vision tower" } }, { status: 400 },
               );
+            }
             const { messages, images } = await extractImages(normalizeMessages(body.messages));
-            if (images.length !== 1)
+            if (images.length !== 1) {
+              disposeRejected();
               return Response.json(
                 { error: { message: "DiffusionGemma image input supports exactly one image" } },
                 { status: 400 },
               );
+            }
             const rendered = ctx.template.render(messages, { tools, addGenerationPrompt: true });
             const rawIds = ctx.tokenizer.encode(rendered, /* addSpecialTokens */ false);
             const { pixels, softTokens } = await dm.visionTower.preprocess(images[0]!);
@@ -1769,10 +2975,12 @@ export function createServer(
             // Loads (and caches) the tower on first image request — text-only
             // sessions never pay for it.
             const tower = getVisionTower(ctx);
-            if (!tower)
+            if (!tower) {
+              disposeRejected();
               return Response.json(
                 { error: { message: "model has no vision sidecar" } }, { status: 400 },
               );
+            }
             const { messages, images } = await extractImages(normalizeMessages(body.messages));
             // The tower is only ever non-null for Gemma4 (sidecar gate in
             // makeVisionLoader), so the model narrow is safe here.
@@ -1786,8 +2994,10 @@ export function createServer(
             const built = promptIdsFor(body, tools);
             promptIds = built.ids;
             startInThinking = built.startInThinking;
+            stableLen = -1; // marker: chat path, probe lazily below
           }
         } catch (e) {
+          disposeRejected();
           return Response.json(
             { error: { message: `prompt build failed: ${(e as Error).message}` } },
             { status: 400 },
@@ -1796,22 +3006,33 @@ export function createServer(
         let options: ReturnType<typeof toOptions>;
         try {
           options = toOptions(body);
+          // Stable cache boundary for the prompt-boundary snapshot (chat
+          // prompts end in a generation primer the next turn won't contain).
+          // The probe costs a second full render+encode (~150 ms at 16k), so
+          // run it ONLY when a snapshot can actually be taken: the cache
+          // must not already hold the strict prefix (warm repeats peek at
+          // len-1 → skip; the snapshot gate needs boundary > cached prefix).
+          if (stableLen !== null) {
+            const cachePeek = promptCache.peekPrefixLen(
+              promptIds, options.adapters?.join("+") ?? "");
+            if (cachePeek < promptIds.length - 1)
+              options.snapshotAt = stableLenFor(body, tools, promptIds);
+          }
         } catch (e) {
           // bad logit_bias (non-numeric keys/values) — mlx-lm's coercion error
-          vision?.embeddings.dispose();
-          vision?.imageMask.dispose();
-          diffusionPixels?.dispose();
+          disposeRejected();
           return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
         }
         if (diffusionPixels) options.visionPixels = diffusionPixels;
+        // Attach the compiled grammar controller (null when no constraint /
+        // degrade — generate() runs the unmasked fast pipelined loop).
+        if (grammarCtrl) options.grammar = grammarCtrl;
         // Admission: reject what cannot finish within the memory budget
         // (the GPU OOM it would otherwise hit is uncatchable and kills
         // the process — Phase 6 finding).
         const requiredCtx = promptIds.length + (options.maxTokens ?? 1024);
         if (requiredCtx > admission.maxSafeContext) {
-          vision?.embeddings.dispose();
-          vision?.imageMask.dispose();
-          diffusionPixels?.dispose();
+          disposeRejected();
           return Response.json(
             {
               error: {
@@ -1833,6 +3054,7 @@ export function createServer(
           const adapterIds = ctx.adapters.resolveSpec(body.adapter ?? serverOptions.defaultAdapter);
           if (adapterIds.length) options.adapters = adapterIds;
         } catch (e) {
+          disposeRejected();
           return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
         }
 
@@ -1850,14 +3072,18 @@ export function createServer(
           options.topLogprobs = topLogprobs;
         }
 
-        // What lane this request takes (vision / adapters / logits processors /
-        // a user-fixed seed → serial; everything else batches when --batch N).
+        // What lane this request takes (vision/audio media / adapters /
+        // logprobs / seed / explicit kv-quant / a mounted draft → serial;
+        // sampler extras, repetition penalty, and grammar all BATCH — see
+        // willBatch). `vision` is the embeddings-prefill payload for BOTH
+        // media kinds, so hasVision routes audio serial too — batching is a
+        // mode, not a fallback, and batched audio has no oracle (§3.2).
         const shape = {
           hasVision: !!vision,
           hasAdapters: !!options.adapters?.length,
           hasRepetitionPenalty: !!options.repetitionPenalty,
-          // min_p / XTC / logit_bias / presence+frequency penalties: serial-only
-          // in v1 (see GenerationGateway.RequestShape.hasLogitsExtras).
+          // Informational since 2026-07-02: per-row logits processors batch;
+          // willBatch no longer gates on these fields.
           hasLogitsExtras: !!(
             options.minP || options.xtcProbability || options.logitBias ||
             options.presencePenalty || options.frequencyPenalty
@@ -1865,8 +3091,26 @@ export function createServer(
           wantsLogprobs: captureLogprobs,
           userSeed: body.seed !== undefined,
           kvQuant: !!(options.kvConfig?.length || options.kvBits),
+          turboQuant: !!options.turboQuant,
+          // grammarCtrl is null on the degrade path (prompt injection) —
+          // those stay batchable. A real controller batches via per-row
+          // matchers (MLX_BUN_GRAMMAR_BATCH=0 forces it serial).
+          hasGrammar: !!grammarCtrl,
+          hasDraft: !!ctx.draft,
         };
         const batched = gateway.willBatch(shape);
+        if (process.env.MLX_BUN_LANE_DEBUG === "1")
+          console.error(`[lane] batched=${batched} shape=${JSON.stringify(shape)} t=${Date.now() % 100000}`);
+        // Per-turn lane (docs/design/web-chat-redesign.md §2.3 caveat / risk #5):
+        // reported on usage AND recorded in the in-process lane registry (keyed
+        // by this response's `id`) so pi-web's WS bridge — which the pi SDK's
+        // usage parsing can't carry a custom field through — can correlate it
+        // via AssistantMessage.responseId. batched wins over hasDraft (mutually
+        // exclusive by construction: willBatch already excludes hasDraft), so
+        // the only ambiguity is serial vs serial+spec, resolved once s.spec is
+        // known post-generation.
+        const lane: Lane = batched ? "batched" : shape.hasDraft ? "serial+spec" : "serial";
+        recordLane(id, lane);
 
         if (body.stream) {
           const stream = new ReadableStream<Uint8Array>({
@@ -1944,6 +3188,11 @@ export function createServer(
                   ? "tool_calls"
                   : stopper.stopped ? "stop"
                   : s.generatedTokens >= (options.maxTokens ?? 1024) ? "length" : "stop";
+                // Refine serial vs serial+spec now that s.spec is known (a mounted
+                // draft can still decode zero speculative tokens on a very short
+                // reply) and re-record for pi-web's WS correlation.
+                const finalLane: Lane = batched ? "batched" : s.spec ? "serial+spec" : lane;
+                if (finalLane !== lane) recordLane(id, finalLane);
                 send({
                   ...chunk({}, finish),
                   usage: {
@@ -1951,6 +3200,8 @@ export function createServer(
                     completion_tokens: s.generatedTokens,
                     total_tokens: s.promptTokens + s.generatedTokens,
                     prompt_tokens_details: { cached_tokens: s.cachedTokens },
+                    lane: finalLane,
+                    ...(s.spec ? { speculation: s.spec } : {}),
                   },
                 });
                 // bare sentinel per the OpenAI spec — JSON.stringify would
@@ -1968,6 +3219,7 @@ export function createServer(
               "content-type": "text/event-stream",
               "cache-control": "no-cache",
               connection: "keep-alive",
+              ...(grammarWarning ? { Warning: grammarWarning } : {}),
             },
           });
         }
@@ -2013,6 +3265,10 @@ export function createServer(
               : stopper.stopped ? "stop"
               : s.generatedTokens >= (options.maxTokens ?? 1024) ? "length" : "stop";
             const logprobsBlock = lpc?.payload() ?? null;
+            // Refine serial vs serial+spec now that s.spec is known; re-record
+            // for pi-web's WS correlation (see the streaming branch above).
+            const finalLane: Lane = batched ? "batched" : s.spec ? "serial+spec" : lane;
+            if (finalLane !== lane) recordLane(id, finalLane);
             return Response.json({
               id, object: "chat.completion", created, model: ctx.modelId,
               choices: [{
@@ -2031,8 +3287,10 @@ export function createServer(
                 completion_tokens: s.generatedTokens,
                 total_tokens: s.promptTokens + s.generatedTokens,
                 prompt_tokens_details: { cached_tokens: s.cachedTokens },
+                lane: finalLane,
+                ...(s.spec ? { speculation: s.spec } : {}),
               },
-            });
+            }, grammarWarning ? { headers: { Warning: grammarWarning } } : undefined);
           }
         } catch (e) {
           return Response.json({ error: { message: (e as Error).message } }, { status: 500 });
@@ -2086,12 +3344,34 @@ export function createServer(
           // bad logit_bias (non-numeric keys/values) — mlx-lm's coercion error
           return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
         }
+        // Grammar-constrained decoding on raw completions too (response_format /
+        // guided_* / structured_outputs). The degrade path for /v1/completions
+        // has no chat template to inject a system message into, so a degrade
+        // only emits the Warning header (no prompt injection) — documented gap
+        // vs the chat lane, which mirrors oMLX's text-completions behavior.
+        let textGrammarWarning: string | null = null;
+        const textGrammarReq =
+          body.response_format != null || !!body.guided_grammar ||
+          !!body.guided_regex || !!body.guided_choice?.length ||
+          body.structured_outputs != null;
+        if (textGrammarReq) {
+          const g = await compileGrammarForRequest(body as unknown as ChatRequest);
+          if (g.controller) options.grammar = g.controller;
+          else if (g.degradeHint)
+            textGrammarWarning = `grammar not enforced: ${g.degradeHint} — no prompt injection on /v1/completions`;
+        }
+        // Mirrors the chat lane: a real controller (not the degrade path)
+        // shapes the request for per-row grammar batching.
+        const textGrammarCtrl = options.grammar ?? null;
         // mlx_lm.server's default max_tokens is 512 (its --max-tokens CLI
         // default). The chat lane's very generous default is wrong for raw
         // completion: with no template an EOS may never come.
         options.maxTokens = body.max_completion_tokens ?? body.max_tokens ?? serverOptions.defaultMaxTokens ?? 512;
         const requiredCtx = promptIds.length + options.maxTokens;
-        if (requiredCtx > admission.maxSafeContext)
+        if (requiredCtx > admission.maxSafeContext) {
+          // Pre-run reject: the gateway only takes grammar disposal ownership
+          // once run — free the WASM matcher here (chat lane: disposeRejected).
+          textGrammarCtrl?.dispose();
           return Response.json(
             {
               error: {
@@ -2106,10 +3386,12 @@ export function createServer(
             },
             { status: 400 },
           );
+        }
         try {
           const adapterIds = ctx.adapters.resolveSpec(body.adapter ?? serverOptions.defaultAdapter);
           if (adapterIds.length) options.adapters = adapterIds;
         } catch (e) {
+          textGrammarCtrl?.dispose();
           return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
         }
         // logprobs capture — same mlx-lm block as chat (generate_response is
@@ -2135,6 +3417,11 @@ export function createServer(
           wantsLogprobs: captureLogprobs,
           userSeed: body.seed !== undefined,
           kvQuant: !!(options.kvConfig?.length || options.kvBits),
+          turboQuant: !!options.turboQuant,
+          // /v1/completions grammar (textGrammarCtrl). Same null-on-degrade
+          // contract as the chat lane.
+          hasGrammar: !!textGrammarCtrl,
+          hasDraft: !!ctx.draft,
         };
         const finishReason = (stopped: boolean, generated: number): "stop" | "length" =>
           stopped ? "stop" : generated >= (options.maxTokens ?? 512) ? "length" : "stop";
@@ -2182,6 +3469,7 @@ export function createServer(
                     completion_tokens: s.generatedTokens,
                     total_tokens: s.promptTokens + s.generatedTokens,
                     prompt_tokens_details: { cached_tokens: s.cachedTokens },
+                    ...(s.spec ? { speculation: s.spec } : {}),
                   },
                 });
                 controller.enqueue(enc.encode("data: [DONE]\n\n"));
@@ -2197,6 +3485,7 @@ export function createServer(
               "content-type": "text/event-stream",
               "cache-control": "no-cache",
               connection: "keep-alive",
+              ...(textGrammarWarning ? { Warning: textGrammarWarning } : {}),
             },
           });
         }
@@ -2231,8 +3520,9 @@ export function createServer(
               completion_tokens: s.generatedTokens,
               total_tokens: s.promptTokens + s.generatedTokens,
               prompt_tokens_details: { cached_tokens: s.cachedTokens },
+                    ...(s.spec ? { speculation: s.spec } : {}),
             },
-          });
+          }, textGrammarWarning ? { headers: { Warning: textGrammarWarning } } : undefined);
         } catch (e) {
           return Response.json({ error: { message: (e as Error).message } }, { status: 500 });
         }
@@ -2598,6 +3888,27 @@ export function createServer(
         saveHfToken(body.token);
         return Response.json({ ok: true });
       }
+
+      // --- Durable tool-approvals settings (plan §5.4/§6.5/§9 Phase 2) ---
+      // The web chat's own "always allow this tool" list
+      // (~/.mlx-bun/tool-approvals.json, src/tool-approvals.ts). The
+      // approval card itself grants an always-allow via the `approval` WS
+      // frame (alwaysAllow:true) — these REST routes are read/forget only,
+      // for the settings panel's list view (matches the hf-token GET/POST
+      // pattern's separation of "the card that grants" vs "settings that
+      // manage" — there is no POST here on purpose, granting always goes
+      // through the approval card, never a bare settings form).
+      if (url.pathname === "/api/settings/tool-approvals" && request.method === "GET") {
+        const { listAlwaysAllowedTools } = await import("./tool-approvals");
+        return Response.json({ ok: true, alwaysAllow: listAlwaysAllowedTools() });
+      }
+      if (url.pathname === "/api/settings/tool-approvals" && request.method === "DELETE") {
+        const body = (await request.json().catch(() => ({}))) as { tool?: string };
+        if (!body.tool) return Response.json({ ok: false, error: "tool required" }, { status: 400 });
+        const { revokeToolAlwaysAllowed } = await import("./tool-approvals");
+        const file = revokeToolAlwaysAllowed(body.tool);
+        return Response.json({ ok: true, alwaysAllow: Object.keys(file.allows).sort() });
+      }
       {
         const m = url.pathname.match(/^\/api\/(quantize|finetune|dataset)\/push$/);
         if (m && request.method === "POST") {
@@ -2626,6 +3937,50 @@ export function createServer(
         }
       }
 
+      // gc plan/execute (web-ui-pass-plan.md #9): thin wrappers over the CLI's
+      // own `mlx-bun gc` planner/executor (src/registry.ts planGc/executeGc).
+      // Loopback-served admin route — no auth beyond the server's own bind
+      // (matches every other /api/* route here). GET plans (read-only, cheap:
+      // config.json + safetensors index reads, no tensor bytes); POST executes
+      // and requires an explicit {yes:true} body (mirrors the CLI's --yes gate)
+      // so a stray call can't delete anything by accident.
+      if (url.pathname === "/api/gc/plan" && request.method === "GET") {
+        const { planGc } = await import("./registry");
+        const plans = planGc().filter(
+          (p) => p.pruneSnapshots.length || p.skippedSnapshots.length || p.deadBlobs.length,
+        );
+        const superseded = plans.map((p) => ({
+          repo_id: p.repoId,
+          prune_snapshots: p.pruneSnapshots.length,
+          skipped_snapshots: p.skippedSnapshots.length,
+          dead_blobs: p.deadBlobs.length,
+          reclaim_bytes: p.reclaimBytes,
+        }));
+        const reclaim_bytes = plans.reduce((a, p) => a + p.reclaimBytes, 0);
+        return Response.json({ ok: true, superseded, reclaim_bytes });
+      }
+      if (url.pathname === "/api/gc/execute" && request.method === "POST") {
+        const body = (await request.json().catch(() => ({}))) as { yes?: boolean };
+        if (body.yes !== true)
+          return Response.json({ ok: false, error: "pass {\"yes\": true} to confirm deletion" }, { status: 400 });
+        const { planGc, executeGc, Registry } = await import("./registry");
+        const plans = planGc().filter(
+          (p) => p.pruneSnapshots.length || p.skippedSnapshots.length || p.deadBlobs.length,
+        );
+        const res = executeGc(plans);
+        const reg = new Registry();
+        try {
+          await reg.scan(); // reap deleted snapshots from the registry
+        } finally {
+          reg.close();
+        }
+        libraryCache = null; // force /library to reflect the deletion
+        return Response.json({
+          ok: true,
+          snapshots: res.snapshots, blobs: res.blobs, reclaimed_bytes: res.reclaimedBytes,
+        });
+      }
+
       if (url.pathname === "/api/jobs" && request.method === "GET") {
         const store = await ensureJobs();
         const limit = Number(url.searchParams.get("limit") ?? "50");