@mlx-node/core 0.0.7 → 0.0.8

package/index.d.cts

@@ -119,81 +119,125 @@ 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.
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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.
    */
   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.
+   * Appends a raw user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
    *
-   * 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
+   * `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.
+   * `ChatSession` layer can route image-changes back through a
+   * fresh `chatSessionStart`.
    */
   chatSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: 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.
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
    *
-   * Requires a live session started via `chatSessionStart`.
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
    */
   chatSessionContinueTool(
     toolCallId: string,
     content: string,
     config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
   ): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
@@ -205,15 +249,24 @@ export declare class Gemma4Model {
   chatStreamSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinueTool`. */
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
   chatStreamSessionContinueTool(
     toolCallId: string,
     content: string,
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 
@@ -471,68 +524,78 @@ 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).
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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.
    */
   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`.
+   * Appends a raw user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
    *
-   * 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.
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
    */
   chatSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
   ): 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`.
- */
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
   chatSessionContinueTool(
     toolCallId: string,
     content: string,
     config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
   ): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
@@ -544,20 +607,25 @@ export declare class Lfm2Model {
   chatStreamSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinueTool`. */
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
   chatStreamSessionContinueTool(
     toolCallId: string,
     content: string,
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
-  /** Get the model configuration. */
-  getConfig(): Lfm2Config;
-  /** Estimated number of model parameters. */
-  numParameters(): number;
 }
 
 export declare class MxArray {
@@ -681,9 +749,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 +1020,43 @@ export declare class OutputStore {
 }
 
 /**
- * Opaque handle to KV cache state from a chat-session turn.
+ * NAPI-exported view of [`PrivacyFilterModel`].
  *
- * 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.
- *
- * 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 +1072,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()`. */
@@ -1034,10 +1138,19 @@ export declare class QianfanOCRModel {
    * 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.
+   *
+   * `audio` exists only to keep this method's positional ABI aligned
+   * with the shared chat surface every other family exposes (the
+   * `chat_napi_surface!` macro inserts `audio` between `images` and
+   * `config`). Qianfan-OCR has no audio support, so a non-empty
+   * `audio` is rejected at the boundary with the shared no-audio
+   * error; `None` / empty is a complete no-op and audio is never
+   * threaded into the model thread.
    */
   chatSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
   ): Promise<ChatResult>;
   /**
@@ -1048,12 +1161,20 @@ export declare class QianfanOCRModel {
    * decodes the model reply. Stops on `<|im_end|>` so the cache stays
    * on a clean turn boundary for the next turn.
    *
+   * `is_error` is the structured tool-error signal. When `Some(true)`,
+   * the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * `<tool_response>` wrapper so the model receives a clear text-level
+   * cue. `None` / `Some(false)` keep the wire bytes byte-equal to the
+   * pre-feature output.
+   *
    * Requires a live session started via `chatSessionStart`.
    */
   chatSessionContinueTool(
     toolCallId: string,
     content: string,
     config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
   ): Promise<ChatResult>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
@@ -1061,19 +1182,35 @@ export declare class QianfanOCRModel {
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinue`. */
+  /**
+   * Streaming variant of `chatSessionContinue`.
+   *
+   * `audio` mirrors the non-streaming entry point: it exists only to
+   * keep the positional ABI aligned with the shared chat surface, and
+   * a non-empty value is rejected at the boundary with the shared
+   * no-audio error. `None` / empty is a complete no-op.
+   */
   chatStreamSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Streaming variant of `chatSessionContinueTool`. */
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * `<tool_response>` wrapper.
+   */
   chatStreamSessionContinueTool(
     toolCallId: string,
     content: string,
     config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
   ): Promise<ChatStreamHandle>;
 }
 
@@ -1085,27 +1222,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.
+   *
+   * `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.
    *
-   * 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.
+   * 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.
    *
@@ -1117,131 +1282,100 @@ export declare class Qwen35Model {
   static load(path: string): Promise<Qwen35Model>;
   /** Generate text from a prompt token sequence. */
   generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
+  /**
+   * 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>;
+  /**
+   * 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 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.
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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.
    */
   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`.
+   * Appends a raw user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
    *
-   * `images` is an opt-in guard parameter: when non-empty, the native
-   * side returns an error whose message begins with
+   * `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`.
+   * `ChatSession` layer can route image-changes back through a
+   * fresh `chatSessionStart`.
    */
   chatSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
   ): Promise<ChatResult>;
   /**
    * 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.
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
    *
-   * 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`.
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
    */
   chatSessionContinueTool(
     toolCallId: string,
     content: string,
     config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
   ): Promise<ChatResult>;
-  /**
-   * Streaming variant of `chatSessionStart`.
-   *
-   * 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.
-   */
+  /** 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,
+    audio: Uint8Array[] | null | undefined,
     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`.
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
    */
   chatStreamSessionContinueTool(
     toolCallId: string,
     content: string,
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
   ): 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 +1387,147 @@ 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.
+   * Get the number of parameters in the model.
    *
-   * 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.
+   * Pure config computation -- no model-thread dispatch needed.
+   */
+  numParameters(): number;
+  /**
+   * Save the model weights and configuration to a directory.
    *
-   * 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.
+   * Dispatches to model thread.
+   */
+  saveModel(savePath: string): Promise<undefined>;
+  /**
+   * 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.
    *
-   * Requires `config.reuse_cache` to be enabled (the default).
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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.
    */
   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`.
+   * Appends a raw user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
    *
-   * `images` is an opt-in guard parameter: when non-empty, the native
-   * side returns an error whose message begins with
+   * `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`.
+   * `ChatSession` layer can route image-changes back through a
+   * fresh `chatSessionStart`.
    */
   chatSessionContinue(
     userMessage: string,
     images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
     config: ChatConfig | null | undefined,
   ): Promise<ChatResult>;
   /**
    * 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.
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
    *
-   * Requires a live session started via `chatSessionStart`.
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
    */
   chatSessionContinueTool(
     toolCallId: string,
     content: string,
     config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
   ): Promise<ChatResult>;
-  /**
-   * Streaming variant of `chatSessionStart`.
-   *
-   * 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.
-   */
+  /** 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,
+    audio: Uint8Array[] | null | undefined,
     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`.
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
    */
   chatStreamSessionContinueTool(
     toolCallId: string,
     content: string,
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
   ): 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 +1539,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 +1587,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 +1626,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 +1647,88 @@ 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.
+   *
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
   /**
    * Load a pretrained model from disk
    *
@@ -2167,124 +2201,46 @@ 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
-   *
-   * High-level API for conversational interaction with images.
-   *
-   * # Arguments
-   * * `messages` - Chat messages (role + content)
-   * * `config` - Chat configuration (including images for automatic processing)
-   *
-   * # Returns
-   * * VLMChatResult with generated text
-   *
-   * # Example
-   * ```typescript
-   * const result = await model.chat(
-   *   [{ role: 'user', content: 'Describe this image.' }],
-   *   { images: [readFileSync('./photo.jpg')], maxNewTokens: 256 }
-   * );
-   * ```
-   */
-  chat(messages: Array<VlmChatMessage>, config?: VlmChatConfig | undefined | null): Promise<VlmChatResult>;
-  /**
-   * Simple OCR: extract text from encoded image bytes
-   *
-   * Convenience method that processes an image and extracts all text.
-   *
-   * # Arguments
-   * * `image_data` - Encoded image bytes (PNG/JPEG)
-   * * `prompt` - Optional custom prompt (default: "Extract all text from this image.")
-   *
-   * # Returns
-   * * Extracted text as a string
-   *
-   * # Example
-   * ```typescript
-   * const text = await model.ocr(imageBuffer);
-   * console.log(text);
-   * ```
-   */
-  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
+   * Chat with the VLM model
    *
-   * Uses KV caching for efficient generation.
+   * High-level API for conversational interaction with images.
    *
    * # 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
+   * * `messages` - Chat messages (role + content)
+   * * `config` - Chat configuration (including images for automatic processing)
    *
    * # Returns
-   * * GenerationResult with tokens, logprobs, and finish reason
+   * * VLMChatResult with generated text
+   *
+   * # Example
+   * ```typescript
+   * const result = await model.chat(
+   *   [{ role: 'user', content: 'Describe this image.' }],
+   *   { images: [readFileSync('./photo.jpg')], maxNewTokens: 256 }
+   * );
+   * ```
    */
-  generate(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-    config?: GenerationConfig | undefined | null,
-  ): Promise<GenerationResult>;
+  chat(messages: Array<VlmChatMessage>, config?: VlmChatConfig | undefined | null): Promise<VlmChatResult>;
   /**
-   * Batch OCR: extract text from multiple images simultaneously
+   * Simple OCR: extract text from encoded image bytes
    *
-   * Processes N images with sequential prefill + batched decode for ~N× decode throughput.
+   * Convenience method that processes an image and extracts all text.
    *
    * # Arguments
-   * * `images` - Encoded image buffers
-   * * `config` - Optional chat configuration (shared across all items)
+   * * `image_data` - Encoded image bytes (PNG/JPEG)
+   * * `prompt` - Optional custom prompt (default: "Extract all text from this image.")
    *
    * # Returns
-   * * Vec of extracted text strings, one per image
+   * * Extracted text as a string
    *
    * # Example
    * ```typescript
-   * import { readFileSync } from 'fs';
-   * const images = ['page1.jpg', 'page2.jpg'].map(p => readFileSync(p));
-   * const texts = await model.ocrBatch(images);
+   * const text = await model.ocr(imageBuffer);
+   * console.log(text);
    * ```
    */
-  ocrBatch(images: Array<Buffer>, config?: VlmChatConfig | undefined | null): Promise<Array<string>>;
+  ocr(imageData: Buffer, prompt?: string | undefined | null): Promise<string>;
   /**
    * Batch chat: process multiple items simultaneously
    *
@@ -2323,25 +2279,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 +2329,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 +2414,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 +2451,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 +2513,40 @@ 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. The renderer prepends a short
+   * `[tool error]` prefix to `content` when emitting the wire-format
+   * tool response so the model receives a clear text-level cue, but
+   * the original `content` stays byte-for-byte intact in the
+   * structured form — no JSON wrapping, no in-band marker that could
+   * collide with a successful tool result whose literal content
+   * happens to start with the same prefix.
+   *
+   * `None` / `Some(false)` produce the unmarked wire format.
+   */
+  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). */
@@ -2482,6 +2559,17 @@ export interface ChatResult {
   reasoningTokens: number;
   finishReason: string;
   rawText: string;
+  /**
+   * 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;
 }
@@ -2509,6 +2597,19 @@ export interface ChatStreamChunk {
   promptTokens?: number;
   reasoningTokens?: number;
   rawText?: string;
+  /**
+   * 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;
   /**
@@ -2579,7 +2680,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 +2696,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 +2796,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 +2851,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 */
@@ -2843,6 +2979,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 +3011,88 @@ 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;
+}
+
+/** 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 +3165,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 +3192,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 +3215,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 +3259,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 +3270,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 +3310,17 @@ 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;
 }
 
 export interface GgufConversionResult {
@@ -3095,6 +3336,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 +3624,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 +3698,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;
@@ -3410,56 +3763,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 +3844,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 +3903,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 +4020,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 +4074,72 @@ 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;
+  /**
+   * 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 +4194,47 @@ 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;
+  /**
+   * 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 +4271,29 @@ 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.
    */
-  useFp8Cache?: boolean | undefined;
+  useBlockPagedCache?: boolean | undefined;
 }
 
 /** Qwen3 language model configuration */
@@ -3768,6 +4320,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 +4417,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 +4699,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 */
@@ -4224,3 +4797,27 @@ export interface VlmChatMessage {
   /** 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;
+}