mlx-bun 0.2.0 → 0.4.0

package/src/server.ts

@@ -1,3 +1,7 @@
+import { ContinuationPersistence } from "./backends/mlx/continuation-persistence";
+import { modelServingBinding } from "./backends/mlx/model-serving";
+import type { ServingContext } from "./serve/model-host";
+export { generationCheckpointKey } from "./serve/checkpoint-identity";
 // OpenAI-compatible HTTP server: /v1/chat/completions (+ SSE streaming)
 // and /v1/models. Phase 4 core — tool calling, vision, and the
 // byte-capped prompt cache land on top of this.
@@ -9,89 +13,30 @@
 // Generation is serialized through a single queue (one GPU, batch=1).
 
 import type { Server } from "bun";
-// Embedded web app — the unified SPA (chat / quantize / finetune /
-// dataset / status). `with { type: "text" }` inlines the file in both
-// `bun run` and the compiled single binary. bun-types types *.html
-// imports as HTMLBundle (the html loader), but the text attribute makes
-// 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 { existsSync, 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;
-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,
-  openGlm52RuntimeModel,
-  type Glm52RuntimeOpenOptions,
-  type RuntimeModel,
-} from "./model/factory";
-import { Glm52Model } from "./model/glm52";
+import { STATIC_ROUTE_ASSETS } from "./web-assets";
+import { readFileSync } from "node:fs";
+import { type TurboQuantScheme } from "./config";
 import {
   GLM52_G5_ASPIRATIONAL_DECODE_TPS,
   GLM52_G5_DIRECT_ORACLE_WARM_DECODE_TPS,
   GLM52_G5_MEASURED_AT,
   GLM52_G5_MEASURED_WARM_DECODE_TPS,
-  type Glm52MemoryPlan,
 } from "./model/glm52-memory";
-import { isMiniCPM5Config } from "./model/support";
-import { resolveModelProfile, type ResolvedModelProfile } from "./model/profile";
-import { Glm52NativeMtpProvider } from "./spec/glm52-mtp-source";
 import {
-  generate,
   type GenerateOptions,
-  type TokenLogprobs,
-  withModelUsageFlush,
-  withModelWiredLimit,
 } from "./generate";
-import { cloneKvCaches, SpillQueue } from "./kv-store";
+import { createPreparationExecutor } from "./serve/preparation";
+import { cloneKvCaches, legacyCacheCodecs, SpillQueue } from "./kv-store";
+import type { Cache } from "./model/gemma4";
 import { resolveKvScheme } from "./kv-scheme";
 import { runtimeValue } from "./runtime-config";
 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 { isMonotone, CURVE_UMIN, type CurveParams } from "./lab/curve/curve-sampler";
+import { GenerationGateway, disposeUnstartedRequest } from "./serve/generation-gateway";
+import { createSessionCompletionEngine } from "./serve/session-completion-engine";
 import {
   CompletionExecutor,
-  CompletionRejected,
-  prepareCompletion,
-  type CompletionSummary,
-  type PreparedCompletion,
 } from "./serve/completion-executor";
 import {
   createPromptResponseTrace,
@@ -99,34 +44,11 @@ import {
 } from "./serve/prompt-response-trace";
 import { handleAdminRoute } from "./serve/admin-routes";
 import { handleAuxiliaryRoute } from "./serve/aux-routes";
-import {
-  createTimedFlowControl,
-  type CompletionEvent,
-  type CompletionStreamProtocol,
-} from "./serve/completion-sink";
 import { createDiscoveryRoutes } from "./serve/discovery-routes";
 import { handleLabRoute } from "./serve/lab-routes";
 import { handleModelAdminRoute } from "./serve/model-admin-routes";
-import { RequestOwnership } from "./serve/request-plan";
 import { handleStaticRoute } from "./serve/static-routes";
-const STATIC_ROUTE_ASSETS = {
-  appPage: APP_PAGE,
-  appJs: APP_JS,
-  hljsJs: HLJS_JS,
-  hljsCss: HLJS_CSS,
-  manifest: MANIFEST_WEBMANIFEST,
-  iconSvg: ICON_SVG,
-  serviceWorker: SW_JS,
-  curvePage: CURVE_PAGE,
-};
-import {
-  ChatTemplate, type ChatMessage, type ToolDefinition,
-} from "./chat-template";
-import { loadTokenizer, type LoadedTokenizer } from "./tokenizer";
-import {
-  CHANNEL_END, CHANNEL_START, parseGeneratedToolCalls, parseToolCalls,
-  TOOL_CALL_END, TOOL_CALL_START,
-} from "./tool-call";
+
 import { PromptCache, cacheBytes } from "./prompt-cache";
 import { SsdCacheStore } from "./ssd-cache";
 import {
@@ -140,27 +62,46 @@ import {
   type AnthropicRequest,
 } from "./anthropic";
 import {
-  ResponseStore, chatJsonToResponses, outputItemsToInputItems,
+  ResponseStore, chatJsonToResponses, resolveResponsesConversation,
   responsesToChatBody, createResponsesStreamProtocol,
   type ResponsesRequest,
 } from "./responses";
-import { AdapterManager } from "./lora";
 import { fit } from "./fit";
 import { setMemoryLimit } from "./mlx/ffi";
-import { VisionTower } from "./vision/embedder";
-import { SiglipVisionTower, parseSiglipConfig } from "./vision/siglip";
-import { Qwen3VLVisionTower } from "./vision/qwen3vl-tower";
-import { buildQwen3VLVisionPrompt } from "./vision/qwen3vl-prompt";
-import { Qwen35Model } from "./model/qwen3_5";
-import type { MropeRequestState } from "./model/qwen3-mrope";
-import {
-  buildMultimodalPrompt, buildVisionPrompt, extractAudio, extractImages, extractVideos,
-  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";
+import { ChatStage } from "./serve/chat-stage";
+import { TextCompletionStage } from "./serve/text-completion-stage";
+import { InferenceStage } from "./serve/inference-request";
+import { admit, respondJson, respondStream, type ErrorFormatter } from "./serve/http";
+import {
+  chatCompletionJson, chatCompletionStream, textCompletionJson, textCompletionStream,
+} from "./serve/openai-wire";
+import { createRequestPrep } from "./serve/request-prep";
+import {
+  detectDraftKind,
+  loadContext,
+  type DraftKind,
+  type GenSamplingDefaults,
+  type LoadContextOptions,
+  type ServerContext,
+} from "./serve/model-host";
+import {
+  ChatRequest,
+  TextCompletionRequest,
+  type ChatRequestParams,
+  type TextCompletionParams,
+} from "./serve/chat-request";
+
+// The serving facade: createServer's companion loaders stay importable from
+// here (public library API via src/index.ts; bench scripts; parity tests).
+export {
+  detectDraftKind,
+  loadContext,
+  type DraftKind,
+  type GenSamplingDefaults,
+  type LoadContextOptions,
+  type ServerContext,
+};
 
 export interface ServerOptions {
   /** Byte cap for the prompt (KV) cache. Default 8 GB. */
@@ -169,34 +110,30 @@ export interface ServerOptions {
    *  (`--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). */
+   *  aggregate cap (an explicit memoryBudget also limits each request). */
   kvBudgetBytes?: number;
   /** KV quantization override. Unset/"off" is bf16. "config" applies the
    *  model's declared mixed-precision kv_config; supported per-layer schemes
    *  compose with continuous scheduling. A number forces uniform bits
    *  (group size 64, start 0) and uses the preserved serial executor. */
   kvQuant?: "off" | "config" | number;
-  /** TurboQuant scheme (docs/design/turboquant-kv.md): a separate axis from
+  /** Optional absolute row offset for KV conversion; omitted preserves start-zero server policy. */
+  quantizedKvStart?: number;
+  /** TurboQuant scheme (docs/design/turboquant.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):
+  /** OPTIONAL paged KV cache (`--paged-kv`, docs/design/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`,
+   *  plain KVCache path, byte-identical). Gemma4-family, bf16, B1/B>1;
+   *  startup refuses `--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
-   *  crash class is UNCATCHABLE (Phase 6 — mlx throws from a Metal
-   *  completion handler ⇒ std::terminate; optiq serve died exactly this
-   *  way loading the 26B). Also caps the mlx allocator
-   *  (mlx_set_memory_limit) as defense in depth. Default: machine RAM ×
-   *  WIRED_FRACTION, admission check only, allocator untouched. */
+  /** Explicit opt-in process budget. Enforces the fit estimate's context
+   *  limit and sets the MLX allocator limit. Unset keeps estimates advisory. */
   memoryBudgetBytes?: number;
   /** Who owns this server's lifetime: "serve" (persistent, mlx-bun
    *  serve) or "pi-session" (dies with the pi session that started
@@ -204,7 +141,7 @@ export interface ServerOptions {
    *  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
+   *  child mode of the isolation architecture (docs/reference/server-config.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;
@@ -244,10 +181,10 @@ export interface ServerOptions {
   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
+   *  long-context TTFT win (docs/design/kv-cache.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). */
+  /** Optional byte cap for the SSD tier (default unbounded). */
   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
@@ -257,9 +194,16 @@ export interface ServerOptions {
   /** Verify every tensor hash on restore (`--ssd-cache-verify`) — reads all
    *  bytes eagerly, defeating lazy fault-in; integrity paranoia only. */
   ssdCacheVerify?: boolean;
+  /** Periodically persist an in-flight serial generation every N emitted
+   *  tokens. An identical request after restart replays the saved assistant
+   *  prefix and continues from the already-sampled next token. Requires the
+   *  SSD cache and --batch 1. */
+  generationCheckpointTokens?: number;
 }
 
 interface ServerLifecycle {
+  stopJobs: () => Promise<void>;
+  close: () => Promise<void>;
   flush: () => Promise<DurabilityFlushResult>;
   stats: () => DurabilitySnapshotStats;
   stopTimers: () => void;
@@ -302,8 +246,10 @@ export async function shutdownServer(
   lifecycle?.stopTimers();
   const stopped = Promise.resolve(server.stop(false));
   const work = (async (): Promise<ServerShutdownResult> => {
+    await lifecycle?.stopJobs();
     await stopped;
     const durability = lifecycle ? await lifecycle.flush() : emptyDurabilityResult();
+    await lifecycle?.close();
     return { stopped: true, timedOut: false, durability };
   })();
   let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
@@ -330,548 +276,6 @@ export async function shutdownServer(
   }
 }
 
-export interface ServerContext {
-  model: RuntimeModel;
-  /** Declared external artifact/family profile that selected model
-   * construction. Request-level methods are resolved separately. */
-  profile: ResolvedModelProfile;
-  tokenizer: LoadedTokenizer;
-  template: ChatTemplate;
-  modelId: string;
-  /** Lazily-loaded vision tower cache — null until the first image request
-   *  (see `getVisionTower`). The tower (SigLIP ~hundreds of MB, encoder-free
-   *  smaller) is not loaded for text-only sessions. */
-  vision: VisionEncoder | null;
-  /** Loads + selects the vision tower on demand; null when the model has no
-   *  (supported) vision sidecar. Invoked at most once, then cached in
-   *  `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;
-   *  ServerOptions.kvQuant overrides ("off" | uniform bits). */
-  kvConfig: KvQuantSpec[] | null;
-  /** Model-author recommended sampling from generation_config.json —
-   *  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;
-  /** Present only for the direct Colibri GLM runtime. This is the exact
-   * header-derived process equation used before opening resident state. */
-  glmMemoryPlan?: Glm52MemoryPlan | null;
-}
-
-export interface LoadContextOptions {
-  memoryBudgetBytes?: number;
-  /** Direct Colibri runtime/resource overrides. Ignored by other models. */
-  glm?: Glm52RuntimeOpenOptions;
-  /** Snapshot dir of a draft model for speculative decoding
-   * (`--draft-model`). Loaded alongside the target; the pair must share
-   * a tokenizer family. */
-  draftModelDir?: string;
-  /** Drafts per round (`--num-draft-tokens`, mlx_lm.server default 3). */
-  numDraftTokens?: number;
-  /** Draft-provider kind override (`--draft-kind`). */
-  draftKind?: DraftKind;
-  ngramMax?: number;
-  ngramMin?: number;
-}
-
-export interface GenSamplingDefaults {
-  temperature?: number;
-  topP?: number;
-  topK?: number;
-  repetitionPenalty?: number;
-}
-
-export type DraftKind = "dspark" | "deepspec" | "assistant" | "two-model" | "ngram" | "mtp";
-
-/** 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";
-    // Native MTP heads split from a qwen3_5-family release
-    // (mlx-community/Qwen3.8-27B-MTP-*): model_type "qwen3_5_mtp". The
-    // target's recurrent DeltaNet caches roll back via the serve loop's
-    // spec-round snapshot/replay contract (SSMCache.specRound*).
-    if (String(cfg.model_type ?? "").endsWith("_mtp")) return "mtp";
-  } 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 {};
-  try {
-    const raw = (await file.json()) as Record<string, unknown>;
-    const num = (v: unknown) => (typeof v === "number" ? v : undefined);
-    return {
-      temperature: num(raw.temperature),
-      topP: num(raw.top_p),
-      topK: num(raw.top_k),
-      repetitionPenalty: num(raw.repetition_penalty),
-    };
-  } catch {
-    return {};
-  }
-}
-
-export async function loadContext(
-  modelDir: string, modelId?: string,
-  opts: LoadContextOptions = {},
-): Promise<ServerContext> {
-  const config = await loadModelConfig(modelDir);
-  const profile = resolveModelProfile(config);
-  const glm = profile.profile.execution.loader === "colibri";
-  // Bundled MTP companion: `--draft-kind mtp` with no --draft-model resolves
-  // to the artifact's own mtp/ subfolder (single-repo packaging — the
-  // companion is a complete model dir the provider already loads). Explicit
-  // --draft-model still wins; a missing bundle is a clear refusal below.
-  if (opts.draftKind === "mtp" && !opts.draftModelDir) {
-    const bundled = `${modelDir}/mtp`;
-    if (await Bun.file(`${bundled}/config.json`).exists()) {
-      opts = { ...opts, draftModelDir: bundled };
-    } else {
-      throw new Error(
-        `--draft-kind mtp needs a companion: pass --draft-model <dir> or use ` +
-        `an artifact that bundles one at <model>/mtp/ (none at ${bundled})`,
-      );
-    }
-  }
-  const externalDraft = opts.draftModelDir !== undefined || opts.draftKind !== undefined;
-  const resolvedDraftKind = opts.draftModelDir
-    ? opts.draftKind ?? await detectDraftKind(opts.draftModelDir)
-    : opts.draftKind;
-  if (glm && externalDraft && opts.glm?.enableMtp === true)
-    throw new Error("native GLM MTP and --draft-model/--draft-kind are mutually exclusive");
-  let weights: Weights | null = null;
-  let model!: RuntimeModel;
-  let glmMemoryPlan: Glm52MemoryPlan | null = null;
-  if (glm) {
-    const enableNativeMtp = !externalDraft && opts.glm?.enableMtp !== false;
-    const opened = await openGlm52RuntimeModel(modelDir, {
-      ...opts.glm,
-      memoryBudgetBytes: opts.memoryBudgetBytes ?? opts.glm?.memoryBudgetBytes,
-      // Every drafter owns the serial speculative lane. Do not reserve a
-      // simultaneous ordinary batch that cannot be admitted while it is live.
-      batchSize: enableNativeMtp || externalDraft ? 1 : opts.glm?.batchSize,
-      // An explicit alternate drafter owns the one speculative lane.
-      enableMtp: enableNativeMtp,
-    });
-    model = opened.model;
-    glmMemoryPlan = opened.plan;
-  } else {
-    weights = await Weights.open(modelDir);
-  }
-  // memoryBudget enforcement at load (Phase 5): Weights.open only mmaps
-  // (no GPU allocation yet), so a model whose weights can never serve
-  // within the budget is refused HERE — before any unified-memory
-  // commitment — with an actionable error instead of a Metal OOM later.
-  if (!glm && opts.memoryBudgetBytes) {
-    const weightsBytes = [...weights!.shards.files.values()]
-      .reduce((a, f) => a + f.mmap.size, 0);
-    const report = fit(config, weightsBytes, 1, undefined, undefined, 0, opts.memoryBudgetBytes);
-    if (report.maxSafeContext < 1)
-      throw new Error(
-        `model does not fit the memory budget: weights ${(weightsBytes / 1e9).toFixed(2)} GB ` +
-        `+ prefill transient leave no room for any context within ` +
-        `${(opts.memoryBudgetBytes / 1e9).toFixed(2)} GB`,
-      );
-  }
-  if (!glm) model = createModel(weights!, config, profile);
-  const tokenizer = await loadTokenizer(modelDir);
-  // Generation must stop on the tokenizer's eos_token — the chat turn
-  // terminator (e.g. Qwen <|im_end|> = 248046). Some configs (Qwen3.5-4B)
-  // declare a different eos_token_id in config.json than the chat format
-  // emits, so without this a turn never ends and generation runs away,
-  // hallucinating both sides of the dialogue until max_tokens. mlx-lm stops on
-  // 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 = resolvedDraftKind!;
-    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 if (kind === "mtp") {
-      const { QwenMtpProvider } = await import("./spec/qwen-mtp-source");
-      const p = await QwenMtpProvider.load(dir);
-      provider = p;
-      // Default the round width to the head's trained block (block_size 3 →
-      // 2 recursive drafts + the pending row per round; the head was trained
-      // multi-step, so an explicit larger --num-draft-tokens is allowed but
-      // acceptance decides whether it pays).
-      const block = (await Bun.file(`${dir}/config.json`).json() as { block_size?: number }).block_size;
-      if (opts.numDraftTokens === undefined && typeof block === "number")
-        numDraftTokens = Math.max(1, block - 1);
-    } 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
-        ? [...weights.shards.files.values()].reduce((a, f) => a + f.mmap.size, 0)
-        : model.weightsBytes;
-      // 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`);
-  }
-
-  // GLM's checkpoint-native MTP row is the production default. It uses the
-  // already-planned bounded auxiliary expert tier and the same tokenizer, so
-  // there is no second artifact or compatibility probe to load.
-  if (!draft && model instanceof Glm52Model && glmMemoryPlan?.enableMtp) {
-    draft = {
-      provider: new Glm52NativeMtpProvider(model),
-      numDraftTokens: glmMemoryPlan.mtpDraftTokens,
-    };
-  }
-
-  return {
-    draft,
-    model,
-    profile,
-    glmMemoryPlan,
-    adapters: new AdapterManager(model),
-    kvConfig: config.kvQuant,
-    genDefaults: await loadGenSamplingDefaults(modelDir),
-    tokenizer,
-    template: await ChatTemplate.load(modelDir),
-    modelId: modelId ?? modelDir.split("/").filter(Boolean).at(-1)!,
-    // Vision is loaded lazily (getVisionTower) — text-only sessions never
-    // pay for the tower. The loader picks the encoder-free gemma4_unified
-    // (12B) tower vs the SigLIP encoder (e2b/e4b/26B/31B) by the sidecar's
-    // vision_config.model_type. Vision sidecars are a Gemma4 feature;
-    // MiniCPM5 never ships one.
-    vision: null,
-    loadVision: makeVisionLoader(modelDir, model, config),
-    visionTokenIds: {
-      imageTokenId: (config.raw.image_token_id as number) ?? 258880,
-      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,
-  };
-}
-
-/** Build the on-demand vision-tower loader, selecting the encoder-free
- *  (gemma4_unified, 12B) tower vs the SigLIP encoder (gemma4_vision:
- *  e2b/e4b/26B/31B) by the sidecar's vision_config.model_type. Returns null
- *  when the model has no usable vision sidecar. */
-function makeVisionLoader(
-  modelDir: string, model: RuntimeModel, config: ModelConfig,
-): (() => VisionEncoder) | null {
-  // Qwen3.5/3.8: the tower ships as optiq/optiq_vision.safetensors (the
-  // artifact's bf16 sidecar). The returned tower is a Qwen3VLVisionTower —
-  // it rides the same lazy slot/capability flags; the qwen chat branch is
-  // the only consumer and casts it back (the gemma branches are gated on
-  // `instanceof Gemma4Model`, so the union never crosses).
-  if (model instanceof Qwen35Model) {
-    // Vision weights arrive either as the OptiQ-convention sidecar OR in-main
-    // (mlx-vlm convention; our artifacts ship one copy in-main since
-    // 2026-08-18 — the tower loader handles both).
-    const hasSidecar = existsSync(`${modelDir}/optiq/optiq_vision.safetensors`);
-    const hasInMain = config.raw.vision_config !== undefined;
-    if (!hasSidecar && !hasInMain) return null;
-    return () =>
-      Qwen3VLVisionTower.load(modelDir) as unknown as VisionEncoder;
-  }
-  if (!(config.hasVisionSidecar && model instanceof Gemma4Model)) return null;
-  const vc = config.raw.vision_config as Record<string, any> | undefined;
-  if (vc?.model_type === "gemma4_vision") {
-    const sigCfg = parseSiglipConfig(vc);
-    return () => SiglipVisionTower.load(modelDir, sigCfg, model.embedScale);
-  }
-  // gemma4_unified_vision (or unlabelled): the encoder-free patch embedder.
-  return () => VisionTower.load(modelDir, model.embedScale, config.text.rmsNormEps);
-}
-
-/** Lazily load + cache the vision tower on first use. A sidecar that fails
- *  to load is a capability gap, not a fatal error: returns null and the
- *  request is answered with a 400 (the loader is cleared so we don't retry
- *  a known-bad load every request). */
-function getVisionTower(ctx: ServerContext): VisionEncoder | null {
-  if (ctx.vision) return ctx.vision;
-  if (!ctx.loadVision) return null;
-  try {
-    ctx.vision = ctx.loadVision();
-    return ctx.vision;
-  } catch (e) {
-    console.warn(`vision sidecar not loadable (${(e as Error).message}) — serving text-only`);
-    ctx.loadVision = null;
-    return 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;
-  max_tokens?: number;
-  max_completion_tokens?: number;
-  temperature?: number;
-  top_p?: number;
-  top_k?: number;
-  seed?: number;
-  repetition_penalty?: number;
-  /** mlx-lm extension: recent-token window for repetition_penalty
-   *  (default 20; 0 = whole history, Python `[-0:]` semantics). */
-  repetition_context_size?: number;
-  /** min-p sampling (mlx_lm.server's `min_p`): keep tokens whose probability
-   *  is ≥ min_p · p(top token). 0 = off. */
-  min_p?: number;
-  /** XTC sampling (mlx_lm.server names): with probability `xtc_probability`
-   *  per step, remove every token above `xtc_threshold` except the least
-   *  likely of them. EOS + the newline token are always exempt (the server
-   *  injects them as xtc special tokens, matching mlx_lm.server). */
-  xtc_probability?: number;
-  xtc_threshold?: number;
-  /** OpenAI logit_bias: {tokenId: additive bias}. JSON object keys arrive as
-   *  strings; coerced to int keys / float values like mlx-lm (400 on failure). */
-  logit_bias?: Record<string, number>;
-  /** OpenAI presence/frequency penalties + mlx-lm's context-size extensions
-   *  (window of recent tokens the penalty looks at; default 20). */
-  presence_penalty?: number;
-  presence_context_size?: number;
-  frequency_penalty?: number;
-  frequency_context_size?: number;
-  /** mlx_lm.server logprobs: `logprobs` is a BOOL (even on /v1/completions —
-   *  not OpenAI's legacy int), `top_logprobs` an int in [0, 11] or the -1
-   *  "unset" sentinel (server.py validates exactly that; OpenAI's cap is 20,
-   *  mlx-lm's is 11 — we copy the reference). Non-stream responses carry
-   *  mlx-lm's logprobs block; stream chunks never do (reference behavior). */
-  logprobs?: boolean;
-  top_logprobs?: number;
-  /** OpenAI stop sequences: plain string or array (spec allows up to 4).
-   *  Matched on DECODED text, not token ids — see StopMatcher. */
-  stop?: string | string[];
-  tools?: ToolDefinition[];
-  tool_choice?: "auto" | "none" | { type: string; function?: { name: string } };
-  /** Forwarded to HF chat templates, matching optiq serve. MiniCPM5 uses
-   *  enable_thinking to select direct answers vs the <think> channel; Qwen3.8
-   *  adds preserve_thinking (keep think blocks from history; template default
-   *  true — better prompt-cache reuse in agent loops). */
-  chat_template_kwargs?: {
-    enable_thinking?: boolean;
-    preserve_thinking?: boolean;
-    [key: string]: unknown;
-  };
-  /** OpenAI reasoning control. For models with a switchable <think> channel
-   *  (Qwen3.5/MiniCPM5) it gates enable_thinking: "none" → off, any level → on.
-   *  This is what Pi sends when the provider advertises reasoning. For
-   *  templates that read a reasoning-depth variable (Qwen3.8: xhigh/medium/
-   *  low), the level ALSO maps into the template via qwenReasoningEffort —
-   *  "xhigh" accepted as a first-class value (Qwen3.8's default/deepest). */
-  reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
-  /** Mounted LoRA adapter selection: "id", "a+b" (stacked), or "none". */
-  adapter?: string;
-  /** HLG tone-curve sampling override (per request). Snake_case wire fields,
-   *  merged over the server's --hlg-sampling config. docs/design/hlg-sampling.md. */
-  hlg?: {
-    enabled?: boolean;
-    width?: number;
-    shoulder?: number;
-    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
- *  template). Sampling/penalty/stop fields are the same names as ChatRequest;
- *  `prompt` replaces `messages`. mlx_lm.server accepts only a STRING prompt
- *  (it calls `tokenizer.encode(request.prompt)` directly) — token-array
- *  prompts are rejected there too, so we match. No `echo` (mlx-lm has none). */
-type TextCompletionRequest = Omit<ChatRequest, "messages" | "tools" | "tool_choice"> & {
-  prompt?: unknown;
-};
 
 export interface ContextAdmissionDecision {
   /** Effective completion ceiling after admission. */
@@ -880,16 +284,8 @@ export interface ContextAdmissionDecision {
   clamped: boolean;
 }
 
-/** Resolve a request's completion upper bound against the admitted context.
- *
- * `max_tokens` is a ceiling, not a promise that every token will be emitted:
- * when a prompt fits but a broad client-wide `max_tokens` would push the
- * reservation past the safe context, the bound is CLAMPED to the remaining
- * room instead of rejecting an otherwise valid request (the pre-v0.0.13
- * behavior 400'd a prompt with thousands of tokens of generation room over a
- * 17-token overshoot). This never weakens the OOM guard — generation stops at
- * the clamped ceiling, inside the admitted context. Only a prompt that leaves
- * no generation slot at all is rejected. */
+/** Resolve a completion cap against an explicitly enforced context limit.
+ * Serving keeps fit estimates advisory unless the operator chooses a budget. */
 export function admitRequestContext(
   promptTokens: number,
   requestedMaxTokens: number,
@@ -902,744 +298,7 @@ export function admitRequestContext(
   return { maxTokens: available, clamped: true };
 }
 
-/** Per-field default HLG knobs when enabling without specifying them. */
-const HLG_DEFAULTS = { width: 4, shoulder: 4, toe: 6, pivotOffset: 6 } as const;
-
-/** Resolve the effective HLG config: a per-request `hlg` object overrides the
- *  server's --hlg-sampling default field-by-field. Returns undefined (HLG off)
- *  unless enabled by the request or the server. */
-function resolveHlg(
-  reqHlg: ChatRequest["hlg"],
-  serverHlg: HlgConfig | undefined,
-): HlgConfig | undefined {
-  const enabled = reqHlg?.enabled ?? serverHlg?.enabled ?? false;
-  if (!enabled) return undefined;
-  const base = serverHlg ?? HLG_DEFAULTS;
-  return {
-    enabled: true,
-    width: reqHlg?.width ?? base.width,
-    shoulder: reqHlg?.shoulder ?? base.shoulder,
-    toe: reqHlg?.toe ?? base.toe,
-    pivotOffset: reqHlg?.pivot_offset ?? base.pivotOffset,
-    pivot: "top",
-  };
-}
-
-interface OpenAIToolCall {
-  id: string;
-  type: "function";
-  function: { name: string; arguments: string };
-}
-
-export type ToolStreamMode = "gemma-sentinel" | "plain" | "buffered-text";
-
-/** Pick the stream router for a model family. The token-id sentinel router is
- *  Gemma-4-ONLY: ids 48/49 (<|tool_call>/<tool_call|>) and 100/101
- *  (<|channel>/<channel|>) are special tokens of that tokenizer family
- *  (src/tool-call.ts). On every other tokenizer — MiniCPM5, Qwen3/3.5, and
- *  the Tier-0 generics (llama, qwen2, phi3, …) — those ids are ordinary
- *  low-id vocab, so the sentinel router would silently swallow output into a
- *  phantom tool/reasoning segment. Everyone else parses tool calls from
- *  decoded text (buffered-text; parseGeneratedToolCalls covers the
- *  OpenAI-JSON <tool_call>, Qwen <function=…>, and MiniCPM5 <function name=…>
- *  shapes) when tools are present, and streams plain otherwise. Models whose
- *  markup isn't covered fail soft: the markup stays in content. */
-export function selectToolStreamMode(modelType: string, hasTools: boolean): ToolStreamMode {
-  if (modelType.startsWith("gemma4")) return "gemma-sentinel";
-  return hasTools ? "buffered-text" : "plain";
-}
-
-/** Routes generated tokens. Gemma uses family-specific sentinel token ids;
- *  MiniCPM5 and other text-template models use decoded-text parsing so
- *  ordinary tokenizer ids like "<" are never swallowed globally. Exported for
- *  unit tests (gemma-channel reasoning split). */
-export class ToolAwareStream {
-  readonly #decoder: StreamDecoder;
-  #inTool = false;
-  #toolTokens: number[] = [];
-  #text = "";
-  /** Chars of #text already returned as content. */
-  #sent = 0;
-  /** Index where tool markup starts; content emission stops there. */
-  #frozen = -1;
-  #textToolCalls: OpenAIToolCall[] | null = null;
-  #textToolParseFailed = false;
-  readonly toolSegments: number[][] = [];
-
-  /** Gemma reasoning-channel state (gemma-sentinel mode). The model wraps
-   *  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` 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 = "";
-  #channelNameDone = false;
-  #reasoning = "";
-
-  /** Decoded-text markers that open tool markup (oracle: the streaming
-   *  parser buffers from `<tool_call`/`<function` on, never the whole
-   *  response — content before a tool call still streams live). */
-  static readonly TOOL_MARKERS = ["<tool_call>", "<function"];
-
-  constructor(
-    readonly tokenizer: LoadedTokenizer,
-    readonly mode: ToolStreamMode,
-    readonly tools: ToolDefinition[] | null,
-  ) {
-    this.#decoder = new StreamDecoder(tokenizer, mode !== "buffered-text");
-    this.#channelDecoder = new StreamDecoder(tokenizer, true);
-  }
-
-  /** 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 word
-    this.#channelNameDone = true;
-    const rest = this.#channelNamePending.slice(nl); // keep the "\n" (mlx-lm does)
-    this.#channelNamePending = "";
-    return rest;
-  }
-
-  /** Drain reasoning captured since the last call (gemma-channel thinking). */
-  takeReasoning(): string {
-    const r = this.#reasoning;
-    this.#reasoning = "";
-    return r;
-  }
-
-  /** Emit the longest #text prefix that cannot be (the start of) tool
-   *  markup; hold back ambiguous tails until disambiguated. */
-  #textDelta(): string {
-    if (this.#frozen >= 0) return "";
-    let markerAt = -1;
-    for (const mk of ToolAwareStream.TOOL_MARKERS) {
-      const i = this.#text.indexOf(mk, this.#sent);
-      if (i !== -1 && (markerAt === -1 || i < markerAt)) markerAt = i;
-    }
-    if (markerAt !== -1) {
-      this.#frozen = markerAt;
-      const out = this.#text.slice(this.#sent, markerAt);
-      this.#sent = markerAt;
-      return out;
-    }
-    let hold = 0;
-    for (const mk of ToolAwareStream.TOOL_MARKERS) {
-      const max = Math.min(mk.length - 1, this.#text.length - this.#sent);
-      for (let k = max; k > hold; k--) {
-        if (this.#text.endsWith(mk.slice(0, k))) { hold = k; break; }
-      }
-    }
-    const limit = this.#text.length - hold;
-    if (limit <= this.#sent) return "";
-    const out = this.#text.slice(this.#sent, limit);
-    this.#sent = limit;
-    return out;
-  }
-
-  /** Returns the content text delta for this token ("" while capturing). */
-  push(token: number): string {
-    if (this.mode !== "gemma-sentinel") {
-      this.#text += this.#decoder.push(token);
-      if (this.mode === "plain") {
-        const out = this.#text.slice(this.#sent);
-        this.#sent = this.#text.length;
-        return out;
-      }
-      return this.#textDelta();
-    }
-    if (this.#inTool) {
-      if (token === TOOL_CALL_END) {
-        this.#inTool = false;
-        this.toolSegments.push(this.#toolTokens);
-        this.#toolTokens = [];
-      } else {
-        this.#toolTokens.push(token);
-      }
-      return "";
-    }
-    // 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 only the "\n" as reasoning (mlx-lm parity) and
-    // leaks nothing into content.
-    if (this.#inChannel) {
-      if (token === CHANNEL_END) {
-        this.#inChannel = false;
-        this.#reasoning += this.#feedChannel(this.#channelDecoder.flush());
-      } else {
-        this.#reasoning += this.#feedChannel(this.#channelDecoder.push(token));
-      }
-      return "";
-    }
-    if (token === CHANNEL_START) {
-      this.#inChannel = true;
-      this.#channelNameDone = false;
-      this.#channelNamePending = "";
-      return "";
-    }
-    if (token === TOOL_CALL_START) {
-      this.#inTool = true;
-      return "";
-    }
-    return this.#decoder.push(token);
-  }
-
-  flush(): string {
-    if (this.mode !== "gemma-sentinel") {
-      this.#text += this.#decoder.flush();
-      if (this.mode === "buffered-text") {
-        const calls = this.toolCalls();
-        if (calls.length && !this.#textToolParseFailed && this.#frozen >= 0) {
-          // markup parsed into tool_calls — emit any prose still held
-          // before it; the markup itself never reaches content
-          const out = this.#text.slice(this.#sent, this.#frozen);
-          this.#sent = this.#text.length;
-          return out;
-        }
-        // no tool call (or parse fallback): release everything withheld
-        const out = this.#text.slice(this.#sent);
-        this.#sent = this.#text.length;
-        return out;
-      }
-      const out = this.#text.slice(this.#sent);
-      this.#sent = this.#text.length;
-      return out;
-    }
-    if (this.#inChannel) {
-      // truncated mid-reasoning (hit max_tokens); surface the partial thought
-      this.#reasoning += this.#feedChannel(this.#channelDecoder.flush());
-      this.#inChannel = false;
-      return "";
-    }
-    if (this.#inTool && this.#toolTokens.length) {
-      // truncated mid-tool-call (hit max_tokens); surface what we have
-      this.toolSegments.push(this.#toolTokens);
-      this.#toolTokens = [];
-    }
-    return this.#decoder.flush();
-  }
-
-  toolCalls(): OpenAIToolCall[] {
-    if (this.mode !== "gemma-sentinel") {
-      if (this.#textToolCalls) return this.#textToolCalls;
-      try {
-        this.#textToolCalls = parseGeneratedToolCalls(this.#text, this.tools ?? []).map((c) => ({
-          id: `call_${crypto.randomUUID().slice(0, 8)}`,
-          type: "function",
-          function: { name: c.name, arguments: JSON.stringify(c.arguments) },
-        }));
-      } catch {
-        this.#textToolParseFailed = true;
-        this.#textToolCalls = [];
-      }
-      return this.#textToolCalls;
-    }
-    const out: OpenAIToolCall[] = [];
-    for (const seg of this.toolSegments) {
-      const text = this.tokenizer.decode(seg, false); // keep <|"|> markers
-      for (const c of parseToolCalls(text)) {
-        out.push({
-          id: `call_${crypto.randomUUID().slice(0, 8)}`,
-          type: "function",
-          function: { name: c.name, arguments: JSON.stringify(c.arguments) },
-        });
-      }
-    }
-    return out;
-  }
-}
-
-/** Decoded-text stop-sequence matcher with streaming hold-back. Matching
- *  on text (not token ids) catches sequences that span token boundaries
- *  or tokenize differently in context; current mlx-lm uses token-id
- *  state machines and misses those. Text that could be the start of a
- *  stop sequence is withheld until disambiguated, so SSE clients never
- *  see any part of the stop sequence itself. */
-export class StopMatcher {
-  #pending = "";
-  stopped = false;
-
-  constructor(readonly sequences: string[]) {}
-
-  /** Feed a text delta; returns the prefix that is now safe to emit.
-   *  After a match fires (`stopped`), text before the match is returned
-   *  and everything from the match on is discarded. */
-  push(text: string): string {
-    if (this.stopped) return "";
-    if (this.sequences.length === 0) return text;
-    this.#pending += text;
-    // earliest full match wins
-    let cut = -1;
-    for (const seq of this.sequences) {
-      const i = this.#pending.indexOf(seq);
-      if (i !== -1 && (cut === -1 || i < cut)) cut = i;
-    }
-    if (cut !== -1) {
-      this.stopped = true;
-      const out = this.#pending.slice(0, cut);
-      this.#pending = "";
-      return out;
-    }
-    // hold back the longest tail that is a proper prefix of any sequence
-    let hold = 0;
-    for (const seq of this.sequences) {
-      const max = Math.min(seq.length - 1, this.#pending.length);
-      for (let k = max; k > hold; k--) {
-        if (this.#pending.endsWith(seq.slice(0, k))) {
-          hold = k;
-          break;
-        }
-      }
-    }
-    if (hold === 0) {
-      const out = this.#pending;
-      this.#pending = "";
-      return out;
-    }
-    const out = this.#pending.slice(0, -hold);
-    this.#pending = this.#pending.slice(-hold);
-    return out;
-  }
-
-  /** Generation ended without a match — release any held-back text. */
-  flush(): string {
-    const out = this.#pending;
-    this.#pending = "";
-    return out;
-  }
-}
-
-/** Split Qwen-style inline <think>...</think> markup into OpenAI reasoning
- *  deltas/content. This keeps raw tags out of normal chat text while giving
- *  pi (TUI + web) proper thinking_delta events. It is streaming-safe: partial
- *  tag prefixes are held until disambiguated. */
-export class ThinkingTagSplitter {
-  #pending = "";
-  #inThinking: boolean;
-  reasoning = "";
-  content = "";
-
-  /** `startInThinking` seeds the parser INSIDE a <think> block. Needed for
-   *  templates (Qwen3.5, MiniCPM5) that prime an OPEN `<think>` in the
-   *  generation prompt when thinking is enabled: the model's output then
-   *  starts mid-reasoning and emits only the closing `</think>`, never an
-   *  opening tag. Without this seed the whole chain-of-thought leaks into
-   *  `content` and the `reasoning` field stays empty. */
-  constructor(private readonly enabled: boolean, startInThinking = false) {
-    this.#inThinking = startInThinking;
-  }
-
-  #safePrefixUntilTag(tag: string): string {
-    const i = this.#pending.indexOf(tag);
-    if (i !== -1) return this.#pending.slice(0, i);
-    let hold = 0;
-    for (let k = Math.min(tag.length - 1, this.#pending.length); k > 0; k--) {
-      if (this.#pending.endsWith(tag.slice(0, k))) { hold = k; break; }
-    }
-    return this.#pending.slice(0, this.#pending.length - hold);
-  }
-
-  push(text: string): { content: string; reasoning: string } {
-    if (!this.enabled) {
-      this.content += text;
-      return { content: text, reasoning: "" };
-    }
-    this.#pending += text;
-    let content = "";
-    let reasoning = "";
-    while (this.#pending) {
-      const tag = this.#inThinking ? "</think>" : "<think>";
-      const i = this.#pending.indexOf(tag);
-      const emit = i === -1 ? this.#safePrefixUntilTag(tag) : this.#pending.slice(0, i);
-      if (!emit && i === -1) break;
-      if (emit) {
-        if (this.#inThinking) reasoning += emit;
-        else content += emit;
-        this.#pending = this.#pending.slice(emit.length);
-      }
-      if (i !== -1 && this.#pending.startsWith(tag)) {
-        this.#pending = this.#pending.slice(tag.length);
-        this.#inThinking = !this.#inThinking;
-        continue;
-      }
-      if (i === -1) break;
-    }
-    this.content += content;
-    this.reasoning += reasoning;
-    return { content, reasoning };
-  }
-
-  flush(): { content: string; reasoning: string } {
-    if (!this.enabled) return { content: "", reasoning: "" };
-    const out = this.#inThinking
-      ? { content: "", reasoning: this.#pending }
-      : { content: this.#pending, reasoning: "" };
-    this.#pending = "";
-    this.content += out.content;
-    this.reasoning += out.reasoning;
-    return out;
-  }
-}
-
-/** True when a rendered prompt ends INSIDE an unclosed `<think>` block — the
- *  generation prompt primed reasoning (Qwen3.5 / MiniCPM5 with thinking on),
- *  so the model continues the chain-of-thought and emits only the closing
- *  `</think>`. Seeds ThinkingTagSplitter so reasoning is split out correctly.
- *  Thinking-off primes a CLOSED empty block (`<think>\n\n</think>`), and
- *  no-thinking templates have no `<think>` at all — both return false. */
-export function promptEndsInOpenThink(rendered: string): boolean {
-  const open = rendered.lastIndexOf("<think>");
-  return open !== -1 && open > rendered.lastIndexOf("</think>");
-}
-
-/** Concatenate the text of an OpenAI content-part array, ignoring non-text
- *  parts. Tolerant of the part shapes clients actually send: `{type:"text",
- *  text}` (OpenAI/pi), `{type:"input_text", text}` (Responses-style), or any
- *  part carrying a string `text`. */
-function contentPartsToText(parts: Array<Record<string, unknown>>): string {
-  return parts
-    .map((p) => (p && typeof p.text === "string" ? p.text : ""))
-    .join("");
-}
-
-/** 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" ||
-        p.type === "video" || p.type === "video_url"),
-  );
-}
-
-/** OpenAI sends assistant tool_call arguments as JSON strings; the
- *  template renders the object form natively — normalize before render.
- *
- *  Two more wire-format → template-format fixes, both "match the format the
- *  model's chat template expects":
- *
- *  1. Map the OpenAI reasoning-model "developer" role to "system": pi-ai (and
- *     OpenAI's own SDKs) rename the system prompt to `developer` whenever a
- *     model advertises reasoning, but our chat templates only know
- *     system/user/assistant/tool and raise "Unexpected message role." This is
- *     why Qwen3.5/MiniCPM5 chat got no messages while Gemma (non-reasoning, so
- *     pi keeps `system`) worked. `developer` IS the system prompt, so the remap
- *     is semantics-preserving.
- *
- *  2. Flatten text-only content-part arrays to a plain string. pi (and any
- *     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 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) && !hasMediaPart(m.content)) {
-      m = { ...m, content: contentPartsToText(m.content) };
-    }
-    if (!m.tool_calls) return m;
-    return {
-      ...m,
-      tool_calls: m.tool_calls.map((tc) => ({
-        ...tc,
-        function: {
-          ...tc.function,
-          arguments:
-            typeof tc.function.arguments === "string"
-              ? (JSON.parse(tc.function.arguments) as Record<string, unknown>)
-              : tc.function.arguments,
-        },
-      })),
-    };
-  });
-}
-
-/** Coerce a wire `logit_bias` ({"tokenId": bias}) to numeric keys/values —
- *  mlx_lm.server's `{int(k): float(v)}` coercion; throws its exact error
- *  message on anything non-numeric (surfaced as a 400). JSON object keys
- *  always arrive as strings, hence the coercion. */
-export function parseLogitBias(
-  raw: Record<string, number> | undefined | null,
-): Record<number, number> | undefined {
-  if (raw == null) return undefined;
-  if (typeof raw !== "object" || Array.isArray(raw))
-    throw new Error("logit_bias must be a dict of int to float");
-  const out: Record<number, number> = {};
-  for (const [k, v] of Object.entries(raw)) {
-    const id = Number(k);
-    const bias = Number(v);
-    if (!Number.isInteger(id) || !Number.isFinite(bias))
-      throw new Error("logit_bias must be a dict of int to float");
-    out[id] = bias;
-  }
-  return Object.keys(out).length ? out : undefined;
-}
-
-/** Default seed for a request that didn't pin one. `Date.now()` alone is NOT
- *  request-unique: under `--batch N` the batch lane serves ONLY default-seed
- *  requests (explicit-seed requests use the serial mechanism, see
- *  GenerationGateway.place),
- *  so two identical prompts arriving in the same millisecond would share a seed
- *  and — with per-row RNG keyed as stepKey(seed, generatedCount) — produce
- *  byte-identical completions, silently collapsing best-of-N diversity. Mix a
- *  per-process Weyl counter (golden-ratio increment, period 2^32) into the
- *  timestamp so every call yields a distinct uint32 within any given ms.
- *  Determinism contract unchanged: reproducibility is only promised for an
- *  EXPLICIT request seed (`req.seed ?? nextDefaultSeed()` — explicit wins,
- *  byte-identical to before); a default seed is fresh entropy per request. */
-let seedWeyl = 0;
-export function nextDefaultSeed(): number {
-  seedWeyl = (seedWeyl + 0x9e3779b9) >>> 0;
-  return ((Date.now() & 0xffffffff) ^ seedWeyl) >>> 0;
-}
-
-/** mlx_lm.server's logprobs request validation, copied exactly (server.py
- *  APIHandler.validate_model_parameters: `_validate("logprobs", bool)` and
- *  `_validate("top_logprobs", int, min_val=0, max_val=11, whitelist=[-1])`
- *  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 {
-  if (body.guided_grammar) {
-    return "You must respond with text matching this grammar:\n\n" + body.guided_grammar;
-  }
-  const rf = body.response_format as { type?: string; json_schema?: { name?: string; description?: string; schema?: unknown } } | undefined;
-  if (rf && typeof rf === "object" && rf.type === "json_object") {
-    return "You must respond with valid JSON only. " +
-      "Do not include any explanation or text outside the JSON object.";
-  }
-  const schemaSpec = rf && typeof rf === "object" && rf.type === "json_schema"
-    ? rf.json_schema
-    : body.structured_outputs && typeof body.structured_outputs === "object"
-      ? { schema: body.structured_outputs }
-      : null;
-  if (schemaSpec) {
-    const spec = schemaSpec;
-    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;
-  }
-  if (body.guided_regex) {
-    return "You must respond with text matching this regular expression:\n\n" +
-      body.guided_regex;
-  }
-  if (body.guided_choice?.length) {
-    return "You must respond with exactly one of these choices:\n\n" +
-      body.guided_choice.map((choice) => JSON.stringify(choice)).join("\n");
-  }
-  return null;
-}
-
-export function applyGrammarDegrade(
-  body: ChatRequest,
-  degradeHint: string,
-): { body: ChatRequest; warning: string } {
-  const content = degradeJsonSystemPrompt(body) ??
-    "Follow the requested output constraint exactly.";
-  return {
-    warning:
-      `grammar not enforced: ${degradeHint} - falling back to prompt injection`,
-    body: {
-      ...body,
-      messages: [{ role: "system", content }, ...body.messages],
-    },
-  };
-}
-
-export function validateLogprobsParams(body: {
-  logprobs?: unknown;
-  top_logprobs?: unknown;
-}): string | null {
-  const lp = body.logprobs ?? false;
-  if (typeof lp !== "boolean") return "logprobs must be of type bool";
-  const tl = body.top_logprobs ?? -1;
-  if (typeof tl !== "number" || !Number.isInteger(tl))
-    return "top_logprobs must be of type int";
-  if (tl === -1) return null; // the "unset" whitelist sentinel
-  if (tl < 0) return "top_logprobs must be at least 0";
-  if (tl > 11) return "top_logprobs must be at most 11";
-  return null;
-}
-
-const REASONING_EFFORT_LEVELS =
-  ["none", "minimal", "low", "medium", "high", "xhigh"] as const;
-
-/** Validate `reasoning_effort` against the accepted level names. An invalid
- *  string must NOT pass through: resolveEnableThinking treats any defined
- *  value ≠ "none" as thinking-ON, so a typo like "hihg" silently flipped the
- *  thinking channel (and its hotter temperature) on thinking-off models and
- *  burned a full default-depth reasoning budget (2026-08-18 review). Same
- *  contract style as validateLogprobsParams above. */
-export function validateReasoningEffort(body: {
-  reasoning_effort?: unknown;
-}): string | null {
-  const v = body.reasoning_effort;
-  if (v === undefined || v === null) return null;
-  if (typeof v !== "string" || !(REASONING_EFFORT_LEVELS as readonly string[]).includes(v))
-    return "reasoning_effort must be one of " +
-      "'none', 'minimal', 'low', 'medium', 'high', 'xhigh'";
-  return null;
-}
-
-/** 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 {
-  static readonly #WINDOW_TOKENS = 32;
-  #ids: number[] = [];
-  #emitted = "";
-  #warnedRevision = false;
-  /** Token index where the bounded decode suffix begins. */
-  #windowStart = 0;
-  /** Exact decoded text before #windowStart, established by suffix matching. */
-  #windowPrefix = "";
-  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.#decodeRaw(ids);
-    return this.#trimLeadingSpace && full.startsWith(" ") ? full.slice(1) : full;
-  }
-
-  #decodeRaw(ids: number[]): string {
-    return this.tokenizer.decode(ids, this.skipSpecialTokens);
-  }
-
-  /** Decode only a bounded suffix once an exact text anchor can be proven.
-   *
-   * At each rebase, decode a candidate suffix independently and accept it only
-   * when it is literally the suffix of the exact text decoded so far. This
-   * preserves ByteLevel/SPM boundary behavior while reducing steady-state
-   * decode work from the whole generation to 32–64 tokens. If no suffix can be
-   * anchored (an unusual/global decoder), leave #windowStart at zero and keep
-   * the full-history correctness path. */
-  #decodeIncremental(): string {
-    const full = this.#windowStart === 0
-      ? this.#decode(this.#ids)
-      : this.#windowPrefix + this.#decodeRaw(this.#ids.slice(this.#windowStart));
-
-    if (this.#ids.length - this.#windowStart < StreamDecoder.#WINDOW_TOKENS * 2)
-      return full;
-
-    const preferred = this.#ids.length - StreamDecoder.#WINDOW_TOKENS;
-    const oldest = Math.max(this.#windowStart, preferred - StreamDecoder.#WINDOW_TOKENS);
-    for (let start = preferred; start >= oldest; start--) {
-      const tail = this.#decodeRaw(this.#ids.slice(start));
-      if ((tail.length > 0 || full.length === 0) && full.endsWith(tail)) {
-        this.#windowStart = start;
-        this.#windowPrefix = full.slice(0, full.length - tail.length);
-        break;
-      }
-    }
-    return full;
-  }
-
-  push(token: number): string {
-    this.#ids.push(token);
-    // 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.#decodeIncremental();
-    // hold back a trailing replacement char (partial multi-byte sequence)
-    const stable = full.endsWith("�") ? full.slice(0, -1) : full;
-    if (!stable.startsWith(this.#emitted)) {
-      // 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;
-    }
-    const delta = stable.slice(this.#emitted.length);
-    this.#emitted = stable;
-    return delta;
-  }
-
-  flush(): string {
-    // 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;
-  }
-}
 
 // v2 curve designer: CORS-open so a file:// editor can call a localhost engine.
 const CURVE_CORS: Record<string, string> = {
@@ -1654,8 +313,9 @@ function curveJunk(s: string): boolean {
   return nonLatin >= 0.02 || /�/.test(s) || /<unused\d+>/.test(s);
 }
 
+
 export function createServer(
-  ctx: ServerContext, port = 0, serverOptions: ServerOptions = {},
+  ctx: ServingContext, port = 0, serverOptions: ServerOptions = {},
 ): Server<unknown> {
   // --batch N is a concurrency cap: N===1 pins the strict serial executor;
   // N>1 admits supported execution compositions to the continuous scheduler.
@@ -1663,7 +323,7 @@ export function createServer(
   // Both full-attention (CPM) and
   // sliding-window (Gemma) models batch — the scheduler assembles each layer's
   // cache by attention type. Non-batchable requests (vision / adapters /
-  // user seed / unsupported explicit kv-quant) drain to the serial executor
+  // unsupported explicit kv-quant) drain to the serial executor
   // (see GenerationGateway.place). No inference setting is rewritten.
   // 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
@@ -1672,7 +332,17 @@ export function createServer(
   // 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 serving = modelServingBinding(ctx);
+  ctx = { ...ctx, serving };
   const batch = Math.max(1, Math.floor(serverOptions.batch ?? 8));
+  if (serverOptions.generationCheckpointTokens !== undefined) {
+    if (!Number.isInteger(serverOptions.generationCheckpointTokens) ||
+        serverOptions.generationCheckpointTokens < 1)
+      throw new Error("--generation-checkpoint expects a positive integer token interval");
+    if (!serverOptions.ssdCacheDir)
+      throw new Error("--generation-checkpoint requires --ssd-cache <dir>");
+
+  }
   const defaultGeneratedTokens =
     serverOptions.defaultMaxTokens ?? ctx.glmMemoryPlan?.maxGenerationTokens;
 
@@ -1694,38 +364,17 @@ export function createServer(
   const resolvedKvScheme = resolveKvScheme({
     override: serverOptions.kvQuant,
     turboQuant: serverOptions.turboQuant,
+    quantizedKvStart: serverOptions.quantizedKvStart,
     config: ctx.kvConfig,
   });
   const kvScheme = resolvedKvScheme.generationOptions;
-  // 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 placement's cache-capability gate).
-  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).
+  // The model execution plan qualifies the method while retaining KV policy.
   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)`,
+        `requests keep the KV scheme; the model execution plan enables speculation ` +
+        `only for a qualified combination. Check response usage for the active method. ` +
+        `(docs/design/speculative-decoding.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
@@ -1740,34 +389,28 @@ export function createServer(
       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`,
+          `(docs/design/turboquant.md) — use --kv-quant config|4|8 or omit it`,
       );
   }
-  // Paged KV v1 (docs/design/paged-kv-cache.md): explicit refusals, not
+  // Paged KV v1 (docs/design/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).
+  // quietly (kv-quant: the swap would drop the scheme; speculative
+  // provider composition with paged storage is not implemented).
   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).`,
+          `blocks are a documented follow-up, docs/design/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).`,
+          `(docs/design/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.`,
+          `(this model: ${ctx.model.config.modelType}) — docs/design/kv-cache.md.`,
       );
     const bs = serverOptions.pagedKv.blockSize;
     if (bs !== undefined && (!Number.isInteger(bs) || bs <= 0))
@@ -1779,11 +422,12 @@ export function createServer(
       );
   }
 
-  // SSD cold tier (docs/design/ssd-kv-cold-tier.md): prefix KV survives RAM
+  // SSD cold tier (docs/design/kv-cache.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).
+  // tokenizer hash (ids must keep meaning the same text). The model binding
+  // also identifies the runtime numerics that produced the persisted state.
   // 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
@@ -1791,24 +435,33 @@ export function createServer(
   // entries still demote to SSD and LRU eviction bounds pressure.
   // --prompt-cache <GB> overrides; 0 disables.
   const promptCacheCap = serverOptions.promptCacheBytes ?? 8e9;
+  const stateCodecs = ctx.stateCodecs ?? legacyCacheCodecs;
+  const cloneState = (caches: Cache[]) => cloneKvCaches(caches, stateCodecs);
   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)");
+    if (typeof serving.stateCompatibility !== "string" || !serving.stateCompatibility.length)
+      throw new Error("--ssd-cache requires the model binding's stateCompatibility identity");
     const schemeKey = resolvedKvScheme.cacheKey;
+    const stateKey = Bun.hash(serving.stateCompatibility).toString(16);
     const tokJson = readFileSync(`${ctx.model.config.modelDir}/tokenizer.json`);
     ssdStore = new SsdCacheStore({
+      codecs: stateCodecs,
       dir: serverOptions.ssdCacheDir,
-      maxBytes: serverOptions.ssdCacheMaxBytes ?? 32 * 2 ** 30,
-      configFingerprint: `${configFingerprint(ctx.model.config)}-${schemeKey}`,
+      maxBytes: serverOptions.ssdCacheMaxBytes ?? Number.POSITIVE_INFINITY,
+      configFingerprint: `${configFingerprint(ctx.model.config)}-${schemeKey}-${stateKey}`,
       tokenizerHash: Bun.hash(tokJson).toString(16),
       modelId: ctx.modelId,
       verify: serverOptions.ssdCacheVerify,
     });
     const recovered = ssdStore.scan();
+    const capacity = Number.isFinite(ssdStore.maxBytes)
+      ? `${(ssdStore.maxBytes / 2 ** 30).toFixed(0)} GiB cap`
+      : "unlimited";
     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`,
+      `${(ssdStore.totalBytes / 2 ** 30).toFixed(2)} GiB, ${capacity}`,
     );
   }
 
@@ -1823,16 +476,18 @@ export function createServer(
           return h ? { prefixLen: h.prefixLen, handle: h.entry } : null;
         },
         restore: (handle: unknown) => {
-          const loaded = ssdStore!.restore(handle as import("./ssd-cache").SsdIndexEntry, ctx.model);
+          const loaded = serving.restore(ssdStore!, handle as import("./ssd-cache").SsdIndexEntry);
           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: () => {} };
+          return { tokens: loaded.tokens, caches: loaded.caches, attachments: loaded.attachments, retain: () => {} };
         },
-        store: (tokens: number[], caches: import("./model/gemma4").Cache[], ns: string) => {
-          ssdStore!.store(tokens, caches, ns);
+        store: (tokens: number[], caches: import("./model/gemma4").Cache[], ns: string,
+          attachments?: import("./backends/mlx/checkpoint-state").CheckpointAttachment[]) => {
+          if (ssdStore!.hasDurablePrefix(tokens, ns)) return true;
+          return ssdStore!.store(tokens, caches, ns, attachments);
         },
       }
     : null;
@@ -1843,7 +498,7 @@ export function createServer(
     // 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) ->
+    // SpillQueue -> storeAsync (generation-locked 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
@@ -1853,10 +508,11 @@ export function createServer(
     ssdStore
       ? {
           spillOwned: (entry) =>
-            spillQueue!.enqueue({ tokens: entry.tokens, caches: entry.caches, ns: entry.ns }),
+            spillQueue!.enqueue({ tokens: entry.tokens, caches: entry.caches, ns: entry.ns, attachments: entry.attachments }),
         }
       : null,
     coldTier,
+    cloneState,
   );
   // Responses-API store for previous_response_id resumption (Phase 11):
   // TTL + byte-capped LRU, port of optiq/response_store.py. Pairs with
@@ -1864,175 +520,38 @@ export function createServer(
   // so its KV prefill is already cached.
   const responseStore = new ResponseStore();
 
-  /** Run one generation with prompt-cache reuse. Must be called under the
-   *  gateway's exclusive lock — the gateway invokes it on the serial lane;
-   *  the curve /generate endpoint wraps it in gateway.runExclusive. (The old
-   *  `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.
-   *  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;
-      multimodalMask?: import("./mlx/array").MlxArray;
-      mrope?: MropeRequestState;
-    },
-    trace?: PromptResponseTrace,
-  ) => {
-    // Qwen vision: install the request's mRoPE state for every forward of
-    // this serial run (prefill AND decode use the 3D interleaved positions +
-    // delta). Scoped inside the try below — under the serial mutex — so
-    // queued text requests never see it and a throw between here and the
-    // try (makeCache under memory pressure, spec-path early return) can't
-    // leave a DEAD request's positions installed for the next generation
-    // (2026-08-18 review).
-    // 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 withModelWiredLimit(
-        ctx.model,
-        () => withModelUsageFlush(
-          ctx.model,
-          () => 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("+") ?? "";
-    // 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 closeCacheLookup = trace?.begin("cache.lookup_restore", {
-      mechanism: "serial",
-      bypassed: skipPromptCache,
-    });
-    const entry = skipPromptCache ? null : promptCache.take(promptIds, cacheNs);
-    closeCacheLookup?.();
-    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 {
-      if (vision?.mrope && ctx.model instanceof Qwen35Model)
-        ctx.model.mrope = vision.mrope;
-      const gen = generate(ctx.model, promptIds, {
-        ...options,
-        pagedKv, // request-scoped (undefined strips the server-wide flag)
-        cache: caches,
-        ...(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 } : {}),
-            }
-          : {}),
-      }, { trace, mechanism: "serial" });
-      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 (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 {
-        // 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 {
-      if (ctx.model instanceof Qwen35Model) ctx.model.mrope = null;
-      vision?.embeddings.dispose();
-      vision?.imageMask?.dispose();
-      vision?.multimodalMask?.dispose();
-      options.visionPixels?.dispose();
-    }
+  // Memory estimates remain available in diagnostics. Only an explicit
+  // operator budget or context cap constrains request planning.
+  const memoryAdmission = ctx.glmMemoryPlan ?? fit(
+    ctx.model.config, ctx.model.weightsBytes, 1,
+    undefined, undefined, 0, serverOptions.memoryBudgetBytes,
+    resolvedKvScheme.fitOptions,
+  );
+  const profileContext = runtimeValue("MLX_BUN_RD_CONTEXT_LIMIT");
+  const profileLimit = profileContext === undefined ? null : Number(profileContext);
+  if (profileLimit !== null && (!Number.isSafeInteger(profileLimit) || profileLimit < 1))
+    throw new Error("MLX_BUN_RD_CONTEXT_LIMIT must be a positive integer");
+  const budgetLimit = serverOptions.memoryBudgetBytes !== undefined
+    ? memoryAdmission.maxSafeContext : ctx.glmMemoryPlan?.contextTokens ?? null;
+  const contextLimit = profileLimit === null ? budgetLimit
+    : Math.min(profileLimit, budgetLimit ?? Infinity);
+  const admission = memoryAdmission;
+  const allocatorLimit =
+    admission.allocatorLimitBytes ?? serverOptions.memoryBudgetBytes;
+  if (allocatorLimit) setMemoryLimit(allocatorLimit);
+
+  let checkpointPersistence: ContinuationPersistence | undefined;
+  const executionServices: import("./backends/mlx/serial-executor").MlxSerialServices = {
+    get checkpointPersistence() { return checkpointPersistence; },
+    promptCache, checkpoints: ssdStore,
+    checkpointEveryTokens: serverOptions.generationCheckpointTokens,
+    identity: { artifact: ctx.profile.artifact, implementation: ctx.profile.profile.execution,
+      stateAbi: "legacy-cache-array-v1", codecs: stateCodecs.id },
+    adapterNamespace: (adapters) => ctx.adapters.cacheNamespace(adapters),
+    cloneState,
   };
+  serving.gateway.configureContinuation?.(executionServices);
+  const runGeneration = serving.createSerial(executionServices);
 
   // Write-behind persistence (restart survival — the oMLX boundary-snapshot
   // idea at whole-entry granularity, spill-on-evict alone can't survive a
@@ -2062,17 +581,17 @@ export function createServer(
   // 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
+  // — including the first — runs through gateway.runWhenIdle(), 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
+  // bounded by the chain). 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 = runtimeValue("MLX_BUN_SSD_WRITEBEHIND") !== "0";
-  const ssdFlushGate = (): Promise<void> => gateway.onIdle();
+  const ssdFlushStep = <T>(step: () => T): Promise<T> =>
+    gateway.runWhenIdle(async () => step());
   // 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 —
@@ -2087,19 +606,28 @@ export function createServer(
   // never drops the item just enqueued).
   // The gateway exists before the spill queue because the SSD writer uses
   // its idle boundary to avoid competing with generation.
-  const gateway = new GenerationGateway(ctx.model, batch, runGeneration, {
+  const gateway = new GenerationGateway(serving.gateway, batch, runGeneration, {
     kvBudgetBytes: serverOptions.kvBudgetBytes,
+    checkpoints: !!(serverOptions.generationCheckpointTokens && ssdStore),
+    stateCodecs,
     kvScheme: resolvedKvScheme,
     promptCache,
+    adapterNamespace: (adapters) => ctx.adapters.cacheNamespace(adapters),
   });
   const spillQueueGbRaw = Number(runtimeValue("MLX_BUN_SSD_SPILL_QUEUE_GB"));
   const spillQueueCapBytes =
     (Number.isFinite(spillQueueGbRaw) && spillQueueGbRaw >= 0 ? spillQueueGbRaw : 2) * 1024 ** 3;
+  // Both queues share the configured total: reserve half for checkpoints
+  // only when that service exists. Each retains the existing soft-cap rule.
+  const checkpointQueueBytes = ssdStore && serverOptions.generationCheckpointTokens
+    ? Math.floor(spillQueueCapBytes / 2) : 0;
+  if (ssdStore && serverOptions.generationCheckpointTokens)
+    checkpointPersistence = new ContinuationPersistence(ssdStore, { maxBytes: checkpointQueueBytes, runStep: ssdFlushStep });
   const spillQueue = ssdStore
     ? new SpillQueue(
-        spillQueueCapBytes,
+        spillQueueCapBytes - checkpointQueueBytes,
         cacheBytes,
-        (item) => ssdStore!.storeAsync(item.tokens, item.caches, item.ns, ssdFlushGate),
+        (item) => ssdStore!.storeAsync(item.tokens, item.caches, item.ns, ssdFlushStep, item.attachments),
         (caches) => { for (const c of caches) c.dispose(); },
       )
     : null;
@@ -2108,28 +636,35 @@ export function createServer(
         gateway,
         promptCache,
         spillQueue,
-        cloneKvCaches,
+        cloneState,
         (tokens, ns) => ssdStore.hasDurablePrefix(tokens, ns),
       )
     : null;
-  const durabilityStats = (): DurabilitySnapshotStats =>
-    durability?.stats ?? {
+  const durabilityStats = (): DurabilitySnapshotStats => {
+    const stats = durability?.stats ?? {
       pendingSnapshots: 0,
       pendingSpills: spillQueue?.pendingCount ?? 0,
       pendingSpillBytes: spillQueue?.pendingBytes ?? 0,
       droppedSpills: spillQueue?.droppedCount ?? 0,
       failedSpills: spillQueue?.failedCount ?? 0,
     };
+    const checkpoints = checkpointPersistence?.stats;
+    return { ...stats, pendingSpills: stats.pendingSpills + (checkpoints?.pendingCount ?? 0),
+      pendingSpillBytes: stats.pendingSpillBytes + (checkpoints?.pendingBytes ?? 0),
+      droppedSpills: stats.droppedSpills + (checkpoints?.dropped ?? 0),
+      failedSpills: stats.failedSpills + (checkpoints?.failed ?? 0) };
+  };
   const flushDurability = async (): Promise<DurabilityFlushResult> => {
-    if (durability) return durability.flush();
     const started = performance.now();
-    await spillQueue?.drain();
+    const checkpoints = await checkpointPersistence?.flush();
+    const result = durability ? await durability.flush() : null;
+    if (!result) await spillQueue?.drain();
     const stats = durabilityStats();
     return {
       ...stats,
-      durable: stats.pendingSpills === 0,
-      flushedSnapshots: 0,
-      missingSnapshots: 0,
+      durable: (result?.durable ?? stats.pendingSpills === 0) && (checkpoints?.durable ?? true) && stats.pendingSpills === 0,
+      flushedSnapshots: result?.flushedSnapshots ?? 0,
+      missingSnapshots: result?.missingSnapshots ?? 0,
       elapsedMs: performance.now() - started,
     };
   };
@@ -2150,7 +685,7 @@ export function createServer(
   let demoteTimer: ReturnType<typeof setInterval> | null = null;
   if (ssdStore && demoteIdleMs > 0) {
     demoteTimer = setInterval(() => {
-      if (gateway.activeRows > 0 || gateway.pendingRows > 0) return;
+      if (gateway.busy) 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`);
@@ -2159,45 +694,8 @@ export function createServer(
     demoteTimer.unref?.();
   }
 
-  const completionExecutor = new CompletionExecutor(gateway);
-  const completionProtocolUsage = (usage: CompletionSummary["usage"]) => ({
-    prompt_tokens: usage.promptTokens,
-    completion_tokens: usage.completionTokens,
-    total_tokens: usage.totalTokens,
-    prompt_tokens_details: { cached_tokens: usage.cachedTokens },
-    ...(usage.speculation ? { speculation: usage.speculation } : {}),
-  });
-  const completionUsage = (summary: CompletionSummary) => ({
-    ...completionProtocolUsage(summary.usage),
-    lane: summary.lane,
-  });
-
-  // Admission ceiling, resolved once (Phase 5 memoryBudget enforcement).
-  // fit() solves max safe context from weights + KV growth + prefill
-  // transient. The active kv-quant scheme (uniform kvBits / per-layer
-  // kvConfig) is billed at its true bytes/element so a quantized cache
-  // advertises and admits the larger window it actually enables; only
-  // TurboQuant still bills bf16 (conservative — no projector for its
-  // layout yet, and it is solo-only in v1).
-  const admission = ctx.glmMemoryPlan ?? fit(
-    ctx.model.config, ctx.model.weightsBytes, 1,
-    undefined, undefined, 0, serverOptions.memoryBudgetBytes,
-    resolvedKvScheme.fitOptions,
-  );
-  // A zero ceiling is a warning, never a startup refusal: killing the
-  // server here can only parrot the per-request admission message (which
-  // still fires, with this same ceiling) or be a false positive from the
-  // fit model itself — it can never save anything the request gate
-  // doesn't. Serve until physically incapable.
-  if (admission.maxSafeContext < 1)
-    console.warn(
-      `[admission] memory budget ${(admission.usableBytes / 1e9).toFixed(2)} GB leaves no ` +
-      `safe context for ${ctx.modelId} (weights ${(ctx.model.weightsBytes / 1e9).toFixed(2)} GB) ` +
-      `— serving anyway; generation requests will be refused until the budget is raised`,
-    );
-  const allocatorLimit =
-    admission.allocatorLimitBytes ?? serverOptions.memoryBudgetBytes;
-  if (allocatorLimit) setMemoryLimit(allocatorLimit);
+  const sessionEngine = createSessionCompletionEngine(gateway, disposeUnstartedRequest);
+  const completionExecutor = new CompletionExecutor(sessionEngine);
 
   // /library response cache (30 s) — registry + config reads only.
   const startedAt = Date.now();
@@ -2224,207 +722,37 @@ export function createServer(
     return jobStore;
   };
 
-  // (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.
-  // We pass the flat equivalent — ALL configured EOS ids plus the bare newline
-  // id(s), encoded WITHOUT special tokens (mlx-lm's encode("\n") can drag a
-  // BOS along on some tokenizers; protecting BOS from XTC is a no-op, so the
-  // flat/no-BOS form is behaviorally identical and cleaner).
-  const xtcSpecialTokens = [
-    ...ctx.model.config.eosTokenIds,
-    ...ctx.tokenizer.encode("\n", false),
-  ];
-
-  // Effective enable_thinking for a request, with the same precedence the chat
-  // template uses (extracted so sampling and template rendering can't disagree):
-  // explicit chat_template_kwargs.enable_thinking → reasoning_effort ("none" =
-  // off) → server --thinking default → model default (MiniCPM5 → off). undefined
-  // means "not a switchable-thinking model / leave the template default".
-  const resolveEnableThinking = (req: ChatRequest): boolean | undefined => {
-    const explicit = req.chat_template_kwargs?.enable_thinking;
-    if (typeof explicit === "boolean") return explicit;
-    const effort = req.reasoning_effort;
-    if (effort !== undefined) return effort !== "none";
-    if (serverOptions.defaultThinking !== undefined) return serverOptions.defaultThinking;
-    return isMiniCPM5Config(ctx.model.config) ? false : undefined;
-  };
-
-  const toOptions = (req: ChatRequest): GenerateOptions & { stopSequences: string[] } => {
-    // Sampling follows the thinking state — which the web UI's thinking button
-    // drives via enable_thinking. Model authors publish a SINGLE
-    // generation_config temperature (the think-mode value) but recommend a
-    // cooler one for direct, no-think replies (MiniCPM5 card: 0.9 think / 0.7
-    // no-think, top_p 0.95 for both). So with no explicit temperature set, a
-    // no-think turn runs at most NO_THINK_TEMPERATURE while a think turn keeps
-    // the model's hotter configured default. An explicit request/CLI
-    // temperature always wins. top_p is unchanged by mode.
-    const NO_THINK_TEMPERATURE = 0.7;
-    const genTemp = ctx.genDefaults.temperature ?? 0.7;
-    const defaultTemp = resolveEnableThinking(req) === false
-      ? Math.min(genTemp, NO_THINK_TEMPERATURE)
-      : genTemp;
-    return {
-      // A thinking turn emits <think>…</think> AND the answer, so a tight cap
-      // truncates the visible reply. Default very generously (the model's
-      // context is far larger); only an explicit max_tokens narrows it. The
-      // model still stops at its eos_token well before this in normal replies.
-      maxTokens: req.max_completion_tokens ?? req.max_tokens ??
-        defaultGeneratedTokens ?? 65_536,
-      temperature: req.temperature ?? serverOptions.defaultTemperature ?? defaultTemp,
-      topP: req.top_p ?? serverOptions.defaultTopP ?? ctx.genDefaults.topP ?? 0,
-      topK: req.top_k ?? serverOptions.defaultTopK ?? ctx.genDefaults.topK ?? 0,
-      seed: req.seed ?? nextDefaultSeed(),
-      repetitionPenalty: req.repetition_penalty ?? ctx.genDefaults.repetitionPenalty,
-      // mlx_lm.server sampling extensions (defaults mirror server.py: min_p /
-      // xtc off, context windows 20). parseLogitBias throws on non-numeric
-      // input — callers surface it as a 400 (mlx-lm's coercion error).
-      minP: req.min_p ?? 0,
-      xtcProbability: req.xtc_probability ?? 0,
-      xtcThreshold: req.xtc_threshold ?? 0,
-      ...(req.xtc_probability ? { xtcSpecialTokens } : {}),
-      logitBias: parseLogitBias(req.logit_bias),
-      repetitionContextSize: req.repetition_context_size ?? 20,
-      presencePenalty: req.presence_penalty ?? 0,
-      presenceContextSize: req.presence_context_size ?? 20,
-      frequencyPenalty: req.frequency_penalty ?? 0,
-      frequencyContextSize: req.frequency_context_size ?? 20,
-      hlg: resolveHlg(req.hlg, serverOptions.hlg),
-      // generate() yields token ids; stop sequences match on decoded text
-      // (they can span token boundaries), so the StopMatcher sits at the
-      // decode layer below and halts the loop via onToken → false.
-      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: "grammar compilation disabled by MLX_BUN_GRAMMAR=0",
-      };
-    }
-    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 };
-  };
-
-  // Map OpenAI reasoning_effort levels onto the Qwen3.8 template's supported
-  // set (xhigh|medium|low — the template raises on anything else). "none"
-  // means thinking off (handled by resolveEnableThinking), so no depth is
-  // passed. Only consumed for templates with readsReasoningEffort.
-  const qwenReasoningEffort = (
-    effort: ChatRequest["reasoning_effort"],
-  ): "xhigh" | "medium" | "low" | undefined => {
-    switch (effort) {
-      case "minimal":
-      case "low":
-        return "low";
-      case "medium":
-        return "medium";
-      case "high":
-      case "xhigh":
-        return "xhigh";
-      default:
-        return undefined; // "none" / unset → template default (xhigh)
-    }
-  };
-
-  const templateOptionsFor = (req: ChatRequest, tools: ToolDefinition[] | null) => {
-    // enableThinking resolution (and its precedence) lives in
-    // resolveEnableThinking so template rendering and sampling stay in sync.
-    return {
-      tools,
-      enableThinking: resolveEnableThinking(req),
-      reasoningEffort: qwenReasoningEffort(req.reasoning_effort),
-      preserveThinking: req.chat_template_kwargs?.preserve_thinking,
-    };
-  };
-
-  const promptIdsFor = (
-    req: ChatRequest,
-    tools: ToolDefinition[] | null,
-  ): { ids: number[]; startInThinking: boolean } => {
-    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}|${opts.reasoningEffort ?? ""}|${opts.preserveThinking ?? ""}`;
-    const primer = primerLenByMode.get(mode);
-    if (primer !== undefined) return Math.max(0, trimmed.length - primer);
-    let stableLen = trimmed.length;
+  // Per-request preparation (options/template/prompt-ids/grammar/router)
+  // and the chat core, each built once with their collaborators injected.
+  // The request pipeline, composed once:
+  //   new ChatRequest(body) → chatStage.run → InferenceRequest
+  //   → inferenceStage.admit → inferenceStage.run → InferenceResult → wire
+  // (/v1/completions substitutes textStage; Anthropic and Responses reuse
+  // chatStage with their own wire formats.)
+  const prep = createRequestPrep({ ctx, serverOptions, kvScheme, defaultGeneratedTokens });
+  const { templateOptionsFor } = prep;
+  const preparation = createPreparationExecutor((work, signal) => gateway.runExclusive(work, undefined, signal), batch);
+  const chatStage = new ChatStage(
+    ctx, prep, promptCache, contextLimit, serverOptions.defaultAdapter,
+    preparation, serving.buildPrompt);
+  const textStage = new TextCompletionStage(
+    ctx, prep, contextLimit, defaultGeneratedTokens, serverOptions.defaultAdapter);
+  const inferenceStage = new InferenceStage(completionExecutor);
+  const openAiMeta = (id: string) => ({ id, created: Math.floor(Date.now() / 1000), model: ctx.modelId });
+  /** Parse the JSON body under the request's trace; a bad body is a 400. */
+  const parseBody = async <T,>(request: Request, trace: PromptResponseTrace | undefined): Promise<T | Response> => {
+    const closeBodyParse = trace?.begin("request.body_parse");
     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;
+      return (await request.json()) as T;
+    } catch {
+      trace?.finish("error", { stage: "body_parse" });
+      return Response.json({ error: { message: "invalid JSON body" } }, { status: 400 });
+    } finally {
+      closeBodyParse?.();
+    }
   };
 
-  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
-    // — see selectToolStreamMode for why sentinel ids must stay family-gated.
-    selectToolStreamMode(ctx.model.config.modelType, !!tools?.length);
 
-  const toolRouter = (tools: ToolDefinition[] | null): ToolAwareStream =>
-    new ToolAwareStream(ctx.tokenizer, toolStreamMode(tools), tools);
 
   if (serverOptions.unixSocket) {
     try { require("node:fs").unlinkSync(serverOptions.unixSocket); } catch {}
@@ -2616,7 +944,7 @@ export function createServer(
         let kvMode = "bf16";
         if (kvScheme.turboQuant) {
           // v1: full-attention layers only (sliding-window stays bf16 —
-          // docs/design/turboquant-kv.md non-goal).
+          // docs/design/turboquant.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;
@@ -2648,7 +976,7 @@ export function createServer(
               dir: serverOptions.ssdCacheDir,
               entries: ssdStore.entries,
               bytes: ssdStore.totalBytes,
-              max_bytes: ssdStore.maxBytes,
+              max_bytes: Number.isFinite(ssdStore.maxBytes) ? ssdStore.maxBytes : null,
               restores: ssdStore.stats.restores,
               spills: ssdStore.stats.spills,
               restore_ms_last: Math.round(ssdStore.stats.restoreMsLast),
@@ -2677,39 +1005,14 @@ export function createServer(
           },
           admission: {
             max_safe_context: admission.maxSafeContext,
+            enforced_context_tokens: contextLimit,
             memory_budget_bytes:
               ctx.glmMemoryPlan?.processLimitBytes ??
               serverOptions.memoryBudgetBytes ?? null,
             usable_bytes: admission.usableBytes,
             weights_bytes: ctx.model.weightsBytes,
           },
-          ...(ctx.glmMemoryPlan ? {
-            glm52: {
-              preset: ctx.glmMemoryPlan.preset,
-              planned_process_bytes: ctx.glmMemoryPlan.plannedProcessBytes,
-              process_limit_bytes: ctx.glmMemoryPlan.processLimitBytes,
-              context_tokens: ctx.glmMemoryPlan.contextTokens,
-              max_generation_tokens: ctx.glmMemoryPlan.maxGenerationTokens,
-              batch_size: ctx.glmMemoryPlan.batchSize,
-              dsa: ctx.model instanceof Glm52Model && ctx.model.capabilities.dsa,
-              mtp: ctx.draft?.provider.id === "glm52-native-mtp",
-              mtp_draft_tokens: ctx.glmMemoryPlan.mtpDraftTokens,
-              resident_weight_bytes: ctx.glmMemoryPlan.lineItems.residentWeightsBytes,
-              main_expert_slab_bytes: ctx.glmMemoryPlan.lineItems.mainExpertSlabBytes,
-              mtp_expert_slab_bytes: ctx.glmMemoryPlan.lineItems.mtpExpertSlabBytes,
-              expert_runtime: ctx.model instanceof Glm52Model &&
-                  ctx.model.expertRuntime
-                ? {
-                    main_residency:
-                      ctx.model.expertRuntime.manager.snapshot(),
-                    mtp_residency:
-                      ctx.model.expertRuntime.mtp?.manager.snapshot() ?? null,
-                    last_turn: ctx.model.expertRuntime.lastTelemetry,
-                    last_repin: ctx.model.expertRuntime.lastRepin,
-                  }
-                : null,
-            },
-          } : {}),
+          ...serving.diagnostics(),
           // --batch: configured cap, whether batching is live for this model,
           // and rows currently decoding in the batch.
           batch: {
@@ -2725,6 +1028,25 @@ export function createServer(
         });
       }
 
+      // A parent-managed GPU job holds this response open. The connection owns
+      // the native lease, so parent death cannot strand the worker lock.
+      if (serverOptions.unixSocket && url.pathname === "/admin/lease" && request.method === "POST") {
+        const lease = await gateway.acquireExecutionLease(request.signal);
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          request.signal.removeEventListener("abort", release);
+          lease.dispose();
+        };
+        request.signal.addEventListener("abort", release, { once: true });
+        if (request.signal.aborted) release();
+        return new Response(new ReadableStream({
+          start(controller) { controller.enqueue(new TextEncoder().encode("leased\n")); },
+          cancel() { release(); },
+        }), { headers: { "content-type": "application/octet-stream" } });
+      }
+
       // 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
@@ -2749,27 +1071,14 @@ export function createServer(
         let sbody: { prompt?: string };
         try { sbody = (await request.json()) as typeof sbody; }
         catch { return Response.json({ error: "invalid JSON" }, { status: 400, headers: CURVE_CORS }); }
-        let sids = ctx.tokenizer.encode(ctx.template.render([{ role: "user", content: typeof sbody.prompt === "string" ? sbody.prompt : "" }], templateOptionsFor({} as ChatRequest, null)));
+        let sids = ctx.tokenizer.encode(ctx.template.render([{ role: "user", content: typeof sbody.prompt === "string" ? sbody.prompt : "" }], templateOptionsFor({} as ChatRequestParams, null)));
         if (sids[0] === sids[1] && sids[0] === ctx.tokenizer.bosTokenId) sids = sids.slice(1);
         try {
           const NB = 80;
           // gateway.runExclusive: this raw forward must not run concurrently
           // with batched decode steps or a serial generation (GPU + shared
           // model state are single-owner — D3, one lock).
-          const result = await gateway.runExclusive(async () => {
-            const cache = ctx.model.makeCache();
-            try {
-              const logits = ctx.model.forward(sids, cache); // [1, L, V]
-              const [, Ln, V] = logits.shape as [number, number, number];
-              const last = logits.slice([0, Ln - 1, 0], [1, Ln, V]);
-              const f = last.toFloat32(); logits.dispose(); last.dispose();
-              let mx = -Infinity; for (const v of f) if (v > mx) mx = v;
-              let Z = 0; for (const v of f) Z += Math.exp(v - mx); const lse = mx + Math.log(Z);
-              const bins = new Array<number>(NB).fill(0);
-              for (const v of f) { const t = Math.max(0, Math.min(1, (v - lse - CURVE_UMIN) / (-CURVE_UMIN))); const bi = Math.min(NB - 1, Math.floor(t * NB)); bins[bi] = (bins[bi] ?? 0) + 1; }
-              return { bins, vocab: V };
-            } finally { for (const c of cache) c.dispose(); }
-          });
+          const result = await gateway.runExclusive(() => serving.signal(sids, NB, CURVE_UMIN));
           return Response.json(result, { headers: CURVE_CORS });
         } catch (e) {
           return Response.json({ error: `signal failed: ${(e as Error).message}` }, { status: 500, headers: CURVE_CORS });
@@ -2778,7 +1087,7 @@ export function createServer(
 
       // ---- v2 HLG Curve Designer: POST /generate {prompt, curve, n, max_tokens, seed} ----
       // The drawn log-prob transfer curve REPLACES temperature+softmax entirely
-      // (src/curve-sampler.ts). The browser editor calls this; same curve object the
+      // (src/lab/curve/curve-sampler.ts). The browser editor calls this; same curve object the
       // tool's "Copy values" emits is the one the sampler consumes — one contract.
       if (url.pathname === "/generate" && request.method === "OPTIONS")
         return new Response(null, { headers: CURVE_CORS });
@@ -2802,7 +1111,7 @@ export function createServer(
         const n = Math.max(1, Math.min(8, Math.floor(Number(body.n) || 3)));
         const maxTokens = Math.max(1, Math.min(256, Math.floor(Number(body.max_tokens) || 80)));
         const baseSeed = Number.isFinite(body.seed) ? Number(body.seed) >>> 0 : (Date.now() & 0xffffffff);
-        let ids = ctx.tokenizer.encode(ctx.template.render([{ role: "user", content: prompt }], templateOptionsFor({} as ChatRequest, null)));
+        let ids = ctx.tokenizer.encode(ctx.template.render([{ role: "user", content: prompt }], templateOptionsFor({} as ChatRequestParams, null)));
         if (ids[0] === ids[1] && ids[0] === ctx.tokenizer.bosTokenId) ids = ids.slice(1);
         const samples: { text: string; junk: boolean }[] = [];
         try {
@@ -2811,9 +1120,14 @@ export function createServer(
             const genOpts: GenerateOptions = useCurve
               ? { curve, seed: baseSeed + i, maxTokens, ...kvScheme }
               : { temperature: recipe.temperature, topP: recipe.topP, topK: recipe.topK, seed: baseSeed + i, maxTokens, ...kvScheme };
-            // runExclusive: runGeneration touches the GPU + prompt cache, so
-            // it needs the gateway lock (this endpoint bypasses gateway.run).
-            await gateway.runExclusive(() => runGeneration(ids, genOpts, (t) => { toks.push(t); }));
+            // The same plan and execution lease cover the Lab comparison endpoint.
+            const shape = { hasVision: false, hasAdapters: false, hasRepetitionPenalty: false,
+              hasLogitsExtras: false, wantsLogprobs: false, userSeed: true,
+              kvQuant: !!(genOpts.kvBits || genOpts.kvConfig?.length), turboQuant: !!genOpts.turboQuant,
+              hasGrammar: false, hasDraft: !!ctx.draft };
+            const placement = gateway.place(shape, genOpts);
+            await gateway.run(ids, genOpts, (t) => { toks.push(t); }, undefined,
+              shape, placement, request.signal);
             const text = ctx.tokenizer.decode(toks, true).trim();
             samples.push({ text, junk: curveJunk(text) });
           }
@@ -2823,478 +1137,6 @@ export function createServer(
         return Response.json({ mode: useCurve ? "curve" : "default", recipe: useCurve ? undefined : recipe, n, seed: baseSeed, samples }, { headers: CURVE_CORS });
       }
 
-      // The chat-completions core, shared by both protocol surfaces:
-      // /v1/chat/completions calls it directly; /v1/messages (Anthropic)
-      // translates its body into this shape and the Response back —
-      // generation, tools, vision, stop sequences, prompt cache, and
-      // admission control all live here exactly once.
-      const handleChat = async (
-        body: ChatRequest,
-        signal: AbortSignal,
-        streamProtocol?: CompletionStreamProtocol,
-        requestId?: string,
-        trace?: PromptResponseTrace,
-      ): Promise<Response> => {
-        if (!Array.isArray(body.messages) || body.messages.length === 0)
-          return Response.json({ error: { message: "messages required" } }, { status: 400 });
-        // mlx-lm validates logprobs params up front (ValueError → 400)
-        const lpParamError = validateLogprobsParams(body);
-        if (lpParamError)
-          return Response.json({ error: { message: lpParamError } }, { status: 400 });
-        // Covers /v1/messages and /v1/responses too — both funnel through
-        // this handler after translation.
-        const effortError = validateReasoningEffort(body);
-        if (effortError)
-          return Response.json({ error: { message: effortError } }, { status: 400 });
-
-        const id = requestId ?? `chatcmpl-${crypto.randomUUID()}`;
-        const closePromptPrepare = trace?.begin("request.prompt_prepare");
-        const created = Math.floor(Date.now() / 1000);
-        const tools =
-          body.tool_choice === "none" ? null : (body.tools?.length ? body.tools : null);
-        const hasImages = body.messages.some(
-          (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",
-            ),
-        );
-        // Video content parts (video_url / video with base64 data) —
-        // Qwen3.5-family only (decoded to sampled frames via the
-        // AVFoundation sidecar, vision/video-frames.ts).
-        const hasVideos = body.messages.some(
-          (m) => Array.isArray(m.content) &&
-            m.content.some((p: any) => p.type === "video_url" || p.type === "video"),
-        );
-        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;
-        const ownership = new RequestOwnership();
-        // 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 = ownership.own(g.controller);
-          if (!g.controller && g.degradeHint) {
-            const degraded = applyGrammarDegrade(body, g.degradeHint);
-            grammarWarning = degraded.warning;
-            body = degraded.body;
-          }
-        }
-        const rejectBeforeRun = (response: Response): Response => {
-          ownership.dispose();
-          return response;
-        };
-        try {
-          // Video is Qwen3.5-family only and never composes with audio —
-          // one early guard so no downstream branch can silently drop a
-          // video part (the gemma/diffusion builders don't know the type).
-          if (hasVideos && (hasAudio || !(ctx.model instanceof Qwen35Model))) {
-            return rejectBeforeRun(Response.json(
-              { error: { message: hasAudio
-                  ? "video and audio content parts cannot be combined"
-                  : `model ${ctx.modelId} does not accept video input — video ` +
-                    `content parts need a Qwen3.5-family model (e.g. Qwen3.8-27B)` } },
-              { status: 400 },
-            ));
-          }
-          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) {
-              return rejectBeforeRun(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) {
-                return rejectBeforeRun(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) {
-              return rejectBeforeRun(Response.json(
-                { error: { message: "this checkpoint has no vision tower" } }, { status: 400 },
-              ));
-            }
-            const { messages, images } = await extractImages(normalizeMessages(body.messages));
-            if (images.length !== 1) {
-              return rejectBeforeRun(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]!);
-            diffusionPixels = ownership.own(pixels);
-            promptIds = spliceImageTokens(rawIds, [softTokens], {
-              image: ctx.visionTokenIds.imageTokenId,
-              boi: ctx.visionTokenIds.boiTokenId,
-              eoi: ctx.visionTokenIds.eoiTokenId,
-            });
-          } else if ((hasImages || hasVideos) && ctx.model instanceof Qwen35Model) {
-            // Qwen3.8 vision + video: the tower is a Qwen3VLVisionTower
-            // riding the shared lazy slot (makeVisionLoader's qwen branch);
-            // image/video spans splice into input embeddings and the request
-            // carries mRoPE positions + delta (PLAN 14v/14w). Videos decode
-            // to sampled frames via the AVFoundation sidecar.
-            const tower = getVisionTower(ctx) as unknown as Qwen3VLVisionTower | null;
-            if (!tower) {
-              return rejectBeforeRun(Response.json(
-                { error: { message: "model has no vision sidecar" } }, { status: 400 },
-              ));
-            }
-            const { messages: withVideos, images } =
-              await extractImages(normalizeMessages(body.messages));
-            const { messages, videos } = await extractVideos(withVideos);
-            const vp = await buildQwen3VLVisionPrompt(
-              ctx.model, tower, ctx.tokenizer, ctx.template, messages, images,
-              {
-                imageTokenId: (ctx.model.config.raw.image_token_id as number) ?? 248056,
-                videoTokenId: (ctx.model.config.raw.video_token_id as number) ?? 248057,
-                visionStartId: (ctx.model.config.raw.vision_start_token_id as number) ?? 248053,
-                visionEndId: (ctx.model.config.raw.vision_end_token_id as number) ?? 248054,
-              },
-              templateOptionsFor(body, tools),
-              videos,
-            );
-            promptIds = vp.ids;
-            vision = { embeddings: vp.embeddings, mrope: vp.mrope };
-          } else if (hasImages) {
-            // Loads (and caches) the tower on first image request — text-only
-            // sessions never pay for it.
-            const tower = getVisionTower(ctx);
-            if (!tower) {
-              return rejectBeforeRun(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.
-            const vp = await buildVisionPrompt(
-              ctx.model as Gemma4Model, tower, ctx.tokenizer, ctx.template,
-              messages, images, ctx.visionTokenIds, tools,
-            );
-            promptIds = vp.ids;
-            vision = { embeddings: vp.embeddings, imageMask: vp.imageMask };
-          } else {
-            const built = promptIdsFor(body, tools);
-            promptIds = built.ids;
-            startInThinking = built.startInThinking;
-            stableLen = -1; // marker: chat path, probe lazily below
-          }
-        } catch (e) {
-          return rejectBeforeRun(Response.json(
-            { error: { message: `prompt build failed: ${(e as Error).message}` } },
-            { status: 400 },
-          ));
-        }
-        ownership.own(vision?.embeddings);
-        ownership.own(vision?.imageMask);
-        ownership.own(vision?.multimodalMask);
-        ownership.own(diffusionPixels);
-        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
-          return rejectBeforeRun(
-            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;
-        const requestedMaxTokens = options.maxTokens ?? 1024;
-        let adapterIds: string[];
-        try {
-          // A request's explicit `adapter` (incl. "none") wins over the
-          // startup default from `serve --adapter <dir>`.
-          adapterIds = ctx.adapters.resolveSpec(body.adapter ?? serverOptions.defaultAdapter);
-        } catch (e) {
-          return rejectBeforeRun(
-            Response.json({ error: { message: (e as Error).message } }, { status: 400 }),
-          );
-        }
-
-        const wantLogprobs = body.logprobs === true;
-        const topLogprobs =
-          typeof body.top_logprobs === "number" && body.top_logprobs > 0
-            ? body.top_logprobs : 0;
-        let prepared: PreparedCompletion;
-        try {
-          prepared = prepareCompletion({
-            requestId: id,
-            plan: {
-              promptIds,
-              options,
-              requestedMaxTokens,
-              maxSafeContext: admission.maxSafeContext,
-              stream: body.stream === true,
-              wantLogprobs,
-              topLogprobs,
-              adapterIds,
-              hasVision: !!vision,
-              userSeed: body.seed !== undefined,
-              hasGrammar: !!grammarCtrl,
-              hasDraft: !!ctx.draft,
-              ownership,
-            },
-            vision,
-            pipeline: {
-              router: toolRouter(tools),
-              stopper: new StopMatcher(options.stopSequences),
-              thinking: new ThinkingTagSplitter(
-                ctx.template.thinkingFormat === "think-tag",
-                startInThinking,
-              ),
-              collectToolCalls: true,
-            },
-            ...(body.stream
-              ? {
-                  createFlowControl: ({ mechanism }) =>
-                    createTimedFlowControl(mechanism === "serial"),
-                }
-              : {}),
-            onPlacement: ({ mechanism, shape }) => {
-              if (runtimeValue("MLX_BUN_LANE_DEBUG") === "1")
-                console.error(
-                  `[scheduling] mechanism=${mechanism} shape=${JSON.stringify(shape)} ` +
-                    `t=${Date.now() % 100000}`,
-                );
-            },
-            idToToken: (tokenId) => ctx.tokenizer.idToToken(tokenId),
-          });
-        } catch (error) {
-          closePromptPrepare?.();
-          trace?.finish("error", { stage: "prepare_completion" });
-          if (!(error instanceof CompletionRejected)) throw error;
-          return Response.json({ error: error.error }, { status: error.status });
-        }
-        closePromptPrepare?.();
-
-        if (body.stream) {
-          const streamAbort = new AbortController();
-          const generationSignal = AbortSignal.any([signal, streamAbort.signal]);
-          let cancelled = false;
-          const stream = new ReadableStream<Uint8Array>({
-            start(controller) {
-              const enc = new TextEncoder();
-              const send = (obj: unknown) => {
-                if (!generationSignal.aborted)
-                  controller.enqueue(enc.encode(`data: ${JSON.stringify(obj)}\n\n`));
-              };
-              const emitFrames = (frames: string[]) => {
-                if (generationSignal.aborted) return;
-                for (const frame of frames) controller.enqueue(enc.encode(frame));
-              };
-              let latestUsage: Readonly<CompletionSummary["usage"]> | null = null;
-              let wroteFirstEvent = false;
-              let traceOutcome: "success" | "error" | "abort" = "success";
-              const chunk = (delta: Record<string, unknown>, finish: string | null) => ({
-                id, object: "chat.completion.chunk", created, model: ctx.modelId,
-                choices: [{ index: 0, delta, finish_reason: finish }],
-              });
-              void (async () => {
-                try {
-                // The gateway owns lane selection + GPU exclusivity; this body
-                // runs per-request (concurrently in batched mode, each writing
-                // its own SSE stream — the per-row fan-out).
-                if (streamProtocol) emitFrames(streamProtocol.start());
-                else send(chunk({ role: "assistant", content: "" }, null));
-                const sendEvents = (events: readonly CompletionEvent[]) => {
-                  if (events.length && !wroteFirstEvent) {
-                    wroteFirstEvent = true;
-                    trace?.mark("response.first_write");
-                  }
-                  if (streamProtocol) {
-                    emitFrames(streamProtocol.addEvents([...events]));
-                    return;
-                  }
-                  for (const event of events) {
-                    if (event.type === "reasoning") {
-                      send(chunk({ reasoning: event.text }, null));
-                    } else if (event.type === "content") {
-                      send(chunk({ content: event.text }, null));
-                    } else {
-                      send(chunk({
-                        tool_calls: event.calls.map((call, index) => ({ index, ...call })),
-                      }, null));
-                    }
-                  }
-                };
-                const summary = await completionExecutor.execute(prepared, {
-                  signal: generationSignal,
-                  trace,
-                  onEvents: sendEvents,
-                  ...(streamProtocol
-                    ? { onUsageProgress: (usage) => { latestUsage = usage; } }
-                    : {}),
-                });
-                const usage = completionUsage(summary);
-                if (streamProtocol) {
-                  emitFrames(streamProtocol.finish(summary.finishReason, usage));
-                } else {
-                  send({ ...chunk({}, summary.finishReason), usage });
-                  // bare sentinel per the OpenAI spec — strict SDK clients
-                  // require the unquoted terminator.
-                  controller.enqueue(enc.encode("data: [DONE]\n\n"));
-                }
-                trace?.mark("response.final_write");
-                } catch (e) {
-                  traceOutcome = generationSignal.aborted ? "abort" : "error";
-                  if (!generationSignal.aborted) {
-                    const message = (e as Error).message;
-                    if (streamProtocol) {
-                      emitFrames([
-                        ...streamProtocol.error(message),
-                        ...streamProtocol.finish(
-                          "stop",
-                          latestUsage ? completionProtocolUsage(latestUsage) : {},
-                        ),
-                      ]);
-                    } else {
-                      send({ error: { message } });
-                    }
-                  }
-                } finally {
-                  trace?.finish(traceOutcome);
-                  if (!cancelled) {
-                    if (generationSignal.aborted) controller.error(generationSignal.reason);
-                    else controller.close();
-                  }
-                }
-              })();
-            },
-            cancel(reason) {
-              cancelled = true;
-              streamAbort.abort(reason);
-            },
-          });
-          return new Response(stream, {
-            headers: {
-              "content-type": "text/event-stream",
-              "cache-control": "no-cache",
-              connection: "keep-alive",
-              ...(grammarWarning ? { Warning: grammarWarning } : {}),
-            },
-          });
-        }
-
-        try {
-          {
-            const summary = await completionExecutor.execute(prepared, { signal, trace });
-            trace?.mark("response.final_write");
-            const response = Response.json({
-              id, object: "chat.completion", created, model: ctx.modelId,
-              choices: [{
-                index: 0,
-                message: {
-                  role: "assistant",
-                  content: summary.content || (summary.toolCalls.length ? null : ""),
-                  ...(summary.reasoning ? { reasoning: summary.reasoning } : {}),
-                  ...(summary.toolCalls.length ? { tool_calls: summary.toolCalls } : {}),
-                },
-                ...(summary.logprobs ? { logprobs: summary.logprobs } : {}),
-                finish_reason: summary.finishReason,
-              }],
-              usage: completionUsage(summary),
-            }, grammarWarning ? { headers: { Warning: grammarWarning } } : undefined);
-            trace?.finish("success");
-            return response;
-          }
-        } catch (e) {
-          trace?.finish(signal.aborted ? "abort" : "error");
-          // A 500 with no server-side trace is undebuggable in the field —
-          // always log the stack (the JSON body keeps only the message).
-          console.error(`[serve] 500 on chat request:\n${(e as Error).stack ?? e}`);
-          return Response.json({ error: { message: (e as Error).message } }, { status: 500 });
-        }
-      };
-
       if (url.pathname === "/v1/chat/completions" && request.method === "POST") {
         const id = `chatcmpl-${crypto.randomUUID()}`;
         const trace = createPromptResponseTrace({
@@ -3302,25 +1144,19 @@ export function createServer(
           requestId: id,
           route: url.pathname,
         });
-        const closeBodyParse = trace?.begin("request.body_parse");
-        let body: ChatRequest;
-        try {
-          body = (await request.json()) as ChatRequest;
-        } catch {
-          closeBodyParse?.();
-          trace?.finish("error", { stage: "body_parse" });
-          return Response.json({ error: { message: "invalid JSON body" } }, { status: 400 });
-        }
-        closeBodyParse?.();
-        return handleChat(body, request.signal, undefined, id, trace);
+        const body = await parseBody<ChatRequestParams>(request, trace);
+        if (body instanceof Response) return body;
+        const meta = openAiMeta(id);
+        const a = await admit(
+          inferenceStage, () => chatStage.run(new ChatRequest(body), id, request.signal), trace, "chat request");
+        if ("response" in a) return a.response;
+        return body.stream
+          ? respondStream(inferenceStage, a.admitted, chatCompletionStream(meta), request.signal, trace)
+          : respondJson(inferenceStage, a.admitted, (r) => chatCompletionJson(r, meta), request.signal, trace);
       }
 
-      // Raw text completion (mlx_lm.server's /v1/completions, request_type
-      // "text"): NO chat template — the prompt string is tokenized directly
-      // (tokenizer.encode with the tokenizer's own special-token handling,
-      // exactly mlx-lm's `tokenizer.encode(request.prompt)`). Rides the same
-      // GenerationGateway + admission + adapter path as chat; no tool router
-      // or thinking splitter (raw text in, raw text out).
+      // Raw text completion (mlx_lm.server's /v1/completions): no chat
+      // template — TextCompletionStage tokenizes the prompt string directly.
       if (url.pathname === "/v1/completions" && request.method === "POST") {
         const id = `cmpl-${crypto.randomUUID()}`;
         const trace = createPromptResponseTrace({
@@ -3328,203 +1164,15 @@ export function createServer(
           requestId: id,
           route: url.pathname,
         });
-        const closeBodyParse = trace?.begin("request.body_parse");
-        let body: TextCompletionRequest;
-        try {
-          body = (await request.json()) as TextCompletionRequest;
-        } catch {
-          closeBodyParse?.();
-          trace?.finish("error", { stage: "body_parse" });
-          return Response.json({ error: { message: "invalid JSON body" } }, { status: 400 });
-        }
-        closeBodyParse?.();
-        const closePromptPrepare = trace?.begin("request.prompt_prepare");
-        if (typeof body.prompt !== "string" || body.prompt.length === 0)
-          return Response.json(
-            {
-              error: {
-                message: "prompt (a non-empty string) is required " +
-                  "(token-array prompts are not accepted, matching mlx_lm.server)",
-              },
-            },
-            { status: 400 },
-          );
-        // mlx-lm validates logprobs params up front (ValueError → 400)
-        const lpParamError = validateLogprobsParams(body);
-        if (lpParamError)
-          return Response.json({ error: { message: lpParamError } }, { status: 400 });
-        const created = Math.floor(Date.now() / 1000);
-        const promptIds = ctx.tokenizer.encode(body.prompt);
-        const ownership = new RequestOwnership();
-        let options: ReturnType<typeof toOptions>;
-        try {
-          options = toOptions(body as unknown as ChatRequest);
-        } catch (e) {
-          // 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 = ownership.own(g.controller);
-          else if (g.degradeHint)
-            textGrammarWarning =
-              `grammar not enforced: ${g.degradeHint} - no prompt injection on /v1/completions`;
-        }
-        // 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.
-        const requestedMaxTokens = body.max_completion_tokens ?? body.max_tokens ??
-          defaultGeneratedTokens ?? 512;
-        let adapterIds: string[];
-        try {
-          adapterIds = ctx.adapters.resolveSpec(body.adapter ?? serverOptions.defaultAdapter);
-        } catch (e) {
-          ownership.dispose();
-          return Response.json({ error: { message: (e as Error).message } }, { status: 400 });
-        }
-        const wantLogprobs = body.logprobs === true;
-        const topLogprobs =
-          typeof body.top_logprobs === "number" && body.top_logprobs > 0
-            ? body.top_logprobs : 0;
-        let prepared: PreparedCompletion;
-        try {
-          prepared = prepareCompletion({
-            requestId: id,
-            plan: {
-              promptIds,
-              options,
-              requestedMaxTokens,
-              maxSafeContext: admission.maxSafeContext,
-              stream: body.stream === true,
-              wantLogprobs,
-              topLogprobs,
-              adapterIds,
-              hasVision: false,
-              userSeed: body.seed !== undefined,
-              hasGrammar: !!options.grammar,
-              hasDraft: !!ctx.draft,
-              ownership,
-            },
-            pipeline: {
-              router: new ToolAwareStream(ctx.tokenizer, "plain", null),
-              stopper: new StopMatcher(options.stopSequences),
-              thinking: new ThinkingTagSplitter(false),
-              collectToolCalls: false,
-            },
-            ...(body.stream
-              ? { createFlowControl: () => createTimedFlowControl(true) }
-              : {}),
-            idToToken: (tokenId) => ctx.tokenizer.idToToken(tokenId),
-          });
-        } catch (error) {
-          closePromptPrepare?.();
-          trace?.finish("error", { stage: "prepare_completion" });
-          if (!(error instanceof CompletionRejected)) throw error;
-          return Response.json({ error: error.error }, { status: error.status });
-        }
-        closePromptPrepare?.();
-
-        if (body.stream) {
-          const streamAbort = new AbortController();
-          const generationSignal = AbortSignal.any([request.signal, streamAbort.signal]);
-          let cancelled = false;
-          const stream = new ReadableStream<Uint8Array>({
-            start(controller) {
-              const enc = new TextEncoder();
-              const send = (obj: unknown) => {
-                if (!generationSignal.aborted)
-                  controller.enqueue(enc.encode(`data: ${JSON.stringify(obj)}\n\n`));
-              };
-              const chunk = (text: string, finish: string | null) => ({
-                id, object: "text_completion", created, model: ctx.modelId,
-                choices: [{ index: 0, text, finish_reason: finish }],
-              });
-              let wroteFirstEvent = false;
-              let traceOutcome: "success" | "error" | "abort" = "success";
-              void (async () => {
-                try {
-                const sendEvents = (events: readonly CompletionEvent[]) => {
-                  if (events.length && !wroteFirstEvent) {
-                    wroteFirstEvent = true;
-                    trace?.mark("response.first_write");
-                  }
-                  for (const event of events) {
-                    if (event.type === "content") send(chunk(event.text, null));
-                  }
-                };
-                const summary = await completionExecutor.execute(prepared, {
-                  signal: generationSignal,
-                  trace,
-                  onEvents: sendEvents,
-                });
-                // final chunk: finish_reason + usage (mlx-lm gates usage behind
-                // stream_options.include_usage; we always attach it, matching
-                // our chat lane — an additive superset OpenAI clients ignore)
-                send({
-                  ...chunk("", summary.finishReason),
-                  usage: completionUsage(summary),
-                });
-                  controller.enqueue(enc.encode("data: [DONE]\n\n"));
-                trace?.mark("response.final_write");
-                } catch (e) {
-                  traceOutcome = generationSignal.aborted ? "abort" : "error";
-                  if (!generationSignal.aborted)
-                    send({ error: { message: (e as Error).message } });
-                } finally {
-                  trace?.finish(traceOutcome);
-                  if (!cancelled) {
-                    if (generationSignal.aborted) controller.error(generationSignal.reason);
-                    else controller.close();
-                  }
-                }
-              })();
-            },
-            cancel(reason) {
-              cancelled = true;
-              streamAbort.abort(reason);
-            },
-          });
-          return new Response(stream, {
-            headers: {
-              "content-type": "text/event-stream",
-              "cache-control": "no-cache",
-              connection: "keep-alive",
-              ...(textGrammarWarning ? { Warning: textGrammarWarning } : {}),
-            },
-          });
-        }
-
-        try {
-          const summary = await completionExecutor.execute(prepared, {
-            signal: request.signal,
-            trace,
-          });
-          trace?.mark("response.final_write");
-          const response = Response.json({
-            id, object: "text_completion", created, model: ctx.modelId,
-            choices: [{
-              index: 0, text: summary.content,
-              ...(summary.logprobs ? { logprobs: summary.logprobs } : {}),
-              finish_reason: summary.finishReason,
-            }],
-            usage: completionUsage(summary),
-          }, textGrammarWarning ? { headers: { Warning: textGrammarWarning } } : undefined);
-          trace?.finish("success");
-          return response;
-        } catch (e) {
-          trace?.finish(request.signal.aborted ? "abort" : "error");
-          return Response.json({ error: { message: (e as Error).message } }, { status: 500 });
-        }
+        const body = await parseBody<TextCompletionParams>(request, trace);
+        if (body instanceof Response) return body;
+        const meta = openAiMeta(id);
+        const a = await admit(
+          inferenceStage, () => textStage.run(new TextCompletionRequest(body), id), trace, "text completion");
+        if ("response" in a) return a.response;
+        return body.stream
+          ? respondStream(inferenceStage, a.admitted, textCompletionStream(meta), request.signal, trace)
+          : respondJson(inferenceStage, a.admitted, (r) => textCompletionJson(r, meta), request.signal, trace);
       }
 
       // Anthropic Messages API (Phase 11) — on by default, mirroring
@@ -3533,41 +1181,35 @@ export function createServer(
       // src/anthropic.ts. Point Claude Code at this port via
       // ANTHROPIC_BASE_URL for a fully local backend.
       if (url.pathname === "/v1/messages" && request.method === "POST") {
-        const anthropicError = (status: number, type: string, message: string) =>
-          Response.json({ type: "error", error: { type, message } }, { status });
+        const anthropicError: ErrorFormatter = (status, message) =>
+          Response.json(
+            { type: "error", error: { type: status >= 500 ? "api_error" : "invalid_request_error", message } },
+            { status },
+          );
         let anthropicBody: AnthropicRequest;
         try {
           anthropicBody = (await request.json()) as AnthropicRequest;
         } catch {
-          return anthropicError(400, "invalid_request_error", "invalid JSON body");
+          return anthropicError(400, "invalid JSON body", {});
         }
-        let chatBody: ChatRequest;
+        let chatBody: ChatRequestParams;
         try {
-          chatBody = anthropicToChatBody(anthropicBody) as unknown as ChatRequest;
+          chatBody = anthropicToChatBody(anthropicBody) as unknown as ChatRequestParams;
         } catch (e) {
-          return anthropicError(400, "invalid_request_error", (e as Error).message);
-        }
-        const resp = await handleChat(
-          chatBody,
-          request.signal,
-          anthropicBody.stream
-            ? createAnthropicStreamProtocol(ctx.modelId)
-            : undefined,
-        );
-        if (!resp.ok) {
-          const err = (await resp.json().catch(() => null)) as
-            | { error?: { message?: string } }
-            | null;
-          return anthropicError(
-            resp.status,
-            resp.status >= 500 ? "api_error" : "invalid_request_error",
-            err?.error?.message ?? "request failed",
-          );
-        }
-        if (anthropicBody.stream) {
-          return resp;
+          return anthropicError(400, (e as Error).message, {});
         }
-        return Response.json(chatJsonToAnthropic(await resp.json(), ctx.modelId));
+        const id = `chatcmpl-${crypto.randomUUID()}`;
+        const a = await admit(
+          inferenceStage, () => chatStage.run(new ChatRequest(chatBody), id, request.signal), undefined,
+          "anthropic request", anthropicError);
+        if ("response" in a) return a.response;
+        if (anthropicBody.stream)
+          return respondStream(
+            inferenceStage, a.admitted, createAnthropicStreamProtocol(ctx.modelId), request.signal);
+        return respondJson(
+          inferenceStage, a.admitted,
+          (r) => chatJsonToAnthropic(chatCompletionJson(r, openAiMeta(id)), ctx.modelId),
+          request.signal, undefined, anthropicError);
       }
 
       // OpenAI Responses API (Phase 11) — Codex/Cursor/Continue speak
@@ -3575,7 +1217,7 @@ export function createServer(
       // ported in src/responses.ts. previous_response_id resumes a prior
       // conversation from the in-process store (TTL + byte-capped LRU).
       if (url.pathname === "/v1/responses" && request.method === "POST") {
-        const responsesError = (status: number, message: string) =>
+        const responsesError: ErrorFormatter = (status, message) =>
           Response.json(
             {
               error: {
@@ -3590,80 +1232,55 @@ export function createServer(
         try {
           responsesBody = (await request.json()) as ResponsesRequest;
         } catch {
-          return responsesError(400, "invalid JSON body");
+          return responsesError(400, "invalid JSON body", {});
         }
 
-        // previous_response_id: prepend the prior conversation's input
-        // + output (as input items); carry instructions forward only if
-        // the new request omits them (oracle semantics).
-        const prevId = responsesBody.previous_response_id ?? null;
-        if (prevId) {
-          const prior = responseStore.get(prevId);
-          if (!prior)
-            return responsesError(404, `previous_response_id '${prevId}' not found or expired`);
-          const prepended = [...prior.input, ...outputItemsToInputItems(prior.output)];
-          const newInput =
-            typeof responsesBody.input === "string"
-              ? responsesBody.input
-                ? [{ type: "message", role: "user", content: responsesBody.input }]
-                : []
-              : responsesBody.input ?? [];
-          responsesBody = {
-            ...responsesBody,
-            input: [...prepended, ...newInput] as Array<Record<string, unknown>>,
-            instructions: responsesBody.instructions ?? prior.instructions ?? undefined,
-          };
-        }
-        // Remember the effective input so a later follow-up that chains
-        // off THIS response sees the full history.
-        const capturedInput: unknown[] =
-          typeof responsesBody.input === "string"
-            ? [{ type: "message", role: "user", content: responsesBody.input }]
-            : [...(responsesBody.input ?? [])];
-        const capturedInstructions = responsesBody.instructions ?? null;
+        let conversation: ReturnType<typeof resolveResponsesConversation>;
+        try { conversation = resolveResponsesConversation(responsesBody, responseStore); }
+        catch (error) { return responsesError(404, (error as Error).message, {}); }
+        responsesBody = conversation.body;
+        const prevId = conversation.previousId;
+        const capturedInput = conversation.input;
+        const capturedInstructions = conversation.instructions;
+        const storeHere = !(serverOptions.unixSocket && request.headers.get("x-mlx-bun-response-owner") === "parent");
+        const remember = (id: string, output: unknown[]) => {
+          if (storeHere) responseStore.put(id, { input: capturedInput, output, instructions: capturedInstructions });
+        };
 
-        let chatBody: ChatRequest;
+        let chatBody: ChatRequestParams;
         try {
-          chatBody = responsesToChatBody(responsesBody) as unknown as ChatRequest;
+          chatBody = responsesToChatBody(responsesBody) as unknown as ChatRequestParams;
         } catch (e) {
-          return responsesError(400, (e as Error).message);
-        }
-        const resp = await handleChat(
-          chatBody,
-          request.signal,
-          responsesBody.stream
-            ? createResponsesStreamProtocol(
-                ctx.modelId,
-                prevId,
-                (final) =>
-                  responseStore.put(final.id as string, {
-                    input: capturedInput,
-                    output: final.output as unknown[],
-                    instructions: capturedInstructions,
-                  }),
-              )
-            : undefined,
-        );
-        if (!resp.ok) {
-          const err = (await resp.json().catch(() => null)) as
-            | { error?: { message?: string } }
-            | null;
-          return responsesError(resp.status, err?.error?.message ?? "request failed");
-        }
-        if (responsesBody.stream) {
-          return resp;
+          return responsesError(400, (e as Error).message, {});
         }
-        const responses = chatJsonToResponses(await resp.json(), ctx.modelId, prevId);
-        responseStore.put(responses.id as string, {
-          input: capturedInput,
-          output: responses.output as unknown[],
-          instructions: capturedInstructions,
-        });
-        return Response.json(responses);
+        const id = `chatcmpl-${crypto.randomUUID()}`;
+        const a = await admit(
+          inferenceStage, () => chatStage.run(new ChatRequest(chatBody), id, request.signal), undefined,
+          "responses request", responsesError);
+        if ("response" in a) return a.response;
+        if (responsesBody.stream)
+          return respondStream(
+            inferenceStage, a.admitted,
+            createResponsesStreamProtocol(
+              ctx.modelId,
+              prevId,
+              (final) =>
+                remember(final.id as string, final.output as unknown[]),
+            ),
+            request.signal);
+        return respondJson(
+          inferenceStage, a.admitted,
+          (r) => {
+            const responses = chatJsonToResponses(chatCompletionJson(r, openAiMeta(id)), ctx.modelId, prevId);
+            remember(responses.id as string, responses.output as unknown[]);
+            return responses;
+          },
+          request.signal, undefined, responsesError);
       }
 
       const labResponse = await handleLabRoute(url, request, {
         ensureJobs,
+        acquireGpu: (signal) => gateway.acquireExecutionLease(signal),
         serverPort: () => server.port,
         invalidateLibrary: () => discoveryRoutes.invalidateLibrary(),
       });
@@ -3679,6 +1296,13 @@ export function createServer(
     },
   });
   serverLifecycles.set(serverRef, {
+    stopJobs: async () => {
+      if (jobStore) {
+        const jobs = await import("./jobs");
+        await Promise.all([jobs.closeSubprocessJobs(jobStore), jobs.closeInProcessJobs(jobStore)]);
+      }
+    },
+    close: async () => { preparation.close(); await sessionEngine.close(); await gateway.close(); },
     flush: flushDurability,
     stats: durabilityStats,
     stopTimers: () => {