@mlx-node/core 0.0.9 → 0.0.12

package/index.d.cts

@@ -26,6 +26,34 @@ export declare class BatchGenerationResult {
   get groupSize(): number;
 }
 
+/**
+ * In-flight non-streaming chat turn returned by the internal
+ * `begin_chat_session_*` operation entry points (H2).
+ *
+ * The dispatching NAPI method resolves with this object IMMEDIATELY
+ * after the command is queued (mirroring how the streaming methods
+ * return their [`ChatStreamHandle`] before the turn runs); the turn's
+ * reply arrives later through [`Self::result`]. `cancel()` flips the
+ * same `Arc<AtomicBool>` the command carries, so it
+ * reaches the model thread's chunk-boundary / per-step polls exactly
+ * like a streaming cancel.
+ *
+ * Reply contract: a cancelled turn REJECTS the `result()` promise with
+ * the exact string `"chat session cancelled"`
+ * ([`crate::engine::session::CHAT_SESSION_CANCELLED`]).
+ */
+export declare class ChatSessionCall {
+  /** Cooperatively cancel this queued or running turn. */
+  cancel(): void;
+  /**
+   * Await the turn's reply. Resolves with the [`ChatResult`] on a
+   * completed turn; rejects with `"chat session cancelled"` when the
+   * turn was cancelled, or with the turn's native error otherwise.
+   * Single-shot: a second call rejects.
+   */
+  result(): Promise<ChatResult>;
+}
+
 /**
  * Handle returned by the streaming chat-session entry points
  * (`chat_stream_session_start`, `chat_stream_session_continue`,
@@ -125,11 +153,8 @@ export declare class Gemma4Model {
    * **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.
+   * intentionally NOT runnable: the cache-limit coordinator's per-model delta is
+   * registered exclusively on the `load()` path.
    *
    * This path does NOT spawn a model thread, NOT materialize any
    * weights, and NOT register with the cache-limit coordinator. The
@@ -139,14 +164,12 @@ export declare class Gemma4Model {
    * 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.
+   * async `resetCaches()` call resolves as 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`.
+   * A runnable model requires `await Gemma4Model.load(path)`. The constructor
+   * signature is fixed by NAPI-RS.
    */
   constructor(config: Gemma4Config);
   /** Returns true if weights have been loaded via `load()`. */
@@ -157,14 +180,14 @@ export declare class Gemma4Model {
    *
    * `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
+   * `Gemma4Config::use_block_paged_cache`). 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;
+  maxConcurrentSequences(): number;
+  schedulerStats(): Promise<SchedulerStats>;
   /**
    * Whether this loaded instance can execute image-bearing chat turns.
    * Config-only stubs and incomplete/non-paged physical paths return false.
@@ -187,11 +210,16 @@ export declare class Gemma4Model {
   /** 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.
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
    */
-  resetCaches(): void;
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
+   */
+  releaseCacheOwner(ownerId: string): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -200,6 +228,16 @@ export declare class Gemma4Model {
    * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from the complete
    * structured conversation. The loaded model template is the
@@ -208,11 +246,27 @@ export declare class Gemma4Model {
    * against the saved token history.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from a complete
    * structured conversation ending in a tool-role message.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -505,14 +559,23 @@ export declare class Lfm2Model {
   hasBlockPagedCache(): boolean;
   /** Get the model configuration. */
   getConfig(): Lfm2Config;
+  /** Native admission capacity for the server's per-model semaphore. */
+  maxConcurrentSequences(): number;
+  /** Snapshot scheduler occupancy and paged-pool admission telemetry. */
+  schedulerStats(): Promise<SchedulerStats>;
   /** 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.
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
+   */
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
    */
-  resetCaches(): void;
+  releaseCacheOwner(ownerId: string): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -521,6 +584,16 @@ export declare class Lfm2Model {
    * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from the complete
    * structured conversation. The loaded model template is the
@@ -529,11 +602,117 @@ export declare class Lfm2Model {
    * against the saved token history.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from a complete
    * structured conversation ending in a tool-role message.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+}
+
+export declare class MuseGlimmerModel {
+  static load(modelPath: string): Promise<MuseGlimmerModel>;
+  hasMtpWeights(): boolean;
+  autoEnablesMtp(): boolean;
+  hasBlockPagedCache(): boolean;
+  maxConcurrentSequences(): number;
+  /**
+   * Model-wide context snapshot used by higher layers for compaction.
+   * `effective_window_tokens` is min(trained, live pool).
+   */
+  contextLimits(): MuseGlimmerContextLimits;
+  schedulerStats(): Promise<SchedulerStats>;
+  /**
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
+   */
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
+   */
+  releaseCacheOwner(ownerId: string): Promise<void>;
+  /**
+   * Start a new chat session.
+   *
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
+  /**
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -821,6 +1000,131 @@ export declare class NativeRewardRegistry {
   setNormalize(normalize: boolean): void;
 }
 
+/**
+ * NVIDIA Nemotron 3.5 Lightning language model: hybrid Mamba-2 SSM + GQA + MoE-FFN
+ * with an optional in-checkpoint MTP head. All model state lives on a dedicated OS
+ * thread; NAPI methods dispatch commands via channels.
+ */
+export declare class NemotronHModel {
+  /**
+   * Load a NemotronH model from a directory containing safetensors and
+   * config.json.
+   */
+  static load(modelPath: string): Promise<NemotronHModel>;
+  /**
+   * Whether this checkpoint shipped a complete MTP head (speculative
+   * decoding is available when enableMtp is set on the request).
+   */
+  hasMtpWeights(): boolean;
+  /**
+   * Whether `ChatSession` should turn MTP ON when the caller sets nothing. FALSE
+   * deliberately, about SCHEDULING not speed: this family's flat MTP core has no
+   * streaming arm, so `enable_mtp == Some(true)` costs a SYNC turn its scheduled
+   * slot — `chat_requires_barrier` routes it to the EXCLUSIVE lane and out of
+   * continuous batching. A streaming turn plans plain autoregressive and keeps its
+   * slot. `MLX_NEMOTRON_MTP_DEFAULT=1` flips the default.
+   */
+  mtpAutoEnabled(): boolean;
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance (default-on unless `use_block_paged_cache: false`).
+   */
+  hasBlockPagedCache(): boolean;
+  /**
+   * Physical/trained context limits captured at load, so the ChatSession preflight
+   * rejects long conversations instead of failing inside paged-cache allocation.
+   */
+  contextLimits(): NemotronHContextLimits;
+  /** Get the model configuration. */
+  getConfig(): NemotronHConfig;
+  /**
+   * Native admission capacity for the server's per-model semaphore.
+   * Paged models advertise the scheduler lane (up to 8 default); flat
+   * models and forced-serial processes report 1.
+   */
+  maxConcurrentSequences(): number;
+  /** Snapshot scheduler occupancy and paged-pool admission telemetry. */
+  schedulerStats(): Promise<SchedulerStats>;
+  /** Estimated number of model parameters. */
+  numParameters(): number;
+  /**
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
+   */
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
+   */
+  releaseCacheOwner(ownerId: string): Promise<void>;
+  /**
+   * Start a new chat session.
+   *
+   * Renders the complete conversation through the loaded chat
+   * template, decodes until the family's session stop token, and
+   * preserves the resulting KV state for exact-prefix reuse.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
+  /**
+   * Continue an existing chat session from the complete
+   * structured conversation. The loaded model template is the
+   * sole authority for the rendered suffix; native cache reuse
+   * occurs only after the completed structured history is verified
+   * against the saved token history.
+   */
+  chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
+  /**
+   * Continue an existing chat session from a complete
+   * structured conversation ending in a tool-role message.
+   */
+  chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+}
+
 /**
  * OutputStore - Persistence layer for training outputs
  *
@@ -1029,8 +1333,13 @@ export declare class QianfanOCRModel {
     maxNewTokens?: number | undefined | null,
     temperature?: number | undefined | null,
   ): Promise<Array<number>>;
-  /** Reset KV caches and token history. */
-  resetCaches(): void;
+  /**
+   * Reset KV caches and token history. Async so a reset queued behind
+   * an in-flight turn parks a tokio future, never the Node event loop
+   * (H1a — same contract as the `chat_napi_surface!` families). Callers
+   * requiring reset-before-next-turn ordering must await this Promise.
+   */
+  resetCaches(): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -1043,17 +1352,33 @@ export declare class QianfanOCRModel {
    * fast-fail used by plain language models.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation for `chatSessionStart`. The returned call exposes an
+   * idempotent `cancel()` immediately; `result()` resolves or rejects with the
+   * exact `chat session cancelled` sentinel.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue from the caller's complete conversation history. The
    * checkpoint's chat template is rendered again and exact prefix matching
    * decides whether the live cache can be reused.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /** Internal operation for `chatSessionContinue`. */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Tool-result continuation over a full history. Tool representation is
    * owned entirely by the model-provided template.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /** Internal operation for `chatSessionContinueTool`. */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1082,27 +1407,39 @@ export declare class QianfanOCRModel {
  * routed through `TrainingDispatch` to the model thread.
  */
 export declare class Qwen35Model {
+  /**
+   * Resolved directory containing this model's tokenizer/config assets.
+   * Streaming wrappers use it after a direct GGUF load so chat templating
+   * reads the reconstructed sidecars from the native-packed cache.
+   */
+  modelAssetsPath(): string;
   /**
    * 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
+   * `Qwen3_5Config::use_block_paged_cache`, default-ON for every compatible
+   * checkpoint). 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.
+   * Native admission width for plain text AR turns. Installed vision and
+   * MTP modules do not disable text batching: requests that actually carry
+   * media or set `enable_mtp=true` are routed through the ordered exclusive
+   * lane by the scheduler.
+   */
+  maxConcurrentSequences(): number;
+  /** Snapshot scheduler occupancy plus unified block/recurrent admission. */
+  schedulerStats(): Promise<SchedulerStats>;
+  /**
+   * Whether this instance has an inline MTP head or external DFlash2
+   * companion. Snapshotted at load time so `ChatSession` can auto-default
+   * `enableMtp = true` without dispatching into the model thread.
    *
    * Note: this only reports weight availability. Whether the
    * speculative-decode path actually runs on a given call also requires the
@@ -1139,7 +1476,7 @@ export declare class Qwen35Model {
    * - model.safetensors (or model-*.safetensors)
    * - tokenizer.json + tokenizer_config.json
    */
-  static load(path: string): Promise<Qwen35Model>;
+  static load(path: string, options?: Qwen35LoadOptions | undefined | null): Promise<Qwen35Model>;
   /** Generate text from a prompt token sequence. */
   generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
   /**
@@ -1155,11 +1492,16 @@ export declare class Qwen35Model {
    */
   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.
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
    */
-  resetCaches(): void;
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
+   */
+  releaseCacheOwner(ownerId: string): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -1168,6 +1510,16 @@ export declare class Qwen35Model {
    * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from the complete
    * structured conversation. The loaded model template is the
@@ -1176,11 +1528,27 @@ export declare class Qwen35Model {
    * against the saved token history.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from a complete
    * structured conversation ending in a tool-role message.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1216,15 +1584,22 @@ export declare class Qwen35MoeModel {
    *
    * `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
+   * `Qwen3_5MoeConfig::use_block_paged_cache`, default-ON for compatible
+   * checkpoints). 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;
+  /**
+   * Native admission width for plain text autoregressive turns. MTP and
+   * multimodal turns remain ordered barriers and do not enter the batched
+   * decode lane.
+   */
+  maxConcurrentSequences(): number;
+  /** Snapshot scheduler occupancy plus unified block/recurrent admission. */
+  schedulerStats(): Promise<SchedulerStats>;
   /**
    * Whether this checkpoint shipped an MTP head (module loaded by
    * `persistence::apply_weights_moe_inner`). Snapshotted at load time from
@@ -1270,11 +1645,16 @@ export declare class Qwen35MoeModel {
    */
   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.
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
+   */
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
    */
-  resetCaches(): void;
+  releaseCacheOwner(ownerId: string): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -1283,6 +1663,16 @@ export declare class Qwen35MoeModel {
    * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from the complete
    * structured conversation. The loaded model template is the
@@ -1291,11 +1681,27 @@ export declare class Qwen35MoeModel {
    * against the saved token history.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from a complete
    * structured conversation ending in a tool-role message.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1317,6 +1723,36 @@ export declare class Qwen35MoeModel {
 }
 export type Qwen3_5MoeModel = Qwen35MoeModel;
 
+export declare class Qwen3AsrCapture {
+  get source(): Qwen3AsrCaptureSource;
+  get deviceName(): string;
+  get sampleRate(): number;
+  get channels(): number;
+  pause(): void;
+  resume(): void;
+  stop(): Promise<Qwen3AsrCaptureStats>;
+}
+
+export declare class Qwen3AsrModel {
+  static load(modelPath: string): Promise<Qwen3AsrModel>;
+  transcribe(audio: Float32Array, options?: Qwen3AsrTranscribeOptions | undefined | null): Promise<Qwen3AsrResult>;
+  createStream(options?: Qwen3AsrStreamOptions | undefined | null): Promise<Qwen3AsrStream>;
+}
+
+export declare class Qwen3AsrStream {
+  feed(samples: Float32Array): Promise<Qwen3AsrResult | undefined | null>;
+  finish(): Promise<Qwen3AsrResult>;
+  /**
+   * Start real-time microphone or system-output capture through Core Audio.
+   * The realtime callback only writes mono float PCM into a bounded lock-free
+   * ring; a separate worker drains it and feeds this streaming session.
+   */
+  startCapture(
+    options: Qwen3AsrCaptureOptions | undefined | null,
+    callback: (err: Error | null, arg: Qwen3AsrResult) => void,
+  ): Qwen3AsrCapture;
+}
+
 /**
  * Qwen3 Model with automatic differentiation support
  *
@@ -1340,6 +1776,17 @@ export declare class Qwen3Model {
    * runtime-routing decision.
    */
   hasBlockPagedCache(): boolean;
+  /**
+   * Maximum number of independent sequences admitted to the continuous
+   * batching scheduler. Flat-cache and forced-serial instances deliberately
+   * report one so the server retains its exclusive dispatch lane.
+   */
+  maxConcurrentSequences(): number;
+  /**
+   * Snapshot continuous-batching scheduler counters after all commands
+   * already ahead of this query have drained.
+   */
+  schedulerStats(): Promise<SchedulerStats>;
   /** Get model configuration */
   getConfig(): Qwen3Config;
   /**
@@ -1434,11 +1881,16 @@ export declare class Qwen3Model {
     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.
+   * Reset all caches and clear cached token history. Async so a reset
+   * queued behind an in-flight turn parks a tokio future, never the
+   * Node event loop (H1: a dead prefill used to freeze all HTTP traffic).
    */
-  resetCaches(): void;
+  resetCaches(): Promise<void>;
+  /**
+   * Release scheduler-owned KV/history state for one logical
+   * session owner without purging content-addressed prefix blocks.
+   */
+  releaseCacheOwner(ownerId: string): Promise<void>;
   /**
    * Start a new chat session.
    *
@@ -1447,6 +1899,16 @@ export declare class Qwen3Model {
    * preserves the resulting KV state for exact-prefix reuse.
    */
   chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionStart` (H2). Resolves
+   * IMMEDIATELY with a `ChatSessionCall` whose `cancel()`
+   * can cancel the queued/running turn; the reply arrives via
+   * `call.result()`. A cancelled turn rejects `result()` with
+   * the exact string `"chat session cancelled"`. The LM wrapper
+   * keeps this two-phase operation private and exposes cancellation
+   * through the ordinary method's `AbortSignal` argument.
+   */
+  beginChatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from the complete
    * structured conversation. The loaded model template is the
@@ -1455,11 +1917,27 @@ export declare class Qwen3Model {
    * against the saved token history.
    */
   chatSessionContinue(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinue` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinue(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /**
    * Continue an existing chat session from a complete
    * structured conversation ending in a tool-role message.
    */
   chatSessionContinueTool(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Internal operation bridge for `chatSessionContinueTool` (H2). Same
+   * contract as `beginChatSessionStart`.
+   */
+  beginChatSessionContinueTool(
+    messages: Array<ChatMessage>,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatSessionCall>;
   /** Streaming variant of `chatSessionStart`. */
   chatStreamSessionStart(
     messages: ChatMessage[],
@@ -1483,8 +1961,8 @@ export declare class Qwen3Model {
    *
    * This loads a model from a directory containing:
    * - config.json: Model configuration
-   * - weights.mlx (optional): MLX format weights with data arrays
-   * - weights.safetensors (optional): SafeTensors format (not yet supported)
+   * - weights.safetensors or model.safetensors (single-file SafeTensors)
+   * - model-*-of-*.safetensors (sharded SafeTensors)
    *
    * # Arguments
    * * `model_path` - Path to the model directory
@@ -2123,8 +2601,45 @@ export declare function calibrateActivationAmaxRaw(
   calibSeq: number,
 ): Promise<number>;
 
+/**
+ * Run the teacher over `texts` and write its top-`top_k` next-token
+ * distribution into `cache_dir`. Returns the number of rows written.
+ *
+ * Each row is tokenized RAW (no chat template, no BOS), truncated to `seq_len`
+ * tokens, and prefilled on fresh caches. The head is projected over positions
+ * in `logit_chunk`-sized chunks so the full-vocabulary logits never
+ * materialize for the whole sequence at once.
+ *
+ * `seq_len` is raised to 2 when lower: the first token primes the forward and
+ * has no target of its own, so a shorter row scores nothing. `top_k` is
+ * clamped to the teacher's vocabulary, so a wider request degrades to an exact
+ * full-vocab KL. The cache records both EFFECTIVE values, not the requested
+ * ones — the support width is what says how far a top-K KL can be trusted.
+ *
+ * A quantized teacher is accepted — anchoring on a released quantized
+ * checkpoint is a real comparison — but it is warned about and recorded in the
+ * cache, because every number then measures divergence from that checkpoint
+ * rather than from the bf16 model.
+ */
+export declare function captureTeacherLogits(
+  teacherPath: string,
+  texts: Array<string>,
+  seqLen: number,
+  topK: number,
+  logitChunk: number,
+  cacheDir: string,
+): Promise<number>;
+
 /** Unified chat configuration shared by all model variants (Qwen3, Qwen3.5, Qwen3.5 MoE). */
 export interface ChatConfig {
+  /**
+   * Security domain for content-addressed paged-KV prefix reuse.
+   * Requests with different values cannot reuse each other's cached
+   * prefixes even when their token sequences are identical. This is
+   * deliberately separate from `cache_owner_id`, which controls logical
+   * session/recurrent-state ownership rather than physical KV sharing.
+   */
+  cacheSalt?: string | undefined;
   /**
    * Internal logical cache owner. The agent provider forwards Pi's stable
    * session id so model-global GDN sidecars can retain parent and child
@@ -2204,6 +2719,20 @@ export interface ChatConfig {
    * loop (pure-Rust eager; qwen3.5 dense and MoE). Requires the model
    * checkpoint to carry an MTP head (otherwise silently ignored). Default:
    * `false`.
+   *
+   * The MTP acceptance gate (`MLX_MTP_ACCEPT_GATE`, default ON) also
+   * applies to explicit requests at fixed depth 1: the model aggregates
+   * first-draft acceptance counts across completed depth-1 turns (history
+   * bounded to roughly the most recent ~512 attempts) and silently runs
+   * plain autoregressive decoding for the next depth-1 turn when an
+   * exact-binomial test at the 5% level shows the aggregate is
+   * inconsistent with the ~0.6 break-even acceptance rate. After 3
+   * consecutive gated turns the gate re-probes with speculation on, and
+   * `resetCaches()` clears the per-model (not per-session) history. The
+   * gate is depth-1-scoped and exempts adaptive-depth turns
+   * (`mtpAdaptiveDepth` and explicit depth > 1 turns are never gated).
+   * Set the env var to `0` / `false` / `off` to bypass the gate and
+   * always run MTP when requested.
    */
   enableMtp?: boolean | undefined;
   /**
@@ -2216,10 +2745,14 @@ export interface ChatConfig {
    * 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):
+   * External drafts (`draftModelPath`) resolve the field against their
+   * checkpoint width instead (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):
+   * - Qwen3.8 DFlash2: checkpoint `block_size = 8` contains one target
+   *   anchor plus seven proposals. Unset uses all seven; an explicit value
+   *   clamps to `[1, 7]` and pins that depth unless
+   *   `mtpAdaptiveDepth: true` explicitly enables the break-even guard.
    * - 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
@@ -2230,6 +2763,10 @@ export interface ChatConfig {
    * - 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`).
+   * - Muse-Glimmer DFlash follows DSpark's external-draft rules: unset
+   *   uses the checkpoint block size (16 for Muse-Glimmer-30B), while an
+   *   explicit value clamps to `[1, block_size]` and pins that depth unless
+   *   `mtpAdaptiveDepth: true` explicitly enables the break-even guard.
    *
    * `mtpAdaptiveDepth` is ignored for the Gemma4 assistant variant.
    */
@@ -2244,9 +2781,10 @@ export interface ChatConfig {
    * `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.
+   * Default: false, except Gemma4 DSpark and Muse-Glimmer DFlash enable the
+   * measured break-even guard when both this field and `mtpDepth` are unset.
+   * Qwen3.8 DFlash2 remains fixed-width by default. An explicit value always
+   * wins over the family default.
    */
   mtpAdaptiveDepth?: boolean | undefined;
 }
@@ -2672,6 +3210,15 @@ export declare function convertForeignWeights(options: ForeignConversionOptions)
 
 export declare function convertGgufToSafetensors(options: GgufConversionOptions): Promise<GgufConversionResult>;
 
+/**
+ * Every convertible `model_type` the converter registry accepts, in dispatch
+ * order — the native half of the CLI detect-table parity gate (same pattern
+ * as `cold_restore_families`): a family with a conversion recipe but no CLI
+ * detect row would otherwise convert generically and produce unloadable
+ * output.
+ */
+export declare function convertibleModelTypes(): Array<string>;
+
 /**
  * Convert a HuggingFace SafeTensors model to MLX format
  *
@@ -2747,6 +3294,11 @@ export declare function createRandomQwen35MoeCheckpoint(config: Qwen35MoeConfig,
  */
 export declare function createRandomQwen3Checkpoint(config: Qwen3Config, savePath: string): Promise<undefined>;
 
+export interface DecodeBatchOccupancyBucket {
+  occupancy: number;
+  steps: number;
+}
+
 /** Document element - either a table or paragraph */
 export interface DocumentElement {
   elementType: ElementType;
@@ -2835,6 +3387,34 @@ export interface EngineStepMetrics {
   activeMemoryMb: number;
 }
 
+/**
+ * Teacher-forced quality of one checkpoint against a cached reference.
+ *
+ * `mean_nll`, `perplexity` and `top1_agreement` are EXACT full-vocab numbers.
+ * `mean_kl_topk` is exact only over the teacher's cached support — read it
+ * together with `teacher_tail_mass`, which is the probability mass that support
+ * leaves out.
+ */
+export interface EvalReport {
+  rows: number;
+  positions: number;
+  topK: number;
+  /** Teacher the cache was captured from, carried through from its metadata. */
+  teacherPath: string;
+  /**
+   * That teacher was itself quantized, so every number below measures
+   * divergence from it rather than from the bf16 model.
+   */
+  teacherQuantized: boolean;
+  meanNll: number;
+  perplexity: number;
+  teacherMeanNll: number;
+  teacherPerplexity: number;
+  meanKlTopk: number;
+  teacherTailMass: number;
+  top1Agreement: number;
+}
+
 export interface ForeignConversionOptions {
   /** Path to the input weights file (.pdparams, .pkl, .pt, .pth) */
   inputPath: string;
@@ -3046,10 +3626,9 @@ export interface Gemma4LoadOptions {
    * 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`.
+   * automatically when present. Draft decoding uses a request-local flat
+   * target-cache lane. The resident target retains its grouped paged pools,
+   * so loading an optional proposer does not disable ordinary batching.
    */
   draftModelPath?: string;
 }
@@ -3224,6 +3803,13 @@ export declare function getMemorySnapshot(): GpuMemorySnapshot;
 /** Retrieve all collected profiling data as a `ProfilingSession`. */
 export declare function getProfilingData(): ProfilingSession;
 
+/**
+ * Read the architecture declared by a GGUF header without loading any tensor
+ * payloads. This is the model-family detection seam for standalone GGUF files
+ * that intentionally do not ship a sibling `config.json`.
+ */
+export declare function ggufArchitecture(inputPath: string): string;
+
 export interface GgufConversionOptions {
   /** Path to the GGUF file */
   inputPath: string;
@@ -3281,13 +3867,20 @@ export interface GgufConversionOptions {
    */
   quantMxfp?: boolean;
   /**
-   * Import ggml Q4_K / Q5_K / Q6_K tensors as MLX K-quant arrays instead of
+   * Import supported ggml K/IQ tensors as native MLX packed arrays instead of
    * rejecting them (default: false). The blocks are repacked, never
-   * dequantized, so the output keeps the source file's weights and byte size.
+   * dequantized, so the output preserves the source quantized values. IQ3_S
+   * expands only its integer grid/sign encoding to signed 8-bit codes.
    * With this off, Q6_K remains the Gemma4 token-embedding BF16 fallback and
    * Q4_K / Q5_K are an error.
    */
   importKQuants?: boolean;
+  /**
+   * Preserve Qwen3.5/3.8 GGUF GDN tensors in llama.cpp's tiled value-head
+   * order. The runtime consumes this layout directly and avoids any packed
+   * weight permutation. Intended for native GGUF execution.
+   */
+  nativeQwen35Layout?: boolean;
 }
 
 export interface GgufConversionResult {
@@ -3624,6 +4217,12 @@ export interface Lfm2Config {
    * fully flat `Lfm2LayerCache` path on all layers.
    */
   useBlockPagedCache?: boolean | undefined;
+  /**
+   * Persist block-paged attention state and the co-keyed short-convolution
+   * sidecar to the SSD cold tier. Explicit config overrides the process-wide
+   * `MLX_PERSIST_PAGED_CACHE` default.
+   */
+  persistPagedCache?: 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).
@@ -3715,6 +4314,104 @@ export declare const enum MultimodalContentOrder {
   ImagesThenText = 'imagesThenText',
 }
 
+/**
+ * Trained and physically available active-context limits for one loaded
+ * Muse-Glimmer model. Values are snapshots because the physical pool is fixed
+ * for the lifetime of the resident model.
+ */
+export interface MuseGlimmerContextLimits {
+  trainedWindowTokens: number;
+  effectiveWindowTokens: number;
+  pagedBlockCapacity: number;
+  pagedBlockSize: number;
+}
+
+/**
+ * NVIDIA Nemotron 3.5 Lightning ("nemotron_h") model configuration.
+ *
+ * Hybrid MoE: every layer is one pre-RMSNorm + ONE mixer + a residual, closed
+ * by `norm_f` and an untied `lm_head`. Parsed fail-closed — unknown block
+ * types, missing fields and unsupported features are rejected at load.
+ */
+export interface NemotronHConfig {
+  vocabSize: number;
+  hiddenSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  headDim: number;
+  maxPositionEmbeddings: number;
+  layerNormEpsilon: number;
+  /**
+   * Per-layer mixer kind, remapped from the checkpoint's
+   * `layers_block_type` to the HF `MIXER_TYPES` names.
+   */
+  layersBlockType: Array<string>;
+  mambaNumHeads: number;
+  mambaHeadDim: number;
+  /** SSM state size, per head per group. */
+  ssmStateSize: number;
+  /** Number of SSM groups; head `h` belongs to group `h / (H / G)`. */
+  nGroups: number;
+  /** Depthwise causal conv1d kernel size. */
+  convKernel: number;
+  chunkSize: number;
+  /**
+   * Declared minimum discretized time step.
+   *
+   * UNUSED BY THE RUNTIME. No served reference clamps dt to it - only HF's
+   * torch fallback does. `time_step_limit_pair()` is the real clamp.
+   */
+  timeStepMin: number;
+  /**
+   * Optional `[min, max]` bounds for the discretized time step. `None` is
+   * the reference default `(0.0, +inf)`, i.e. no clamp.
+   */
+  timeStepLimit?: number[];
+  nRoutedExperts: number;
+  numExpertsPerTok: number;
+  /** Routing weight scale, applied after normalization. */
+  routedScalingFactor: number;
+  /** Renormalize the gathered top-k weights to sum to 1 before scaling. */
+  normTopkProb: boolean;
+  /** Per-expert MLP intermediate size (non-gated up -> relu2 -> down). */
+  intermediateSize: number;
+  /** Shared-expert MLP intermediate size; it runs on ALL tokens. */
+  moeSharedExpertIntermediateSize: number;
+  /** EOS token ids, from the config.json scalar or array. */
+  eosTokenIds: number[];
+  /** MTP layer kinds, remapped like `layers_block_type`. */
+  mtpLayersBlockType: string[];
+  /** Number of MTP predictor steps (`num_nextn_predict_layers`). */
+  nMtpLayers: number;
+  /**
+   * Optional block-paged KV cache memory cap in MiB. `None` requests one
+   * `max_position_embeddings` sequence (6 GiB on Lightning 30B-A3B) then
+   * clips with load-time Metal/RAM sizing after weights. Explicit values
+   * skip the auto-sizer.
+   */
+  pagedCacheMemoryMb?: number;
+  /** Optional paged block size in tokens (default 16). */
+  pagedBlockSize?: number;
+  /**
+   * Opt in/out of the block-paged KV adapter. `None` enables the paged pool
+   * and the continuous-batching lane; `Some(false)` reverts to whole-turn.
+   */
+  useBlockPagedCache?: boolean;
+}
+
+/**
+ * Physical and trained context limits captured at load time, surfaced through
+ * `context_limits()` so the ChatSession preflight can compact or reject against
+ * the paged pool's ACTUAL capacity instead of the trained window.
+ */
+export interface NemotronHContextLimits {
+  trainedWindowTokens: number;
+  effectiveWindowTokens: number;
+  pagedBlockCapacity: number;
+  pagedBlockSize: number;
+}
+
 /** Result from document orientation classification. */
 export interface OrientationResult {
   /** Detected rotation angle (0, 90, 180, or 270 degrees) */
@@ -3885,6 +4582,12 @@ export interface PhaseProfile {
   count: number;
 }
 
+/**
+ * Header-only DFlash validation for the CLI's transactional ordering. This
+ * runs before the primary conversion touches its output directory.
+ */
+export declare function preflightMuseDflashGguf(inputPath: string, targetConfigDir: string): void;
+
 /**
  * Per-call Viterbi calibration overrides.
  *
@@ -4062,6 +4765,15 @@ export interface Qwen35Config {
    * Default: automatically sized for one full-context sequence.
    */
   pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Initial paged KV pool size in MiB for the grow-on-demand pool: the
+   * pool starts at this size and grows toward the max budget
+   * (`paged_cache_memory_mb` or the auto one-full-context default) on
+   * exhaustion. Unset (default) makes the initial pool equal the max —
+   * the historical fixed-pool behavior. `MLX_PAGED_CACHE_INITIAL_MB` wins
+   * over this field at load time.
+   */
+  pagedCacheInitialMemoryMb?: number | undefined;
   /**
    * Block size for paged attention (tokens per block).
    * Only used when `use_block_paged_cache` is true.
@@ -4072,7 +4784,7 @@ export interface Qwen35Config {
    * Use the block-paged KV cache adapter (`PagedKVCacheAdapter`) for
    * full-attention layers.
    *
-   * **OPT-IN — experimental.** When `Some(true)`, `Qwen35Inner`
+   * When enabled (the default), `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
@@ -4083,12 +4795,12 @@ export interface Qwen35Config {
    * 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
+   * over the eager flat decode. When enabled, 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.
+   * an explicit false runs eager flat decode. Either way the forward is
+   * pure-Rust eager.
    *
-   * **VLM under paged**: a VLM checkpoint defaults this flag ON at load, so
+   * **VLM under paged**: VLM checkpoints also default this flag ON, 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
@@ -4098,8 +4810,9 @@ export interface Qwen35Config {
    * 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`).
+   * Load default: `Some(true)` for compatible text and VLM checkpoints.
+   * Explicit false remains available for flat-path diagnostics; sym8 is
+   * forced flat by persistence after its storage mode is known.
    */
   useBlockPagedCache?: boolean | undefined;
   /**
@@ -4117,12 +4830,20 @@ export interface Qwen35Config {
    * unavailable.
    */
   nMtpLayers: number;
+  /**
+   * Internal layout marker written by native Qwen3.5/3.8 GGUF conversion.
+   * `Some("tiled")` keeps llama.cpp's value-head order and lets GDN map
+   * value head h to key head h % Hk without permuting packed weights.
+   */
+  qwen35GgufGdnLayout?: string | undefined;
 }
 
 /**
  * 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.
+ * Qwen3.5 model. Values are snapshots taken at load: `effective_window`
+ * derives from the pool's MAX capacity (grow-on-demand pools are preflighted
+ * against the ceiling they grow toward), while `paged_block_capacity` is the
+ * physical pool size actually allocated at load and may lag after a grow.
  */
 export interface Qwen35ContextLimits {
   trainedWindowTokens: number;
@@ -4148,6 +4869,11 @@ export interface Qwen35GenerationResult {
   finishReason: string;
 }
 
+export interface Qwen35LoadOptions {
+  /** External z-lab DFlash2 checkpoint directory. */
+  draftModelPath?: string;
+}
+
 /**
  * Qwen3.5 MoE model configuration.
  *
@@ -4189,6 +4915,15 @@ export interface Qwen35MoeConfig {
    * Default: automatically sized for one full-context sequence.
    */
   pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Initial paged KV pool size in MiB for the grow-on-demand pool: the
+   * pool starts at this size and grows toward the max budget
+   * (`paged_cache_memory_mb` or the auto one-full-context default) on
+   * exhaustion. Unset (default) makes the initial pool equal the max —
+   * the historical fixed-pool behavior. `MLX_PAGED_CACHE_INITIAL_MB` wins
+   * over this field at load time.
+   */
+  pagedCacheInitialMemoryMb?: number | undefined;
   /**
    * Block size for paged attention (tokens per block).
    * Only used when `use_block_paged_cache` is true.
@@ -4198,8 +4933,8 @@ export interface Qwen35MoeConfig {
   /**
    * 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
+   * 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`
@@ -4213,7 +4948,8 @@ export interface Qwen35MoeConfig {
    * runtime; warm image-bearing session continues / cache-hit reuse are
    * cold-started (no warm GDN two-pass prefix).
    *
-   * Default: `None` / `false`.
+   * Default: enabled for compatible Metal checkpoints. Explicit `false`
+   * and `MLX_QWEN35_PAGED_OVERRIDE=0` retain the flat rollback path.
    */
   useBlockPagedCache?: boolean | undefined;
   /**
@@ -4232,6 +4968,13 @@ export interface Qwen35MoeConfig {
    * unavailable.
    */
   nMtpLayers: number;
+  /**
+   * Internal layout marker written by native Qwen3.5/3.8 GGUF conversion.
+   * `Some("tiled")` keeps llama.cpp's value-head order and lets the shared
+   * GDN runtime map value head h to key head h % Hk without permuting
+   * packed weights.
+   */
+  qwen35GgufGdnLayout?: string | undefined;
 }
 
 /** Generation configuration for Qwen3.5 MoE */
@@ -4251,6 +4994,145 @@ export interface Qwen35MoeGenerationResult {
   finishReason: string;
 }
 
+export interface Qwen3AsrAudioDevice {
+  id: string;
+  name: string;
+  source: Qwen3AsrCaptureSource;
+  isDefault: boolean;
+  sampleRate: number;
+  channels: number;
+}
+
+export declare function qwen3AsrAudioDevices(): Array<Qwen3AsrAudioDevice>;
+
+export interface Qwen3AsrCaptureOptions {
+  /** Audio source. Omit to capture the microphone. */
+  source?: Qwen3AsrCaptureSource;
+  /**
+   * Stable Core Audio device UID returned by `qwen3AsrAudioDevices()` or
+   * `qwen3AsrInputDevices()`.
+   */
+  deviceId?: string;
+  /**
+   * Device name. Omit to use the default input or output device for the
+   * selected source.
+   */
+  deviceName?: string;
+  /**
+   * For system audio, optionally capture only processes with these bundle
+   * identifiers. Empty or omitted captures all audio sent to the device.
+   */
+  applicationBundleIds?: Array<string>;
+  /** Lock-free callback ring capacity in seconds (default 10). */
+  ringSeconds?: number;
+  /** Amount drained from the ring into each model feed (default 100 ms). */
+  feedMilliseconds?: number;
+}
+
+export declare const enum Qwen3AsrCaptureSource {
+  Microphone = 'microphone',
+  SystemAudio = 'systemAudio',
+}
+
+export interface Qwen3AsrCaptureStats {
+  capturedFrames: number;
+  droppedFrames: number;
+}
+
+export interface Qwen3AsrInputDevice {
+  id: string;
+  name: string;
+  isDefault: boolean;
+  sampleRate: number;
+  channels: number;
+  sampleFormat: string;
+}
+
+export declare function qwen3AsrInputDevices(): Array<Qwen3AsrInputDevice>;
+
+export interface Qwen3AsrResult {
+  /**
+   * Complete transcription for the latest rolling revision. The trailing
+   * provisional region may be replaced by the next revision.
+   */
+  text: string;
+  /**
+   * Prefix that survived the stream's provisional-token rollback window.
+   * Equals `text` for a final or one-shot result.
+   */
+  stableText: string;
+  /**
+   * Trailing text that may be replaced by the next rolling revision.
+   * Empty for a final or one-shot result.
+   */
+  provisionalText: string;
+  language?: string;
+  tokenIds: Array<number>;
+  /**
+   * True when generation used the entire configured token budget without
+   * reaching an end token. The revision may contain incomplete or repeated
+   * text and callers may choose to flag it for review.
+   */
+  reachedMaxTokens: boolean;
+  /** Total audio committed by this stream, or the full one-shot duration. */
+  audioSeconds: number;
+  /** Newly consumed audio duration for this update. */
+  segmentAudioSeconds: number;
+  featureMs: number;
+  encoderMs: number;
+  prefillMs: number;
+  decodeMs: number;
+  totalMs: number;
+  tokensPerSecond: number;
+  realTimeFactor: number;
+  /**
+   * Streaming revisions increment whenever a rolling decode replaces
+   * previously provisional text. Zero for one-shot transcription.
+   */
+  revision: number;
+  isFinal: boolean;
+}
+
+export interface Qwen3AsrStreamOptions {
+  sampleRate?: number;
+  prompt?: string;
+  language?: string;
+  /**
+   * Maximum continuation tokens generated per revision (default 32).
+   * Keeping this bounded is essential for realtime latency.
+   */
+  maxTokens?: number;
+  /** Minimum newly buffered audio before a rolling decode (default 2 s). */
+  chunkSeconds?: number;
+  /**
+   * Number of trailing raw decoder tokens rolled back and regenerated on
+   * the next revision (default 5).
+   */
+  provisionalTokens?: number;
+  /**
+   * Number of initial chunks decoded without transcript conditioning
+   * (default 2), matching Qwen's official streaming policy.
+   */
+  unfixedChunks?: number;
+}
+
+export interface Qwen3AsrTranscribeOptions {
+  /**
+   * Sampling rate of `audio`. Inputs are resampled to the checkpoint's
+   * native 16 kHz rate before feature extraction.
+   */
+  sampleRate?: number;
+  /** Optional domain/context prompt placed in the system turn. */
+  prompt?: string;
+  /**
+   * Language code (`en`, `zh`, ...) or canonical language name. Omit for
+   * automatic language detection.
+   */
+  language?: string;
+  /** Maximum number of newly generated tokens (default 256). */
+  maxTokens?: number;
+}
+
 /** Qwen3 model configuration */
 export interface Qwen3Config {
   vocabSize: number;
@@ -4419,6 +5301,54 @@ export interface SamplingConfig {
  */
 export declare function saveToXlsx(text: string, filePath: string): void;
 
+/**
+ * Read-only NAPI/dashboard mirror. Counters use `f64`, matching the other
+ * native metrics snapshots and avoiding BigInt round-trips in JavaScript.
+ */
+export interface SchedulerStats {
+  globalSteps: number;
+  maxBatchOccupancy: number;
+  decodeBatchOccupancyHist: Array<DecodeBatchOccupancyBucket>;
+  fusedGreedyEpilogueSteps: number;
+  admitted: number;
+  completed: number;
+  admissionDeferredBlocks: number;
+  rowsAllocEvicted: number;
+  blockCapacity: number;
+  freeBlocks: number;
+  reclaimableBlocks: number;
+  allocatedBlocks: number;
+  watermarkBlocks: number;
+  reservedBlocks: number;
+  memoryCapacityBytes: number;
+  memoryWatermarkBytes: number;
+  reservedBlockBytes: number;
+  reservedStateBytes: number;
+  admissionDeferredState: number;
+  ssdRestoreWaiting: number;
+  ssdRestoreBytes: number;
+  ssdRestoreWaitMs: number;
+  preemptions: number;
+  preemptionsRecompute: number;
+  preemptionsSsd: number;
+}
+
+/**
+ * Teacher-force `model_path` over the token ids cached in `cache_dir` and
+ * report its NLL, perplexity, top-1 agreement and KL against the teacher.
+ *
+ * The candidate is refused when it cannot answer for the cached rows: a
+ * different `model_type`, a different tokenizer, or a different vocabulary
+ * width. Score reads its token ids FROM THE CACHE, so a tokenizer mismatch
+ * would otherwise report a finite, plausible number measured on the wrong
+ * text.
+ */
+export declare function scoreAgainstTeacher(
+  modelPath: string,
+  cacheDir: string,
+  logitChunk: number,
+): Promise<EvalReport>;
+
 /** Enable or disable profiling globally. */
 export declare function setProfilingEnabled(enabled: boolean): void;