@mlx-node/core 0.0.7 → 0.0.9

package/index.d.cts

@@ -119,82 +119,100 @@ export declare class DocUnwarpModel {
  * commands via channels and await responses.
  */
 export declare class Gemma4Model {
+  /**
+   * Create an uninitialized `Gemma4Model` stub from a config.
+   *
+   * **Prefer [`Gemma4Model::load`]** for any real usage — `new(config)`
+   * is a config-only stub that matches the OCR-model pattern
+   * (`VLModel::new(config)`, `QianfanOCRModel::new(config)`) and is
+   * intentionally NOT runnable. It was introduced in the cache-limit
+   * coordinator work so that the coordinator's per-model delta is
+   * registered exclusively on the `load()` path, eliminating a
+   * baseline-registration gap where a no-op `new(config)` would have
+   * leaked an empty guard into the coordinator.
+   *
+   * This path does NOT spawn a model thread, NOT materialize any
+   * weights, and NOT register with the cache-limit coordinator. The
+   * returned instance is only useful for config inspection — every
+   * session method (`chatSessionStart` / `chatSessionContinue` /
+   * `chatSessionContinueTool` and their streaming variants) rejects
+   * with a `napi::Error` whose message is exactly
+   * `"Model not initialized. Call Gemma4Model.load() first."` until
+   * `load()` runs and installs the underlying model thread. The
+   * synchronous `resetCaches()` call is a silent no-op on the stub
+   * to keep `ChatSession.reset()` idempotent across both runnable
+   * and stub instances.
+   *
+   * A runnable model requires `await Gemma4Model.load(path)`. The
+   * constructor signature is fixed by NAPI-RS; the stub-only behavior is
+   * covered by the regression tests in
+   * `__test__/models/model-loader-gemma4.test.ts`.
+   */
   constructor(config: Gemma4Config);
+  /** Returns true if weights have been loaded via `load()`. */
+  get isInitialized(): boolean;
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Gemma4Inner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Gemma4Config::use_block_paged_cache`). The
+   * `gemma4_paged_vs_flat_parity` integration test pins greedy
+   * byte-equal at BF16 against real Gemma-4-E2B-IT weights. Stubs
+   * constructed via `new(config)` always return `false`. Surfaced
+   * through this NAPI method so server endpoints can branch on it
+   * without a model-thread roundtrip.
+   */
+  hasBlockPagedCache(): boolean;
+  /**
+   * Whether this loaded instance can execute image-bearing chat turns.
+   * Config-only stubs and incomplete/non-paged physical paths return false.
+   */
+  supportsImages(): boolean;
   modelId(): number;
-  /** Load a Gemma4 model from a directory. */
-  static load(modelPath: string): Promise<Gemma4Model>;
   /**
-   * Reset all caches and clear cached token history. Exposed so
-   * tests and session-management code can start from a known clean
-   * state between turns.
+   * Whether a draft model — DSpark or Google assistant — is loaded on
+   * this instance (via `Gemma4LoadOptions::draft_model_path`), enabling
+   * the speculative-decode whole-turn path.
    *
-   * Synchronous on the NAPI boundary — every other `SessionCapableModel`
-   * exposes `resetCaches(): void` and the `ChatSession<M>` cross-model
-   * wrapper calls this inline during the image-change restart and
-   * `reset()` flows. Running it as an async NAPI method would break
-   * that contract and silently drop reset failures because
-   * `ChatSession.reset()` and the session-start restart path invoke
-   * `model.resetCaches()` without awaiting.
+   * Note: this only reports draft availability. Whether speculative
+   * decoding actually runs on a given call also requires the per-request
+   * `enableMtp` flag. Named `hasMtpWeights` for parity with the Qwen3.5
+   * surface, but it reports an external draft model (either variant),
+   * not in-checkpoint MTP heads. Stubs from `new(config)` always return
+   * `false`.
+   */
+  hasMtpWeights(): boolean;
+  /** Load a Gemma4 model from a directory. */
+  static load(modelPath: string, options?: Gemma4LoadOptions | undefined | null): Promise<Gemma4Model>;
+  /**
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
    */
   resetCaches(): void;
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until Gemma4's
-   * `<turn|>` delimiter, and leaves the KV caches on a clean turn
-   * boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on top
-   * without re-rendering the chat template.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw Gemma4 user/model delta to the session's cached KV
-   * state, then decodes the model reply. Stops on `<turn|>` so the
-   * cache remains on a clean turn boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty, carries image state, or if
-   * `config.reuse_cache` is explicitly set to `false`.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the native
-   * side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route image-changes
-   * back through a fresh `chatSessionStart` uniformly across all
-   * model backends.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
-  /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a Gemma4-format tool delta
-   * (`
-  <|turn>tool
-  {content}<turn|>
-  <|turn>model
-  `) from
-   * `content` and prefills it on top of the live session caches,
-   * then decodes the model reply. Stops on `<turn|>` so the cache
-   * stays on a clean turn boundary for the next turn.
-   *
-   * The `tool_call_id` is currently dropped by the wire format —
-   * Gemma4's chat template identifies tool responses positionally,
-   * not via an explicit id. Callers may still log it for their own
-   * bookkeeping.
-   *
-   * Requires a live session started via `chatSessionStart`.
-   */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -203,15 +221,13 @@ export declare class Gemma4Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
@@ -471,69 +487,53 @@ export declare class Lfm2Model {
   /** Load an LFM2 model from a directory containing safetensors and config.json. */
   static load(modelPath: string): Promise<Lfm2Model>;
   /**
-   * Reset all caches and clear cached token history. Exposed so
-   * tests and session-management code can start from a known clean
-   * state between turns.
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Lfm2Inner::paged_adapter` was successfully constructed
+   * at load time (driven by `Lfm2Config::use_block_paged_cache`,
+   * defaulting to `true` after paged-vs-flat parity verification).
+   * LFM2 is hybrid (10 conv + 6 full-attention layers); only the
+   * full-attention layers route through the adapter, conv layers stay
+   * on flat `Lfm2LayerCache::Conv` regardless. When `true`, the native
+   * cache reuses SYS blocks across `chatSessionStart` calls via
+   * content-addressing, so the JS-side warm slot in
+   * `SessionRegistry.getOrCreateWarmAny` is redundant and the
+   * `/v1/messages` server endpoint allocates a fresh `ChatSession` per
+   * request.
+   */
+  hasBlockPagedCache(): boolean;
+  /** Get the model configuration. */
+  getConfig(): Lfm2Config;
+  /** Estimated number of model parameters. */
+  numParameters(): number;
+  /**
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
    */
   resetCaches(): void;
   /**
    * Start a new chat session.
    *
-   * Runs the full jinja chat template once, decodes until
-   * `<|im_end|>`, and leaves the KV/conv caches on a clean ChatML
-   * boundary so subsequent `chatSessionContinue` /
-   * `chatSessionContinueTool` calls can append a raw delta on top
-   * without re-rendering the chat template.
-   *
-   * Requires `config.reuse_cache` to be enabled (the default).
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's
-   * cached KV/conv state, then decodes the assistant reply. Stops
-   * on `<|im_end|>` so the cache remains on a clean boundary for
-   * the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty, carries image state, or if
-   * `config.reuse_cache` is explicitly set to `false`.
-   *
-   * LFM2 is text-only; `images` is an opt-in guard parameter: when
-   * non-empty the native side returns an error whose message begins
-   * with `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route
-   * image-changes back through a fresh `chatSessionStart`
-   * uniformly across all model backends.
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds an LFM2-format tool delta (`<|im_start|>tool
-{content}
- * <|im_end|>`) from `content` and prefills it on top of the live
- * session caches, then decodes the assistant reply. Stops on
- * `<|im_end|>` so the cache stays on a clean boundary for the
- * next turn.
- *
- * The `tool_call_id` is currently dropped by the wire format —
- * LFM2's chat template identifies tool responses positionally,
- * not via an explicit id. Callers may still log it for their own
- * bookkeeping.
- *
- * Requires a live session started via `chatSessionStart`.
- */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -542,22 +542,16 @@ export declare class Lfm2Model {
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
   /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Get the model configuration. */
-  getConfig(): Lfm2Config;
-  /** Estimated number of model parameters. */
-  numParameters(): number;
 }
 
 export declare class MxArray {
@@ -681,9 +675,20 @@ export declare class MxArray {
   divScalar(value: number): MxArray;
   matmul(other: MxArray): MxArray;
   /**
-   * Fused matrix multiply-add: D = beta * C + alpha * (self @ B)
-   * where self is A. More efficient than separate matmul and add operations.
-   * Default: alpha=1.0, beta=1.0, giving D = C + (self @ B)
+   * Matrix multiply-add: D = beta * C + alpha * (self @ B), where self is A.
+   * Default: alpha=1.0, beta=1.0, giving D = C + (self @ B).
+   *
+   * Computed explicitly (matmul, optional alpha scale, then add beta*C)
+   * rather than via the fused `mlx::core::addmm` primitive. The fused
+   * primitive is correct on a well-formed metallib, but this project's local
+   * release build is known to non-deterministically miscompile fused GEMM
+   * kernels (see the metallib-corruption notes), which manifested as the
+   * fused addmm dropping `beta*C` and corrupting every biased linear — most
+   * visibly the vision tower (`qkv`, `proj`, `fc1`, `fc2`, merger all carry a
+   * bias; bias-free LM/MoE linears pass a zero `C` and were unaffected). The
+   * explicit form keeps the `C` term robust to that build hazard; the
+   * `nn::linear` unit tests assert it applies a non-zero `C`, so they double
+   * as a canary if a future build corrupts the matmul kernel too.
    */
   addmm(c: MxArray, b: MxArray, alpha?: number | undefined | null, beta?: number | undefined | null): MxArray;
   abs(): MxArray;
@@ -941,23 +946,43 @@ export declare class OutputStore {
 }
 
 /**
- * Opaque handle to KV cache state from a chat-session turn.
- *
- * Pass this back via `model.setCache(cache)` before the next
- * chat-session call to enable incremental prefill — only new tokens
- * since the last turn are processed, avoiding redundant computation.
+ * NAPI-exported view of [`PrivacyFilterModel`].
  *
- * Created internally by the model during chat-session turns.
- * Extract via `model.takeCache()`, restore via `model.setCache(cache)`.
+ * Construct via [`PrivacyFilterModelJs::load`] and run end-to-end
+ * classification via [`PrivacyFilterModelJs::classify`].
  */
-export declare class PromptCache {
-  /** Number of tokens stored in this cache. */
-  get tokenCount(): number;
-  /** Whether this cache has been consumed (caches moved out). */
-  get isEmpty(): boolean;
-  /** Release GPU memory held by this cache. */
-  dispose(): void;
+export declare class PrivacyFilterModel {
+  /**
+   * Load a privacy-filter checkpoint from a directory.
+   *
+   * The directory must contain `config.json`, `model.safetensors`,
+   * `tokenizer.json`, and optionally `viterbi_calibration.json` and
+   * `tokenizer_config.json`. Synchronous to match the loader pattern
+   * used by every other model in this crate (e.g. `TextDetModel`).
+   */
+  static load(modelPath: string): PrivacyFilterModel;
+  /**
+   * Classify `text` and return detected PII entities (and optionally
+   * per-token tags).
+   *
+   * Pipeline:
+   * 1. Tokenize the text with byte offsets, no special tokens.
+   * 2. Run the forward pass to get `[1, T, 33]` logits.
+   * 3. Compute softmax (for per-tag confidences) and log-softmax (for
+   *    Viterbi emissions) over the class axis.
+   * 4. Build the transition matrix from the default calibration
+   *    merged with any per-call overrides.
+   * 5. Viterbi-decode using log-softmax emissions to get the BIOES
+   *    tag sequence.
+   * 6. For each token, take the softmax probability of the
+   *    Viterbi-emitted tag (so per-token `tag` and `score` share
+   *    decoders), then walk the tags + offsets + those probabilities
+   *    to extract coherent spans whose mean probability clears
+   *    `threshold`.
+   */
+  classify(text: string, opts?: PrivacyClassifyOptions | undefined | null): PrivacyClassifyResult;
 }
+export type PrivacyFilterModelJs = PrivacyFilterModel;
 
 /**
  * Qianfan-OCR Vision-Language Model (InternVL architecture).
@@ -973,8 +998,13 @@ export declare class QianfanOCRModel {
    * Create a new QianfanOCRModel from config (uninitialized, no weights).
    *
    * This constructor path does not spawn a model thread — the returned
-   * instance is only useful for config inspection. Call
-   * [`QianfanOCRModel::load`] to actually run inference.
+   * instance is only useful for `is_initialized` queries until
+   * [`QianfanOCRModel::load`] is called to actually run inference. The
+   * `config` argument is accepted to preserve the `new
+   * QianfanOCRModel(config)` JS surface; the value is discarded because
+   * nothing on the uninitialized path consults it (any future config
+   * getter would forward to the inner thread state populated by
+   * `load()`).
    */
   constructor(config: QianfanOcrConfig);
   /** Returns true if weights have been loaded via `load()`. */
@@ -1004,11 +1034,9 @@ export declare class QianfanOCRModel {
   /**
    * Start a new chat session.
    *
-   * Runs the full chat template once, decodes until `<|im_end|>`,
-   * and leaves the KV caches on a clean turn boundary so subsequent
-   * `chatSessionContinue` / `chatSessionContinueTool` calls can
-   * append a raw ChatML delta on top without re-rendering the chat
-   * template.
+   * Renders the complete structured conversation through the checkpoint
+   * template, decodes until `<|im_end|>`, and preserves KV state for an
+   * exact-prefix check against the next complete template render.
    *
    * Qianfan-OCR is always a VLM (InternViT + Qwen3 language model), so
    * this entry point accepts images in `messages` without the text-only
@@ -1016,62 +1044,31 @@ export declare class QianfanOCRModel {
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's cached
-   * KV state, then decodes the model reply. Stops on `<|im_end|>` so
-   * the cache remains on a clean turn boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty or if `config.reuse_cache` is
-   * explicitly set to `false`.
-   *
-   * `images` is an opt-in guard parameter: when non-empty the native
-   * side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route image-changes
-   * back through a fresh `chatSessionStart` uniformly across all
-   * model backends. Qianfan-OCR is a VLM but the continue path cannot
-   * splice new vision features into a live KV cache — image changes
-   * always require a fresh session start.
+   * Continue from the caller's complete conversation history. The
+   * checkpoint's chat template is rendered again and exact prefix matching
+   * decides whether the live cache can be reused.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a ChatML `<tool_response>` delta from `tool_call_id` and
-   * `content` and prefills it on top of the live session caches, then
-   * decodes the model reply. Stops on `<|im_end|>` so the cache stays
-   * on a clean turn boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`.
+   * Tool-result continuation over a full history. Tool representation is
+   * owned entirely by the model-provided template.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinue`. */
+  /** Streaming continuation over a complete conversation history. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinueTool`. */
+  /** Streaming tool-result continuation over a complete history. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
@@ -1085,27 +1082,55 @@ export declare class QianfanOCRModel {
  * routed through `TrainingDispatch` to the model thread.
  */
 export declare class Qwen35Model {
-  /** Initialize caches for incremental generation. */
-  initCaches(): void;
-  /** Reset all caches. */
-  resetCaches(): void;
   /**
-   * Take the KV cache from the model, returning a `PromptCache` handle.
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
    *
-   * The cache is moved out of the model — calling `takeCache()` twice
-   * returns `null` the second time. Pass the cache back via `setCache()`
-   * before the next `chatSessionStart` / `chatSessionContinue` call for
-   * incremental prefill.
+   * `true` iff `Qwen35Inner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Qwen3_5Config::use_block_paged_cache`, default-OFF for text-only
+   * checkpoints because parity is pending real-weights validation, and
+   * default-ON for VLM checkpoints). On VLM checkpoints dense image turns
+   * ONLY run on the paged-vision core; a vision turn that reaches a None
+   * adapter errors at dispatch. Surfaced through this NAPI method so
+   * server endpoints can branch on it without round-tripping through
+   * the model thread.
+   */
+  hasBlockPagedCache(): boolean;
+  /**
+   * Whether this checkpoint shipped an MTP head (module loaded by
+   * `persistence::apply_weights_inner`). Snapshotted at load time from
+   * `Qwen35Inner::has_mtp_weights()` so the TS `ChatSession` can
+   * auto-default `enableMtp = true` for MTP-capable checkpoints without
+   * dispatching a command into the model thread.
+   *
+   * Note: this only reports weight availability. Whether the
+   * speculative-decode path actually runs on a given call also requires the
+   * per-request `enableMtp` flag.
+   */
+  hasMtpWeights(): boolean;
+  /**
+   * Whether this loaded model instance can execute image-bearing turns.
+   *
+   * This is an authoritative load-time snapshot, not a `config.json`
+   * family guess: it requires a loaded vision encoder, image processor,
+   * and the block-paged KV adapter used by the dense vision path.
+   */
+  supportsImages(): boolean;
+  /**
+   * Synchronous snapshot used by higher layers to preflight rendered
+   * prompts and clamp output before native cache allocation.
    */
-  takeCache(): PromptCache | null;
+  contextLimits(): Qwen35ContextLimits;
   /**
-   * Restore a previously taken `PromptCache` into the model.
+   * Compute the exact prompt length after Qwen image-placeholder expansion
+   * without running the vision encoder or touching inference caches.
    *
-   * On the next `chatSessionStart` / `chatSessionContinue` call with
-   * `reuseCache: true`, the model will prefix-match the new tokens against
-   * the cache and only prefill the delta.
+   * `prompt_tokens` is the already-rendered chat-template output. `messages`
+   * supplies the complete image history so both fresh and leased-session
+   * preflights account for every image in template order.
    */
-  setCache(cache: PromptCache): void;
+  expandedPromptTokenCount(promptTokens: Uint32Array, messages: Array<ChatMessage>): Promise<number>;
   /**
    * Load a pretrained model from a directory.
    *
@@ -1118,130 +1143,62 @@ export declare class Qwen35Model {
   /** Generate text from a prompt token sequence. */
   generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
   /**
-   * Start a new chat session.
+   * Get the number of parameters in the model.
    *
-   * Runs the full jinja chat template once and uses `<|im_end|>` as
-   * its stop token so the cached KV state ends on a clean ChatML
-   * boundary. Image support is conditional on the loaded
-   * checkpoint: a Qwen3.5-VL dense model loaded with vision weights
-   * accepts images in `messages` (the vision encoder handles
-   * prefill), while a plain text Qwen3.5 checkpoint rejects them
-   * with a runtime error. Subsequent turns in the same session MUST
-   * go through `chatSessionContinue` so the caller appends raw
-   * ChatML deltas on top of the live caches without rerunning the
-   * jinja template; a mid-session image change requires a fresh
-   * `chatSessionStart` call. The session is owned end-to-end by
-   * the `chatSession*` surface.
-   *
-   * This method is the production entry point used by the TypeScript
-   * `ChatSession` wrapper for turn 1 of a multi-round conversation.
+   * Pure config computation — no model-thread dispatch needed.
    */
-  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  numParameters(): number;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply. Stops on `<|im_end|>`
-   * so the cache remains on a clean boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty, carries image state, or if
-   * `config.reuse_cache` is explicitly set to `false`.
+   * Save the model weights and configuration to a directory.
    *
-   * `images` is an opt-in guard parameter: when non-empty, the native
-   * side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route image-changes
-   * back through a fresh `chatSessionStart`.
+   * Dispatches to model thread.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  saveModel(savePath: string): Promise<undefined>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a ChatML `<tool_response>`-wrapped delta from `content` and
-   * prefills it on top of the live session caches, then decodes the
-   * assistant reply. Stops on `<|im_end|>` so the cache stays on a
-   * clean boundary for the next turn.
-   *
-   * The `tool_call_id` is currently dropped by the wire format —
-   * Qwen3.5's chat template identifies tool responses by position +
-   * wrapper tags, not an explicit id. Callers may still log it for
-   * their own bookkeeping.
-   *
-   * Requires a live session started via `chatSessionStart`.
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
+  resetCaches(): void;
   /**
-   * Streaming variant of `chatSessionStart`.
+   * Start a new chat session.
    *
-   * Dispatches to the dedicated model thread. Behaviourally identical
-   * to `chatSessionStart` (resets caches, uses `<|im_end|>` as
-   * eos, inherits the same VLM-vs-text image-support contract) but
-   * streams token deltas through the JS callback instead of
-   * returning a `ChatResult`. Used by the TypeScript
-   * `ChatSession.sendStream()` for turn 1 of a multi-round streaming
-   * conversation.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinue`.
-   *
-   * Appends a ChatML user/assistant delta on top of the live session
-   * caches and streams the decoded reply. Requires a live session
-   * started via `chatStreamSessionStart` (or the non-streaming
-   * `chatSessionStart`). Used by the TypeScript
-   * `ChatSession.sendStream()` for turns 2..N of a multi-round
-   * streaming conversation.
-   *
-   * `images` is an opt-in guard parameter: when non-empty, the
-   * streaming path emits an error chunk whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes through a fresh
-   * session start.
-   */
+  /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * Builds a ChatML tool-response delta on top of the live session
-   * caches and streams the decoded reply. Requires a live session
-   * started via `chatSessionStart` / `chatStreamSessionStart`.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Get the number of parameters in the model.
-   *
-   * Pure config computation — no model-thread dispatch needed.
-   */
-  numParameters(): number;
-  /**
-   * Save the model weights and configuration to a directory.
-   *
-   * Dispatches to model thread.
-   */
-  saveModel(savePath: string): Promise<undefined>;
 }
 export type Qwen3_5Model = Qwen35Model;
 
@@ -1253,142 +1210,110 @@ export type Qwen3_5Model = Qwen35Model;
  * routed through `TrainingDispatch` to the model thread.
  */
 export declare class Qwen35MoeModel {
-  /** Initialize caches for incremental generation. */
-  initCaches(): void;
-  /** Reset all caches. */
-  resetCaches(): void;
-  /** Take the KV cache from the model, returning a `PromptCache` handle. */
-  takeCache(): PromptCache | null;
-  /** Restore a previously taken `PromptCache` into the model. */
-  setCache(cache: PromptCache): void;
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Qwen35MoeInner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Qwen3_5MoeConfig::use_block_paged_cache`, currently default-OFF
+   * because parity is pending real-weights validation). On VLM
+   * checkpoints the adapter can still be active for text-only
+   * inference; image-bearing chat turns are rejected at runtime by
+   * the chat-entry sites. Surfaced through this NAPI method so
+   * server endpoints can branch on it without round-tripping through
+   * the model thread.
+   */
+  hasBlockPagedCache(): boolean;
+  /**
+   * Whether this checkpoint shipped an MTP head (module loaded by
+   * `persistence::apply_weights_moe_inner`). Snapshotted at load time from
+   * `Qwen35MoeInner::has_mtp_weights()` so the TS `ChatSession` can
+   * auto-default `enableMtp = true` for MTP-capable checkpoints without
+   * dispatching a command into the model thread. Mirrors
+   * `Qwen3_5Model::has_mtp_weights`.
+   *
+   * Note: this only reports weight availability. Whether the
+   * speculative-decode path actually runs on a given call also requires
+   * the per-request `enableMtp` flag.
+   */
+  hasMtpWeights(): boolean;
+  /**
+   * Whether this loaded model instance can execute image-bearing turns.
+   *
+   * This is an authoritative load-time snapshot, not a model-family guess:
+   * it requires the loaded vision encoder, image processor, and block-paged
+   * KV adapter used by the MoE vision path.
+   */
+  supportsImages(): boolean;
+  /** Synchronous active-context snapshot shared with the dense wrapper. */
+  contextLimits(): Qwen35ContextLimits;
+  /**
+   * Exact, non-mutating Qwen image-placeholder expansion count for a fully
+   * rendered prompt and complete message history.
+   */
+  expandedPromptTokenCount(promptTokens: Uint32Array, messages: Array<ChatMessage>): Promise<number>;
   /** Load a pretrained model from a directory. */
   static load(path: string): Promise<Qwen35MoeModel>;
   /** Generate text from a prompt token sequence. */
   generate(promptTokens: MxArray, config: Qwen35MoeGenerationConfig): Promise<Qwen35MoeGenerationResult>;
   /**
-   * Start a new chat session.
-   *
-   * Runs the full jinja chat template once, decodes until `<|im_end|>`,
-   * and leaves the KV caches on a clean ChatML boundary so subsequent
-   * `chatSessionContinue` / `chatSessionContinueTool` calls can
-   * append a raw delta on top without re-rendering the chat
-   * template.
-   *
-   * Image support is conditional on the loaded checkpoint: a
-   * Qwen3.5-VL MoE model loaded with vision weights accepts images
-   * in `messages` (the vision encoder handles prefill), while a
-   * plain text Qwen3.5 MoE checkpoint rejects them with a runtime
-   * error. A mid-session image change requires a fresh
-   * `chatSessionStart` call.
+   * Get the number of parameters in the model.
    *
-   * Requires `config.reuse_cache` to be enabled (the default).
+   * Pure config computation -- no model-thread dispatch needed.
    */
-  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  numParameters(): number;
   /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's cached
-   * KV state, then decodes the assistant reply. Stops on `<|im_end|>`
-   * so the cache remains on a clean boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`.
-   * Errors if the session is empty, carries image state, or if
-   * `config.reuse_cache` is explicitly set to `false`.
+   * Save the model weights and configuration to a directory.
    *
-   * `images` is an opt-in guard parameter: when non-empty, the native
-   * side returns an error whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can catch the prefix and route image-changes
-   * back through a fresh `chatSessionStart`.
+   * Dispatches to model thread.
    */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
+  saveModel(savePath: string): Promise<undefined>;
   /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a ChatML `<tool_response>`-wrapped delta from `content` and
-   * prefills it on top of the live session caches, then decodes the
-   * assistant reply. Stops on `<|im_end|>` so the cache stays on a
-   * clean boundary for the next turn.
-   *
-   * The `tool_call_id` is currently dropped by the wire format —
-   * Qwen3.5's chat template identifies tool responses by position +
-   * wrapper tags, not an explicit id. Callers may still log it for
-   * their own bookkeeping.
-   *
-   * Requires a live session started via `chatSessionStart`.
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
    */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
+  resetCaches(): void;
   /**
-   * Streaming variant of `chatSessionStart`.
+   * Start a new chat session.
    *
-   * Dispatches to the dedicated model thread. Behaviourally identical
-   * to `chatSessionStart` (resets caches, uses `<|im_end|>` as
-   * eos, inherits the same VLM-vs-text image-support contract) but
-   * streams token deltas through the JS callback instead of
-   * returning a `ChatResult`. Used by the TypeScript
-   * `ChatSession.sendStream()` for turn 1 of a multi-round streaming
-   * conversation.
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
    */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinue`.
-   *
-   * Appends a ChatML user/assistant delta on top of the live session
-   * caches and streams the decoded reply. Requires a live session
-   * started via `chatStreamSessionStart` (or the non-streaming
-   * `chatSessionStart`). Used by the TypeScript
-   * `ChatSession.sendStream()` for turns 2..N of a multi-round
-   * streaming conversation.
-   *
-   * `images` is an opt-in guard parameter: when non-empty, the
-   * streaming path emits an error chunk whose message begins with
-   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
-   * `ChatSession` layer can route image-changes through a fresh
-   * session start.
-   */
+  /** Streaming variant of `chatSessionContinue`. */
   chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Streaming variant of `chatSessionContinueTool`.
-   *
-   * Builds a ChatML tool-response delta on top of the live session
-   * caches and streams the decoded reply. Requires a live session
-   * started via `chatSessionStart` / `chatStreamSessionStart`.
-   */
+  /** Streaming variant of `chatSessionContinueTool`. */
   chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
+    messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /**
-   * Get the number of parameters in the model.
-   *
-   * Pure config computation -- no model-thread dispatch needed.
-   */
-  numParameters(): number;
-  /**
-   * Save the model weights and configuration to a directory.
-   *
-   * Dispatches to model thread.
-   */
-  saveModel(savePath: string): Promise<undefined>;
 }
 export type Qwen3_5MoeModel = Qwen35MoeModel;
 
@@ -1400,117 +1325,21 @@ export type Qwen3_5MoeModel = Qwen35MoeModel;
  */
 export declare class Qwen3Model {
   /**
-   * Reset the KV cache used for cache reuse across chat-session turns.
-   * Call this when starting a new conversation to ensure a full prefill.
-   */
-  resetCache(): void;
-  /**
-   * Initialize KV caches for incremental generation
-   *
-   * Creates one KV cache per transformer layer. Call this before starting generation.
-   */
-  initKvCaches(): void;
-  /**
-   * Reset all KV caches
-   *
-   * Clears cached key-value states. Call this between different generation sequences.
-   */
-  resetKvCaches(): void;
-  /**
-   * Get paged attention memory statistics (if enabled)
-   *
-   * Returns memory usage statistics for the paged KV cache.
-   */
-  pagedCacheStats(): PagedCacheStats | null;
-  /**
-   * Get scheduler statistics (if paged attention is enabled)
-   *
-   * Returns the number of waiting, running, and completed sequences.
-   */
-  schedulerStats(): SchedulerStatsNapi | null;
-  /**
-   * Forward pass with paged attention for memory-efficient inference.
-   *
-   * This method uses block-based KV cache management via Metal kernels for:
-   * - Variable-length sequences with efficient memory usage
-   * - Continuous batching with dynamic batch composition
-   * - Long context support beyond GPU memory limits
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs, shape: [num_seqs, 1] for decode
-   * * `slot_mapping` - Slot indices for cache updates, shape: [num_seqs]
-   * * `seq_ids` - Sequence IDs in the batch (for looking up block tables/context lens)
-   * * `positions` - Token positions for RoPE, shape: [num_seqs] (per-sequence positions)
-   *
-   * # Returns
-   * * Logits, shape: [num_seqs, 1, vocab_size] for decode
-   */
-  forwardPaged(inputIds: MxArray, slotMapping: MxArray, seqIds: Array<number>, positions: MxArray): MxArray;
-  /**
-   * Prefill a sequence using standard attention and write K/V to paged cache.
-   *
-   * This method should be called before `step_paged_generation()` for each
-   * new prompt. It runs the full forward pass using standard attention
-   * (which is faster for long sequences), then writes the K/V cache to
-   * the paged cache for subsequent decode steps.
-   *
-   * # Arguments
-   * * `prompt_tokens` - Token IDs for the prompt (as u32 array)
-   * * `seq_id` - Sequence ID (obtained from scheduler)
-   *
-   * # Returns
-   * * Logits for the last token, shape: [1, vocab_size]
-   */
-  prefillPaged(promptTokens: Array<number>, seqId: number): MxArray;
-  /**
-   * Add a request to the paged attention scheduler.
-   *
-   * The scheduler queues requests and allocates blocks for KV cache.
-   * Use `step_paged_generation()` to process the scheduled batch.
-   *
-   * Note: The actual sequence ID is assigned during scheduling, not when the
-   * request is added. Use the `request_id` to track your requests through
-   * the generation process.
-   *
-   * # Arguments
-   * * `request_id` - Unique identifier for the request (returned in outputs)
-   * * `prompt_tokens` - Token IDs for the prompt
-   * * `max_new_tokens` - Maximum new tokens to generate
-   * * `priority` - Optional priority (higher = scheduled first)
-   *
-   * # Returns
-   * * Number of pending requests in the queue
-   */
-  addPagedRequest(
-    requestId: string,
-    promptTokens: Array<number>,
-    maxNewTokens: number,
-    priority?: number | undefined | null,
-  ): number;
-  /**
-   * Schedule and execute one step of paged generation.
-   *
-   * This method:
-   * 1. Schedules the next batch of sequences
-   * 2. Runs forward pass with paged attention
-   * 3. Samples next tokens
-   * 4. Returns the generated tokens for each sequence
-   *
-   * # Arguments
-   * * `config` - Generation configuration (temperature, top_k, etc.)
-   *
-   * # Returns
-   * * `PagedGenerationStep` with token outputs for each sequence
-   */
-  stepPagedGeneration(config?: GenerationConfig | undefined | null): PagedGenerationStep | null;
-  /**
-   * Get completed sequences from the scheduler.
-   *
-   * Call this after `step_paged_generation()` returns outputs with `is_finished: true`.
-   */
-  getCompletedSequences(): Array<PagedCompletedSequence>;
-  /** Check if the scheduler has pending work. */
-  hasPagedWork(): boolean;
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Qwen3Inner::paged_adapter` was successfully constructed
+   * at load time (driven by `Qwen3Config::use_block_paged_cache`,
+   * defaulting to `true` for Qwen3 since paged-vs-flat parity has been
+   * verified). When `true`, the native cache reuses SYS blocks across
+   * `chatSessionStart` calls via content-addressing in
+   * `BlockAllocator`'s prefix-hash table — the JS-side warm slot in
+   * `SessionRegistry.getOrCreateWarmAny` becomes redundant and the
+   * `/v1/messages` server endpoint allocates a fresh `ChatSession` per
+   * request. See `packages/server/src/endpoints/messages.ts` for the
+   * runtime-routing decision.
+   */
+  hasBlockPagedCache(): boolean;
   /** Get model configuration */
   getConfig(): Qwen3Config;
   /**
@@ -1544,83 +1373,6 @@ export declare class Qwen3Model {
    * ```
    */
   generate(messages: Array<ChatMessage>, config?: GenerationConfig | undefined | null): Promise<GenerationResult>;
-  /**
-   * Reset all caches and clear cached token history. Exposed so
-   * tests and session-management code can start from a known clean
-   * state between turns.
-   */
-  resetCaches(): void;
-  /**
-   * Start a new chat session.
-   *
-   * Runs the full jinja chat template once, decodes until `<|im_end|>`,
-   * and leaves the KV caches on a clean ChatML boundary so subsequent
-   * `chatSessionContinue` / `chatSessionContinueTool` calls can
-   * append a raw delta on top without re-rendering the chat
-   * template.
-   *
-   * Requires `config.reuse_cache` to be enabled (the default).
-   */
-  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
-  /**
-   * Continue an existing chat session with a new user message.
-   *
-   * Appends a raw ChatML user/assistant delta to the session's
-   * cached KV state, then decodes the assistant reply. Stops on
-   * `<|im_end|>` so the cache remains on a clean boundary for the
-   * next turn.
-   *
-   * Requires a live session started via `chatSessionStart`. Errors
-   * if the session is empty, carries image state, or if
-   * `config.reuse_cache` is explicitly set to `false`.
-   *
-   * Qwen3 legacy is text-only; `images` is an opt-in guard parameter:
-   * when non-empty the native side returns an error whose message
-   * begins with `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the
-   * TypeScript `ChatSession` layer can catch the prefix and route
-   * image-changes back through a fresh `chatSessionStart` uniformly
-   * across all model backends.
-   */
-  chatSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null | undefined,
-  ): Promise<ChatResult>;
-  /**
-   * Continue an existing chat session with a tool-result turn.
-   *
-   * Builds a Qwen3.5-style `<tool_response>`-wrapped user-role delta
-   * from `content` and prefills it on top of the live session
-   * caches, then decodes the assistant reply. Stops on `<|im_end|>`
-   * so the cache stays on a clean boundary for the next turn.
-   *
-   * Requires a live session started via `chatSessionStart`.
-   */
-  chatSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config?: ChatConfig | undefined | null,
-  ): Promise<ChatResult>;
-  /** Streaming variant of `chatSessionStart`. */
-  chatStreamSessionStart(
-    messages: ChatMessage[],
-    config: ChatConfig | null,
-    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-  ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinue`. */
-  chatStreamSessionContinue(
-    userMessage: string,
-    images: Uint8Array[] | null | undefined,
-    config: ChatConfig | null,
-    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-  ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinueTool`. */
-  chatStreamSessionContinueTool(
-    toolCallId: string,
-    content: string,
-    config: ChatConfig | null,
-    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
-  ): Promise<ChatStreamHandle>;
   /**
    * Generate multiple completions for multiple prompts in batch
    *
@@ -1660,20 +1412,6 @@ export declare class Qwen3Model {
     groupSize: number,
     config?: GenerationConfig | undefined | null,
   ): Promise<BatchGenerationResult>;
-  /**
-   * Decode token IDs to text using the internal tokenizer
-   *
-   * Helper method for decoding generated tokens. The model must have been loaded
-   * via load() to have a tokenizer available.
-   *
-   * # Arguments
-   * * `token_ids` - Token IDs to decode as Uint32Array
-   * * `skip_special_tokens` - Whether to skip special tokens (default: true)
-   *
-   * # Returns
-   * * Decoded text string
-   */
-  decode(tokenIds: Uint32Array, skipSpecialTokens?: boolean | undefined | null): Promise<string>;
   /**
    * Apply chat template and encode to token IDs
    *
@@ -1695,6 +1433,51 @@ export declare class Qwen3Model {
     tools?: Array<ToolDefinition> | undefined | null,
     enableThinking?: boolean | undefined | null,
   ): Promise<Uint32Array>;
+  /**
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
+   */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
+   *
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
   /**
    * Load a pretrained model from disk
    *
@@ -1828,6 +1611,9 @@ export declare class Qwen3Tokenizer {
    * * `add_generation_prompt` - Whether to add assistant prompt at end (default: true)
    * * `tools` - Optional array of tool definitions for function calling
    * * `enable_thinking` - Optional flag to enable thinking mode (<think> tags)
+   * * `content_order` - Optional structured multimodal content ordering
+   * * `existing_image_placeholder` - Optional model marker that suppresses
+   *   synthetic image parts when it is already present in sanitized text
    *
    * # Returns
    * Encoded token IDs ready for model input
@@ -1853,6 +1639,8 @@ export declare class Qwen3Tokenizer {
     addGenerationPrompt?: boolean | undefined | null,
     tools?: Array<ToolDefinition> | undefined | null,
     enableThinking?: boolean | undefined | null,
+    contentOrder?: MultimodalContentOrder | undefined | null,
+    existingImagePlaceholder?: string | undefined | null,
   ): Promise<Uint32Array>;
   /** Get vocabulary size */
   vocabSize(): number;
@@ -2135,17 +1923,11 @@ export declare class TextRecModel {
   recognizeCrop(rgbData: Uint8Array, width: number, height: number): RecResult;
 }
 
-/** Result from VLM chat */
 export declare class VlmChatResult {
-  /** Get the response text */
   get text(): string;
-  /** Get the generated tokens */
   get tokens(): MxArray;
-  /** Get the log probabilities */
   get logprobs(): MxArray;
-  /** Get the finish reason */
   get finishReason(): 'stop' | 'length' | 'repetition';
-  /** Get the number of tokens generated */
   get numTokens(): number;
 }
 export type VLMChatResult = VlmChatResult;
@@ -2167,10 +1949,6 @@ export declare class VLModel {
    * for loading a model from disk.
    */
   constructor(config: ModelConfig);
-  /** Set the tokenizer */
-  setTokenizer(tokenizer: Qwen3Tokenizer): void;
-  /** Check if tokenizer is available */
-  get hasTokenizer(): boolean;
   /**
    * Chat with the VLM model
    *
@@ -2211,80 +1989,6 @@ export declare class VLModel {
    * ```
    */
   ocr(imageData: Buffer, prompt?: string | undefined | null): Promise<string>;
-  /**
-   * Get input embeddings with vision features merged
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs [batch, seq_len]
-   * * `pixel_values` - Optional image patches [batch, seq, channels, patch_h, patch_w]
-   * * `image_grid_thw` - Optional grid dimensions [num_images, 3]
-   *
-   * # Returns
-   * * Input embeddings with vision features inserted at image token positions
-   */
-  getInputEmbeddings(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-  ): MxArray;
-  /**
-   * Forward pass
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs [batch, seq_len]
-   * * `pixel_values` - Optional image patches
-   * * `image_grid_thw` - Optional grid dimensions
-   * * `mask` - Optional attention mask
-   *
-   * # Returns
-   * * Logits [batch, seq_len, vocab_size]
-   */
-  forward(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-    mask?: MxArray | undefined | null,
-  ): MxArray;
-  /**
-   * Generate text tokens given input tokens and optional image
-   *
-   * Uses KV caching for efficient generation.
-   *
-   * # Arguments
-   * * `input_ids` - Input token IDs [1, seq_len]
-   * * `pixel_values` - Optional image patches [1, num_patches, C, H, W]
-   * * `image_grid_thw` - Optional grid dimensions [1, 3]
-   * * `config` - Generation configuration
-   *
-   * # Returns
-   * * GenerationResult with tokens, logprobs, and finish reason
-   */
-  generate(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-    config?: GenerationConfig | undefined | null,
-  ): Promise<GenerationResult>;
-  /**
-   * Batch OCR: extract text from multiple images simultaneously
-   *
-   * Processes N images with sequential prefill + batched decode for ~N× decode throughput.
-   *
-   * # Arguments
-   * * `images` - Encoded image buffers
-   * * `config` - Optional chat configuration (shared across all items)
-   *
-   * # Returns
-   * * Vec of extracted text strings, one per image
-   *
-   * # Example
-   * ```typescript
-   * import { readFileSync } from 'fs';
-   * const images = ['page1.jpg', 'page2.jpg'].map(p => readFileSync(p));
-   * const texts = await model.ocrBatch(images);
-   * ```
-   */
-  ocrBatch(images: Array<Buffer>, config?: VlmChatConfig | undefined | null): Promise<Array<string>>;
   /**
    * Batch chat: process multiple items simultaneously
    *
@@ -2323,25 +2027,6 @@ export declare class VLModel {
    * ```
    */
   static load(modelPath: string): Promise<VLModel>;
-  /**
-   * Load model configuration from disk without loading weights
-   *
-   * This is useful for inspecting model configuration before loading the full model.
-   *
-   * # Arguments
-   * * `model_path` - Path to the model directory containing config.json
-   *
-   * # Returns
-   * * ModelConfig with vision and text configuration
-   *
-   * # Example
-   * ```typescript
-   * import { VLModel } from '@mlx-node/vlm';
-   * const config = await VLModel.loadConfig('./models/paddleocr-vl');
-   * console.log(config.visionConfig.hiddenSize);
-   * ```
-   */
-  static loadConfig(modelPath: string): Promise<ModelConfig>;
 }
 
 /**
@@ -2392,8 +2077,68 @@ export declare const enum BuiltinRewardType {
   JsonSchema = 'JsonSchema',
 }
 
+/**
+ * Data-free static FP8 activation-amax calibration over RAW-text PREFILL
+ * (NVIDIA modelopt `MaxCalibrator` parity), end to end in native code.
+ *
+ * The nvidia recipe covers BOTH `qwen3_5` (dense) and `qwen3_5_moe` (MoE), so
+ * this reads `<model_path>/config.json`'s `model_type` and dispatches to the
+ * matching loader + `CalibratePrefillRaw` command (any other `model_type` is a
+ * clear error). Both loaders are the SAME ones the inference session uses
+ * ([`persistence::load_with_thread`]) — the model is only usable on its
+ * dedicated model thread. Then:
+ *   1. dispatches `{Qwen35Cmd,Qwen35MoeCmd}::CalibratePrefillRaw`, which on the
+ *      model thread SELF-ARMS that thread's thread-local
+ *      [`ActivationAmaxCollector`] flag (RAII, AFTER load so no load-time eval
+ *      is recorded), tokenizes each `text` WITHOUT the chat template, truncates
+ *      to `calib_seq` tokens, and runs PREFILL ONLY (no generation) so every
+ *      mxfp8 attn/GDN projection's activation tap fires over realistic raw-text
+ *      activations, resetting caches between rows, then disarms on exit;
+ *   2. ONLY if the full loop succeeded — drains the per-tensor amax and
+ *      ATOMICALLY writes it into `<model_path>/config.json` (temp file +
+ *      `rename`).
+ *
+ * CONCURRENCY: the whole clear→prefill→take→write section is serialized by
+ * [`calib_guard`] (a process-wide `try_lock`); a second concurrent calibration
+ * fails fast with "another calibration is in progress". The arm flag is
+ * thread-local (so a concurrent inference model can't contaminate the run), but
+ * the running-max MAP is process-global, so serializing RUNS keeps two
+ * calibrations from interleaving `record`/`take` on it. The map is CLEARED at
+ * the very start so stale amax from a prior PANICKED run cannot leak into this
+ * write.
+ *
+ * On ANY error before the final write, the partial amax is discarded and
+ * `config.json` is left UNTOUCHED (a failed calibration must not mutate the
+ * live model in place). A run that prefilled ZERO rows (empty dataset, or every
+ * row tokenized to nothing) is likewise an ERROR that leaves `config.json`
+ * untouched — a no-op calibration must not report a silent success. Returns the
+ * number of projections calibrated (the count of collected amax entries); 0
+ * means a real prefill ran but the model exercised no activation-fp8 sites (not
+ * an nvidia-recipe checkpoint), and in that case `config.json` is left
+ * UNCHANGED (no rewrite).
+ */
+export declare function calibrateActivationAmaxRaw(
+  modelPath: string,
+  texts: Array<string>,
+  calibSeq: number,
+): Promise<number>;
+
 /** Unified chat configuration shared by all model variants (Qwen3, Qwen3.5, Qwen3.5 MoE). */
 export interface ChatConfig {
+  /**
+   * Internal logical cache owner. The agent provider forwards Pi's stable
+   * session id so model-global GDN sidecars can retain parent and child
+   * branches independently. This does not namespace the physical paged KV
+   * cache; exact token/extra-key hashes remain shareable across owners.
+   */
+  cacheOwnerId?: string | undefined;
+  /**
+   * Internal top-level owner for the bounded Qwen3.5 GDN sidecar store.
+   * `cache_owner_id` may identify a child Pi session; this separately
+   * identifies the current interactive root so /new and /resume can rotate
+   * the protected branch without changing PagedAttention cache identity.
+   */
+  cacheRootOwnerId?: string | undefined;
   maxNewTokens?: number | undefined;
   temperature?: number | undefined;
   topK?: number | undefined;
@@ -2417,11 +2162,11 @@ export interface ChatConfig {
   frequencyPenalty?: number | undefined;
   /** Number of recent tokens to consider for frequency penalty (default: 20) */
   frequencyContextSize?: number | undefined;
-  /** Max consecutive identical tokens before stopping (default: 16, 0 = disabled) */
+  /** Max consecutive identical tokens before stopping (default: 0 = disabled; opt in with a positive value) */
   maxConsecutiveTokens?: number | undefined;
-  /** Max n-gram repetitions before stopping (default: 3, 0 = disabled) */
+  /** Max n-gram repetitions before stopping (default: 0 = disabled; opt in with a positive value) */
   maxNgramRepeats?: number | undefined;
-  /** Max pattern size for n-gram repetition detection (default: 64) */
+  /** Max pattern size for n-gram repetition detection (default: 0 = disabled; opt in with a positive value) */
   ngramSize?: number | undefined;
   tools?: Array<ToolDefinition>;
   /**
@@ -2454,6 +2199,56 @@ export interface ChatConfig {
    * avoiding redundant computation for multi-turn conversations.
    */
   reuseCache?: boolean | undefined;
+  /**
+   * MTP: opt-in flag enabling the Multi-Token Prediction speculative decode
+   * loop (pure-Rust eager; qwen3.5 dense and MoE). Requires the model
+   * checkpoint to carry an MTP head (otherwise silently ignored). Default:
+   * `false`.
+   */
+  enableMtp?: boolean | undefined;
+  /**
+   * MTP: number of draft tokens per speculative cycle.
+   *
+   * On Qwen3.5 native MTP heads it is clamped to `[1, 5]` by the verify
+   * FFI contract, and when unset native code currently pins depth 1.
+   * When `mtpAdaptiveDepth` is `true`, this value is used as the
+   * throughput-policy seed and the expected-value policy's max depth.
+   * Adaptive depth is opt-in; set `mtpAdaptiveDepth: true` explicitly to
+   * enable it.
+   *
+   * Gemma4 external drafts (`draftModelPath`) resolve the field per draft
+   * variant instead (`gemma4/model.rs` `resolve_params`, always from the
+   * RAW config value — the engine's central `[1, 5]` clamp is an MTP-head
+   * contract that does not apply to external drafts):
+   * - DSpark: with both knobs unset, full draft blocks (the checkpoint's
+   *   block size — 7 tokens on `dspark_gemma4_12b_block7`) run behind a
+   *   short target-AR/DSpark break-even calibration. A short generation
+   *   budget that cannot finish calibration retains the fixed-block
+   *   schedule. An explicit
+   *   `mtpDepth` caps and pins the block unless `mtpAdaptiveDepth: true`
+   *   opts the guard back in; explicit `false` disables it.
+   * - Assistant (Google `gemma-4-*-it-assistant`): an unset `mtpDepth`
+   *   drafts 3 tokens per cycle (`ASSISTANT_DEFAULT_DEPTH`), and an
+   *   explicit `mtpDepth` clamps to `[1, 8]` (`ASSISTANT_MAX_DEPTH`).
+   *
+   * `mtpAdaptiveDepth` is ignored for the Gemma4 assistant variant.
+   */
+  mtpDepth?: number | undefined;
+  /**
+   * MTP: when true, the decode loop runs the adaptive
+   * depth policy. Default mode is a per-depth EMA hill-climb plus
+   * DFlash-style 3-state machine `full | reduced | probe`.
+   * `MLX_MTP_ADAPTIVE_DEPTH_MODE=expected-value` instead uses the
+   * MTPLX-style intra-cycle expected-value gate, which deepens toward
+   * `mtpDepth` by default (T=0 byte-parity verified); set
+   * `MLX_MTP_EV_ALLOW_DEEPEN=0` to pin the base depth.
+   * When false, the loop pins `mtpDepth` for every cycle.
+   *
+   * Default: false, except Gemma4 DSpark enables its measured break-even
+   * guard when both this field and `mtpDepth` are unset. An explicit value
+   * always wins over the family default.
+   */
+  mtpAdaptiveDepth?: boolean | undefined;
 }
 
 /** Chat message with tool calling support */
@@ -2466,10 +2261,34 @@ export interface ChatMessage {
   toolCalls?: Array<ToolCall>;
   /** Tool call ID this message is responding to (for tool messages) */
   toolCallId?: string;
+  /**
+   * Whether this tool-role message represents an errored tool result.
+   *
+   * Authoritative, structured signal of tool-call failure. Set to
+   * `Some(true)` when the caller (e.g. the Anthropic
+   * `tool_result.is_error === true` translator) wants the model to
+   * treat the tool output as an error. It is exposed to the model's
+   * chat template as `message.is_error`; Rust never rewrites `content`
+   * or invents a model-facing error marker.
+   */
+  isError?: boolean;
   /** Reasoning content for thinking mode (used with <think> tags) */
   reasoningContent?: string;
+  /**
+   * Thinking mode used when this assistant message was generated.
+   *
+   * This is replay provenance, not a request override. Gemma4's disabled-
+   * thinking generation prefix contains an explicit empty thought channel,
+   * while an enabled-thinking turn that emitted no reasoning contains no
+   * such channel. Keeping the historical mode on the message lets the chat
+   * template reproduce either byte sequence even when a later request
+   * changes its current thinking setting.
+   */
+  thinkingEnabled?: boolean;
   /** Image data for VLM models (encoded image bytes: PNG/JPEG, passed as Uint8Array/Buffer) */
   images?: Array<Uint8Array> | undefined;
+  /** Audio data for unified Gemma 4 (encoded audio bytes: WAV, passed as Uint8Array/Buffer) */
+  audio?: Array<Uint8Array> | undefined;
 }
 
 /** Unified chat result shared by all model variants (Qwen3, Qwen3.5, Qwen3.5 MoE). */
@@ -2477,24 +2296,45 @@ export interface ChatResult {
   text: string;
   toolCalls: Array<ToolCallResult>;
   thinking?: string;
+  /**
+   * Effective `enable_thinking` boolean passed to the model-provided
+   * chat template for this turn. This is replay provenance and is
+   * intentionally distinct from the family's decode-time
+   * [`ThinkingSetup`](crate::engine::ThinkingSetup).
+   */
+  thinkingEnabled: boolean;
   numTokens: number;
   promptTokens: number;
   reasoningTokens: number;
   finishReason: string;
   rawText: string;
+  /**
+   * Reasoning-redacted raw output computed from the same token-aware
+   * boundary as `raw_text`. Session wrappers may request full reasoning
+   * internally for deterministic replay, then expose this safe view to a
+   * caller that set `includeReasoning: false`.
+   */
+  publicRawText?: string | undefined;
+  /**
+   * Number of prompt tokens served from the reused KV-cache prefix.
+   *
+   * When the native prefix-cache machinery successfully matches the new
+   * prompt against the cached conversation history (via
+   * `verify_cache_prefix_direct`), only the trailing delta is re-prefilled
+   * and this field reports the length of the reused prefix. `0` when
+   * the cache was missed or disabled and the full prompt had to be
+   * re-prefilled.
+   */
+  cachedTokens: number;
   /** Performance metrics (present when `reportPerformance: true` in config) */
   performance?: PerformanceMetrics;
 }
 
-/** Chat message role (lowercase values matching standard convention) */
+/** Chat message role (lowercase values matching standard convention). */
 export declare const enum ChatRole {
-  /** User message */
   User = 'user',
-  /** Assistant response */
   Assistant = 'assistant',
-  /** System prompt */
   System = 'system',
-  /** Tool response */
   Tool = 'tool',
 }
 
@@ -2505,10 +2345,36 @@ export interface ChatStreamChunk {
   finishReason?: string;
   toolCalls?: Array<ToolCallResult>;
   thinking?: string;
+  /**
+   * Effective template `enable_thinking` value. Present on the terminal
+   * chunk only; incremental text/reasoning chunks leave it unset.
+   */
+  thinkingEnabled?: boolean | undefined;
   numTokens?: number;
   promptTokens?: number;
   reasoningTokens?: number;
   rawText?: string;
+  /** Reasoning-redacted counterpart to `raw_text` on terminal chunks. */
+  publicRawText?: string | undefined;
+  /**
+   * Whether terminal `text` is the authoritative parsed assistant content.
+   * Generic emitters set true; Gemma streams visible content exclusively as
+   * deltas and set false so session history commits the accumulated text.
+   */
+  textAuthoritative?: boolean | undefined;
+  /**
+   * Number of prompt tokens served from the reused KV-cache prefix on
+   * this turn. Populated on the terminal chunk (`done == true`) only;
+   * `None` on mid-stream delta chunks.
+   *
+   * Zero on a cache miss or disabled reuse; equal to the matched
+   * prefix length on a hit. Mirrors `ChatResult.cached_tokens`
+   * verbatim so session-aware streaming consumers can observe
+   * prefix-cache reuse without round-tripping to the non-streaming
+   * path. Non-terminal chunks always carry `None` — only the
+   * terminal chunk is authoritative.
+   */
+  cachedTokens?: number | undefined;
   /** Performance metrics (only present in the final chunk when `reportPerformance: true`) */
   performance?: PerformanceMetrics;
   /**
@@ -2531,16 +2397,181 @@ export interface ClassifyRotateResult {
   image: Uint8Array;
 }
 
-/** Statistics about cleanup operations (NAPI wrapper) */
-export interface CleanupStats {
-  /** Number of training steps deleted */
-  stepsDeleted: number;
-  /** Number of generations deleted */
-  generationsDeleted: number;
-  /** Number of tool calls deleted */
-  toolCallsDeleted: number;
-  /** Number of logs deleted */
-  logsDeleted: number;
+/** Statistics about cleanup operations (NAPI wrapper) */
+export interface CleanupStats {
+  /** Number of training steps deleted */
+  stepsDeleted: number;
+  /** Number of generations deleted */
+  generationsDeleted: number;
+  /** Number of tool calls deleted */
+  toolCallsDeleted: number;
+  /** Number of logs deleted */
+  logsDeleted: number;
+}
+
+/**
+ * Flush every accepted cold-tier block to disk, blocking until the
+ * background writer has fsync+renamed each write enqueued before this call,
+ * or `timeout_ms` elapses. Returns `true` when the drain completed — or when
+ * the tier was never opened (nothing to flush) — and `false` on timeout.
+ *
+ * Called from the agent's one-shot (`mlx agent -p`) shutdown so a prompt's
+ * just-persisted prefix blocks reach the drive before the process exits,
+ * rather than being abandoned in the write queue.
+ *
+ * The payload flush is `fsync(2)`, not `F_FULLFSYNC`: a drained block
+ * survives process death and kernel panic, but a sudden power loss can leave
+ * it torn. Torn objects fail the payload checksum on the next read and are
+ * pruned as a miss, so the cost is a recomputed prefix, never wrong state.
+ */
+export declare function coldCacheDrain(timeoutMs: number): boolean;
+
+/**
+ * Return a snapshot of the process-wide cold tier. Read-only: never opens
+ * the tier itself, so it reports `enabled: false` until inference first
+ * initializes the tier.
+ *
+ * The source snapshot is DESTRUCTURED rather than field-accessed, so a
+ * counter added to `ColdCacheStats` and forgotten here fails to compile.
+ * The failure this guards is silent and has already happened twice: a native
+ * counter that never reaches this struct reaches no JS consumer either, and
+ * nothing downstream can tell "the counter is zero" from "the counter was
+ * never carried across".
+ */
+export declare function coldCacheStats(): ColdCacheStats;
+
+/**
+ * Snapshot of the process-wide SSD cold tier for paged prefix blocks.
+ * Counters are cumulative since the tier was opened; all numeric values
+ * are returned as `f64` to avoid BigInt round-trips in JS.
+ */
+export interface ColdCacheStats {
+  /**
+   * `false` until the tier is first opened by inference, or when opening
+   * failed (fail-open: inference then runs without persistence).
+   */
+  enabled: boolean;
+  /** Cache root directory (empty while disabled). */
+  root: string;
+  /** Disk quota in bytes. */
+  quotaBytes: number;
+  /** Blocks restored from disk after validation. */
+  hits: number;
+  /** Lookups that found no usable block (includes corrupt entries). */
+  misses: number;
+  /**
+   * Objects accepted onto the background write queue — K/V blocks and
+   * family state sidecars alike, since both take a slot in the same queue.
+   * `coldSidecarEnqueued` counts a subset of this; never sum them.
+   */
+  enqueued: number;
+  /**
+   * Writes REFUSED at admission because the bounded queue was full. Same
+   * object scope as `enqueued`. Disjoint from `writeErrors`, which counts
+   * accepted writes that then failed to land — never sum the two into one
+   * "lost writes" number.
+   */
+  queueDrops: number;
+  /**
+   * Bytes that LANDED, credited after the payload sync, the commit rename
+   * and the directory fsync all succeeded. Not an enqueue-time estimate:
+   * a failed write credits nothing here and one `writeErrors` instead.
+   */
+  bytesWritten: number;
+  /** Total bytes read back on validated hits. */
+  bytesRestored: number;
+  /** Entries evicted to respect the quota / free-space reserve. */
+  evictions: number;
+  /** Entries that failed checksum/identity validation and were removed. */
+  corruptions: number;
+  /**
+   * Writes the queue accepted that never reached disk — a read-only, full
+   * or unmounted cache root, a failed rename, a failed fsync. The writer is
+   * fail-open and reports the error to nobody, so without this a cache that
+   * stores nothing at all still looks perfectly healthy.
+   */
+  writeErrors: number;
+  /**
+   * Restores refused before any block was looked up. Neither a hit nor a
+   * miss — so a refused restore reads as `0/0`, exactly like a turn that
+   * never consulted the tier.
+   */
+  restoreDeclines: number;
+}
+
+/**
+ * The native cold-restore allowlist, exposed so a test can assert it agrees
+ * exactly with the TypeScript `COLD_TIER_RESTORE_FAMILIES` set.
+ */
+export declare function coldRestoreFamilies(): Array<string>;
+
+/**
+ * Return the process-wide sidecar counters. Unlike [`cold_cache_stats`] this
+ * never consults the tier at all, so it is valid before any inference has run
+ * and reports honestly even when the tier failed to open.
+ *
+ * The plain-Rust [`cold_sidecar_telemetry`] stays as it is: the parity harness
+ * and the in-crate tests destructure `ColdSidecarTelemetry`, and a napi
+ * `#[napi(object)]` return type cannot serve both.
+ */
+export declare function coldSidecarStats(): ColdSidecarStats;
+
+/**
+ * Snapshot of [`ColdSidecarTelemetry`] for JS. Counters are cumulative since
+ * process start; all values are `f64` to avoid BigInt round-trips.
+ *
+ * Separate from [`ColdCacheStatsJs`] because this one isolates SIDECARS — the
+ * recurrent and sliding-window state that lives outside the pool — while that
+ * one is scoped to the write queue as a whole. Both structs carry an
+ * `enqueued` and a `queue_drops`, and they are NOT disjoint: a sidecar
+ * admission bumps both, so these are a subset of those and summing them
+ * double-counts. The JS side keeps them apart by prefix (`coldEnqueued` vs
+ * `coldSidecarEnqueued`); read the sidecar pair when you need "did the family
+ * state persist?", the block pair when you need "is the writer keeping up?".
+ */
+export interface ColdSidecarStats {
+  /**
+   * Turns that reached a family's sidecar capture at all. Every other
+   * counter here is a sub-count of this one, so `captureReached == 0`
+   * separates "the finalize path never calls the capture" from "the capture
+   * ran and declined".
+   */
+  captureReached: number;
+  /**
+   * Turns whose persisted K/V chain covered no whole block, so there was no
+   * prefix to anchor recurrent state under.
+   */
+  chainEmpty: number;
+  /**
+   * Turns whose chain covered blocks but where no retained checkpoint sat at
+   * or below its reach.
+   */
+  boundarySkips: number;
+  /**
+   * Turns that selected a boundary already on disk — nothing written, and
+   * nothing needed to be. The steady state of a repeated prompt, and the
+   * only thing that tells a healthy run from a collapsed ladder.
+   */
+  alreadyPersisted: number;
+  /** Sidecars handed to the bounded writer queue. */
+  enqueued: number;
+  /** Sidecars the bounded writer queue refused because it was full. */
+  queueDrops: number;
+  /**
+   * Restored sidecars a family actually INSTALLED as its live per-turn
+   * state. The one read-side counter, and the only signal that separates
+   * "restored and used" from "restored and silently re-derived by a full
+   * O(prefix) replay" — every other counter, and text parity itself, is
+   * satisfied by the replay.
+   */
+  installed: number;
+  /**
+   * Restores a family THREW AWAY after the walk served them, restarting the
+   * turn cold. Unlike `ColdCacheStats.restoreDeclines` this one comes AFTER
+   * real `coldHits` and `coldBytesRestored`, so the turn looks like it
+   * reused a prefix right up to the point where it recomputed all of it.
+   */
+  restoreSuppressed: number;
 }
 
 /**
@@ -2579,7 +2610,11 @@ export interface ConversionOptions {
   quantBits?: number;
   /** Quantization group size (default: 64 for affine, 32 for mxfp8) */
   quantGroupSize?: number;
-  /** Quantization mode: "affine" (default) or "mxfp8" */
+  /**
+   * Quantization mode: "affine" (default), "mxfp4", "mxfp8", "nvfp4", or
+   * "sym8" (per-output-channel symmetric int8; qwen3_5 + qwen3_5_moe + lfm2/lfm2_moe + gemma4,
+   * implies bits=8, no group_size — consciously NOT mlx-lm-loadable)
+   */
   quantMode?: string;
   /**
    * Quantization recipe for per-layer mixed-bit quantization.
@@ -2591,6 +2626,35 @@ export interface ConversionOptions {
    * Improves quantization quality by amplifying important weight channels.
    */
   imatrixPath?: string;
+  /**
+   * Upgrade quantization to micro-scaling FP (mxfp4 / mxfp8).
+   * When true, applies after the recipe predicate: eligible 8-bit affine
+   * decisions become mxfp8 and 4-bit become mxfp4. Kept affine (not upgraded):
+   * affine-only loaders (lm_head, embed_tokens, router.proj,
+   * embedding_projection) at their recipe bits, MoE router gates (8-bit affine),
+   * and the recipe-pinned attention/GDN projections (o_proj / out_proj /
+   * in_proj_a / in_proj_b, 8-bit affine). Requires `quant_mode = "affine"`.
+   * Forces `group_size = 32` for upgraded layers.
+   */
+  quantMxfp?: boolean;
+  /**
+   * Optional Qwen MTP quantization policy: "off" (default), "cyankiwi", "all",
+   * or "split" (alias "drafter").
+   * "cyankiwi" keeps mtp.fc dense and quantizes only the MTP layer linears as
+   * 4-bit affine group_size=32. For dense `qwen3_5` the quantized linears are
+   * emitted into an MTPLX-compatible mtp.safetensors sidecar; for MoE
+   * (`qwen3_5_moe`) there is no sidecar — they are quantized in place and stored
+   * inline in the main safetensors shards.
+   * "all" additionally quantizes mtp.fc. For dense `qwen3_5` the quantized MTP
+   * linears land in the mtp.safetensors sidecar; for MoE (`qwen3_5_moe`) there
+   * is no sidecar — they are quantized in place and stored inline in the main
+   * safetensors shards.
+   * "split"/"drafter" emits a body checkpoint with NO mtp.* tensors plus a
+   * separate `mtp-drafter/` directory in mlx-vlm's `qwen3_5_mtp` format
+   * (bare-keyed MTP head, format:mlx). It does NOT require --quantize/--q-recipe;
+   * the body may be bf16 or already-quantized and the MTP head stays bf16.
+   */
+  quantMtp?: string;
 }
 
 export interface ConversionResult {
@@ -2662,11 +2726,11 @@ export declare function createRandomQwen35Checkpoint(config: Qwen35Config, saveP
 /**
  * Create a random-init Qwen3.5 MoE model and save it to disk.
  *
- * Spawns a dedicated `ModelThread<Qwen35MoeCmd>` whose init builds a fresh
- * random-weight `Qwen35MoeInner` directly, then dispatches
- * `Qwen35MoeCmd::SaveModel` on that thread. The thread is dropped at the end
- * of the promise, so the in-memory model is released once the checkpoint has
- * been written. Used by TypeScript test fixtures that need an on-disk
+ * Spawns a dedicated model thread whose init runs
+ * [`create_random_qwen35_moe_checkpoint_sync`] (random-init inner + save);
+ * the thread holds no state and is dropped once the promise resolves, so
+ * the in-memory model is released as soon as the checkpoint has been
+ * written. Used by TypeScript test fixtures that need an on-disk
  * checkpoint without keeping a NAPI model instance alive.
  */
 export declare function createRandomQwen35MoeCheckpoint(config: Qwen35MoeConfig, savePath: string): Promise<undefined>;
@@ -2717,6 +2781,8 @@ export declare const enum DType {
   BFloat16 = 3,
   Uint32 = 4,
   Uint8 = 5,
+  /** Signed int8 — sym8 per-output-channel symmetric quantized weights. */
+  Int8 = 6,
 }
 
 /** Document element type */
@@ -2809,6 +2875,26 @@ export interface FunctionParameters {
   required?: Array<string>;
 }
 
+/**
+ * How many GDN prefix checkpoints the native store holds across all owners
+ * ([`GDN_PREFIX_CHECKPOINT_LIMIT`]), exposed for the same reason
+ * [`cold_restore_families`] is: it is one half of a cross-language invariant
+ * and nothing else carries it over the boundary.
+ *
+ * The other half is `MAX_CONCURRENCY` in
+ * `packages/agent/src/extensions/subagent.ts`. The store's demand is
+ * `MAX_CONCURRENCY + 1` — one owner per concurrent child loop plus the root
+ * session — and the cliff sits exactly one owner past the cap, where every
+ * owner holds a single entry and the store is still over it, so each publish
+ * takes somebody's last checkpoint. `retention_sim` measures that as 0 blind
+ * turns at five owners and 28 of 40 at six.
+ *
+ * No Rust gate can see a TypeScript-only edit, so raising the fleet alone
+ * would land in that regime with every Rust gate still green.
+ * `packages/agent/__test__/gdn-checkpoint-capacity.test.ts` is what stops it.
+ */
+export declare function gdnPrefixCheckpointLimit(): number;
+
 /**
  * Gemma 4 model configuration (dense variant).
  *
@@ -2843,6 +2929,20 @@ export interface Gemma4Config {
   /** Head dimension for global layers. If None, uses head_dim. */
   globalHeadDim?: number;
   attentionKEqV: boolean;
+  /**
+   * True for the unified multimodal Gemma 4 checkpoint
+   * (`model_type == "gemma4_unified"` or
+   * `architectures[0] == "Gemma4UnifiedForConditionalGeneration"`).
+   * The text decoder is shared, but the unified checkpoint carries
+   * vision/audio embedder weights that must be dropped in a text-only load.
+   */
+  isUnified: boolean;
+  /**
+   * `text_config.use_bidirectional_attention` from the unified checkpoint
+   * (e.g. `"vision"`). Parsed for a stable struct surface; the text-only
+   * decode path does not consume it.
+   */
+  useBidirectionalAttention?: string;
   finalLogitSoftcapping?: number;
   perLayerInputEmbeds: boolean;
   hiddenSizePerLayerInput?: number;
@@ -2861,10 +2961,97 @@ export interface Gemma4Config {
   topKExperts?: number;
   moeIntermediateSize?: number;
   visionConfig?: Gemma4VisionConfig;
+  /**
+   * Encoder-free vision config for the unified multimodal checkpoint.
+   * `Some` only when `is_unified` and the checkpoint carries a
+   * `vision_config` sub-dict. Disjoint from `vision_config` (the SigLIP
+   * path) — the unified vision embedder is built from this instead.
+   */
+  unifiedVisionConfig?: UnifiedVisionConfig;
   imageTokenId?: number;
   boiTokenId?: number;
   eoiTokenId?: number;
   visionSoftTokensPerImage?: number;
+  /**
+   * True when the checkpoint declares an `audio_config` sub-dict. Parallels
+   * `unified_vision_config.is_some()`; gates the un-drop + load of
+   * `embed_audio` weights and the audio merge path.
+   */
+  hasAudio: boolean;
+  /**
+   * Audio placeholder token id (258881). Each `<audio>` placeholder expands to
+   * `boa + audio_token × n_frames + eoa`.
+   */
+  audioTokenId?: number;
+  /** Begin-of-audio token id (256000), emitted before the audio token run. */
+  boaTokenId?: number;
+  /**
+   * End-of-audio token id, parsed from the config's `eoa_token_index` (258883).
+   * A real appended token (like `eoi`), despite the "index" name.
+   */
+  eoaTokenId?: number;
+  /**
+   * Raw audio samples per audio token (640 = 40 ms @ 16 kHz), from
+   * `audio_config.audio_samples_per_token`. Frame size for the encoder-free
+   * pad+reshape feature extractor.
+   */
+  audioSamplesPerToken?: number;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: auto-sized to cover `max_position_embeddings` for the
+   * physical full-attention layers.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the new block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * When `Some(true)` or unset (the default), `Gemma4Inner` builds
+   * model-independent KV-cache specs, groups them, and allocates a
+   * `BlockAllocator` + `LayerKVPool` pair for physical full-attention
+   * layers. Sliding-window layers still use `RotatingKVCache` until
+   * true paged sliding-window groups are wired. KV-shared layers are
+   * aliases: they reuse their anchor's cache slot and do not allocate
+   * separate physical storage.
+   *
+   * Default: `true` (paged adapter on; opt-out via
+   * `use_block_paged_cache: false` in `config.json` to use the flat
+   * (non-paged) all-`Gemma4LayerCache` path instead). Parity between
+   * the two paths is verified by
+   * `crates/mlx-core/tests/gemma4_paged_vs_flat_parity.rs` against
+   * real Gemma-4-E2B weights.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist full paged KV blocks — and gemma4's out-of-pool sliding-window
+   * state, as a cold-tier sidecar — to the SSD cold tier so warm prefixes
+   * survive process restarts. Off unless explicitly enabled.
+   *
+   * An EXPLICIT value here is authoritative and beats the ambient
+   * `MLX_PERSIST_PAGED_CACHE` default (`cold_tier::resolve_persist_cold`).
+   */
+  persistPagedCache?: boolean | undefined;
+}
+
+/** Optional load-time settings for [`Gemma4Model::load`]. */
+export interface Gemma4LoadOptions {
+  /**
+   * Directory of a draft checkpoint (config.json + safetensors) to load
+   * alongside the target model for speculative decoding — either a
+   * DSpark draft or a Google assistant draft; the kind is probed from
+   * the draft config.json. When omitted, `<model_path>/draft/` is loaded
+   * automatically when present. Draft decoding runs only on the flat
+   * KV-cache path: setting this while the model config explicitly enables
+   * `use_block_paged_cache` is a hard load error, and an unset
+   * `use_block_paged_cache` is forced to `false`.
+   */
+  draftModelPath?: string;
 }
 
 /**
@@ -2937,19 +3124,19 @@ export interface GenerationConfig {
   /** Number of recent tokens to consider for frequency penalty (default: 20) */
   frequencyContextSize?: number;
   /**
-   * Stop if same token repeats this many times consecutively (default: 16)
-   * Set to 0 to disable. Prevents OOM from degenerate repetitive generation.
+   * Stop if same token repeats this many times consecutively (default: 0 = disabled).
+   * Opt in by setting a positive value to guard against degenerate repetitive generation.
    */
   maxConsecutiveTokens?: number;
   /**
-   * Stop if a pattern repeats this many times consecutively (default: 3)
-   * Set to 0 to disable. Detects patterns like "A B A B A B".
+   * Stop if a pattern repeats this many times consecutively (default: 0 = disabled).
+   * Opt in with a positive value to detect patterns like "A B A B A B".
    * Uses range-based detection: checks all pattern sizes from 2 to ngram_size.
    */
   maxNgramRepeats?: number;
   /**
-   * Maximum pattern size for repetition detection (default: 64)
-   * All pattern sizes from 2 up to this value are checked each decode step.
+   * Maximum pattern size for repetition detection (default: 0 = disabled).
+   * When enabled, all pattern sizes from 2 up to this value are checked each decode step.
    * Larger values catch long phrase-level repetition common in small models.
    */
   ngramSize?: number;
@@ -2964,29 +3151,6 @@ export interface GenerationConfig {
    * Set to 0 to disable chunking and process the entire prompt at once.
    */
   prefillStepSize?: number;
-  /**
-   * KV cache quantization bits (default: 16 = no quantization)
-   * - 16: Full precision (bfloat16/float16), no quantization
-   * - 8: 8-bit quantization, ~2x memory savings, minimal quality loss
-   * - 4: 4-bit quantization, ~4x memory savings, some quality degradation
-   *
-   * Quantized KV cache is useful for long sequences where memory becomes a bottleneck.
-   * Note: Adds dequantization overhead per forward pass.
-   */
-  kvCacheBits?: number;
-  /**
-   * KV cache quantization group size (default: 64)
-   * Number of elements per quantization group. Smaller groups = better accuracy
-   * but more overhead from storing scales/biases.
-   * Only used when kv_cache_bits is 4 or 8.
-   */
-  kvCacheGroupSize?: number;
-  /**
-   * Number of draft tokens to generate speculatively (default: 5)
-   * Only used when a draft model is provided for speculative decoding.
-   * Higher values can increase throughput but may reduce acceptance rate.
-   */
-  numDraftTokens?: number;
 }
 
 export interface GenerationProfile {
@@ -3010,6 +3174,24 @@ export interface GenerationProfile {
   timeToFirstTokenMs: number;
   /** Per-phase breakdown. */
   phases: Array<PhaseProfile>;
+  /**
+   * MTP speculative decode: mean accepted *draft* tokens per cycle
+   * (excludes the always-verified token). Historical drafts-only metric.
+   */
+  mtpMeanAcceptedTokens?: number;
+  /**
+   * MTP speculative decode: mean *committed* tokens per cycle, INCLUDING
+   * the always-verified token (`mtp_accepted_drafts_total / mtp_cycles
+   * + 1.0`). mlx-vlm-comparable headline; equals mlx-vlm's
+   * `(accepted_drafts + rounds) / rounds` (`common.py:247`).
+   */
+  mtpMeanAcceptedTokensTotal?: number;
+  /** MTP speculative decode: per-draft-position acceptance rate. */
+  mtpAcceptanceByPosition?: Array<number>;
+  /** MTP speculative decode: number of draft+verify cycles executed. */
+  mtpCycles?: number;
+  /** MTP speculative decode: mean attempted draft depth per cycle. */
+  mtpMeanDepth?: number;
   /** Memory snapshot before generation. */
   memoryBefore?: MemorySnapshot;
   /** Memory snapshot after generation. */
@@ -3036,8 +3218,8 @@ export interface GenerationWithToolCalls {
   toolCalls: Array<ToolCallRecord>;
 }
 
-/** Get expected weight keys for PaddleOCR-VL model */
-export declare function getExpectedWeightKeys(): Array<string>;
+/** Sample MLX's GPU memory counters. See [`GpuMemorySnapshot`]. */
+export declare function getMemorySnapshot(): GpuMemorySnapshot;
 
 /** Retrieve all collected profiling data as a `ProfilingSession`. */
 export declare function getProfilingData(): ProfilingSession;
@@ -3047,6 +3229,13 @@ export interface GgufConversionOptions {
   inputPath: string;
   /** Output directory for converted SafeTensors model */
   outputDir: string;
+  /**
+   * Optional directory containing the authoritative HuggingFace config and
+   * tokenizer/processor assets. GGUF metadata is not rich enough to recreate
+   * unified Gemma4 config fields such as head_dim, layer_types, vision, and
+   * audio configuration exactly.
+   */
+  configSourceDir?: string;
   /** Target dtype: "float32", "float16", "bfloat16" (default: keep original) */
   dtype?: string;
   /** Enable verbose logging */
@@ -3080,6 +3269,25 @@ export interface GgufConversionOptions {
    * This makes the safetensors compatible with mlx-vlm.
    */
   vlmKeyPrefix?: boolean;
+  /**
+   * Upgrade quantization to micro-scaling FP (mxfp4 / mxfp8).
+   * When true, applies after the recipe predicate: eligible 8-bit affine
+   * decisions become mxfp8 and 4-bit become mxfp4. Kept affine (not upgraded):
+   * affine-only loaders (lm_head, embed_tokens, router.proj,
+   * embedding_projection) at their recipe bits, MoE router gates (8-bit affine),
+   * and the recipe-pinned attention/GDN projections (o_proj / out_proj /
+   * in_proj_a / in_proj_b, 8-bit affine). Requires `quant_mode = "affine"`.
+   * Forces `group_size = 32` for upgraded layers.
+   */
+  quantMxfp?: boolean;
+  /**
+   * Import ggml Q4_K / Q5_K / Q6_K tensors as MLX K-quant arrays instead of
+   * rejecting them (default: false). The blocks are repacked, never
+   * dequantized, so the output keeps the source file's weights and byte size.
+   * With this off, Q6_K remains the Gemma4 token-embedding BF16 fallback and
+   * Q4_K / Q5_K are an error.
+   */
+  importKQuants?: boolean;
 }
 
 export interface GgufConversionResult {
@@ -3095,6 +3303,33 @@ export interface GpuInfo {
   architectureGen: number;
 }
 
+/**
+ * Snapshot of MLX's GPU memory counters at this instant. All values
+ * are in bytes. On Apple Silicon, GPU and CPU share unified memory,
+ * so these are NOT a separate "VRAM" pool — they reflect MLX's own
+ * tracking of `StorageModePrivate` Metal buffers (model weights,
+ * `LayerKVPool`, transient intermediate tensors) attributed to the
+ * MLX runtime in this process.
+ *
+ * Useful for live observability during long-running sessions:
+ *
+ * ```js
+ * const { getMemorySnapshot } = require('@mlx-node/core');
+ * setInterval(() => {
+ *   const m = getMemorySnapshot();
+ *   console.log(`active=${(m.activeBytes/1e9).toFixed(2)}GB peak=${(m.peakBytes/1e9).toFixed(2)}GB cache=${(m.cacheBytes/1e9).toFixed(2)}GB`);
+ * }, 1000);
+ * ```
+ */
+export interface GpuMemorySnapshot {
+  /** Current actively-used GPU buffer bytes (excludes cache pool). */
+  activeBytes: number;
+  /** Peak GPU buffer bytes since the last `resetPeakMemory()` call. */
+  peakBytes: number;
+  /** Bytes held in MLX's caching allocator (released by `clearCache`). */
+  cacheBytes: number;
+}
+
 /** Configuration for the GRPO training engine */
 export interface GrpoEngineConfig {
   /** Learning rate (default: 1e-6) */
@@ -3356,6 +3591,69 @@ export interface Lfm2Config {
   eosTokenId: number;
   bosTokenId: number;
   padTokenId: number;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 2048 (2GB).
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the new block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * Default: `true` since 2026-04-28 (parity-verified via
+   * `crates/mlx-core/tests/lfm2_paged_vs_flat_parity.rs` against real
+   * LFM2.5-1.2B weights: byte-equal greedy decode + prefix-reuse
+   * byte-equal at BF16). Wired through
+   * `Lfm2DecoderLayer::forward_paged_or_flat`.
+   *
+   * Per-layer routing: LFM2's hybrid architecture means only
+   * `full_attention` layers go through the paged adapter; conv layers
+   * stay on the existing flat `Lfm2LayerCache::Conv(ArraysCache)`
+   * storage regardless of this flag. The `LayerKVPool` is sized to
+   * the count of `full_attention` layers and indexed by
+   * attention-ordinal (via `config.full_attn_idxs()`), not by absolute
+   * layer index.
+   *
+   * Opt out with `use_block_paged_cache: Some(false)` to revert to the
+   * fully flat `Lfm2LayerCache` path on all layers.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * MLP intermediate size for the DENSE-in-MoE layers (`layer_idx <
+   * num_dense_layers`). Used DIRECTLY (no 2/3 `computed_ff_dim()` shrink).
+   * Only present on MoE checkpoints.
+   */
+  intermediateSize?: number | undefined;
+  /** Per-expert MLP intermediate size for the sparse MoE layers. */
+  moeIntermediateSize?: number | undefined;
+  /** Total number of routed experts. */
+  numExperts?: number | undefined;
+  /** Top-k experts selected per token. */
+  numExpertsPerTok?: number | undefined;
+  /** Number of leading DENSE layers before MoE layers begin. */
+  numDenseLayers?: number | undefined;
+  /**
+   * Renormalize the top-k routing weights to sum to 1 (`/(sum+1e-20)`).
+   *
+   * `Option<bool>` so TS callers may omit it (napi renders bare `bool` as
+   * required). Absent (None) is read as `true` everywhere via
+   * `.unwrap_or(true)`, matching the prior `default = "default_true"`.
+   */
+  normTopkProb?: boolean | undefined;
+  /**
+   * Add the learned per-expert bias to the post-softmax gates BEFORE top-k.
+   *
+   * `Option<bool>` so TS callers may omit it (napi renders bare `bool` as
+   * required). Absent (None) is read as `true` everywhere via
+   * `.unwrap_or(true)`, matching the prior `default = "default_true"`.
+   */
+  useExpertBias?: boolean | undefined;
 }
 
 export interface MemorySnapshot {
@@ -3367,6 +3665,28 @@ export interface MemorySnapshot {
   cacheBytes: number;
 }
 
+/**
+ * Return a snapshot of the MLX allocator's memory counters. Primarily
+ * useful for dashboards and for debugging the `MLX_CACHE_LIMIT_GB`
+ * override. Read-only — does not mutate allocator state.
+ */
+export declare function memoryStats(): MemoryStats;
+
+/**
+ * Snapshot of the MLX Metal allocator's memory state. All values are in
+ * bytes and returned as `f64` to avoid forcing BigInt round-trips in JS.
+ */
+export interface MemoryStats {
+  /** Actively-used memory (excludes the cached free-pool). */
+  active: number;
+  /** Peak memory usage since load / the last `resetPeakMemory`. */
+  peak: number;
+  /** Cache / free-pool memory currently held by the allocator. */
+  cache: number;
+  /** Metal `max_recommended_working_set_size` snapshot (0 on non-Metal). */
+  wiredLimit: number;
+}
+
 /** Full model configuration */
 export interface ModelConfig {
   visionConfig: VisionConfig;
@@ -3380,6 +3700,21 @@ export interface ModelConfig {
   eosTokenId: number;
 }
 
+/**
+ * Ordering policy for structured multimodal content parts handed to a
+ * checkpoint-provided Jinja template.
+ *
+ * The default preserves the generic serializer's existing text-before-media
+ * behavior. PaddleOCR-VL and Qianfan-OCR were trained with image placeholders
+ * before the instruction and opt into
+ * [`MultimodalContentOrder::ImagesThenText`] at their adapter boundaries.
+ * Audio remains after text in both modes.
+ */
+export declare const enum MultimodalContentOrder {
+  TextThenMedia = 'textThenMedia',
+  ImagesThenText = 'imagesThenText',
+}
+
 /** Result from document orientation classification. */
 export interface OrientationResult {
   /** Detected rotation angle (0, 90, 180, or 270 degrees) */
@@ -3410,56 +3745,6 @@ export interface OutputStoreConfig {
   localPath: string;
 }
 
-/** Paged attention memory statistics (NAPI-compatible) */
-export interface PagedCacheStats {
-  /** Total number of blocks in the pool */
-  totalBlocks: number;
-  /** Number of free blocks */
-  freeBlocks: number;
-  /** Number of allocated blocks */
-  allocatedBlocks: number;
-  /** Total memory in MB */
-  totalMemoryMb: number;
-  /** Used memory in MB */
-  usedMemoryMb: number;
-  /** Utilization percentage */
-  utilizationPercent: number;
-}
-
-/** A completed sequence from paged generation */
-export interface PagedCompletedSequence {
-  /** Original request ID */
-  requestId: string;
-  /** All generated tokens (excluding prompt) */
-  tokens: Array<number>;
-  /** Reason for completion ("stop", "length", "repetition", "tool_calls") */
-  finishReason: string;
-}
-
-/** Result of a paged generation step */
-export interface PagedGenerationStep {
-  /** Token outputs for each sequence in the batch */
-  outputs: Array<PagedTokenOutput>;
-  /** Number of sequences that were in prefill phase */
-  numPrefill: number;
-  /** Number of sequences that were in decode phase */
-  numDecode: number;
-}
-
-/** Output from a single token generation step in paged attention */
-export interface PagedTokenOutput {
-  /** Sequence ID in the scheduler */
-  seqId: number;
-  /** Request ID for this sequence */
-  requestId: string;
-  /** Generated token ID */
-  token: number;
-  /** Log probability of the token (f64 for NAPI compatibility) */
-  logprob: number;
-  /** Whether this sequence has finished */
-  isFinished: boolean;
-}
-
 /** A text paragraph */
 export interface Paragraph {
   content: string;
@@ -3541,6 +3826,52 @@ export interface PerformanceMetrics {
    * Excludes the first token (counted as prefill).
    */
   decodeTokensPerSecond: number;
+  /**
+   * MTP speculative decode: mean accepted *draft* tokens per cycle
+   * (range `[0, depth]`). EXCLUDES the always-verified token each cycle
+   * commits. `None` on plain autoregressive runs where no MTP cycle
+   * executed. This is the historical drafts-only metric; for the
+   * mlx-vlm-comparable headline see [`Self::mtp_mean_accepted_tokens_total`].
+   */
+  mtpMeanAcceptedTokens?: number;
+  /**
+   * MTP speculative decode: mean *committed* tokens per cycle, INCLUDING
+   * the single always-verified token each cycle emits — i.e.
+   * `mtp_accepted_drafts_total / mtp_cycles + 1.0`. This is the
+   * mlx-vlm-comparable headline accept rate: it equals mlx-vlm's
+   * `mean_accepted_tokens = (accepted_drafts + rounds) / rounds`
+   * (`mlx-vlm/mlx_vlm/speculative/common.py:247`), where our
+   * `mtp_cycles` is the 1:1 analog of mlx-vlm's `rounds` (one
+   * draft+verify iteration; `record_mtp_cycle` is called exactly once
+   * per cycle). The per-cycle `+1.0` matches mlx-vlm's `+rounds`
+   * assumption — every round commits exactly one verified token
+   * (the residual on partial-accept, the bonus on full-accept), even
+   * when the final cycle's tail is EOS/length-truncated downstream
+   * (mlx-vlm makes the same assumption: it appends to `accept_lens`
+   * once per round regardless of truncation). `None` on plain
+   * autoregressive runs.
+   */
+  mtpMeanAcceptedTokensTotal?: number;
+  /**
+   * MTP speculative decode: per-draft-position acceptance rate
+   * (index = draft position). `None` on plain autoregressive runs.
+   */
+  mtpAcceptanceByPosition?: Array<number>;
+  /**
+   * MTP speculative decode: number of draft+verify cycles executed.
+   * `None` on plain autoregressive runs.
+   */
+  mtpCycles?: number;
+  /**
+   * MTP speculative decode: mean attempted draft depth per cycle.
+   * `None` on plain autoregressive runs.
+   */
+  mtpMeanDepth?: number;
+  /**
+   * Optional decode phase breakdown. Present when decode profiling
+   * is enabled via `MLX_PROFILE_DECODE=1` or `setProfilingEnabled(true)`.
+   */
+  profilePhases?: Array<PhaseProfile>;
 }
 
 export interface PhaseProfile {
@@ -3554,6 +3885,76 @@ export interface PhaseProfile {
   count: number;
 }
 
+/**
+ * Per-call Viterbi calibration overrides.
+ *
+ * Any field set to `Some(_)` overrides the corresponding bias from the
+ * model's default calibration (loaded from `viterbi_calibration.json`
+ * at load time). Missing fields fall back to the default.
+ */
+export interface PrivacyCalibration {
+  transitionBiasBackgroundStay?: number;
+  transitionBiasBackgroundToStart?: number;
+  transitionBiasEndToBackground?: number;
+  transitionBiasEndToStart?: number;
+  transitionBiasInsideToContinue?: number;
+  transitionBiasInsideToEnd?: number;
+}
+
+/**
+ * Options for [`PrivacyFilterModelJs::classify`].
+ *
+ * - `threshold` (default `0.5`): minimum mean per-token probability for
+ *   an extracted span to be returned.
+ * - `calibration`: per-call overrides on top of the checkpoint default.
+ * - `return_tokens` (default `false`): when `true`, the result includes
+ *   a `tokens` array with one entry per input token.
+ */
+export interface PrivacyClassifyOptions {
+  threshold?: number;
+  calibration?: PrivacyCalibration;
+  returnTokens?: boolean;
+}
+
+/** Result of [`PrivacyFilterModelJs::classify`]. */
+export interface PrivacyClassifyResult {
+  entities: Array<PrivacyEntity>;
+  tokens?: Array<PrivacyToken>;
+}
+
+/**
+ * A privacy entity detected by [`PrivacyFilterModelJs::classify`].
+ *
+ * `start`/`end` are byte offsets into the input string (Hugging Face
+ * `tokenizers` convention). `label` is the privacy class without the
+ * BIOES prefix (e.g. `"private_email"`). `score` is the mean — across
+ * the span's tokens — of the softmax probability of the Viterbi-emitted
+ * tag at each token.
+ */
+export interface PrivacyEntity {
+  label: string;
+  start: number;
+  end: number;
+  score: number;
+  text: string;
+}
+
+/**
+ * Per-token output emitted when [`PrivacyClassifyOptions::return_tokens`]
+ * is `true`. `tag` is the full BIOES tag (`"O"` or `"B-..."`/`"I-..."`/
+ * `"E-..."`/`"S-..."`) chosen by the Viterbi decoder. `score` is the
+ * softmax probability of that emitted tag at this token, so `tag` and
+ * `score` always share decoders (at boundary tokens the Viterbi tag can
+ * differ from the local argmax).
+ */
+export interface PrivacyToken {
+  text: string;
+  tag: string;
+  score: number;
+  start: number;
+  end: number;
+}
+
 export interface ProfilingSession {
   /** GPU hardware info. */
   gpuInfo: GpuInfo;
@@ -3601,6 +4002,32 @@ export interface QianfanOcrConfig {
   minDynamicPatch: number;
 }
 
+/** Microbench result for the production quantized qmv dispatch path. */
+export interface QmvQuantizedMicrobenchResult {
+  /** Median `quantized_matmul` wall-clock per call, in nanoseconds. */
+  medianNs: number;
+  /** A tiny materialized checksum of the final output, used to keep the call live. */
+  checksum: number;
+}
+
+/**
+ * Run the production quantized-qmv microbench in the current process.
+ *
+ * To compare `MLX_MTP_SMALL_M_QMV=0` versus `1`, call this from separate
+ * processes. MLX caches the env-backed dispatch predicate statically.
+ */
+export declare function quantizedQmvMicrobench(
+  k: number,
+  n: number,
+  m: number,
+  groupSize: number,
+  bits: number,
+  mode: string,
+  dtype: DType,
+  warmup?: number | undefined | null,
+  iters?: number | undefined | null,
+): QmvQuantizedMicrobenchResult;
+
 /**
  * Qwen3.5 model configuration (dense variant).
  *
@@ -3629,6 +4056,79 @@ export interface Qwen35Config {
   fullAttentionInterval: number;
   partialRotaryFactor: number;
   ropeTheta: number;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: automatically sized for one full-context sequence.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the block-paged KV cache adapter (`PagedKVCacheAdapter`) for
+   * full-attention layers.
+   *
+   * **OPT-IN — experimental.** When `Some(true)`, `Qwen35Inner`
+   * allocates a `BlockAllocator` + `LayerKVPool` pair sized for the
+   * model's full-attention layer count and constructs a
+   * `PagedKVCacheAdapter`. The chat-session forward dispatch routes
+   * full-attention layers through this adapter while linear-attention
+   * (GatedDeltaNet / GDN) layers continue to use the existing
+   * `Qwen3_5LayerCache::Linear(ArraysCache)` path with no
+   * cross-request prefix reuse — vLLM's `MambaManager`-style "no
+   * prefix reuse for recurrent layers" stance.
+   *
+   * **Paged vs flat eager**: this flag selects the eager paged decode
+   * over the eager flat decode. When `Some(true)`, full-attention
+   * layers run through the paged adapter (cross-request prefix reuse);
+   * when unset, they run the eager flat decode. Either way the forward
+   * is pure-Rust eager.
+   *
+   * **VLM under paged**: a VLM checkpoint defaults this flag ON at load, so
+   * dense image turns ONLY run on the paged-vision core. A fresh single-turn
+   * image-bearing prompt prefills through the paged adapter (M-RoPE positions
+   * feed the rotary; the merged vision embeddings feed the forward) and
+   * decodes plain AR — MTP weights are ignored on image turns. Warm
+   * image-bearing session continues / cache-hit reuse are still rejected at
+   * runtime (the GDN two-pass warm prefix is not byte-exact). A vision turn
+   * that reaches a None adapter (explicit `Some(false)`, non-Metal build, or
+   * a sym8 checkpoint) errors at dispatch.
+   *
+   * Default: `None` for text-only checkpoints (eager flat decode);
+   * `Some(true)` for VLM checkpoints (block-paged, set in `parse_config`).
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist the out-of-pool GDN recurrent state (and the paged KV blocks it
+   * gates) to the SSD cold tier so warm prefixes survive process restarts.
+   * Off unless explicitly enabled. See `crate::models::qwen3_5::gdn_sidecar`
+   * and `crate::cold_tier::resolve_persist_cold`.
+   */
+  persistPagedCache?: boolean | undefined;
+  /**
+   * Number of MTP (Multi-Token Prediction) head layers shipped with the
+   * checkpoint. Populated from `mtp_num_hidden_layers` /
+   * `num_nextn_predict_layers` in `config.json`. `0` means the
+   * checkpoint has no MTP heads and the speculative-decode path is
+   * unavailable.
+   */
+  nMtpLayers: number;
+}
+
+/**
+ * Trained and physically available active-context limits for one loaded
+ * Qwen3.5 model. Values are snapshots because the physical pool is fixed for
+ * the lifetime of the resident model.
+ */
+export interface Qwen35ContextLimits {
+  trainedWindowTokens: number;
+  effectiveWindowTokens: number;
+  pagedBlockCapacity: number;
+  pagedBlockSize: number;
 }
 
 /** Generation configuration for Qwen3.5 */
@@ -3683,6 +4183,55 @@ export interface Qwen35MoeConfig {
   moeIntermediateSize?: number | undefined;
   normTopkProb: boolean;
   mlpOnlyLayers?: number[] | undefined;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: automatically sized for one full-context sequence.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the block-paged KV cache adapter for full-attention layers.
+   *
+   * **OPT-IN — experimental.** Same semantics as the dense
+   * `Qwen3_5Config::use_block_paged_cache` field. Selects the eager
+   * paged decode over the eager flat decode: routes full-attention
+   * layers through `PagedKVCacheAdapter` (cross-request prefix reuse);
+   * GDN linear-attention layers stay on `Qwen3_5LayerCache::Linear`
+   * either way. When disabled, full-attention layers run the eager flat
+   * decode instead.
+   *
+   * **VLM under paged**: a VLM checkpoint loads with this flag set, and a
+   * fresh single-turn image-bearing prompt prefills through the paged
+   * adapter (M-RoPE positions feed the rotary; the merged vision embeddings
+   * feed the forward). Image-bearing MTP turns are still rejected at
+   * runtime; warm image-bearing session continues / cache-hit reuse are
+   * cold-started (no warm GDN two-pass prefix).
+   *
+   * Default: `None` / `false`.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist the out-of-pool GDN recurrent state (and the paged KV blocks it
+   * gates) to the SSD cold tier so warm prefixes survive process restarts.
+   * Off unless explicitly enabled. Shares the dense qwen3_5 GDN sidecar codec
+   * (`crate::models::qwen3_5::gdn_sidecar`) via `to_dense_config`; the
+   * precedence rules live in `crate::cold_tier::resolve_persist_cold`.
+   */
+  persistPagedCache?: boolean | undefined;
+  /**
+   * Number of MTP (Multi-Token Prediction) head layers shipped with
+   * the checkpoint. Populated from `mtp_num_hidden_layers` /
+   * `num_nextn_predict_layers` in `config.json`. `0` means the
+   * checkpoint has no MTP heads and the speculative-decode path is
+   * unavailable.
+   */
+  nMtpLayers: number;
 }
 
 /** Generation configuration for Qwen3.5 MoE */
@@ -3719,29 +4268,34 @@ export interface Qwen3Config {
   padTokenId: number;
   eosTokenId: number;
   bosTokenId: number;
-  /**
-   * Enable paged attention for memory-efficient inference.
-   * Default: false (use standard KVCache)
-   */
-  usePagedAttention?: boolean | undefined;
   /**
    * GPU memory budget for paged KV cache in megabytes.
-   * Only used when use_paged_attention is true.
    * Default: 2048 (2GB)
    */
   pagedCacheMemoryMb?: number | undefined;
   /**
    * Block size for paged attention (tokens per block).
-   * Only used when use_paged_attention is true.
    * Default: 16
    */
   pagedBlockSize?: number | undefined;
   /**
-   * Use FP8 cache for 2x memory reduction (experimental).
-   * Only used when use_paged_attention is true.
-   * Default: false
+   * Use the block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * When `Some(true)` (the default for Qwen3), `Qwen3Inner` allocates a
+   * `BlockAllocator` + `LayerKVPool` pair and constructs a
+   * `PagedKVCacheAdapter` for cross-request KV prefix reuse (vLLM-style
+   * block-paged storage with refcounted prefix caching). When
+   * `Some(false)`, the flat (non-paged) `Vec<KVCache>` cache path is
+   * used instead.
+   *
+   * Default: true.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist full paged KV blocks to the SSD cold tier so warm prefixes
+   * survive process restarts. Off unless explicitly enabled.
    */
-  useFp8Cache?: boolean | undefined;
+  persistPagedCache?: boolean | undefined;
 }
 
 /** Qwen3 language model configuration */
@@ -3768,6 +4322,14 @@ export interface RecResult {
   score: number;
 }
 
+/**
+ * Reset MLX's peak-memory counter to the current active level.
+ * Useful for measuring per-request peak memory in a long-running
+ * process — call before a request, sample
+ * `getMemorySnapshot().peakBytes` after.
+ */
+export declare function resetPeakMemory(): void;
+
 /** Clear all collected profiling data and reset session timer. */
 export declare function resetProfilingData(): void;
 
@@ -3857,22 +4419,6 @@ export interface SamplingConfig {
  */
 export declare function saveToXlsx(text: string, filePath: string): void;
 
-/** Scheduler statistics (NAPI-compatible) */
-export interface SchedulerStatsNapi {
-  /** Number of requests waiting to be scheduled */
-  numWaiting: number;
-  /** Number of sequences currently running */
-  numRunning: number;
-  /** Number of completed sequences */
-  numCompleted: number;
-  /** Number of sequences in prefill phase */
-  numPrefill: number;
-  /** Number of sequences in decode phase */
-  numDecode: number;
-  /** Total tokens across all running sequences */
-  totalRunningTokens: number;
-}
-
 /** Enable or disable profiling globally. */
 export declare function setProfilingEnabled(enabled: boolean): void;
 
@@ -4155,6 +4701,35 @@ export interface TrainStepResultWithOutputs {
   completionLengths: Array<number>;
 }
 
+/**
+ * Encoder-free vision configuration for the Gemma 4 unified multimodal model.
+ *
+ * Parsed from the `vision_config` sub-dict of a `gemma4_unified` checkpoint
+ * (`model_type == "gemma4_unified_vision"`). This is a different shape from the
+ * SigLIP-style [`super::vision_config::Gemma4VisionConfig`] used by the dense
+ * gemma4 family: the unified vision path has no transformer encoder, only a
+ * patch embedder (LayerNorm + Linear + 2D positional embedding) feeding the
+ * multimodal projection.
+ */
+export interface UnifiedVisionConfig {
+  /** Pixel side length of a single image patch (48 = patch_size 16 × pooling 3). */
+  modelPatchSize: number;
+  /** Embedding width inside the vision embedder (3840, == text hidden_size). */
+  mmEmbedDim: number;
+  /** Number of rows in the 2D positional-embedding table (1120). */
+  mmPosembSize: number;
+  /** Maximum soft tokens (patches) per image after resize (280). */
+  numSoftTokens: number;
+  /** Output projection width of `embed_vision` (3840, == text hidden_size). */
+  outputProjDims: number;
+  /** Pixel-grid patch size used by the resize math (16). */
+  patchSize: number;
+  /** Pooling kernel size used by the resize math (3). */
+  poolingKernelSize: number;
+  /** Epsilon for the embedder LayerNorms and the projection RMSNorm. */
+  rmsNormEps: number;
+}
+
 /** Result from document unwarping. */
 export interface UnwarpResult {
   /** Unwarped image as PNG bytes */
@@ -4177,50 +4752,55 @@ export interface VisionConfig {
   spatialMergeSize: number;
 }
 
-/** A batch item for VLM batch inference */
 export interface VlmBatchItem {
-  /** Chat messages for this item */
   messages: Array<VlmChatMessage>;
-  /** Encoded image buffers for this item (one image per item for OCR) */
   images?: Array<Buffer>;
 }
 
-/** Configuration for VLM chat */
 export interface VlmChatConfig {
-  /** Encoded image buffers to process (PNG/JPEG bytes) */
   images?: Array<Buffer>;
-  /** Maximum number of new tokens to generate (default: 512) */
   maxNewTokens?: number;
-  /** Sampling temperature (0 = greedy, higher = more random) (default: 0.0 for OCR) */
   temperature?: number;
-  /** Top-k sampling (default: 0) */
   topK?: number;
-  /** Top-p (nucleus) sampling (default: 1.0) */
   topP?: number;
-  /** Repetition penalty (default: 1.5) */
   repetitionPenalty?: number;
-  /**
-   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
-   * token that appeared at least once in context. Matches OpenAI API semantics.
-   */
   presencePenalty?: number;
-  /** Number of recent tokens to consider for presence penalty (default: 20) */
   presenceContextSize?: number;
-  /**
-   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
-   * logits of each token in context. Matches OpenAI API semantics.
-   */
   frequencyPenalty?: number;
-  /** Number of recent tokens to consider for frequency penalty (default: 20) */
   frequencyContextSize?: number;
-  /** Whether to return log probabilities (default: false) */
   returnLogprobs?: boolean;
 }
 
-/** A chat message with optional image */
+/**
+ * A chat message with textual content. Images are supplied through
+ * [`VLMChatConfig`] and attached to the first user content part before the
+ * model template is rendered.
+ */
 export interface VlmChatMessage {
-  /** Role of the message sender */
   role: ChatRole;
-  /** Text content of the message */
   content: string;
 }
+
+export declare namespace __internal__ {
+  /**
+   * Drain the MLX allocator's free-pool.
+   *
+   * @internal
+   *
+   * This is a process-wide drain routed through MLX's default-stream
+   * `mlx_synchronize()`, which does NOT wait on the custom generation
+   * streams that the per-model threads run on. Calling this from user
+   * code while a decode is in flight can race live Metal command buffers
+   * and risk use-after-free. The only safe caller today is
+   * `@mlx-node/server`'s idle sweeper, which only triggers after the
+   * in-flight request counter has returned to zero.
+   *
+   * Exposed under the `__internal__` NAPI namespace — reachable as
+   * `require('@mlx-node/core').__internal__.clearCache()` and NOT on
+   * the root `require('@mlx-node/core')` object. The namespace prefix
+   * is a deliberate speed-bump that forces any caller to acknowledge
+   * this is a private drain with custom-stream caveats; the root
+   * surface stays clean of the footgun.
+   */
+  export function clearCache(): void;
+}