@tryhamster/gerbil 1.11.4 → 1.13.0

package/dist/{index-h8TDu1qm.d.mts → index-Fj2XkP-o.d.mts}

@@ -814,1038 +814,1947 @@ declare function quantizeKaniBackbone(graph: ModelGraph, weights: Map<string, {
   shape: number[];
 }>): void;
 //#endregion
-//#region src/gpu/sampler.d.ts
-/**
- * CPU-side token sampling from logits.
- *
- * Applies temperature, top-k, and top-p (nucleus) filtering,
- * then samples from the resulting probability distribution.
- *
- * Uses typed arrays and min-heap for zero-allocation top-K selection.
- * For vocab_size ~152K with topK=50, this avoids creating 152K JS tuples.
- */
-interface SamplingParams {
-  temperature?: number;
-  topK?: number;
-  topP?: number;
-  repetitionPenalty?: number;
-}
-//#endregion
-//#region src/gpu/vision-preprocess.d.ts
-/**
- * Host-side vision preprocessing for the Qwen3.5 ViT.
- *
- * The learned position embeddings (bilinear-interpolated over the patch grid)
- * and the 2D rotary cos/sin tables are functions of the image grid (t, h, w)
- * ONLY — not of the model weights or pixel values. They are cheap to compute on
- * the CPU and fed to the GPU graph as input activations, keeping the graph to
- * weight-dependent math while staying byte-identical to HF transformers.
- *
- * Ports (verified against transformers 5.12 vision_utils.py + modeling_qwen3_5):
- *   - get_vision_bilinear_indices_and_weights  → buildPosEmbeds()
- *   - get_vision_position_ids                  → buildPositionIds()
- *   - Qwen3_5VisionRotaryEmbedding             → buildRotaryCosSin()
- *
- * Patch ordering: both the pos-embed gather and the position ids reorder patches
- * into spatial_merge_size×spatial_merge_size groups, matching the HF image
- * processor's output ordering, so the merger's [N,h]→[N/u,h*u] reshape lines up.
- */
-interface VisionGridConfig {
-  hiddenSize: number;
-  numHeads: number;
-  numPositionEmbeddings: number;
-  spatialMergeSize: number;
-  ropeTheta?: number;
-}
-interface VisionPositionTensors {
-  /** [N, hidden_size] bilinear-interpolated learned position embeddings. */
-  posEmbeds: Float32Array;
-  /** [N, head_dim] rotary cosines. */
-  cos: Float32Array;
-  /** [N, head_dim] rotary sines. */
-  sin: Float32Array;
-  numPatches: number;
-}
-/**
- * Build bilinear-interpolated learned position embeddings [N, hidden].
- * posEmbedTable is the raw pos_embed.weight [num_position_embeddings, hidden].
- */
-declare function buildPosEmbeds(gridTHW: [number, number, number], posEmbedTable: Float32Array, cfg: VisionGridConfig): Float32Array;
-/**
- * Build the reordered (row, col) position ids [N, 2] for rotary, matching
- * get_vision_position_ids.
- */
-declare function buildPositionIds(gridTHW: [number, number, number], merge: number): Int32Array;
-/**
- * Build rotary cos/sin tables [N, head_dim] from position ids, matching
- * Qwen3_5VisionRotaryEmbedding + the cat((rotary, rotary)) in VisionModel.forward.
- *
- * rotary_pos_emb(position_ids) = (position_ids[..,None] * inv_freq).flatten(1)
- *   where inv_freq has length (head_dim/2)/2 = head_dim/4, computed over dim=head_dim/2.
- * For each token the two position components (h, w) each produce head_dim/4 freqs,
- * concatenated → head_dim/2, then duplicated → head_dim for cos/sin.
- */
-declare function buildRotaryCosSin(positionIds: Int32Array, headDim: number, theta?: number): {
-  cos: Float32Array;
-  sin: Float32Array;
-  numPatches: number;
-};
-/**
- * Build all host position tensors for a single image grid in one call.
- */
-declare function buildVisionPositionTensors(gridTHW: [number, number, number], posEmbedTable: Float32Array, cfg: VisionGridConfig): VisionPositionTensors;
-interface Gemma4VisionGridConfig {
-  hiddenSize: number;
-  numHeads: number;
-  headDim: number;
-  ropeTheta: number;
-  poolingKernelSize: number;
-}
-interface Gemma4VisionPositionTensors {
-  /** [N, hidden] axial position embeddings (table[0][x] + table[1][y]). */
-  posEmbeds: Float32Array;
-  /** [N, headDim] axial rotary cosines. */
-  cos: Float32Array;
-  /** [N, headDim] axial rotary sines. */
-  sin: Float32Array;
-  /** [Np, N] average-pooling matrix (1/k² in-cell, 0 elsewhere). */
-  poolMatrix: Float32Array;
-  /** number of patches N (= gridH*gridW). */
-  numPatches: number;
-  /** number of pooled (soft) tokens Np (= ceil(gridH/k)*ceil(gridW/k)). */
-  numPooled: number;
-}
-/**
- * Build axial learned position embeddings [N, hidden] from the [2, posSize, hidden]
- * table: pos[p] = table[0][x_p] + table[1][y_p]. Direct lookup, no interpolation
- * (HF F.embedding on clamped positions).
- */
-declare function buildGemma4PosEmbeds(gridH: number, gridW: number, posEmbedTable: Float32Array,
-// [2, posSize, hidden] flattened
-hidden: number, posSize: number): Float32Array;
-/**
- * Build the 2D axial rotary cos/sin tables [N, headDim].
- *   spatial_dim = headDim / 2;  inv_freq[j] = 1/theta^((2j)/spatial_dim), j in [0, spatial_dim/2)
- *   per spatial dim: f = pos * inv_freq (spatial_dim/2 values); emb = cat(f, f) (spatial_dim values)
- *   cos/sin = cat([emb_x, emb_y]) → headDim values, layout [fx,fx,fy,fy].
- * Applied with the global-half rotate_half kernel (ApplyRotaryEmb), which computes
- * out = x*cos + rotate_half(x)*sin element-wise — exact for this layout.
- */
-declare function buildGemma4RotaryCosSin(gridH: number, gridW: number, headDim: number, theta: number): {
-  cos: Float32Array;
-  sin: Float32Array;
-};
-/**
- * Build the [Np, N] average-pooling matrix for k×k spatial pooling over the real
- * (unpadded) grid, matching modeling_gemma4's kernel_idxs/one_hot pooling:
- *   cell(p) = floor(x_p/k) + ceil(gridW/k) * floor(y_p/k)
- *   poolMatrix[cell, p] = 1/k²  (so pooled = poolMatrix @ hidden = mean over the k×k block)
- * Np = ceil(gridH/k) * ceil(gridW/k). Each pooled cell averages exactly the patches
- * that fall in it (edge cells with fewer than k² patches still divide by k², matching
- * HF's fixed 1/k² normalization).
- */
-declare function buildGemma4PoolMatrix(gridH: number, gridW: number, k: number): {
-  poolMatrix: Float32Array;
-  numPooled: number;
-};
+//#region src/gpu/executor.d.ts
 /**
- * Build all Gemma 4 vision host tensors for one image grid in one call.
- * `posEmbedTable` is the raw [2, posSize, hidden] flattened table.
+ * Safari/Metal workaround: shader variant alternation.
+ * Metal caches argument buffers per compiled function. When consecutive dispatches
+ * use the same WGSL code (same Metal function), Metal reuses the previous dispatch's
+ * argument buffer, ignoring setBindGroup(). We alternate between variant 0/1 of each
+ * shader (prepending `const _MV: u32 = Xu;`) to force different Metal function
+ * specializations, preventing argument buffer reuse.
  */
-declare function buildGemma4VisionPositionTensors(gridH: number, gridW: number, posEmbedTable: Float32Array, posSize: number, cfg: Gemma4VisionGridConfig): Gemma4VisionPositionTensors;
-/** Gemma 4 image processor config (from processor_config.json). */
-declare const GEMMA4_IMAGE_PROCESSOR: ImageProcessorConfig;
-interface Gemma4PreprocessedImage {
-  /** Flattened patches [N, 3·patch²] row-major (row-major patch grid). */
-  patches: Float32Array;
-  /** Patch grid (gridH, gridW). */
-  gridHW: [number, number];
+interface ExecutorOptions {
+  maxSeqLen: number;
+  /** KV cache kernel strategy. Defaults to "native-f16" when not specified. */
+  kvMode?: KvMode;
+  /**
+   * WebKit only: dispatches per command buffer, with at most one command
+   * buffer in flight (awaited). 1 (default) is the proven-correct floor on
+   * iPad; larger values are faster if this WebKit version keeps storage
+   * writes visible across dispatches within one submission. Sweepable via
+   * the ?group=N URL param.
+   */
+  webkitGroupSize?: number;
 }
-/**
- * Preprocess a decoded RGB image for the Gemma 4 ViT: aspect-preserving resize so
- * the patch grid is ≤ max_soft_tokens·k² patches and H,W divisible by k·patch,
- * rescale ×1/255 (no normalize), patchify row-major into [N, 3·16·16].
- *
- * @param pixels row-major HWC RGB (0..255), length width*height*3.
- */
-declare function preprocessImageGemma4(pixels: Float32Array | Uint8ClampedArray | Uint8Array, width: number, height: number, maxSoftTokens?: number, poolingKernelSize?: number, patchSize?: number): Gemma4PreprocessedImage;
-interface ImageProcessorConfig {
-  patchSize: number;
-  temporalPatchSize: number;
-  mergeSize: number;
-  imageMean: [number, number, number];
-  imageStd: [number, number, number];
-  /** rescale factor applied to raw 0..255 pixels before normalization (1/255). */
-  rescaleFactor: number;
-  /** min total pixels after resize (shortest_edge). */
-  minPixels: number;
-  /** max total pixels after resize (longest_edge). */
-  maxPixels: number;
+interface ForwardResult {
+  logits: Float32Array;
 }
-declare const QWEN3_5_IMAGE_PROCESSOR: ImageProcessorConfig;
-interface PreprocessedImage {
-  /** Flattened patches [N, 1536] in the spatial-merge order encodeImage expects. */
-  patches: Float32Array;
-  /** (t, h, w) patch grid. t=1 for a single image, h/w in patch units. */
-  gridTHW: [number, number, number];
+/** One tensor reference of a decode-graph node, with its pool-buffer identity. */
+interface DecodeGraphTensorRef {
+  tensor: string;
+  /** Declared shape (may contain symbolic dims "T" / "L_max"). */
+  shape: Array<number | string>;
+  /** Shape resolved at T=1, seqPos = dump position. */
+  resolvedShape: number[] | null;
+  /** Label of the GPUBuffer this tensor is bound to. Pooled activation
+   * buffers are shared by many tensors — equal labels here = aliasing. */
+  buffer: string | null;
+  bufferBytes: number | null;
+}
+/** One ORIGINAL (pre-fusion) graph node covered by a dispatch entry. */
+interface DecodeGraphNode {
+  id: string;
+  opType: string;
+  inputs: DecodeGraphTensorRef[];
+  outputs: DecodeGraphTensorRef[];
+  attributes: Record<string, number | string | boolean>;
+}
+/** One entry of the post-fusion decode dispatch list (= one GPU dispatch). */
+interface DecodeGraphEntry {
+  index: number;
+  nodeId: string;
+  /** Anchor node's opType (fused entries report their anchor constituent). */
+  opType: string;
+  fused: boolean;
+  /** Pre-fusion constituent node ids, execution order. Null when unfused. */
+  fusedNodeIds: string[] | null;
+  /** Storage (non-uniform) bindings the kernel declares. */
+  storageBindings: number;
+  totalBindings: number;
+  dispatchSize: [number, number, number] | null;
+  paramsBytes: number;
+  /** Uniform params as raw u32 words (f32 fields appear as their bit pattern). */
+  paramsU32: number[];
+  /** Buffer labels in bind-group order, when captured at entry creation. */
+  bindBufferLabels: string[] | null;
+  /** The original graph nodes this dispatch covers (1 for unfused entries). */
+  nodes: DecodeGraphNode[];
+}
+interface DecodeGraphDump {
+  dispatchesPerToken: number;
+  unfusedDispatchesPerToken: number;
+  maxStorageBuffersPerShaderStage: number;
+  /** seqPos the shapes/params were resolved at (T=1 decode step). */
+  dumpSeqPos: number;
+  /** Every GPU buffer referenced by the decode entries. */
+  buffers: Array<{
+    label: string;
+    bytes: number;
+    kind: string;
+  }>;
+  entries: DecodeGraphEntry[];
 }
-/**
- * Qwen2-VL smart-resize: round H and W to multiples of factor=patch*merge,
- * keeping aspect ratio and clamping the total pixel budget to [minPixels, maxPixels].
- * Matches transformers.models.qwen2_vl.image_processing.smart_resize.
- */
-declare function smartResize(height: number, width: number, factor: number, minPixels: number, maxPixels: number): [number, number];
-/**
- * Preprocess a decoded RGB image into the [N, 1536] patch tensor + grid_thw that
- * `encodeImage()` expects, matching the HF Qwen2-VL image processor:
- *   smart_resize → rescale (×1/255) → normalize → temporal-pair (×temporal_patch_size)
- *   → patchify into spatial_merge×spatial_merge blocks → flatten to [N, C·T·P·P].
- *
- * @param pixels row-major HWC RGB, length width*height*3. Values 0..255 (default)
- *   or already 0..1 if `rescaled` is true.
- * @param width  source pixel width
- * @param height source pixel height
- */
-declare function preprocessImage(pixels: Float32Array | Uint8ClampedArray | Uint8Array, width: number, height: number, cfg?: ImageProcessorConfig, rescaled?: boolean): PreprocessedImage;
-declare function buildMRoPEPositionIds(inputIds: Int32Array | Uint32Array | number[], imageGrids: Array<[number, number, number]>, imageTokenId: number, mergeSize: number): Int32Array;
-/**
- * Per-pair frequency→dimension assignment for interleaved M-RoPE, matching
- * Qwen3_5TextRotaryEmbedding.apply_interleaved_mrope. For pair index i in
- * [0, sum(section)) the position component is section-cyclic: T,H,W,T,H,W,...
- * but each component capped at its section count. Returns an array of length
- * (rope_dim/2) with values 0=T, 1=H, 2=W.
- */
-declare function mropeFreqDims(mropeSection: [number, number, number]): Int32Array;
-/**
- * Build the interleaved-M-RoPE cos/sin tables [seq, rope_dim] from 3D position
- * ids, matching Qwen3_5TextRotaryEmbedding.forward:
- *   freqs[d][i] = pos[d] * inv_freq[i],  inv_freq[i] = 1/theta^(2i/rope_dim)
- *   freq[i] picks component mropeFreqDims[i]; emb = cat(freqs, freqs).
- * cos/sin have length seq*rope_dim. For text-only (all 3 pos rows equal) this
- * reduces exactly to standard 1D partial RoPE.
- *
- * @param positionIds3 [3, seq] as produced by buildMRoPEPositionIds.
- * @param ropeDim      number of rotated dims per head (head_dim * partial_factor).
- */
-declare function buildMRoPECosSin(positionIds3: Int32Array, seq: number, ropeDim: number, theta: number, mropeSection: [number, number, number]): {
-  cos: Float32Array;
-  sin: Float32Array;
-};
-//#endregion
-//#region src/gpu/defaults.d.ts
-/**
- * Default model per capability. Kept in its own tiny module (no heavy imports)
- * so the React hooks can resolve defaults without statically pulling in the GPU
- * engine — they import the engine dynamically to stay light.
- */
-declare const DEFAULT_MODELS: {
-  /** Text generation (also the vision-capable checkpoint). */
-  readonly text: "mlx-community/Qwen3.5-0.8B-4bit";
-  /** Image understanding — same checkpoint, vision tower built on demand. */
-  readonly vision: "mlx-community/Qwen3.5-0.8B-4bit";
-  /** Text embeddings. */
-  readonly embedding: "mlx-community/embeddinggemma-300m-4bit";
-  /** Text-to-speech (Apache-2.0; LFM2-350M backbone + NanoCodec). Small/fast default. */
-  readonly tts: "nineninesix/kani-tts-450m-0.2-ft";
-  /**
-   * Selectable many-voices TTS (OuteTTS-1.0-0.6B: Qwen3-0.6B codec-LM + DAC.speech).
-   * Pass this as the `repo`/`model` to engine.speak()/useTTS to route to OuteTTS.
-   */
-  readonly ttsOute: "OuteAI/OuteTTS-1.0-0.6B";
+declare class Executor {
+  private ctx;
+  private graph;
+  /** Output tensor names of this executor's graph (read-only; used by non-LM
+   * codec executors that need to locate the decoded-audio output tensor). */
+  get graphOutputs(): string[];
+  private weightBuffers;
+  private activationBuffers;
+  private ssmStateBuffers;
+  private kvCacheBuffers;
+  /** Pre-allocated input_ids buffer (maxSeqLen * 4 bytes). */
+  private inputIdsBuffer;
+  /**
+   * CPU-resident Per-Layer-Embeddings (PLE) source for Gemma 4. The PLE table
+   * (`embed_tokens_per_layer`, [vocab, L*256]) is ~1.17GB at 4-bit and is kept
+   * OFF the GPU. Each forward step we gather + dequantize only the rows for the
+   * actual input tokens and upload a tiny [T, L*256] f32 buffer. See setPleSource.
+   */
+  private pleSource;
+  /** Reusable scratch for the dequantized PLE rows (resized on demand). */
+  private pleScratch;
+  /**
+   * One-time promise that materializes a cache-backed PLE table into heap. The
+   * table is read from CacheStorage on the FIRST forward — i.e. AFTER the GPU
+   * weight upload has completed, so the ~1.17 GB does not stack on top of the
+   * upload's transient allocations at the load-time memory high-water mark.
+   */
+  private pleReady;
+  /**
+   * Dummy GPU buffer bound to an otherwise-aliasing storage-read-write slot.
+   * Used by RoPE-Q-only nodes (Gemma 4 KV-shared layers) whose node lists the
+   * same tensor as input and output: the RoPE kernel always declares two
+   * read_write bindings (q, k), but with num_kv_heads=0 the k slot is never
+   * touched. WebGPU still rejects two read_write bindings aliasing one buffer,
+   * so we bind this throwaway buffer to the unused k slot. Allocated lazily.
+   */
+  private bindingScratchBuffer;
+  /** Readback buffer for logits. */
+  private logitsReadback;
+  /** GPU buffer for argmax result (1 u32). */
+  private argmaxResultBuffer;
+  /** Readback buffer for argmax result (1 u32). */
+  private argmaxReadback;
+  /** Readback ring for pipelined greedy decode (created lazily). */
+  private decodeReadbacks;
+  /** Window size K (GERBIL_DECODE_WINDOW). 0 = off. */
+  readonly decodeWindowK: number;
+  /** Readback ring for decode windows (4·K bytes per slot; created lazily). */
+  private windowReadbacks;
+  /**
+   * Per-step uniform/bind-group variants for the few seq-pos-dependent decode
+   * entries (RoPE position, KV-append offset, attention S). Keyed by nodeId;
+   * index k holds the variant used at window step k (1..K-1 — step 0 uses the
+   * entry's base uniform). Created lazily, rewritten per window pre-submit.
+   */
+  private windowVariants;
+  /**
+   * Staging buffer for uniform param updates.
+   * Safari/Metal has weaker visibility guarantees for queue.writeBuffer() to
+   * UNIFORM buffers — early writes get dropped when hundreds are queued.
+   * Instead, we pack all params into this STORAGE staging buffer (1 writeBuffer),
+   * then use encoder.copyBufferToBuffer to distribute to each uniform buffer.
+   * Copies are GPU-sequenced and guaranteed to complete before compute passes.
+   */
+  private uniformStagingBuffer;
+  private uniformStagingCapacity;
+  /** Dispatch entries for prefill (M>1): uses tiled matmul kernels. */
+  private dispatchEntries;
+  /** Dispatch entries for decode (M=1): uses K-parallel matvec kernels. */
+  private decodeEntries;
+  /**
+   * Column-concatenated INT4 weight buffers built by the Mamba-front fusion
+   * (qkv|a|b|z packed into one q/scales/zeros set per layer). Retained here so
+   * they outlive the fusion pass and are not garbage-collected while the fused
+   * bind groups still reference them.
+   */
+  private mambaFrontConcatBuffers;
+  /** Per-node decode entries captured BEFORE fusion (the overlay base). */
+  private decodeEntriesUnfused;
+  /** True while a runtime adapter is applied. */
+  private loraActive;
+  /** Decode entries (unfused base + spliced LoRA dispatches). */
+  private decodeEntriesLoRA;
+  /** Prefill entries (base + spliced LoRA dispatches). */
+  private prefillEntriesLoRA;
+  /** GPU buffers owned by the current adapter (A/B factors + tmp); freed on swap. */
+  private loraBuffers;
+  /** Argmax dispatch entry (created in initBindGroups). */
+  private argmaxEntry;
+  /** True when running on Safari/WebKit (needs multi-encoder submit). */
+  readonly needsMultiEncoder: boolean;
+  private maxSeqLen;
+  private kvMode;
+  private seqPos;
+  private webkitGroupSize;
+  private readonly pagedKV;
+  private kvBlockManager;
+  /** Lockstep batch width (GERBIL_BATCH). 0 = batching off. */
+  readonly batchSize: number;
+  /** Block-table row stride — set for any paged mode. */
+  private maxBlocksPerSeq;
+  /** Block-table row the single-sequence paths target (batch prefill slot). */
+  private activeSeqSlot;
+  /** Batched dispatch entries (built once in initBindGroups when batch on). */
+  private batchEntries;
+  /** Per-slot SSM/conv state pools: slot b's state at offset b*slotBytes. */
+  private batchSsmPools;
+  /** Batch-widened tail buffers (SliceLastRow output + logits at [N, ...]). */
+  private batchTailBuffers;
+  private batchPositionsBuffer;
+  private batchSeqLensBuffer;
+  private batchSampledBuffer;
+  private batchReadbacks;
+  private batchArgmaxEntry;
+  /** JS-side authoritative per-slot token counts (positions source). */
+  private batchSeqLens;
+  /** Scratch for per-step positions/seq_lens uploads. */
+  private batchPositionsScratch;
+  private batchSeqLensScratch;
+  /** Cached batch-resolved shapes (static: T == batchSize every step). */
+  private batchShapes;
+  /** True once the batched-argmax uniform has been written this session. */
+  private batchArgmaxParamsWritten;
+  /** True when GERBIL_BATCH_LORA=1 rode in on an active batch path. */
+  readonly batchLoraEnabled: boolean;
+  /** Registered adapters (expanded deltas), indexed by adapter id. */
+  private batchAdapterDeltas;
+  /** Per-lane adapter ids (u32; 0xFFFFFFFF = bare base). */
+  private batchAdapterIdsBuffer;
+  /** GPU buffers owned by the batch-LoRA overlay (factors, maps, tmp, uniforms). */
+  private batchLoraBuffers;
+  /** Batch entries snapshotted BEFORE the batch fusion passes (overlay base). */
+  private batchEntriesUnfused;
+  /** Batch entries with the per-lane LoRA dispatches spliced in. */
+  private batchEntriesLoRA;
+  /** True while at least one lane carries an adapter (set by setBatchLaneAdapters). */
+  private batchLoraActive;
+  private profileEnabled;
+  private readonly profileData;
+  private querySet;
+  private queryResolveBuf;
+  private queryReadbackBuf;
+  constructor(ctx: GPUContext, graph: ModelGraph, options: ExecutorOptions);
+  /**
+   * Register the CPU-resident Gemma 4 PLE table. The quantized table is kept in
+   * JS memory (NOT uploaded to a GPU buffer), and {@link forward} gathers +
+   * dequantizes only the rows for the current input tokens each step, uploading a
+   * small [T, width] f32 buffer into `targetTensor`. This is what keeps Gemma 4
+   * mobile-viable: resident GPU memory is just the active transformer weights.
+   */
+  setPleSource(src: {
+    packed: Uint32Array;
+    scales: Float32Array;
+    zeros: Float32Array;
+    width: number;
+    groupSize: number;
+    targetTensor: string;
+    cache?: {
+      cacheName: string;
+      packedKey: string;
+      scalesKey: string;
+      zerosKey: string;
+      packedLen: number;
+    };
+  }): void;
+  /**
+   * True when this model streams a CPU-resident Per-Layer-Embedding table
+   * (Gemma 4): each decode step must gather+upload the PLE rows for the ACTUAL
+   * input token id on the CPU before the forward runs. The GPU-chained pipelined
+   * decode path and forwardArgmax both bypass CPU token knowledge, so they leave
+   * `ple_embed_out` stale and must NOT be used for these models — only the
+   * per-step forward() path (which calls streamPleRows) is correct. See generate().
+   */
+  hasPleSource(): boolean;
+  /**
+   * Materialize a cache-backed PLE table into heap exactly once. Deferred to the
+   * first forward (after GPU upload) so the ~1.17 GB table is not co-resident
+   * with the upload's transient allocations during the load-time memory peak.
+   */
+  private ensurePleLoaded;
+  /**
+   * Gather + dequantize the PLE rows for `inputIds` and upload them into the
+   * target activation buffer. Touches only T rows (T*width floats) — the full
+   * [vocab, width] quantized table never goes to the GPU.
+   */
+  private streamPleRows;
+  /**
+   * Stream weights to the GPU one tensor at a time, pulling each from the
+   * `WeightSource` only when it is about to be uploaded and dropping the
+   * reference immediately afterward.
+   *
+   * This is the property that bounds peak JS heap: with a cache-backed source
+   * (browser/mobile), only ONE tensor's bytes are materialized in heap at a time
+   * (read from CacheStorage in `source.get()`), uploaded to its GPU buffer, then
+   * released before the next tensor is fetched. The whole model is never co-
+   * resident in heap. With a heap-backed source (Node/desktop), behavior matches
+   * the old Map path (the source deletes each entry as it is consumed).
+   *
+   * Accepts either a `WeightSource` (new, streamed/async) or a plain Map
+   * (back-compat for callers that build a Map directly, e.g. Kani/Moonshine).
+   */
+  uploadWeights(source: WeightSource | Map<string, {
+    data: ArrayBufferView;
+    shape: number[];
+  }>): Promise<void>;
+  /**
+   * Synchronous Map upload (Node/desktop and the Kani/Moonshine sub-executors,
+   * which build small heap Maps). Deletes each entry as it is consumed to free
+   * the JS-side bytes once they are GPU-resident. Safe to call from a constructor.
+   */
+  uploadWeightsMap(weights: Map<string, {
+    data: ArrayBufferView;
+    shape: number[];
+  }>): void;
+  /**
+   * Build all pipelines and bind groups. Call ONCE after uploadWeights().
+   *
+   * Creates two dispatch entry arrays:
+   * - dispatchEntries: tiled matmul for prefill (any M)
+   * - decodeEntries: K-parallel matvec for decode (M=1)
+   */
+  initBindGroups(): void;
+  /** True while a runtime LoRA overlay is applied. */
+  get hasRuntimeAdapter(): boolean;
+  /** Decode entries in effect for the current adapter state. */
+  private get activeDecodeEntries();
+  /**
+   * Apply a runtime LoRA overlay on the STATIC base. For each delta whose target
+   * maps to a base linear (MatMulInt4 / MatMul) with matching dims, uploads the
+   * f32 A/B factors and splices two low-rank dispatches — `tmp = A·x`, then
+   * `y += scaling·B·tmp` — right after that node in both the decode and prefill
+   * paths, so the corrected output is live before any consumer reads it.
+   *
+   * Rebuilds the overlay from scratch each call (this is how adapters hot-swap);
+   * the base weight buffers and bind groups are never touched or re-uploaded.
+   * Pass an empty list (or call {@link clearRuntimeLoRA}) to drop the overlay.
+   */
+  /** Find the base linear (MatMulInt4 / MatMul) node whose weight is `key`. */
+  private findBaseLinear;
+  /**
+   * Expand any fused query+gate delta into separate `q_proj` + `attn_gate`
+   * deltas so it can splice onto a deinterleaved runtime graph.
+   *
+   * Qwen3.5-style gated attention ships `q_proj.weight` fused as
+   * `[2·num_heads·head_dim, hidden]` (per-head: query rows then gate rows); the
+   * model loader splits it into two runtime linears (`q_proj`, `attn_gate`). An
+   * adapter trained on the fused checkpoint carries a single `q_proj` delta whose
+   * out-dim is 2× either split node, so it matches neither. When BOTH split
+   * linears exist and the delta is exactly their combined width, split it via the
+   * same per-head row deinterleave the loader uses; otherwise the delta passes
+   * through untouched (e.g. a base that never split the projection).
+   */
+  private expandFusedQGateDeltas;
+  applyRuntimeLoRA(deltas: LoRADelta[]): {
+    applied: number;
+    skipped: number;
+  };
+  /** Drop the runtime LoRA overlay and free its GPU buffers. Base is untouched. */
+  clearRuntimeLoRA(): void;
+  /** Build the [down, up] low-rank dispatch pair for one adapted node. */
+  private buildLoraPair;
+  /** Copy a base entry list, splicing each node's LoRA pair in right after it. */
+  private spliceLoraOverlay;
+  /** Original constituent node ids a (possibly fused) decode entry covers. */
+  private coveredNodeIds;
+  /**
+   * Build the decode entry list for an active adapter with SELECTIVE unfusing.
+   * Every fused group that covers no adapted linear is kept exactly as the
+   * no-adapter fast path runs it (full SwiGLU/dual/gated fusion, no numerics
+   * change). Only the groups that cover an adapted node fall back to their
+   * pre-fusion per-node dispatches (pulled from {@link decodeEntriesUnfused}),
+   * with the low-rank `[down, up]` pair spliced right after each adapted node so
+   * its corrected output is live before any consumer reads it. Replaying the
+   * exact pre-fusion entries reproduces the validated unfused numerics for the
+   * adapted groups while leaving all other groups on the fused path.
+   */
+  private buildSelectiveLoraDecode;
+  /**
+   * Run a forward pass. Uses matvec kernels for M=1 (decode), tiled for M>1 (prefill).
+   *
+   * `opts.readLogits: false` skips the logits copy + readback entirely (the
+   * returned logits array is empty) and returns right after submission — used
+   * by the scheduler's chunked prefill, where only the FINAL chunk's logits
+   * are ever sampled. seqPos still advances by T.
+   */
+  forward(inputIds: Uint32Array, opts?: {
+    readLogits?: boolean;
+  }): Promise<ForwardResult>;
+  /**
+   * Profiling variant of the desktop dispatch path: one compute pass per dispatch,
+   * each bracketed by timestamp queries, so we get per-op GPU time. Accumulates
+   * into profileData by opType. Only runs under GERBIL_PROFILE with timestamp-query
+   * support — slower than the batched path (it measures relative cost, not tok/s).
+   */
+  private runProfiledDispatches;
+  /** Per-opType GPU time (ns) + dispatch count accumulated by GERBIL_PROFILE, hottest first. */
+  getProfile(): Array<{
+    opType: string;
+    ns: number;
+    count: number;
+  }>;
+  /** Clear accumulated profiler data (e.g. to drop warm-up tokens). */
+  resetProfile(): void;
+  /** GPU dispatches per decode token (post-fusion). On mobile this drives the
+   * submit-group count = ceil(dispatchCount / webkitGroupSize). */
+  get decodeDispatchCount(): number;
+  /** Device limit that gates the INT4 projection fusions (they need ≥9). If a
+   * device caps at 8 the dual/gated/swiglu-gated INT4 fusions silently fall back,
+   * inflating the decode dispatch count. */
+  get maxStorageBuffers(): number;
+  /**
+   * Build a machine-readable dump of the post-fusion decode entry list (the
+   * exact per-token dispatch sequence), with per-tensor pool-buffer identities
+   * so pooled-aliasing hazards are visible offline. Debug/analysis only — never
+   * called on any hot path; reached via the GERBIL_DUMP_GRAPH hook at the end
+   * of {@link initBindGroups} or directly by tooling.
+   */
+  dumpDecodeGraph(dumpSeqPos?: number): DecodeGraphDump;
+  /**
+   * Profile ONE real decode step: times the actual `decodeEntries` (the kernels
+   * the pipelined greedy benchmark runs) with per-dispatch timestamps. Timing is
+   * token-independent, so pass any valid id; runs un-pipelined with a synchronous
+   * timestamp readback (measurement only, not for production decode). Argmax (one
+   * tiny dispatch) is intentionally excluded — it is not a hotspot target.
+   */
+  profileDecodeStep(tokenId: number): Promise<void>;
+  /**
+   * Profile ONE batched decode step (GERBIL_BATCH): times each batchEntries
+   * dispatch with timestamp queries, accumulating GPU ns per opType into the
+   * same profile as profileDecodeStep. Measurement-only (un-pipelined, CPU
+   * tokens). Call after prefilling the batch slots; advances every slot by
+   * one position like a real step.
+   */
+  profileBatchDecodeStep(tokens: Uint32Array<ArrayBuffer>): Promise<void>;
+  /**
+   * Run a single forward pass over `inputIds` and read back the L2-normalized
+   * embedding vector. Requires an embedding graph (one whose output tensor is
+   * "embedding", produced by the last-token-pool + L2-norm tail).
+   *
+   * Always runs in a fresh-state single pass (caller should reset() first):
+   * embeddings are non-autoregressive, so the whole sequence is one prefill.
+   */
+  embed(inputIds: Uint32Array): Promise<Float32Array>;
+  /**
+   * Generic one-shot dispatch for a non-LM graph: run every entry once over a
+   * single forward and read back `elemCount` f32 elements of the named output
+   * tensor. Used to execute the NanoCodec decoder graph (codes→PCM) — its ops use
+   * concrete lengths and it has no "logits" output, so the normal forward()
+   * logits-readback path does not apply. Caller writes any inputs (e.g. audio_codes)
+   * via writeInput() and reset()s first.
+   */
+  runGraphOutput(outputName: string, elemCount: number): Promise<Float32Array>;
   /**
-   * Selectable describe-your-voice TTS (Parler-TTS-mini-v1: Flan-T5 encoder +
-   * cross-attending decoder LM + dac_44khz). Pass this as the `repo`/`model` to
-   * engine.speak()/useTTS with a `describeVoice` natural-language description.
+   * Autoregressive step for a multi-output decoder graph (e.g. Parler-TTS's 9 codebook
+   * lm_heads). Dispatches the whole graph ONCE at the current seqPos (so the per-layer
+   * KVCacheAppend writes at the right cache row), reads back each named output, then
+   * advances seqPos by `tokens` (default 1, for a prefilled prompt span pass tokens=T).
+   * The caller writes inputs (dec_input_embed + frozen cross-attn K/V) and reset()s
+   * before the first step. Unlike forward(), there is no single "logits" output —
+   * the caller decodes each codebook row itself.
    */
-  readonly ttsParler: "parler-tts/parler-tts-mini-v1";
-  /** Speech-to-text. */
-  readonly stt: "UsefulSensors/moonshine-base";
-};
-declare const OUTETTS_ASSETS: {
-  /** Folded DAC.speech.v1.0 encoder+decoder weights (prep-dac-speech.py output). */
-  readonly codecWeightsURL: "https://pub-0522ecec25fc412bb35a523f3e3f63c6.r2.dev/tryhamster/gerbil-outetts-assets/dac-speech-folded.safetensors";
-  /** Base URL for the preset speaker JSONs (`{name}.json`). */
-  readonly speakersBaseURL: "https://pub-0522ecec25fc412bb35a523f3e3f63c6.r2.dev/tryhamster/gerbil-outetts-assets/speakers";
-  /** The default preset voice. */
-  readonly defaultVoice: "en-female-1-neutral";
-};
-/**
- * Bundled OuteTTS preset voices.
- *
- * Provenance (honest labelling):
- *  - `en-female-1-neutral` is the ONE AUTHENTIC OuteAI voice — the OuteTTS v3 bundled
- *    default speaker (default_speakers/en-female-1-neutral), copied verbatim.
- *  - `gerbil-voice-2..6` are DERIVED voices: distinct timbres produced by running
- *    pitch/tempo-varied renderings of that authentic clip back through the REAL
- *    DAC.speech encode + prosody pipeline (scripts/engine/stage-outetts-assets.py).
- *    They are genuine DAC-encoded OuteSpeakers, but they are NOT OuteAI's own
- *    `en-male-*` voices, so they are not labelled as such. (Earlier builds mislabelled
- *    them as `en-male-2-neutral` etc.; renamed for honesty.)
- */
-declare const OUTETTS_PRESET_VOICES: readonly ["en-female-1-neutral", "gerbil-voice-2", "gerbil-voice-3", "gerbil-voice-4", "gerbil-voice-5", "gerbil-voice-6"];
-/**
- * True when `repo`/`architecture` identify a text-to-speech checkpoint that must
- * run through a dedicated native TTS engine (KaniTTS, OuteTTS, or Parler-TTS)
- * rather than the single-graph base text loader. Mirrors the routing used by
- * `WebGPUEngine.speak()` / `Gerbil.ensureNativeTTSEngine`:
- *   - Parler  → encoder-decoder (`ParlerTTSForConditionalGeneration`)
- *   - OuteTTS → Qwen3-0.6B codec-LM
- *   - Kani    → conv-backbone codec-LM (`KaniTTS2ForCausalLM`, or the Apache
- *               default which is a plain `Lfm2ForCausalLM` — hence the repo-name
- *               gate; the architecture string alone does not identify it).
- * At `create()` time only the repo is known (the architecture is discovered
- * during load), so the repo-name signals below cover all three DEFAULT_MODELS
- * and conventionally-named TTS repos; the architecture arg is honored when a
- * caller already has it.
- */
-declare function isTTSRepo(repo?: string, architecture?: string): boolean;
-/** Resolve the model repo for a set of options, falling back to the defaults. */
-declare function resolveDefaultRepo(opts: {
-  repo?: string;
-  embedding?: boolean;
-  enableVision?: boolean;
-}): string;
-//#endregion
-//#region src/gpu/architectures/gemma4_vision.d.ts
-interface Gemma4VisionGraphInfo {
-  hiddenSize: number;
-  numHeads: number;
-  headDim: number;
-  depth: number;
-  intermediateSize: number;
-  textHidden: number;
-  patchSize: number;
-  patchDim: number;
-  poolingKernelSize: number;
-  ropeTheta: number;
-  rmsNormEps: number;
-}
-/**
- * Resolve the Gemma 4 vision dims from a raw HF config. Accepts either the
- * top-level config (reads `.vision_config` + `.text_config.hidden_size`) or a
- * bare vision_config (then `textHidden` falls back to the projector row count if
- * present, else hidden). Family-general — no E2B constants.
- */
-declare function resolveGemma4VisionInfo(rawConfig: Record<string, unknown>): Gemma4VisionGraphInfo;
-/**
- * Dequantize an MLX affine-int4 weight to a plain f32 [rows, cols] matrix.
- * MLX packs 8 int4 values per u32 (low-nibble first); each group of `groupSize`
- * columns shares one scale + bias: w[r,c] = scale[r, c/gs] * q + bias[r, c/gs].
- * Used for the Gemma 4 multimodal projector (`embed_vision.embedding_projection`)
- * in MLX-4bit checkpoints, where (unlike the BF16 ViT body) the projector is int4.
- */
-declare function dequantizeMLXProjection(packed: Uint32Array, scales: Float32Array, biases: Float32Array, rows: number, cols: number, groupSize: number): Float32Array;
-/**
- * If the Gemma 4 multimodal projector arrived as an MLX affine-int4 triplet
- * (`embed_vision.embedding_projection.{weight(U32), scales, biases}`), dequantize
- * it in-place to a plain f32 `embed_vision.embedding_projection.weight` and drop
- * the scales/biases, so the vision graph's plain MatMul on the projector works for
- * MLX-4bit checkpoints too. No-op for BF16 (HF) checkpoints (weight already f32).
- */
-declare function dequantizeGemma4VisionProjection(weights: Map<string, {
-  data: ArrayBufferView;
-  shape: number[];
-}>, groupSize: number, rows: number, cols: number): void;
-/**
- * Patch the ClippedMatMul nodes of a Gemma 4 vision graph with the calibrated clip
- * scalars from the checkpoint (Gemma4ClippableLinear's per-tensor input/output
- * min/max buffers), then drop those scalar tensors from the weights map so the
- * vision executor doesn't try to upload them as GPU buffers. Call BEFORE
- * VisionExecutor.uploadWeights(). Missing scalars default to ±inf (clip = identity),
- * so a checkpoint without calibration still loads.
- */
-declare function patchGemma4VisionClips(graph: ModelGraph, weights: Map<string, {
-  data: ArrayBufferView;
-  shape: number[];
-}>): void;
-/**
- * Build the Gemma 4 ViT graph. Shaped by symbolic "N" (number of patches, runtime)
- * and "Np" (number of pooled tokens = ceil(grid_h/k)·ceil(grid_w/k), runtime),
- * resolved from input tensor dims — like the Qwen ViT's "N"/"Nm".
- */
-declare function generateGemma4VisionGraph(rawConfig: Record<string, unknown>): ModelGraph;
-//#endregion
-//#region src/gpu/architectures/kani_tts.d.ts
-/** Parsed KaniTTS2 backbone config (the LFM2 dims + the TTS-specific fields). */
-interface KaniConfig {
-  textVocabSize: number;
-  vocabSize: number;
-  tokensPerFrame: number;
-  audioStep: number;
-  useLearnableRope: boolean;
-  alphaMin: number;
-  alphaMax: number;
-  speakerEmbDim: number;
-  audioTokensStart: number;
-  startOfSpeech: number;
-  endOfSpeech: number;
-  codebookSize: number;
+  runGraphStep(outputs: Array<{
+    name: string;
+    elemCount: number;
+  }>, tokens?: number): Promise<Float32Array[]>;
   /**
-   * Whether the backbone uses KaniTTS2's frame-level position IDs (the 4 audio
-   * tokens of a frame share one logical position) + learnable per-layer RoPE.
-   * The `KaniTTS2ForCausalLM` checkpoints (e.g. kani-tts-2-en) do; the plain
-   * `Lfm2ForCausalLM` family (e.g. the Apache kani-tts-450m-0.2-ft / kani-tts-370m)
-   * does NOT — those run standard sequential positions with α=1 plain RoPE.
-   * Detected from the presence of `use_learnable_rope`/`tokens_per_frame`/the
-   * `KaniTTS2ForCausalLM` architecture marker in config.json.
+   * Greedy decode step: forward + GPU argmax. Returns token ID directly.
+   * Always uses matvec kernels (M=1). Reads back 4 bytes instead of vocab_size*4.
    */
-  frameLevelPositions: boolean;
-}
-declare function parseKaniConfig(rawConfig: Record<string, unknown>): KaniConfig;
-/**
- * Convert the model's flat audio-token stream (the IDs between start/end-of-speech)
- * into NanoCodec codes [NUM_GROUPS, T]. Mirrors NemoAudioPlayer.get_nano_codes:
- *   reshape [-1, 4]; codes[:,c] -= codebook_size*c; codes -= audio_tokens_start;
- *   transpose → [4, T]. Returns a Uint32Array laid out group-major ([g*T + t]).
- */
-declare function audioTokensToCodes(audioTokenIds: number[], cfg?: KaniConfig): {
-  codes: Uint32Array;
-  numFrames: number;
-};
-interface NanoCodecGraphOptions {
-  /** Number of audio frames T (the code grid width). PCM length = T * 1764. */
-  numFrames: number;
-}
-declare function generateNanoCodecDecoderGraph(opts: NanoCodecGraphOptions): ModelGraph;
-/**
- * Generate the KaniTTS codec-LM backbone graph (LFM2-350M body, full-vocab logits,
- * per-layer learnable MRoPE). Mirrors generateLfm2Graph block-for-block; the only
- * difference is that each attention layer rotates Q/K with the MRoPE op fed a
- * per-layer host cos/sin table instead of the position-counter RoPE op.
- *
- * dtype:
- *   • undefined / "f32" — full precision (the checkpoint is bf16/f32 → f32).
- *   • "q4" — weight-only group-wise INT4 (W4A16) for the LFM2 linear projections
- *     (q/k/v/o, gate/up/down, short-conv in/out_proj) via MatMulInt4. The tied
- *     embedding + LM head stay at f32 on purpose: decoder-LM heads are the most
- *     quantization-sensitive part of a codec-LM and the embed table is the single
- *     buffer shared by both, so quantizing it would degrade audio quality for no
- *     load-size win that the int4 projections do not already capture. Backbone
- *     drops from ~1.5 GB (f32) to ~0.37 GB. The NanoCodec decoder is a separate
- *     graph and always runs f32.
- */
-declare function generateKaniTtsGraph(rawConfig: Record<string, unknown>, dtype?: GraphDType, groupSize?: number, kvDtype?: KVDType): ModelGraph;
-//#endregion
-//#region src/gpu/architectures/moonshine.d.ts
-/**
- * Historical record of the executor-side work the keystone left open; all items
- * are now implemented (see the STATUS note above). Retained as exported
- * documentation of the dependency surface.
- */
-declare const MOONSHINE_REMAINING_WORK: readonly ["DONE: Transpose op kernel (conv output [C,L] → encoder input [L,C]).", "DONE: GroupNorm(num_groups=1) over conv channels (weight+bias).", "DONE: Tanh elementwise op (conv1 activation).", "DONE: Interleaved-RoPE variant (Moonshine rotates adjacent dim pairs 2p/2p+1).", "DONE: No-bias LayerNorm variant (Moonshine norms are weight-only).", "DONE: Per-utterance conv graph regeneration from the concrete sample count.", "DONE: Dual-graph executor — encoder once → frozen cross-attn K/V → AR decode.", "DONE: engine.transcribe(pcm) host path (MoonshineSTT): conv → encode → AR decode → detokenize."];
-interface MoonshineDims {
-  hidden_size: number;
-  enc_layers: number;
-  dec_layers: number;
-  num_heads: number;
-  num_kv_heads: number;
-  head_dim: number;
-  rotary_dim: number;
-  intermediate_size: number;
-  vocab_size: number;
-  rope_base: number;
-  context_length: number;
-  ln_eps: number;
-}
-/** Pull and derive Moonshine dimensions from the raw HF config. */
-declare function parseMoonshineConfig(raw: Record<string, unknown>): MoonshineDims;
-/** Number of encoder frames produced by the conv frontend for n_samples PCM. */
-declare function moonshineEncoderFrames(nSamples: number): number;
-/**
- * Encoder graph: raw-waveform conv frontend + bidirectional transformer.
- * @param nSamples concrete PCM sample count (the conv frontend is length-static).
- * The output tensor "encoder_out" is [T_frames, hidden] and is consumed (after
- * per-layer K/V projection) as the frozen K/V for the decoder's cross-attention.
- */
-declare function generateMoonshineEncoderGraph(raw: Record<string, unknown>, nSamples: number): ModelGraph;
-/**
- * Decoder graph: AR transformer with causal self-attn (KV-cache) + cross-attn to
- * the frozen encoder output. Built for a single decode step (T=1). The encoder K/V
- * are supplied as graph inputs "enc_k_layer{i}" / "enc_v_layer{i}" — the host
- * pre-projects the encoder output through each layer's encoder_attn.k_proj/v_proj
- * ONCE and binds them frozen for the whole decode (the CrossAttention contract).
- */
-declare function generateMoonshineDecoderGraph(raw: Record<string, unknown>, sEnc: number): ModelGraph;
-//#endregion
-//#region src/gpu/architectures/outetts.d.ts
-/** Parsed OuteTTS backbone config (the Qwen3 dims). Reuses the generic Qwen path. */
-interface OuteTtsConfig {
-  hidden_size: number;
-  num_layers: number;
-  num_heads: number;
-  num_kv_heads: number;
-  head_dim: number;
-  intermediate_size: number;
-  vocab_size: number;
-  rope_base: number;
-  rms_norm_eps: number;
-  max_position_embeddings: number;
-}
-declare function parseOuteTtsConfig(rawConfig: Record<string, unknown>): OuteTtsConfig;
-/**
- * Convert the flat generated token stream (the run BETWEEN <|audio_start|> and
- * <|audio_end|>) into a DAC code grid [NUM_CODEBOOKS, T] (codebook-major [c*T + t]).
- *
- * Mirrors outetts v3 `extract_audio_from_tokens`: filter the stream into two ordered
- * lists by membership of the c1 / c2 ranges, recover the raw code
- * (id − base), drop the reserved index 1024, and truncate to the shorter list. The
- * model emits c1,c2 interleaved per frame, but the parse is membership-based (it does
- * not assume strict pairing) so a stray token cannot desync the grid.
- */
-declare function audioTokensToDacCodes(tokenIds: number[]): {
-  codes: Uint32Array;
-  numFrames: number;
-};
-interface DacSpeechGraphOptions {
-  /** Number of audio frames T (the code-grid width). */
-  numFrames: number;
+  forwardArgmax(inputIds: Uint32Array): Promise<number>;
+  /** KV-cache positions still available for decode steps. */
+  decodeCapacityRemaining(): number;
+  /** Number of decode steps that may be in flight in the pipelined path. */
+  static readonly PIPELINE_DEPTH = 2;
   /**
-   * Number of RVQ codebooks. Default 2 (DAC.speech.v1.0). Parler-TTS's
-   * dac_44khz_8kbps uses 9 — the RVQDequant kernel loops over NCB so the only
-   * change is the codebook/out_proj tensor first-dim and the codes grid height.
+   * Pipelined greedy decode step (Dawn only — WebKit uses forwardArgmax).
+   *
+   * Encodes one full decode forward + argmax and submits WITHOUT awaiting
+   * completion. The input token is taken from `tokenId` for the first step
+   * after prefill; for subsequent steps (tokenId === null) the previous step's
+   * argmax result is copied into input_ids ON THE GPU, so the decode loop
+   * never blocks on a readback before submitting the next step. The argmax
+   * result is copied to a per-slot readback buffer, read later (one step
+   * behind) via readDecodeToken(slot).
+   *
+   * queue.writeBuffer is queue-ordered: uniform updates land after the
+   * previously submitted step's command buffer and before this one's, so
+   * shared uniform buffers are safe with multiple steps in flight.
    */
-  numCodebooks?: number;
+  submitGreedyDecodeStep(tokenId: number | null, slot: number): void;
+  /** Read back the token produced by the pipelined step that used `slot`. */
+  readDecodeToken(slot: number): Promise<number>;
   /**
-   * Decoder upsampling rates (the DecoderBlock strides). Default [8,5,4,2]
-   * (DAC.speech.v1.0). Parler's dac_44khz uses [8,8,4,2] (hop 512). Channels
-   * still halve per stage from `decoderDim`.
+   * K-step greedy decode window (GERBIL_DECODE_WINDOW=K — dispatch-collapse
+   * campaign Lever 1; Dawn only).
+   *
+   * Records `steps` full decode forwards + argmax into ONE command buffer and
+   * submits once. Between recorded steps the previous step's argmax result is
+   * copied into input_ids ON THE GPU (the same 4-byte chain the pipelined path
+   * uses across submits), so no CPU sync exists inside the window. Each step's
+   * winning token id is copied into the slot's window readback at offset 4·k;
+   * {@link readDecodeWindow} maps it once per window.
+   *
+   * Seq-pos-dependent entries (RoPE position, KV-append offset, attention S —
+   * ~3 per full-attention layer; Mamba layers carry state and have none) get
+   * lazily-built per-step uniform/bind-group variants, ALL written with
+   * queue.writeBuffer BEFORE the submit (queue-ordered, so safe with a prior
+   * window still in flight). Params are built against per-step resolved shapes
+   * (L_max tensors resolve to seqPos+T — attention S comes from the KV shape).
+   * Dispatch grids are encoded ONCE per window at the worst case (last step's
+   * shapes, pos+K-1): decode grids are step-invariant in practice, and any
+   * L_max-derived grid over-dispatches for early steps, which is safe because
+   * kernels bound their work from uniforms.
+   *
+   * EOS is only observable at window granularity: up to K-1 tokens beyond EOS
+   * are computed and discarded by the caller. KV overshoot is harmless (seqPos
+   * governs reads) but SSM/conv state is NOT rewindable — continuing the same
+   * context past an intra-window EOS requires a re-prefill from that point.
+   *
+   * Evidence base: measured FLAT on M4 Max/Metal (results.jsonl r13-E2 /
+   * r14-E2v2 — depth-2 pipelining already hides submit+readback there);
+   * targeted at Dawn/Vulkan where the submit roundtrip is 52µs and decode is
+   * dispatch/driver-bound (A5000 gate, arXiv:2604.02344). See
+   * docs/design/dispatch-collapse-campaign.md §3.
+   */
+  submitGreedyDecodeWindow(firstToken: number | null, steps: number, slot: number): void;
+  /** Get (or lazily create) entry's per-step uniform/bind-group variant. */
+  private getWindowVariant;
+  /** Read back the `steps` token ids produced by the window that used `slot`. */
+  readDecodeWindow(slot: number, steps: number): Promise<Uint32Array>;
+  reset(): void;
+  /**
+   * Diagnostic: dispatch ONLY the first kernel (EmbeddingInt4) using the
+   * production bind group, pipeline, and buffers — but in isolation (1 dispatch,
+   * no staging, fresh encoder). Compares against full forward pass to isolate
+   * whether the issue is the bind group/pipeline or the multi-dispatch context.
    */
-  decoderRates?: readonly number[];
-  /** First-conv output channels (decoder_dim). Default 1536. */
-  decoderDim?: number;
-  /** Quantizer out_proj output / first-conv input dim (latent_dim). Default 1024. */
-  latentDim?: number;
-}
-declare function generateDacSpeechDecoderGraph(opts: DacSpeechGraphOptions): ModelGraph;
-/**
- * Final decoded PCM length (samples) for a T-frame code grid, via the DAC stage chain.
- * `rates` defaults to DAC.speech.v1.0 ([8,5,4,2]); pass [8,8,4,2] for Parler's dac_44khz.
- */
-declare function dacOutputLength(numFrames: number, rates?: readonly number[]): number;
-declare function generateOuteTtsBackboneGraph(rawConfig: Record<string, unknown>, dtype?: GraphDType, groupSize?: number, kvDtype?: KVDType): ModelGraph;
-//#endregion
-//#region src/gpu/architectures/qwen3_5_vision.d.ts
-/**
- * Build the ViT graph. The graph is shaped by symbolic "N" (number of patches),
- * resolved at run time from the input tensor's first dim — exactly like the LM's
- * symbolic "T".
- */
-declare function generateQwen3_5VisionGraph(rawConfig: Record<string, unknown>): ModelGraph;
-//#endregion
-//#region src/gpu/executor.d.ts
-/**
- * Safari/Metal workaround: shader variant alternation.
- * Metal caches argument buffers per compiled function. When consecutive dispatches
- * use the same WGSL code (same Metal function), Metal reuses the previous dispatch's
- * argument buffer, ignoring setBindGroup(). We alternate between variant 0/1 of each
- * shader (prepending `const _MV: u32 = Xu;`) to force different Metal function
- * specializations, preventing argument buffer reuse.
- */
-interface ExecutorOptions {
-  maxSeqLen: number;
-  /** KV cache kernel strategy. Defaults to "native-f16" when not specified. */
-  kvMode?: KvMode;
+  debugFirstDispatch(inputIds: Uint32Array): Promise<{
+    nodeId: string;
+    opType: string;
+    dispatchSize: [number, number, number];
+    output: Float32Array;
+  }>;
   /**
-   * WebKit only: dispatches per command buffer, with at most one command
-   * buffer in flight (awaited). 1 (default) is the proven-correct floor on
-   * iPad; larger values are faster if this WebKit version keeps storage
-   * writes visible across dispatches within one submission. Sweepable via
-   * the ?group=N URL param.
+   * Diagnostic: run a single dispatch entry by index, in isolation.
+   * Call after debugFirstDispatch() to test whether entry[1] (RMSNorm)
+   * can read embed_out written by entry[0] (EmbeddingInt4).
    */
-  webkitGroupSize?: number;
-}
-interface ForwardResult {
-  logits: Float32Array;
-}
-declare class Executor {
-  private ctx;
-  private graph;
-  private weightBuffers;
-  private activationBuffers;
-  private ssmStateBuffers;
-  private kvCacheBuffers;
-  /** Pre-allocated input_ids buffer (maxSeqLen * 4 bytes). */
-  private inputIdsBuffer;
+  debugDispatchEntry(entryIndex: number, T: number): Promise<{
+    nodeId: string;
+    opType: string;
+    output: Float32Array;
+  }>;
   /**
-   * CPU-resident Per-Layer-Embeddings (PLE) source for Gemma 4. The PLE table
-   * (`embed_tokens_per_layer`, [vocab, L*256]) is ~1.17GB at 4-bit and is kept
-   * OFF the GPU. Each forward step we gather + dequantize only the rows for the
-   * actual input tokens and upload a tiny [T, L*256] f32 buffer. See setPleSource.
+   * Diagnostic: compute the JS-side params for the first N decode entries
+   * WITHOUT dispatching. Shows what buildParams produces.
    */
-  private pleSource;
-  /** Reusable scratch for the dequantized PLE rows (resized on demand). */
-  private pleScratch;
+  debugComputeParams(T: number, count?: number): Array<{
+    idx: number;
+    nodeId: string;
+    opType: string;
+    paramsU32: number[];
+    dispatchSize: [number, number, number];
+  }>;
   /**
-   * One-time promise that materializes a cache-backed PLE table into heap. The
-   * table is read from CacheStorage on the FIRST forward — i.e. AFTER the GPU
-   * weight upload has completed, so the ~1.17 GB does not stack on top of the
-   * upload's transient allocations at the load-time memory high-water mark.
+   * Diagnostic: after a forward pass, read back output tensors at several points
+   * in the pipeline to find where data drops to zero.
    */
-  private pleReady;
+  debugPipelineProbe(T: number): Promise<Array<{
+    idx: number;
+    nodeId: string;
+    opType: string;
+    tensor: string;
+    sum: number;
+    first4: number[];
+    uniformParams?: number[];
+  }>>;
+  debugWriteBuffer(tensorName: string, data: ArrayBufferView): void;
   /**
-   * Dummy GPU buffer bound to an otherwise-aliasing storage-read-write slot.
-   * Used by RoPE-Q-only nodes (Gemma 4 KV-shared layers) whose node lists the
-   * same tensor as input and output: the RoPE kernel always declares two
-   * read_write bindings (q, k), but with num_kv_heads=0 the k slot is never
-   * touched. WebGPU still rejects two read_write bindings aliasing one buffer,
-   * so we bind this throwaway buffer to the unused k slot. Allocated lazily.
+   * Write a host-supplied activation input buffer (e.g. multimodal M-RoPE
+   * cos/sin, spliced vision embeddings, image row-map). The buffer must be a
+   * persistent activation tensor in the graph. Call before forward().
    */
-  private bindingScratchBuffer;
-  /** Readback buffer for logits. */
-  private logitsReadback;
-  /** GPU buffer for argmax result (1 u32). */
-  private argmaxResultBuffer;
-  /** Readback buffer for argmax result (1 u32). */
-  private argmaxReadback;
-  /** Readback ring for pipelined greedy decode (created lazily). */
-  private decodeReadbacks;
+  writeInput(tensorName: string, data: ArrayBufferView): void;
+  /** Write a host activation buffer at a byte offset (for per-row decode updates). */
+  writeInputAt(tensorName: string, data: ArrayBufferView, byteOffset: number): void;
+  /** True if the graph has a buffer with this name (multimodal-capability probe). */
+  hasBuffer(tensorName: string): boolean;
+  /** Current sequence position (number of tokens processed since reset). */
+  get currentSeqPos(): number;
+  debugReadBuffer(tensorName: string, maxElements?: number, byteOffset?: number): Promise<Float32Array>;
+  destroy(): void;
   /**
-   * Staging buffer for uniform param updates.
-   * Safari/Metal has weaker visibility guarantees for queue.writeBuffer() to
-   * UNIFORM buffers — early writes get dropped when hundreds are queued.
-   * Instead, we pack all params into this STORAGE staging buffer (1 writeBuffer),
-   * then use encoder.copyBufferToBuffer to distribute to each uniform buffer.
-   * Copies are GPU-sequenced and guaranteed to complete before compute passes.
+   * Allocate activation buffers with liveness-based reuse.
+   *
+   * One dedicated buffer per activation tensor at full maxSeqLen is ~2.3GB for
+   * Qwen3.5-0.8B at T=512 — over the iOS jetsam budget on its own. Instead,
+   * a buffer returns to a size-keyed pool once its tensor's last reader has
+   * executed, so concurrently-live tensors share a small working set.
+   *
+   * Graph outputs and tensors read before they are written (cross-forward
+   * state) keep dedicated buffers. Within a forward, dispatches execute in
+   * executionOrder on every path (single-pass Dawn, per-dispatch WebKit), and
+   * WebGPU synchronizes hazards between dispatches, so reuse is safe.
+   *
+   * Caveat: debugReadBuffer() on an intermediate tensor is only meaningful
+   * before a later op reuses its buffer (probes that stop mid-graph are fine).
    */
-  private uniformStagingBuffer;
-  private uniformStagingCapacity;
-  /** Dispatch entries for prefill (M>1): uses tiled matmul kernels. */
-  private dispatchEntries;
-  /** Dispatch entries for decode (M=1): uses K-parallel matvec kernels. */
-  private decodeEntries;
-  /** Per-node decode entries captured BEFORE fusion (the overlay base). */
-  private decodeEntriesUnfused;
-  /** True while a runtime adapter is applied. */
-  private loraActive;
-  /** Decode entries (unfused base + spliced LoRA dispatches). */
-  private decodeEntriesLoRA;
-  /** Prefill entries (base + spliced LoRA dispatches). */
-  private prefillEntriesLoRA;
-  /** GPU buffers owned by the current adapter (A/B factors + tmp); freed on swap. */
-  private loraBuffers;
-  /** Argmax dispatch entry (created in initBindGroups). */
-  private argmaxEntry;
-  /** True when running on Safari/WebKit (needs multi-encoder submit). */
-  readonly needsMultiEncoder: boolean;
-  private maxSeqLen;
-  private kvMode;
-  private seqPos;
-  private webkitGroupSize;
-  private profileEnabled;
-  private readonly profileData;
-  private querySet;
-  private queryResolveBuf;
-  private queryReadbackBuf;
-  constructor(ctx: GPUContext, graph: ModelGraph, options: ExecutorOptions);
+  private allocateActivationBuffers;
+  private allocateSSMStateBuffers;
+  private allocateKVCacheBuffers;
+  /** f16 SSM-state kernels are selected on Dawn with f16 support (not WebKit). */
+  private get usesF16Ssm();
   /**
-   * Register the CPU-resident Gemma 4 PLE table. The quantized table is kept in
-   * JS memory (NOT uploaded to a GPU buffer), and {@link forward} gathers +
-   * dequantizes only the rows for the current input tokens each step, uploading a
-   * small [T, width] f32 buffer into `targetTensor`. This is what keeps Gemma 4
-   * mobile-viable: resident GPU memory is just the active transformer weights.
+   * Batched-decode state (GERBIL_BATCH=N): per-slot SSM/conv state pools, the
+   * per-row positions/seq_lens buffers, the sampled-token buffer + readback
+   * ring, and batch-widened buffers for the lm-head tail (SliceLastRow output
+   * and logits become [N, ...]).
+   *
+   * SSM pool slot stride: the f16 MambaSSM kernel indexes its state buffer in
+   * f16 ELEMENTS (the buffer is f32-sized with the upper half unused), so its
+   * pool slot stride is elems*2 bytes; conv state (f32 kernels) uses the full
+   * f32 byte size. The batched kernels compute `slot * elems` in their own
+   * element space, so the pool stride must match each kernel's element width.
    */
-  setPleSource(src: {
-    packed: Uint32Array;
-    scales: Float32Array;
-    zeros: Float32Array;
-    width: number;
-    groupSize: number;
-    targetTensor: string;
-    cache?: {
-      cacheName: string;
-      packedKey: string;
-      scalesKey: string;
-      zerosKey: string;
-      packedLen: number;
-    };
-  }): void;
+  private allocateBatchState;
+  private resolveShapes;
+  private getBuffer;
+  /**
+   * Batch-path buffer resolution: lm-head tail tensors use their [B, ...]
+   * widened buffers, ssm_state tensors bind the per-slot pool, everything
+   * else falls through to the regular buffer maps.
+   */
+  private getBatchBuffer;
+  /**
+   * True when this node's KV traffic goes through the paged path: the flag is
+   * on AND the node actually touches a kv_cache tensor (KVCacheAppend writes
+   * one; self-attention reads one as its K input). SSM/conv state and
+   * ViT/cross-attention over plain activations never match — on hybrid models
+   * only the attention layers page, exactly as the design requires.
+   */
+  private usesPagedKV;
+  /**
+   * Paged KV only: make sure blocks are mapped for logical positions
+   * [0, seqPos + T) BEFORE this forward's dispatches are submitted.
+   * queue.writeBuffer is queue-ordered, so the (rare — once per 16 tokens)
+   * table upload always lands ahead of the submits that read it, including in
+   * the pipelined decode path with PIPELINE_DEPTH steps in flight.
+   */
+  private preparePagedKV;
+  /** Runtime context for batched dispatches (positions live in buffers). */
+  private batchRuntimeCtx;
+  /**
+   * Shapes for the batched step: every "T" dimension is the batch width, and
+   * the lm-head tail tensors (statically [1, ...] in the graph) widen to
+   * [B, ...] — every row IS a last row on the batch path.
+   */
+  private resolveBatchShapes;
+  /**
+   * Build the batched dispatch-entry list: one lockstep decode step for all
+   * batchSize rows. Row-independent ops (embedding, norms, elementwise) keep
+   * their prefill kernels at T=B; linear layers run the batched INT4 GEMM;
+   * every position/state-dependent op swaps to its batch-indexed variant
+   * (paged attention + append via per-row block-table rows, RoPE via the
+   * positions buffer, conv/SSM via the per-slot state pool).
+   */
+  private buildBatchEntries;
+  /**
+   * Batched-path fusion driver (Phase 4). Ports the single-sequence decode
+   * fusions onto `batchEntries`: identical math (the fused kernels reproduce
+   * the unfused chain operation-for-operation — exact-tier GEMM reductions
+   * keep the V2 order, elementwise prologues/epilogues keep the registry
+   * kernels' formulas), strictly fewer dispatches. `GERBIL_BATCH_FUSE`
+   * selects a subset for A/B measurement: unset/"all" = every pass,
+   * "none" = none, or a comma list of pass names.
+   */
+  private fuseBatchDecodeEntries;
+  /**
+   * Batch port of fuseSwiGLUDecodeEntries: gate MatMulInt4 + up MatMulInt4 +
+   * elementwise SwiGLU → ONE fused batched GEMM (saves 2 dispatches per MLP
+   * block and the gate/up activation round-trips).
+   */
+  private fuseBatchSwiGLUMLPEntries;
+  /**
+   * Batch port of fuseDualMatVecDecodeEntries: two adjacent MatMulInt4s
+   * sharing one input and identical K/N/group_size (q+gate, k+v) → ONE dual
+   * batched GEMM dispatch (wid.y selects the projection — per-projection
+   * math unchanged).
+   */
+  private fuseBatchDualMatVecEntries;
   /**
-   * True when this model streams a CPU-resident Per-Layer-Embedding table
-   * (Gemma 4): each decode step must gather+upload the PLE rows for the ACTUAL
-   * input token id on the CPU before the forward runs. The GPU-chained pipelined
-   * decode path and forwardArgmax both bypass CPU token knowledge, so they leave
-   * `ple_embed_out` stale and must NOT be used for these models — only the
-   * per-step forward() path (which calls streamPleRows) is correct. See generate().
+   * Batch port of fuseDualKVCacheAppendEntries: adjacent K+V paged appends →
+   * ONE BATCHED_PAGED_DUAL_KV_APPEND dispatch (pure memcpys — identical
+   * writes, one dispatch per attention layer saved).
    */
-  hasPleSource(): boolean;
+  private fuseBatchDualKVAppendEntries;
   /**
-   * Materialize a cache-backed PLE table into heap exactly once. Deferred to the
-   * first forward (after GPU upload) so the ~1.17 GB table is not co-resident
-   * with the upload's transient allocations during the load-time memory peak.
+   * Batch port of fuseGatedOProjDecodeEntries ("sigmoid": SigmoidGate →
+   * o_proj) and fuseSwiGLUGatedProjDecodeEntries ("swiglu": Mamba SwiGLU →
+   * out_proj): the elementwise gate is recomputed inside the GEMM's input
+   * load with the registry kernel's exact formula — one dispatch per layer
+   * saved plus the gated-activation round-trip.
    */
-  private ensurePleLoaded;
+  private fuseBatchGatedProjEntries;
   /**
-   * Gather + dequantize the PLE rows for `inputIds` and upload them into the
-   * target activation buffer. Touches only T rows (T*width floats) — the full
-   * [vocab, width] quantized table never goes to the GPU.
+   * Batch port of fuseDualRMSNormRoPEDecodeEntries: [q_norm, k_norm, RoPE]
+   * → ONE BATCHED_DUAL_RMSNORM_ROPE dispatch (per-row rotation position from
+   * the positions buffer). Saves 2 dispatches per full-attention layer.
    */
-  private streamPleRows;
+  private fuseBatchDualRMSNormRoPEEntries;
   /**
-   * Stream weights to the GPU one tensor at a time, pulling each from the
-   * `WeightSource` only when it is about to be uploaded and dropping the
-   * reference immediately afterward.
+   * Reset ALL batch slots for a new lockstep generation: frees every
+   * sequence's KV blocks, zeroes the single-sequence SSM state (the prefill
+   * staging area), and clears per-slot lengths. State-pool slots need no
+   * zeroing — finishBatchSlot overwrites a slot in full before it is read.
+   */
+  resetBatch(): void;
+  /**
+   * Route the single-sequence forward() path at batch slot `slot`: paged KV
+   * writes/reads use the slot's block-table row (RuntimeContext.tableBase) and
+   * SSM state accumulates in the singleton staging buffers (zeroed).
+   * Call once per prompt, then forward(promptIds), then finishBatchSlot().
+   */
+  beginBatchSlot(slot: number): void;
+  /**
+   * Adopt the just-prefilled sequence into `slot`: records its length, copies
+   * the singleton SSM/conv state into the slot's pool rows (KV already lives
+   * in the slot's block-table row via tableBase), and zeroes the singleton
+   * staging state for the next prefill.
+   */
+  finishBatchSlot(slot: number): void;
+  /** Per-slot token counts (prompt + generated) on the batch path. */
+  get batchSlotLengths(): Uint32Array;
+  /**
+   * Submit one lockstep batched decode step (pipelined — does not await).
+   * `tokens` feeds input_ids on the first step; pass null afterwards to chain
+   * the previous step's sampled ids into input_ids ON the GPU. Sampled ids
+   * land in the `slot` readback (read one step behind via readBatchTokens).
+   */
+  submitBatchDecodeStep(tokens: Uint32Array<ArrayBuffer> | null, slot: number): void;
+  /** Read the sampled ids produced by the batched step that used `slot`. */
+  readBatchTokens(slot: number): Promise<Uint32Array>;
+  /** Batch entries in effect for the current lane-adapter state. */
+  private get activeBatchEntries();
+  /** Number of adapters registered for per-lane batched decode. */
+  get batchAdapterCount(): number;
+  /**
+   * Register a LoRA adapter for per-lane batched decode and return its integer
+   * adapter id (assign lanes via {@link setBatchLaneAdapters}). Factors are
+   * packed into per-adapted-node GPU buffers ONCE — every lane running this
+   * adapter reads the same factors. Fused query+gate deltas are expanded with
+   * the same deinterleave the single-sequence overlay uses.
    *
-   * This is the property that bounds peak JS heap: with a cache-backed source
-   * (browser/mobile), only ONE tensor's bytes are materialized in heap at a time
-   * (read from CacheStorage in `source.get()`), uploaded to its GPU buffer, then
-   * released before the next tensor is fetched. The whole model is never co-
-   * resident in heap. With a heap-backed source (Node/desktop), behavior matches
-   * the old Map path (the source deletes each entry as it is consumed).
+   * Phase-1 constraint: every adapter adapting a given linear must share that
+   * node's LoRA rank (the packed factor arena is fixed-stride; mixed ranks are
+   * deferred).
+   */
+  registerBatchAdapter(deltas: LoRADelta[]): number;
+  /** Drop every registered batch adapter and free the overlay's GPU buffers. */
+  clearBatchAdapters(): void;
+  /**
+   * Assign each batch lane its adapter: `ids[b]` is a registered adapter id or
+   * -1 for the bare base. Uploads the per-lane adapter_ids buffer (the
+   * positions/seq_lens per-row pattern) and switches the step's entry list to
+   * the LoRA overlay iff any lane carries an adapter — an all-base assignment
+   * runs the untouched plain batch entries at zero extra cost.
+   */
+  setBatchLaneAdapters(ids: ArrayLike<number>): void;
+  /** Free the batch-LoRA overlay's GPU buffers (factors, maps, tmp, uniforms). */
+  private destroyBatchLoraBuffers;
+  /**
+   * (Re)build the per-lane LoRA overlay: pack every registered adapter's
+   * factors per adapted node, and derive `batchEntriesLoRA` from the fused
+   * batch entry list with SELECTIVE unfusing — every fused group that covers
+   * no adapted linear stays exactly as the plain batch path runs it; groups
+   * covering an adapted node fall back to their pre-fusion per-node entries
+   * (token-exact by the Phase 2/4 derivation discipline) with the per-lane
+   * `[down, up]` gather pair spliced right after each adapted node, so the
+   * corrected output is live before any consumer reads it.
+   */
+  private rebuildBatchLoraOverlay;
+  /** Total physical KV blocks in the paged pool (admission-control bound). */
+  get kvTotalBlocks(): number;
+  /** KV blocks currently unallocated. */
+  get kvFreeBlocks(): number;
+  /** Tokens per KV block (admission-control block-count math). */
+  get kvBlockSizeTokens(): number;
+  /** Blocks a single sequence may map (== ceil(maxSeqLen / blockSize)). */
+  get kvMaxBlocksPerSeq(): number;
+  /** Effective context length (scheduler admission math). */
+  get maxSequenceLength(): number;
+  /**
+   * Retire a batch lane: free its KV blocks and zero its length so masked
+   * steps treat the slot as empty (seq_lens[slot] = 0). The SSM pool row
+   * needs no cleanup — re-admission overwrites it in full (finishBatchSlot).
+   */
+  retireBatchSlot(slot: number): void;
+  /**
+   * Seed `slot`'s next input token (the first token sampled from its prefill
+   * logits). Written into the sampled-ids buffer so the next masked step's
+   * on-GPU chain copy propagates it into input_ids. queue.writeBuffer is
+   * queue-ordered: it lands AFTER any in-flight step's argmax write to the
+   * same word and BEFORE the next submitted step's chain copy — correct even
+   * with PIPELINE_DEPTH steps in flight.
+   */
+  injectBatchToken(slot: number, token: number): void;
+  /**
+   * Submit one MASKED batched decode step (the scheduler's step; pipelined —
+   * does not await). Only lanes with `active[b] != 0` advance: inactive lanes
+   * get positions=0 / seq_lens=0, which masks their KV appends (kernel guard)
+   * and clamps their attention window to nothing; their other row-local ops
+   * compute garbage that stays confined to their rows/state slots and is
+   * fully overwritten on re-admission.
    *
-   * Accepts either a `WeightSource` (new, streamed/async) or a plain Map
-   * (back-compat for callers that build a Map directly, e.g. Kani/Moonshine).
+   * The step's dispatch width is dynamic: kernels take their batch dimension
+   * from the runtime context, so only rows [0, maxActiveSlot] are dispatched
+   * (GEMM b-tiles may cover a few dead rows past the last active one —
+   * in-bounds stale writes that are never read). Input tokens always chain
+   * from the sampled-ids buffer on the GPU; newly admitted lanes are seeded
+   * via injectBatchToken. Sampled ids land in the `slot` readback (read one
+   * step behind via readBatchTokens).
+   */
+  submitBatchDecodeStepMasked(active: Uint8Array, slot: number): void;
+  /** Write the batched-argmax uniform once per batch session (invariant). */
+  private writeBatchArgmaxParams;
+  private requireBatch;
+  /**
+   * Detect gate_proj + up_proj + SwiGLU patterns in decode entries and replace
+   * with a single fused SwiGLUMatVec dispatch. Saves 2 dispatches per MLP block.
    */
-  uploadWeights(source: WeightSource | Map<string, {
-    data: ArrayBufferView;
-    shape: number[];
-  }>): Promise<void>;
   /**
-   * Synchronous Map upload (Node/desktop and the Kani/Moonshine sub-executors,
-   * which build small heap Maps). Deletes each entry as it is consumed to free
-   * the JS-side bytes once they are GPU-resident. Safe to call from a constructor.
+   * Fuse [ResidualRMSNorm, gate MatMulInt4, up MatMulInt4, SwiGLU] → ONE
+   * NormSwiGLUMatVec dispatch. The kernel computes the residual sum + RMS in a
+   * prologue (workgroup 0 persists the residual sum for the downstream residual
+   * chain) and normalizes the activation on the fly, so the norm dispatch AND
+   * the normed tensor's write+read roundtrip disappear. INT4-only; falls back
+   * when the device can't bind 11 storage buffers. Windows it skips fall
+   * through to fuseSwiGLUDecodeEntries.
    */
-  uploadWeightsMap(weights: Map<string, {
-    data: ArrayBufferView;
-    shape: number[];
-  }>): void;
   /**
-   * Build all pipelines and bind groups. Call ONCE after uploadWeights().
+   * Fuse [ResidualRMSNorm → Mamba qkv MatVecInt4] → ONE NormMatVec dispatch.
+   * The kernel recomputes the residual sum + RMS in a prologue (workgroup 0
+   * persists BOTH the residual sum and the full normed vector — the latter is
+   * live for the sibling a_proj/b_proj/z_proj), then the GEMV normalizes the
+   * activation on the fly. Saves the ResidualRMSNorm dispatch (−1 per Mamba
+   * layer, ×17). 10 storage bindings — fits the Dawn/Metal 10-binding adapter.
+   * INT4-only.
    *
-   * Creates two dispatch entry arrays:
-   * - dispatchEntries: tiled matmul for prefill (any M)
-   * - decodeEntries: K-parallel matvec for decode (M=1)
+   * OPT-IN, DEFAULT OFF (GERBIL_FUSE_NORM_QKV=1). Round r28 (2026-07-25) measured
+   * this a −4.6% REGRESSION on M4 Max/Metal: the qkv GEMV is the widest projection
+   * (N=6144 → 384 workgroups), so recomputing the 1024-wide residual+RMS reduction
+   * per workgroup + normalizing activations on the fly costs far more ALU than the
+   * single saved ResidualRMSNorm dispatch returns on a bandwidth-plateaued backend.
+   * The −17 dispatch/token reduction still targets Vulkan/WebKit (dispatch-count-
+   * bound) — validate on the kernel-lab A5000 rig before enabling anywhere.
+   */
+  private fuseNormMatVecDecodeEntries;
+  private fuseNormSwiGLUDecodeEntries;
+  private fuseSwiGLUDecodeEntries;
+  /**
+   * Fuse the Mamba-front projections — qkv (MatVec), a (MatVec), b (MatVec),
+   * z (MatVec) — into ONE QuadMatVecInt4 dispatch per Mamba layer. All four
+   * read the SAME `input_layernorm` output and share K and group_size, so their
+   * INT4 weight matrices (stored column-major, one column contiguous) are
+   * column-concatenated into a single q/scales/zeros buffer by a plain
+   * byte-append (a GPU buffer-to-buffer copy at init). The fused kernel runs a
+   * single GEMV over the concatenated N and routes each output column back to
+   * its ORIGINAL destination buffer, so downstream consumers (conv1d reads qkv,
+   * MambaSSM reads a/b, the gated out_proj reads z) are untouched.
+   *
+   * Numerically identical to the three separate dispatches (same dequant, same
+   * K-parallel reduction, same per-column sum — the concatenated weights are the
+   * same bytes), so this is token-exact and WebKit-safe. It removes 2
+   * dispatches per Mamba layer (3 front dispatches → 1) plus one input read and
+   * two weight-read passes.
+   *
+   * Runs BEFORE fuseDualMatVecDecodeEntries so the a/b pair is still two
+   * standalone MatVec entries here (not yet a DualMatVec). Restricted to the
+   * Mamba front by weight-name (`.in_proj_qkv/a/b/z.`), so the attention front
+   * (q/gate/k/v) is never matched. Bindings: A + q/s/z + 4 outs + params = 9
+   * (fits Metal's 10-binding wall). Gate: default-on when the adapter offers ≥9
+   * storage bindings; opt-out via GERBIL_FUSE_MAMBA_FRONT=0.
    */
-  initBindGroups(): void;
-  /** True while a runtime LoRA overlay is applied. */
-  get hasRuntimeAdapter(): boolean;
-  /** Decode entries in effect for the current adapter state. */
-  private get activeDecodeEntries();
+  private fuseMambaFrontDecodeEntries;
   /**
-   * Apply a runtime LoRA overlay on the STATIC base. For each delta whose target
-   * maps to a base linear (MatMulInt4 / MatMul) with matching dims, uploads the
-   * f32 A/B factors and splices two low-rank dispatches — `tmp = A·x`, then
-   * `y += scaling·B·tmp` — right after that node in both the decode and prefill
-   * paths, so the corrected output is live before any consumer reads it.
+   * Fuse two adjacent INT4 projections that share the same input activation and
+   * the same K/N (e.g. q_proj+gate_proj and k_proj+v_proj in full-attention
+   * decode) into a single DualMatVecInt4 dispatch. Reads the shared input vector
+   * once and writes both projection outputs — removing one GPU round-trip (one
+   * submit+drain on Safari/iOS) per fused pair.
    *
-   * Rebuilds the overlay from scratch each call (this is how adapters hot-swap);
-   * the base weight buffers and bind groups are never touched or re-uploaded.
-   * Pass an empty list (or call {@link clearRuntimeLoRA}) to drop the overlay.
+   * Numerics are identical to running the two MatVecInt4 kernels separately
+   * (same dequant, same K-parallel reduction), so this is WebKit-safe: it reuses
+   * the proven INT4 matvec math and only merges two writes into one dispatch.
+   *
+   * Must run AFTER fuseSwiGLUDecodeEntries so the MLP gate+up pair (which is
+   * consumed by a SwiGLU node) is already collapsed and won't be matched here.
    */
-  /** Find the base linear (MatMulInt4 / MatMul) node whose weight is `key`. */
-  private findBaseLinear;
+  private fuseDualMatVecDecodeEntries;
   /**
-   * Expand any fused query+gate delta into separate `q_proj` + `attn_gate`
-   * deltas so it can splice onto a deinterleaved runtime graph.
+   * Fuse the adjacent K-cache and V-cache appends in each full-attention layer
+   * into a single DualKVCacheAppend dispatch. Both are pure memcpys into f32
+   * caches sharing the same width and dst_offset, so one dispatch with two
+   * src/dst buffers writes both — removing one GPU round-trip per layer.
    *
-   * Qwen3.5-style gated attention ships `q_proj.weight` fused as
-   * `[2·num_heads·head_dim, hidden]` (per-head: query rows then gate rows); the
-   * model loader splits it into two runtime linears (`q_proj`, `attn_gate`). An
-   * adapter trained on the fused checkpoint carries a single `q_proj` delta whose
-   * out-dim is 2× either split node, so it matches neither. When BOTH split
-   * linears exist and the delta is exactly their combined width, split it via the
-   * same per-head row deinterleave the loader uses; otherwise the delta passes
-   * through untouched (e.g. a base that never split the projection).
+   * Supports f32, native-f16, and packed-f16 caches (the dual kernel mirrors the
+   * single-append kernel selected for the active kvMode). Numerically identical
+   * to the separate appends — WebKit-safe (the packed-f16 variant is the Safari
+   * path and uses pack2x16float, no `enable f16`).
    */
-  private expandFusedQGateDeltas;
-  applyRuntimeLoRA(deltas: LoRADelta[]): {
-    applied: number;
-    skipped: number;
-  };
-  /** Drop the runtime LoRA overlay and free its GPU buffers. Base is untouched. */
-  clearRuntimeLoRA(): void;
-  /** Build the [down, up] low-rank dispatch pair for one adapted node. */
-  private buildLoraPair;
-  /** Copy a base entry list, splicing each node's LoRA pair in right after it. */
-  private spliceLoraOverlay;
-  /** Original constituent node ids a (possibly fused) decode entry covers. */
-  private coveredNodeIds;
+  private fuseDualKVCacheAppendEntries;
   /**
-   * Build the decode entry list for an active adapter with SELECTIVE unfusing.
-   * Every fused group that covers no adapted linear is kept exactly as the
-   * no-adapter fast path runs it (full SwiGLU/dual/gated fusion, no numerics
-   * change). Only the groups that cover an adapted node fall back to their
-   * pre-fusion per-node dispatches (pulled from {@link decodeEntriesUnfused}),
-   * with the low-rank `[down, up]` pair spliced right after each adapted node so
-   * its corrected output is live before any consumer reads it. Replaying the
-   * exact pre-fusion entries reproduces the validated unfused numerics for the
-   * adapted groups while leaving all other groups on the fused path.
+   * Fuse the attention SigmoidGate (attn_out * sigmoid(gate)) into the INT4
+   * o_proj that consumes it: a GatedMatVecInt4 reads attn_out and gate directly,
+   * applies the sigmoid gate to its input vector, and runs the projection in ONE
+   * dispatch — removing the standalone SigmoidGate (one round-trip per
+   * full-attention layer).
+   *
+   * Numerically identical to SigmoidGate→MatVecInt4 (same gate formula, same INT4
+   * dequant + reduction). Slight extra ALU: the gated input is recomputed per
+   * output column, but A reads hit L1 and the saved submit+drain dominates on
+   * mobile. WebKit risk: low — reuses the proven INT4 matvec, only the A vector
+   * is built from two reads + a sigmoid (no new reduction/barrier pattern).
+   *
+   * Runs after the dual fusions so it only sees the post-attention SigmoidGate.
    */
-  private buildSelectiveLoraDecode;
+  private fuseGatedOProjDecodeEntries;
   /**
-   * Run a forward pass. Uses matvec kernels for M=1 (decode), tiled for M>1 (prefill).
+   * Fuse a standalone SwiGLU (silu(gate) * up) into the INT4 projection that
+   * consumes its output: a SwiGLUGatedMatVecInt4 reads gate and up directly,
+   * builds the gated input vector, and runs the projection in ONE dispatch.
+   * Targets the Mamba block's mamba_swiglu (silu(z) * norm_out) feeding out_proj
+   * — one round-trip saved per linear-attention layer.
+   *
+   * The MLP SwiGLU is already collapsed into a SwiGLUMatVec entry by
+   * fuseSwiGLUDecodeEntries (it has no surviving standalone SwiGLU node), so only
+   * the Mamba SwiGLU matches here. Numerically identical to SwiGLU→MatVecInt4;
+   * WebKit risk low (reuses the proven INT4 matvec, only the A vector changes).
    */
-  forward(inputIds: Uint32Array): Promise<ForwardResult>;
+  private fuseSwiGLUGatedProjDecodeEntries;
   /**
-   * Profiling variant of the desktop dispatch path: one compute pass per dispatch,
-   * each bracketed by timestamp queries, so we get per-op GPU time. Accumulates
-   * into profileData by opType. Only runs under GERBIL_PROFILE with timestamp-query
-   * support — slower than the batched path (it measures relative cost, not tok/s).
+   * Fuse two adjacent per-row RMSNorms sharing hidden_size + eps into a single
+   * DualRMSNorm dispatch (e.g. the per-head q_norm and k_norm in full-attention
+   * decode). One workgroup still handles one row; the fused grid just spans both
+   * inputs' rows, so each row's reduction is unchanged — numerically identical to
+   * two separate RMSNorm dispatches. One round-trip saved per fused pair.
+   *
+   * WebKit risk: low — same single-workgroup reduction as the proven RMSNorm
+   * kernel, only the row→input routing is added.
    */
-  private runProfiledDispatches;
-  /** Per-opType GPU time (ns) + dispatch count accumulated by GERBIL_PROFILE, hottest first. */
-  getProfile(): Array<{
-    opType: string;
-    ns: number;
-    count: number;
-  }>;
-  /** Clear accumulated profiler data (e.g. to drop warm-up tokens). */
-  resetProfile(): void;
-  /** GPU dispatches per decode token (post-fusion). On mobile this drives the
-   * submit-group count = ceil(dispatchCount / webkitGroupSize). */
-  get decodeDispatchCount(): number;
-  /** Device limit that gates the INT4 projection fusions (they need ≥9). If a
-   * device caps at 8 the dual/gated/swiglu-gated INT4 fusions silently fall back,
-   * inflating the decode dispatch count. */
-  get maxStorageBuffers(): number;
   /**
-   * Profile ONE real decode step: times the actual `decodeEntries` (the kernels
-   * the pipelined greedy benchmark runs) with per-dispatch timestamps. Timing is
-   * token-independent, so pass any valid id; runs un-pipelined with a synchronous
-   * timestamp readback (measurement only, not for production decode). Argmax (one
-   * tiny dispatch) is intentionally excluded — it is not a hotspot target.
+   * Fuse [CausalConv1dSiLU|CausalConv1dGated → ConvStateUpdate] into one
+   * dispatch (decode entries only). At T=1 the conv read and the rolling-state
+   * write for a channel live in the same thread, so the fused kernel is
+   * race-free; prefill (T>1) keeps the two-dispatch path.
    */
-  profileDecodeStep(tokenId: number): Promise<void>;
+  private fuseConvStateUpdateDecodeEntries;
   /**
-   * Run a single forward pass over `inputIds` and read back the L2-normalized
-   * embedding vector. Requires an embedding graph (one whose output tensor is
-   * "embedding", produced by the last-token-pool + L2-norm tail).
-   *
-   * Always runs in a fresh-state single pass (caller should reset() first):
-   * embeddings are non-autoregressive, so the whole sequence is one prefill.
+   * Fuse [per-head q_norm RMSNorm, k_norm RMSNorm, in-place RoPE] into ONE
+   * DualRMSNormRoPE dispatch. Numerically identical (norm then rotate, same
+   * math); requires head_dim <= 256 and RoPE operating in-place on exactly the
+   * two norm outputs. Saves 2 dispatches per full-attention layer — a mobile
+   * (WebKit submit-per-dispatch) win, desktop-neutral.
    */
-  embed(inputIds: Uint32Array): Promise<Float32Array>;
   /**
-   * Generic one-shot dispatch for a non-LM graph: run every entry once over a
-   * single forward and read back `elemCount` f32 elements of the named output
-   * tensor. Used to execute the NanoCodec decoder graph (codes→PCM) — its ops use
-   * concrete lengths and it has no "logits" output, so the normal forward()
-   * logits-readback path does not apply. Caller writes any inputs (e.g. audio_codes)
-   * via writeInput() and reset()s first.
+   * Fuse [Add → RMSNorm] into a single ResidualRMSNorm dispatch: the add's sum
+   * is still materialized (sum_output — downstream residual chain reads it) and
+   * the norm result is written in the same dispatch. Numerically identical.
    */
-  runGraphOutput(outputName: string, elemCount: number): Promise<Float32Array>;
+  private fuseAddRMSNormDecodeEntries;
+  private fuseDualRMSNormRoPEDecodeEntries;
+  private fuseDualRMSNormDecodeEntries;
   /**
-   * Autoregressive step for a multi-output decoder graph (e.g. Parler-TTS's 9 codebook
-   * lm_heads). Dispatches the whole graph ONCE at the current seqPos (so the per-layer
-   * KVCacheAppend writes at the right cache row), reads back each named output, then
-   * advances seqPos by `tokens` (default 1, for a prefilled prompt span pass tokens=T).
-   * The caller writes inputs (dec_input_embed + frozen cross-attn K/V) and reset()s
-   * before the first step. Unlike forward(), there is no single "logits" output —
-   * the caller decodes each codebook row itself.
+   * Gather buffer entries for a bind group, matching the kernel spec's binding layout.
+   * Uses the pre-allocated inputIdsBuffer for the "input_ids" tensor.
    */
-  runGraphStep(outputs: Array<{
-    name: string;
-    elemCount: number;
-  }>, tokens?: number): Promise<Float32Array[]>;
+  private gatherBuffers;
+  /** Lazily allocate a scratch storage buffer at least `minBytes` large. */
+  private getBindingScratchBuffer;
+}
+//#endregion
+//#region src/gpu/batch/scheduler.d.ts
+/** Options for a single scheduled request. */
+interface ServeOptions {
+  /** Max new tokens (clamped to context; default 128). */
+  maxTokens?: number;
+  stopSequences?: string[];
+  systemPrompt?: string;
+  /** Greedy-only in Phase 5: temperature must be 0 (or omitted). */
+  sampling?: {
+    temperature?: number;
+  };
+  /**
+   * Registered adapter name this request decodes with (SGMV — requires
+   * `GERBIL_BATCH_LORA=1` and a prior `registerAdapter` call on the engine);
+   * undefined = bare base. Requests with different adapters (or none) decode
+   * concurrently over the shared base, each token-exact vs a solo run with
+   * that adapter loaded.
+   */
+  adapter?: string;
+  /** Streamed per-token callback (decoded text piece). */
+  onToken?: (token: string, meta: {
+    requestId: number;
+    tokenId: number;
+    generated: number;
+  }) => void;
+}
+/** Per-request result + serving timings (all performance.now() ms). */
+interface ServeResult {
+  requestId: number;
+  text: string;
+  tokenIds: number[];
+  tokensGenerated: number;
+  finishReason: "eos" | "max_tokens" | "stop_sequence";
+  /** The adapter name the request decoded with (echoed through), if any. */
+  adapter?: string;
+  /** submit() call time. */
+  submittedAt: number;
+  /** Admission into a batch slot (prefill start). */
+  admittedAt: number;
+  /** First token available (end of prefill). */
+  firstTokenAt: number;
+  finishedAt: number;
+  /** Time-to-first-token from submission (queue wait + prefill). */
+  ttftMs: number;
+  e2eMs: number;
+}
+/** Wiring the engine hands the scheduler (see WebGPUEngine.createScheduler). */
+interface SchedulerHost {
+  executor: Executor;
+  encodeChat(messages: ChatMessage[]): number[];
+  decodeToken(id: number): string;
+  eosTokenId: number | null;
+  eotTokenId: number | null;
+  /** Vocab-prune remap for CPU-sampled tokens (identity when unpruned). */
+  remapToken(id: number): number;
+  /**
+   * Resolve a registered batch-adapter name to its executor adapter id +
+   * parsed deltas. Must throw a clear error for unregistered names (surfaced
+   * at submit() time, before the request is queued).
+   */
+  resolveAdapter(name: string): {
+    id: number;
+    deltas: LoRADelta[];
+  };
+  /** Serialize against generate()/embed() on the same engine. */
+  acquireLock(): Promise<() => void>;
+}
+interface SchedulerStats {
+  submitted: number;
+  completed: number;
+  stepsSubmitted: number;
+  prefillChunks: number;
+  tokensGenerated: number;
+  /** Wall-clock ms the serving loop was live (work outstanding). */
+  busyMs: number;
+  peakActiveLanes: number;
+}
+declare class RequestScheduler {
+  private readonly host;
+  private readonly batchSize;
+  private readonly maxSeqLen;
+  private readonly blockSize;
+  private readonly prefillChunk;
+  /** Free KV blocks kept unreserved as safety headroom. */
+  private readonly blockHeadroom;
+  private nextId;
+  private queue;
+  /** slot → occupying request (prefilling or decoding). */
+  private slots;
+  /** Sum of blocksReserved across live (admitted, unfinished) requests. */
+  private reservedBlocks;
+  private prefilling;
+  private inFlight;
+  /**
+   * The slot→adapter-id assignment last uploaded to the executor (null =
+   * nothing uploaded this batch session). Steps only re-upload when the
+   * assignment changes (admissions/retirements), and the very first upload is
+   * skipped entirely while every lane is bare base — an adapter-free serving
+   * session never touches the LoRA machinery.
+   */
+  private lastLaneAdapterIds;
+  private stepCounter;
+  private loop;
+  private closed;
+  private stats;
+  constructor(host: SchedulerHost, options?: {
+    prefillChunkTokens?: number;
+  });
+  /**
+   * Submit a request; resolves with the full result when it finishes.
+   * Tokens stream through options.onToken as they are decoded.
+   */
+  submit(prompt: string | ChatMessage[], options?: ServeOptions): Promise<ServeResult>;
+  /** Resolves when every submitted request has completed. */
+  drain(): Promise<void>;
+  /** Stop accepting requests; resolves when in-flight work drains. */
+  close(): Promise<void>;
+  getStats(): SchedulerStats;
+  private pump;
+  private hasWork;
+  private activeMask;
+  /** The serving loop. Holds the engine generation lock while live. */
+  private run;
+  /**
+   * Upload the slot→adapter assignment for the step about to be submitted,
+   * when it differs from the last uploaded one. Called immediately before
+   * every decode-step submit: `queue.writeBuffer` is queue-ordered, so steps
+   * already in flight keep the assignment they were submitted under, and a
+   * retiring lane's slot can never leak its adapter into the slot's next
+   * occupant — the next occupant's assignment is re-derived from `slots`
+   * before its first decode step. Masked (free/prefilling) lanes are pinned
+   * to bare base; their output is discarded regardless.
+   */
+  private syncLaneAdapters;
+  /**
+   * Admission: move the next queued request into a free slot when (a) a slot
+   * is free, (b) no other prefill is staged (the single-sequence prefill path
+   * stages SSM state in singleton buffers — one at a time), and (c) its
+   * worst-case block need fits the unreserved KV pool with headroom.
+   */
+  private admit;
+  /**
+   * Run one bounded prefill chunk for the staged request on the
+   * single-sequence path (into its slot's block-table row via tableBase).
+   * Intermediate chunks are submit-only; the final chunk reads logits, adopts
+   * the singleton SSM state into the slot's pool row, seeds the lane's first
+   * token, and flips the lane to decoding.
+   */
+  private prefillChunkStep;
+  /** Read the oldest in-flight step and deliver its tokens. */
+  private readStep;
+  /** Append one generated token; finish + retire the lane when terminal. */
+  private consumeToken;
+  /** Retire the lane immediately: free KV blocks, open the slot, resolve. */
+  private finish;
+}
+//#endregion
+//#region src/gpu/batch/swarm.d.ts
+/** Per-request options a swarm sub-task may set (the member picks the adapter). */
+type SwarmTaskOptions = Omit<ServeOptions, "adapter">;
+/** One planned sub-task: which member decodes which prompt. */
+interface SwarmTask {
+  /** Member name (a key of the swarm's `members`). */
+  member: string;
+  prompt: string | ChatMessage[];
+  /** Per-task overrides merged over the run's options. */
+  options?: SwarmTaskOptions;
+}
+/** One member's completed sub-task (plan order is preserved). */
+interface SwarmMemberResult {
+  member: string;
+  result: ServeResult;
+}
+/**
+ * Swarm configuration.
+ *
+ * @template R The reduced result type (defaults to the member-keyed map the
+ *   default reduce produces).
+ */
+interface SwarmOptions<R = Record<string, ServeResult>> {
   /**
-   * Greedy decode step: forward + GPU argmax. Returns token ID directly.
-   * Always uses matvec kernels (M=1). Reads back 4 bytes instead of vocab_size*4.
+   * Member name → adapter source (`hf:owner/repo`, URL, or `file:./dir`), or
+   * null for a member that decodes on the bare base. Every non-null source is
+   * registered on the engine (factors packed into shared GPU buffers once).
    */
-  forwardArgmax(inputIds: Uint32Array): Promise<number>;
-  /** KV-cache positions still available for decode steps. */
-  decodeCapacityRemaining(): number;
-  /** Number of decode steps that may be in flight in the pipelined path. */
-  static readonly PIPELINE_DEPTH = 2;
+  members: Record<string, string | null>;
   /**
-   * Pipelined greedy decode step (Dawn only — WebKit uses forwardArgmax).
-   *
-   * Encodes one full decode forward + argmax and submits WITHOUT awaiting
-   * completion. The input token is taken from `tokenId` for the first step
-   * after prefill; for subsequent steps (tokenId === null) the previous step's
-   * argmax result is copied into input_ids ON THE GPU, so the decode loop
-   * never blocks on a readback before submitting the next step. The argmax
-   * result is copied to a per-slot readback buffer, read later (one step
-   * behind) via readDecodeToken(slot).
+   * input → sub-tasks routed to members. Default: broadcast the input to
+   * every member (one sub-task each, declaration order).
+   */
+  plan?: (input: string, members: string[]) => SwarmTask[] | Promise<SwarmTask[]>;
+  /**
+   * Joined sub-results → final answer. Default: a member-keyed map of
+   * ServeResults (a duplicated member's later tasks get `name#2`, `name#3`…).
+   */
+  reduce?: (results: SwarmMemberResult[]) => R | Promise<R>;
+}
+/**
+ * A swarm handle: registered members + plan/reduce over the engine's
+ * scheduler. Create via {@link WebGPUEngine.createSwarm}.
+ */
+declare class Swarm<R = Record<string, ServeResult>> {
+  private readonly scheduler;
+  private readonly memberSources;
+  private readonly plan;
+  private readonly reduce;
+  constructor(scheduler: RequestScheduler, options: SwarmOptions<R>);
+  /** Member names, declaration order. */
+  get members(): string[];
+  /**
+   * Run one input through the swarm: plan → concurrent fan-out (one batched
+   * pass across the scheduler's lanes) → reduce.
    *
-   * queue.writeBuffer is queue-ordered: uniform updates land after the
-   * previously submitted step's command buffer and before this one's, so
-   * shared uniform buffers are safe with multiple steps in flight.
+   * @param input The task input handed to the plan (default plan: broadcast
+   *   it to every member as the prompt).
+   * @param options Per-request options applied to every sub-task (a task's
+   *   own `options` win field-by-field).
    */
-  submitGreedyDecodeStep(tokenId: number | null, slot: number): void;
-  /** Read back the token produced by the pipelined step that used `slot`. */
-  readDecodeToken(slot: number): Promise<number>;
-  reset(): void;
+  run(input: string, options?: SwarmTaskOptions): Promise<R>;
   /**
-   * Diagnostic: dispatch ONLY the first kernel (EmbeddingInt4) using the
-   * production bind group, pipeline, and buffers — but in isolation (1 dispatch,
-   * no staging, fresh encoder). Compares against full forward pass to isolate
-   * whether the issue is the bind group/pipeline or the multi-dispatch context.
+   * Mode-A access: decode one prompt with a single member (no plan/reduce).
+   * Still rides the shared scheduler, so it batches with any concurrent work.
    */
-  debugFirstDispatch(inputIds: Uint32Array): Promise<{
-    nodeId: string;
-    opType: string;
-    dispatchSize: [number, number, number];
-    output: Float32Array;
-  }>;
+  generate(member: string, prompt: string | ChatMessage[], options?: SwarmTaskOptions): Promise<ServeResult>;
+  private submitFor;
+}
+//#endregion
+//#region src/gpu/sampler.d.ts
+/**
+ * CPU-side token sampling from logits.
+ *
+ * Applies temperature, top-k, and top-p (nucleus) filtering,
+ * then samples from the resulting probability distribution.
+ *
+ * Uses typed arrays and min-heap for zero-allocation top-K selection.
+ * For vocab_size ~152K with topK=50, this avoids creating 152K JS tuples.
+ */
+interface SamplingParams {
+  temperature?: number;
+  topK?: number;
+  topP?: number;
+  repetitionPenalty?: number;
   /**
-   * Diagnostic: run a single dispatch entry by index, in isolation.
-   * Call after debugFirstDispatch() to test whether entry[1] (RMSNorm)
-   * can read embed_out written by entry[0] (EmbeddingInt4).
+   * Seed for the sampling RNG. When set, sampled decoding is reproducible:
+   * the same params object draws a deterministic random stream (seeded on its
+   * first use — pass a fresh options object per generation for run-to-run
+   * reproducibility). Unset: Math.random() (non-deterministic, the default).
    */
-  debugDispatchEntry(entryIndex: number, T: number): Promise<{
-    nodeId: string;
-    opType: string;
-    output: Float32Array;
-  }>;
+  seed?: number;
+}
+//#endregion
+//#region src/gpu/vision-preprocess.d.ts
+/**
+ * Host-side vision preprocessing for the Qwen3.5 ViT.
+ *
+ * The learned position embeddings (bilinear-interpolated over the patch grid)
+ * and the 2D rotary cos/sin tables are functions of the image grid (t, h, w)
+ * ONLY — not of the model weights or pixel values. They are cheap to compute on
+ * the CPU and fed to the GPU graph as input activations, keeping the graph to
+ * weight-dependent math while staying byte-identical to HF transformers.
+ *
+ * Ports (verified against transformers 5.12 vision_utils.py + modeling_qwen3_5):
+ *   - get_vision_bilinear_indices_and_weights  → buildPosEmbeds()
+ *   - get_vision_position_ids                  → buildPositionIds()
+ *   - Qwen3_5VisionRotaryEmbedding             → buildRotaryCosSin()
+ *
+ * Patch ordering: both the pos-embed gather and the position ids reorder patches
+ * into spatial_merge_size×spatial_merge_size groups, matching the HF image
+ * processor's output ordering, so the merger's [N,h]→[N/u,h*u] reshape lines up.
+ */
+interface VisionGridConfig {
+  hiddenSize: number;
+  numHeads: number;
+  numPositionEmbeddings: number;
+  spatialMergeSize: number;
+  ropeTheta?: number;
+}
+interface VisionPositionTensors {
+  /** [N, hidden_size] bilinear-interpolated learned position embeddings. */
+  posEmbeds: Float32Array;
+  /** [N, head_dim] rotary cosines. */
+  cos: Float32Array;
+  /** [N, head_dim] rotary sines. */
+  sin: Float32Array;
+  numPatches: number;
+}
+/**
+ * Build bilinear-interpolated learned position embeddings [N, hidden].
+ * posEmbedTable is the raw pos_embed.weight [num_position_embeddings, hidden].
+ */
+declare function buildPosEmbeds(gridTHW: [number, number, number], posEmbedTable: Float32Array, cfg: VisionGridConfig): Float32Array;
+/**
+ * Build the reordered (row, col) position ids [N, 2] for rotary, matching
+ * get_vision_position_ids.
+ */
+declare function buildPositionIds(gridTHW: [number, number, number], merge: number): Int32Array;
+/**
+ * Build rotary cos/sin tables [N, head_dim] from position ids, matching
+ * Qwen3_5VisionRotaryEmbedding + the cat((rotary, rotary)) in VisionModel.forward.
+ *
+ * rotary_pos_emb(position_ids) = (position_ids[..,None] * inv_freq).flatten(1)
+ *   where inv_freq has length (head_dim/2)/2 = head_dim/4, computed over dim=head_dim/2.
+ * For each token the two position components (h, w) each produce head_dim/4 freqs,
+ * concatenated → head_dim/2, then duplicated → head_dim for cos/sin.
+ */
+declare function buildRotaryCosSin(positionIds: Int32Array, headDim: number, theta?: number): {
+  cos: Float32Array;
+  sin: Float32Array;
+  numPatches: number;
+};
+/**
+ * Build all host position tensors for a single image grid in one call.
+ */
+declare function buildVisionPositionTensors(gridTHW: [number, number, number], posEmbedTable: Float32Array, cfg: VisionGridConfig): VisionPositionTensors;
+interface Gemma4VisionGridConfig {
+  hiddenSize: number;
+  numHeads: number;
+  headDim: number;
+  ropeTheta: number;
+  poolingKernelSize: number;
+}
+interface Gemma4VisionPositionTensors {
+  /** [N, hidden] axial position embeddings (table[0][x] + table[1][y]). */
+  posEmbeds: Float32Array;
+  /** [N, headDim] axial rotary cosines. */
+  cos: Float32Array;
+  /** [N, headDim] axial rotary sines. */
+  sin: Float32Array;
+  /** [Np, N] average-pooling matrix (1/k² in-cell, 0 elsewhere). */
+  poolMatrix: Float32Array;
+  /** number of patches N (= gridH*gridW). */
+  numPatches: number;
+  /** number of pooled (soft) tokens Np (= ceil(gridH/k)*ceil(gridW/k)). */
+  numPooled: number;
+}
+/**
+ * Build axial learned position embeddings [N, hidden] from the [2, posSize, hidden]
+ * table: pos[p] = table[0][x_p] + table[1][y_p]. Direct lookup, no interpolation
+ * (HF F.embedding on clamped positions).
+ */
+declare function buildGemma4PosEmbeds(gridH: number, gridW: number, posEmbedTable: Float32Array,
+// [2, posSize, hidden] flattened
+hidden: number, posSize: number): Float32Array;
+/**
+ * Build the 2D axial rotary cos/sin tables [N, headDim].
+ *   spatial_dim = headDim / 2;  inv_freq[j] = 1/theta^((2j)/spatial_dim), j in [0, spatial_dim/2)
+ *   per spatial dim: f = pos * inv_freq (spatial_dim/2 values); emb = cat(f, f) (spatial_dim values)
+ *   cos/sin = cat([emb_x, emb_y]) → headDim values, layout [fx,fx,fy,fy].
+ * Applied with the global-half rotate_half kernel (ApplyRotaryEmb), which computes
+ * out = x*cos + rotate_half(x)*sin element-wise — exact for this layout.
+ */
+declare function buildGemma4RotaryCosSin(gridH: number, gridW: number, headDim: number, theta: number): {
+  cos: Float32Array;
+  sin: Float32Array;
+};
+/**
+ * Build the [Np, N] average-pooling matrix for k×k spatial pooling over the real
+ * (unpadded) grid, matching modeling_gemma4's kernel_idxs/one_hot pooling:
+ *   cell(p) = floor(x_p/k) + ceil(gridW/k) * floor(y_p/k)
+ *   poolMatrix[cell, p] = 1/k²  (so pooled = poolMatrix @ hidden = mean over the k×k block)
+ * Np = ceil(gridH/k) * ceil(gridW/k). Each pooled cell averages exactly the patches
+ * that fall in it (edge cells with fewer than k² patches still divide by k², matching
+ * HF's fixed 1/k² normalization).
+ */
+declare function buildGemma4PoolMatrix(gridH: number, gridW: number, k: number): {
+  poolMatrix: Float32Array;
+  numPooled: number;
+};
+/**
+ * Build all Gemma 4 vision host tensors for one image grid in one call.
+ * `posEmbedTable` is the raw [2, posSize, hidden] flattened table.
+ */
+declare function buildGemma4VisionPositionTensors(gridH: number, gridW: number, posEmbedTable: Float32Array, posSize: number, cfg: Gemma4VisionGridConfig): Gemma4VisionPositionTensors;
+/** Gemma 4 image processor config (from processor_config.json). */
+declare const GEMMA4_IMAGE_PROCESSOR: ImageProcessorConfig;
+interface Gemma4PreprocessedImage {
+  /** Flattened patches [N, 3·patch²] row-major (row-major patch grid). */
+  patches: Float32Array;
+  /** Patch grid (gridH, gridW). */
+  gridHW: [number, number];
+}
+/**
+ * Preprocess a decoded RGB image for the Gemma 4 ViT: aspect-preserving resize so
+ * the patch grid is ≤ max_soft_tokens·k² patches and H,W divisible by k·patch,
+ * rescale ×1/255 (no normalize), patchify row-major into [N, 3·16·16].
+ *
+ * @param pixels row-major HWC RGB (0..255), length width*height*3.
+ */
+declare function preprocessImageGemma4(pixels: Float32Array | Uint8ClampedArray | Uint8Array, width: number, height: number, maxSoftTokens?: number, poolingKernelSize?: number, patchSize?: number): Gemma4PreprocessedImage;
+interface ImageProcessorConfig {
+  patchSize: number;
+  temporalPatchSize: number;
+  mergeSize: number;
+  imageMean: [number, number, number];
+  imageStd: [number, number, number];
+  /** rescale factor applied to raw 0..255 pixels before normalization (1/255). */
+  rescaleFactor: number;
+  /** min total pixels after resize (shortest_edge). */
+  minPixels: number;
+  /** max total pixels after resize (longest_edge). */
+  maxPixels: number;
+}
+declare const QWEN3_5_IMAGE_PROCESSOR: ImageProcessorConfig;
+interface PreprocessedImage {
+  /** Flattened patches [N, 1536] in the spatial-merge order encodeImage expects. */
+  patches: Float32Array;
+  /** (t, h, w) patch grid. t=1 for a single image, h/w in patch units. */
+  gridTHW: [number, number, number];
+}
+/**
+ * Qwen2-VL smart-resize: round H and W to multiples of factor=patch*merge,
+ * keeping aspect ratio and clamping the total pixel budget to [minPixels, maxPixels].
+ * Matches transformers.models.qwen2_vl.image_processing.smart_resize.
+ */
+declare function smartResize(height: number, width: number, factor: number, minPixels: number, maxPixels: number): [number, number];
+/**
+ * Preprocess a decoded RGB image into the [N, 1536] patch tensor + grid_thw that
+ * `encodeImage()` expects, matching the HF Qwen2-VL image processor:
+ *   smart_resize → rescale (×1/255) → normalize → temporal-pair (×temporal_patch_size)
+ *   → patchify into spatial_merge×spatial_merge blocks → flatten to [N, C·T·P·P].
+ *
+ * @param pixels row-major HWC RGB, length width*height*3. Values 0..255 (default)
+ *   or already 0..1 if `rescaled` is true.
+ * @param width  source pixel width
+ * @param height source pixel height
+ */
+declare function preprocessImage(pixels: Float32Array | Uint8ClampedArray | Uint8Array, width: number, height: number, cfg?: ImageProcessorConfig, rescaled?: boolean): PreprocessedImage;
+declare function buildMRoPEPositionIds(inputIds: Int32Array | Uint32Array | number[], imageGrids: Array<[number, number, number]>, imageTokenId: number, mergeSize: number): Int32Array;
+/**
+ * Per-pair frequency→dimension assignment for interleaved M-RoPE, matching
+ * Qwen3_5TextRotaryEmbedding.apply_interleaved_mrope. For pair index i in
+ * [0, sum(section)) the position component is section-cyclic: T,H,W,T,H,W,...
+ * but each component capped at its section count. Returns an array of length
+ * (rope_dim/2) with values 0=T, 1=H, 2=W.
+ */
+declare function mropeFreqDims(mropeSection: [number, number, number]): Int32Array;
+/**
+ * Build the interleaved-M-RoPE cos/sin tables [seq, rope_dim] from 3D position
+ * ids, matching Qwen3_5TextRotaryEmbedding.forward:
+ *   freqs[d][i] = pos[d] * inv_freq[i],  inv_freq[i] = 1/theta^(2i/rope_dim)
+ *   freq[i] picks component mropeFreqDims[i]; emb = cat(freqs, freqs).
+ * cos/sin have length seq*rope_dim. For text-only (all 3 pos rows equal) this
+ * reduces exactly to standard 1D partial RoPE.
+ *
+ * @param positionIds3 [3, seq] as produced by buildMRoPEPositionIds.
+ * @param ropeDim      number of rotated dims per head (head_dim * partial_factor).
+ */
+declare function buildMRoPECosSin(positionIds3: Int32Array, seq: number, ropeDim: number, theta: number, mropeSection: [number, number, number]): {
+  cos: Float32Array;
+  sin: Float32Array;
+};
+//#endregion
+//#region src/gpu/defaults.d.ts
+/**
+ * Default model per capability. Kept in its own tiny module (no heavy imports)
+ * so the React hooks can resolve defaults without statically pulling in the GPU
+ * engine — they import the engine dynamically to stay light.
+ */
+declare const DEFAULT_MODELS: {
+  /** Text generation (also the vision-capable checkpoint). */
+  readonly text: "mlx-community/Qwen3.5-0.8B-4bit";
+  /** Image understanding — same checkpoint, vision tower built on demand. */
+  readonly vision: "mlx-community/Qwen3.5-0.8B-4bit";
+  /** Text embeddings. */
+  readonly embedding: "mlx-community/embeddinggemma-300m-4bit";
+  /** Text-to-speech (Apache-2.0; LFM2-350M backbone + NanoCodec). Small/fast default. */
+  readonly tts: "nineninesix/kani-tts-450m-0.2-ft";
   /**
-   * Diagnostic: compute the JS-side params for the first N decode entries
-   * WITHOUT dispatching. Shows what buildParams produces.
+   * Selectable many-voices TTS (OuteTTS-1.0-0.6B: Qwen3-0.6B codec-LM + DAC.speech).
+   * Pass this as the `repo`/`model` to engine.speak()/useTTS to route to OuteTTS.
    */
-  debugComputeParams(T: number, count?: number): Array<{
-    idx: number;
-    nodeId: string;
-    opType: string;
-    paramsU32: number[];
-    dispatchSize: [number, number, number];
-  }>;
+  readonly ttsOute: "OuteAI/OuteTTS-1.0-0.6B";
   /**
-   * Diagnostic: after a forward pass, read back output tensors at several points
-   * in the pipeline to find where data drops to zero.
+   * Selectable describe-your-voice TTS (Parler-TTS-mini-v1: Flan-T5 encoder +
+   * cross-attending decoder LM + dac_44khz). Pass this as the `repo`/`model` to
+   * engine.speak()/useTTS with a `describeVoice` natural-language description.
    */
-  debugPipelineProbe(T: number): Promise<Array<{
-    idx: number;
-    nodeId: string;
-    opType: string;
-    tensor: string;
-    sum: number;
-    first4: number[];
-    uniformParams?: number[];
-  }>>;
-  debugWriteBuffer(tensorName: string, data: ArrayBufferView): void;
+  readonly ttsParler: "parler-tts/parler-tts-mini-v1";
   /**
-   * Write a host-supplied activation input buffer (e.g. multimodal M-RoPE
-   * cos/sin, spliced vision embeddings, image row-map). The buffer must be a
-   * persistent activation tensor in the graph. Call before forward().
+   * Selectable streaming TTS (Gepard-1.0: stock Qwen3.5 full-attention codec-LM +
+   * 32 parallel FSQ classifier heads emitting a whole audio frame per forward +
+   * NanoCodec 21.5 fps decoder). Apache-2.0. Frame-synchronous, so audio streams
+   * out chunk-by-chunk via speak(text, { model, onChunk }).
    */
-  writeInput(tensorName: string, data: ArrayBufferView): void;
-  /** Write a host activation buffer at a byte offset (for per-row decode updates). */
-  writeInputAt(tensorName: string, data: ArrayBufferView, byteOffset: number): void;
-  /** True if the graph has a buffer with this name (multimodal-capability probe). */
-  hasBuffer(tensorName: string): boolean;
-  /** Current sequence position (number of tokens processed since reset). */
-  get currentSeqPos(): number;
-  debugReadBuffer(tensorName: string, maxElements?: number, byteOffset?: number): Promise<Float32Array>;
-  destroy(): void;
+  readonly ttsGepard: "nineninesix/gepard-1.0";
+  /** Speech-to-text. */
+  readonly stt: "UsefulSensors/moonshine-base";
+};
+declare const OUTETTS_ASSETS: {
+  /** Folded DAC.speech.v1.0 encoder+decoder weights (prep-dac-speech.py output). */
+  readonly codecWeightsURL: "https://pub-0522ecec25fc412bb35a523f3e3f63c6.r2.dev/tryhamster/gerbil-outetts-assets/dac-speech-folded.safetensors";
+  /** Base URL for the preset speaker JSONs (`{name}.json`). */
+  readonly speakersBaseURL: "https://pub-0522ecec25fc412bb35a523f3e3f63c6.r2.dev/tryhamster/gerbil-outetts-assets/speakers";
+  /** The default preset voice. */
+  readonly defaultVoice: "en-female-1-neutral";
+};
+/**
+ * Bundled OuteTTS preset voices.
+ *
+ * Provenance (honest labelling):
+ *  - `en-female-1-neutral` is the ONE AUTHENTIC OuteAI voice — the OuteTTS v3 bundled
+ *    default speaker (default_speakers/en-female-1-neutral), copied verbatim.
+ *  - `gerbil-voice-2..6` are DERIVED voices: distinct timbres produced by running
+ *    pitch/tempo-varied renderings of that authentic clip back through the REAL
+ *    DAC.speech encode + prosody pipeline (scripts/engine/stage-outetts-assets.py).
+ *    They are genuine DAC-encoded OuteSpeakers, but they are NOT OuteAI's own
+ *    `en-male-*` voices, so they are not labelled as such. (Earlier builds mislabelled
+ *    them as `en-male-2-neutral` etc.; renamed for honesty.)
+ */
+declare const OUTETTS_PRESET_VOICES: readonly ["en-female-1-neutral", "gerbil-voice-2", "gerbil-voice-3", "gerbil-voice-4", "gerbil-voice-5", "gerbil-voice-6"];
+/**
+ * True when `repo`/`architecture` identify a text-to-speech checkpoint that must
+ * run through a dedicated native TTS engine (KaniTTS, OuteTTS, or Parler-TTS)
+ * rather than the single-graph base text loader. Mirrors the routing used by
+ * `WebGPUEngine.speak()` / `Gerbil.ensureNativeTTSEngine`:
+ *   - Parler  → encoder-decoder (`ParlerTTSForConditionalGeneration`)
+ *   - OuteTTS → Qwen3-0.6B codec-LM
+ *   - Kani    → conv-backbone codec-LM (`KaniTTS2ForCausalLM`, or the Apache
+ *               default which is a plain `Lfm2ForCausalLM` — hence the repo-name
+ *               gate; the architecture string alone does not identify it).
+ * At `create()` time only the repo is known (the architecture is discovered
+ * during load), so the repo-name signals below cover all three DEFAULT_MODELS
+ * and conventionally-named TTS repos; the architecture arg is honored when a
+ * caller already has it.
+ */
+declare function isTTSRepo(repo?: string, architecture?: string): boolean;
+/** Resolve the model repo for a set of options, falling back to the defaults. */
+declare function resolveDefaultRepo(opts: {
+  repo?: string;
+  embedding?: boolean;
+  enableVision?: boolean;
+}): string;
+//#endregion
+//#region src/gpu/architectures/gemma4_vision.d.ts
+interface Gemma4VisionGraphInfo {
+  hiddenSize: number;
+  numHeads: number;
+  headDim: number;
+  depth: number;
+  intermediateSize: number;
+  textHidden: number;
+  patchSize: number;
+  patchDim: number;
+  poolingKernelSize: number;
+  ropeTheta: number;
+  rmsNormEps: number;
+}
+/**
+ * Resolve the Gemma 4 vision dims from a raw HF config. Accepts either the
+ * top-level config (reads `.vision_config` + `.text_config.hidden_size`) or a
+ * bare vision_config (then `textHidden` falls back to the projector row count if
+ * present, else hidden). Family-general — no E2B constants.
+ */
+declare function resolveGemma4VisionInfo(rawConfig: Record<string, unknown>): Gemma4VisionGraphInfo;
+/**
+ * Dequantize an MLX affine-int4 weight to a plain f32 [rows, cols] matrix.
+ * MLX packs 8 int4 values per u32 (low-nibble first); each group of `groupSize`
+ * columns shares one scale + bias: w[r,c] = scale[r, c/gs] * q + bias[r, c/gs].
+ * Used for the Gemma 4 multimodal projector (`embed_vision.embedding_projection`)
+ * in MLX-4bit checkpoints, where (unlike the BF16 ViT body) the projector is int4.
+ */
+declare function dequantizeMLXProjection(packed: Uint32Array, scales: Float32Array, biases: Float32Array, rows: number, cols: number, groupSize: number): Float32Array;
+/**
+ * If the Gemma 4 multimodal projector arrived as an MLX affine-int4 triplet
+ * (`embed_vision.embedding_projection.{weight(U32), scales, biases}`), dequantize
+ * it in-place to a plain f32 `embed_vision.embedding_projection.weight` and drop
+ * the scales/biases, so the vision graph's plain MatMul on the projector works for
+ * MLX-4bit checkpoints too. No-op for BF16 (HF) checkpoints (weight already f32).
+ */
+declare function dequantizeGemma4VisionProjection(weights: Map<string, {
+  data: ArrayBufferView;
+  shape: number[];
+}>, groupSize: number, rows: number, cols: number): void;
+/**
+ * Patch the ClippedMatMul nodes of a Gemma 4 vision graph with the calibrated clip
+ * scalars from the checkpoint (Gemma4ClippableLinear's per-tensor input/output
+ * min/max buffers), then drop those scalar tensors from the weights map so the
+ * vision executor doesn't try to upload them as GPU buffers. Call BEFORE
+ * VisionExecutor.uploadWeights(). Missing scalars default to ±inf (clip = identity),
+ * so a checkpoint without calibration still loads.
+ */
+declare function patchGemma4VisionClips(graph: ModelGraph, weights: Map<string, {
+  data: ArrayBufferView;
+  shape: number[];
+}>): void;
+/**
+ * Build the Gemma 4 ViT graph. Shaped by symbolic "N" (number of patches, runtime)
+ * and "Np" (number of pooled tokens = ceil(grid_h/k)·ceil(grid_w/k), runtime),
+ * resolved from input tensor dims — like the Qwen ViT's "N"/"Nm".
+ */
+declare function generateGemma4VisionGraph(rawConfig: Record<string, unknown>): ModelGraph;
+//#endregion
+//#region src/gpu/architectures/gepard_tts.d.ts
+/** Per-channel FSQ cardinalities in head order (channel c = group⌊c/4⌋, dim c%4). */
+declare function gepardChannelLevels(): number[];
+/** Text-repetition layout config (stamped into gepard_config.json). */
+interface GepardTextRepetition {
+  enabled: boolean;
+  targetTextTokens: number;
+  applyBelow: number;
+  maxRepeats: number;
+}
+/** Parsed gepard_config.json — everything the host driver needs. */
+interface GepardConfig {
+  /** The nested Qwen3.5 backbone config (fed to generateGepardBackboneGraph). */
+  backboneConfig: Record<string, unknown>;
+  /** Per-head vocab sizes in channel order (level_audio_0..31). */
+  vocabSizes: number[];
+  audioEmbedDim: number;
+  startOfText: number;
+  endOfText: number;
+  startOfSpeech: number;
+  textRepetition: GepardTextRepetition;
+  /** Codec identity + geometry from the config's codec block. */
+  codecId: string;
+  fsqLevels: number[];
+  sampleRate: number;
+}
+/**
+ * Parse gepard_config.json. Head order is recovered from the numeric suffix of
+ * each `level_audio_{i}` key (NOT the serialized key order), so the wiring is
+ * immune to any JSON round-trip that re-sorts keys.
+ */
+declare function parseGepardConfig(raw: Record<string, unknown>): GepardConfig;
+/**
+ * Build the (possibly repeated) text-id layout — mirrors the reference
+ * TextRepeater byte-for-byte (text_repetition.py):
+ *   R == 1 → [ SOT, *text, EOT, SOS ]
+ *   R >  1 → [ SOT, *text, EOT ] × (R−1) + [ SOT, *text, EOT, SOS ]
+ * Only the final (canonical) copy carries SOS. R is deterministic from the
+ * text-token count: ceil(target / n) capped at maxRepeats, applied only when
+ * n < applyBelow (short prompts derail without the extra text mass).
+ */
+declare function buildGepardTextLayout(textTokenIds: number[], cfg: GepardConfig): number[];
+/**
+ * Dequantize per-channel FSQ codes [32, T] (channel-major) into the decoder
+ * latent [32, T] f32: value = (code − L//2) / (L//2), matching
+ * UnfoldedCodecModel.decode_from_codes / codec_ops.dequantize_codes.
+ */
+declare function gepardCodesToLatent(codes: Uint32Array, numFrames: number): Float32Array;
+declare function generateGepardBackboneGraph(backboneConfig: Record<string, unknown>, dtype?: GraphDType, groupSizeOverride?: number, kvDtype?: KVDType): ModelGraph;
+//#endregion
+//#region src/gpu/architectures/kani_tts.d.ts
+/** Parsed KaniTTS2 backbone config (the LFM2 dims + the TTS-specific fields). */
+interface KaniConfig {
+  textVocabSize: number;
+  vocabSize: number;
+  tokensPerFrame: number;
+  audioStep: number;
+  useLearnableRope: boolean;
+  alphaMin: number;
+  alphaMax: number;
+  speakerEmbDim: number;
+  audioTokensStart: number;
+  startOfSpeech: number;
+  endOfSpeech: number;
+  codebookSize: number;
   /**
-   * Allocate activation buffers with liveness-based reuse.
-   *
-   * One dedicated buffer per activation tensor at full maxSeqLen is ~2.3GB for
-   * Qwen3.5-0.8B at T=512 — over the iOS jetsam budget on its own. Instead,
-   * a buffer returns to a size-keyed pool once its tensor's last reader has
-   * executed, so concurrently-live tensors share a small working set.
-   *
-   * Graph outputs and tensors read before they are written (cross-forward
-   * state) keep dedicated buffers. Within a forward, dispatches execute in
-   * executionOrder on every path (single-pass Dawn, per-dispatch WebKit), and
-   * WebGPU synchronizes hazards between dispatches, so reuse is safe.
-   *
-   * Caveat: debugReadBuffer() on an intermediate tensor is only meaningful
-   * before a later op reuses its buffer (probes that stop mid-graph are fine).
+   * Whether the backbone uses KaniTTS2's frame-level position IDs (the 4 audio
+   * tokens of a frame share one logical position) + learnable per-layer RoPE.
+   * The `KaniTTS2ForCausalLM` checkpoints (e.g. kani-tts-2-en) do; the plain
+   * `Lfm2ForCausalLM` family (e.g. the Apache kani-tts-450m-0.2-ft / kani-tts-370m)
+   * does NOT — those run standard sequential positions with α=1 plain RoPE.
+   * Detected from the presence of `use_learnable_rope`/`tokens_per_frame`/the
+   * `KaniTTS2ForCausalLM` architecture marker in config.json.
    */
-  private allocateActivationBuffers;
-  private allocateSSMStateBuffers;
-  private allocateKVCacheBuffers;
-  private resolveShapes;
-  private getBuffer;
+  frameLevelPositions: boolean;
+}
+declare function parseKaniConfig(rawConfig: Record<string, unknown>): KaniConfig;
+/**
+ * Convert the model's flat audio-token stream (the IDs between start/end-of-speech)
+ * into NanoCodec codes [NUM_GROUPS, T]. Mirrors NemoAudioPlayer.get_nano_codes:
+ *   reshape [-1, 4]; codes[:,c] -= codebook_size*c; codes -= audio_tokens_start;
+ *   transpose → [4, T]. Returns a Uint32Array laid out group-major ([g*T + t]).
+ */
+declare function audioTokensToCodes(audioTokenIds: number[], cfg?: KaniConfig): {
+  codes: Uint32Array;
+  numFrames: number;
+};
+interface NanoCodecGraphOptions {
+  /** Number of audio frames T (the code grid width). PCM length = T * hop. */
+  numFrames: number;
   /**
-   * Detect gate_proj + up_proj + SwiGLU patterns in decode entries and replace
-   * with a single fused SwiGLUMatVec dispatch. Saves 2 dispatches per MLP block.
+   * Optional decoder geometry override. Defaults to the Kani 12.5 fps codec
+   * (rates [7,7,6,3,2], input dim 16). Gepard's 21.5 fps codec is the SAME
+   * CausalHiFiGANDecoder family with rates [8,8,4,2,2] and input dim 32.
    */
-  private fuseSwiGLUDecodeEntries;
-  /**
-   * Fuse two adjacent INT4 projections that share the same input activation and
-   * the same K/N (e.g. q_proj+gate_proj and k_proj+v_proj in full-attention
-   * decode) into a single DualMatVecInt4 dispatch. Reads the shared input vector
-   * once and writes both projection outputs — removing one GPU round-trip (one
-   * submit+drain on Safari/iOS) per fused pair.
-   *
-   * Numerics are identical to running the two MatVecInt4 kernels separately
-   * (same dequant, same K-parallel reduction), so this is WebKit-safe: it reuses
-   * the proven INT4 matvec math and only merges two writes into one dispatch.
-   *
-   * Must run AFTER fuseSwiGLUDecodeEntries so the MLP gate+up pair (which is
-   * consumed by a SwiGLU node) is already collapsed and won't be matched here.
+  geometry?: {
+    upSampleRates: readonly number[];
+    inputDim: number;
+  };
+  /**
+   * When true the graph takes the dequantized FSQ latent directly as a host
+   * input ("nc_latent" [inputDim, T] f32) instead of packed "audio_codes" u32 —
+   * used by Gepard, whose 32 per-dimension codes dequantize trivially host-side.
    */
-  private fuseDualMatVecDecodeEntries;
+  latentInput?: boolean;
+}
+declare function generateNanoCodecDecoderGraph(opts: NanoCodecGraphOptions): ModelGraph;
+/**
+ * Generate the KaniTTS codec-LM backbone graph (LFM2-350M body, full-vocab logits,
+ * per-layer learnable MRoPE). Mirrors generateLfm2Graph block-for-block; the only
+ * difference is that each attention layer rotates Q/K with the MRoPE op fed a
+ * per-layer host cos/sin table instead of the position-counter RoPE op.
+ *
+ * dtype:
+ *   • undefined / "f32" — full precision (the checkpoint is bf16/f32 → f32).
+ *   • "q4" — weight-only group-wise INT4 (W4A16) for the LFM2 linear projections
+ *     (q/k/v/o, gate/up/down, short-conv in/out_proj) via MatMulInt4. The tied
+ *     embedding + LM head stay at f32 on purpose: decoder-LM heads are the most
+ *     quantization-sensitive part of a codec-LM and the embed table is the single
+ *     buffer shared by both, so quantizing it would degrade audio quality for no
+ *     load-size win that the int4 projections do not already capture. Backbone
+ *     drops from ~1.5 GB (f32) to ~0.37 GB. The NanoCodec decoder is a separate
+ *     graph and always runs f32.
+ */
+declare function generateKaniTtsGraph(rawConfig: Record<string, unknown>, dtype?: GraphDType, groupSize?: number, kvDtype?: KVDType): ModelGraph;
+//#endregion
+//#region src/gpu/architectures/moonshine.d.ts
+/**
+ * Historical record of the executor-side work the keystone left open; all items
+ * are now implemented (see the STATUS note above). Retained as exported
+ * documentation of the dependency surface.
+ */
+declare const MOONSHINE_REMAINING_WORK: readonly ["DONE: Transpose op kernel (conv output [C,L] → encoder input [L,C]).", "DONE: GroupNorm(num_groups=1) over conv channels (weight+bias).", "DONE: Tanh elementwise op (conv1 activation).", "DONE: Interleaved-RoPE variant (Moonshine rotates adjacent dim pairs 2p/2p+1).", "DONE: No-bias LayerNorm variant (Moonshine norms are weight-only).", "DONE: Per-utterance conv graph regeneration from the concrete sample count.", "DONE: Dual-graph executor — encoder once → frozen cross-attn K/V → AR decode.", "DONE: engine.transcribe(pcm) host path (MoonshineSTT): conv → encode → AR decode → detokenize."];
+interface MoonshineDims {
+  hidden_size: number;
+  enc_layers: number;
+  dec_layers: number;
+  num_heads: number;
+  num_kv_heads: number;
+  head_dim: number;
+  rotary_dim: number;
+  intermediate_size: number;
+  vocab_size: number;
+  rope_base: number;
+  context_length: number;
+  ln_eps: number;
+}
+/** Pull and derive Moonshine dimensions from the raw HF config. */
+declare function parseMoonshineConfig(raw: Record<string, unknown>): MoonshineDims;
+/** Number of encoder frames produced by the conv frontend for n_samples PCM. */
+declare function moonshineEncoderFrames(nSamples: number): number;
+/**
+ * Encoder graph: raw-waveform conv frontend + bidirectional transformer.
+ * @param nSamples concrete PCM sample count (the conv frontend is length-static).
+ * The output tensor "encoder_out" is [T_frames, hidden] and is consumed (after
+ * per-layer K/V projection) as the frozen K/V for the decoder's cross-attention.
+ */
+declare function generateMoonshineEncoderGraph(raw: Record<string, unknown>, nSamples: number): ModelGraph;
+/**
+ * Decoder graph: AR transformer with causal self-attn (KV-cache) + cross-attn to
+ * the frozen encoder output. Built for a single decode step (T=1). The encoder K/V
+ * are supplied as graph inputs "enc_k_layer{i}" / "enc_v_layer{i}" — the host
+ * pre-projects the encoder output through each layer's encoder_attn.k_proj/v_proj
+ * ONCE and binds them frozen for the whole decode (the CrossAttention contract).
+ */
+declare function generateMoonshineDecoderGraph(raw: Record<string, unknown>, sEnc: number): ModelGraph;
+//#endregion
+//#region src/gpu/architectures/outetts.d.ts
+/** Parsed OuteTTS backbone config (the Qwen3 dims). Reuses the generic Qwen path. */
+interface OuteTtsConfig {
+  hidden_size: number;
+  num_layers: number;
+  num_heads: number;
+  num_kv_heads: number;
+  head_dim: number;
+  intermediate_size: number;
+  vocab_size: number;
+  rope_base: number;
+  rms_norm_eps: number;
+  max_position_embeddings: number;
+}
+declare function parseOuteTtsConfig(rawConfig: Record<string, unknown>): OuteTtsConfig;
+/**
+ * Convert the flat generated token stream (the run BETWEEN <|audio_start|> and
+ * <|audio_end|>) into a DAC code grid [NUM_CODEBOOKS, T] (codebook-major [c*T + t]).
+ *
+ * Mirrors outetts v3 `extract_audio_from_tokens`: filter the stream into two ordered
+ * lists by membership of the c1 / c2 ranges, recover the raw code
+ * (id − base), drop the reserved index 1024, and truncate to the shorter list. The
+ * model emits c1,c2 interleaved per frame, but the parse is membership-based (it does
+ * not assume strict pairing) so a stray token cannot desync the grid.
+ */
+declare function audioTokensToDacCodes(tokenIds: number[]): {
+  codes: Uint32Array;
+  numFrames: number;
+};
+interface DacSpeechGraphOptions {
+  /** Number of audio frames T (the code-grid width). */
+  numFrames: number;
   /**
-   * Fuse the adjacent K-cache and V-cache appends in each full-attention layer
-   * into a single DualKVCacheAppend dispatch. Both are pure memcpys into f32
-   * caches sharing the same width and dst_offset, so one dispatch with two
-   * src/dst buffers writes both — removing one GPU round-trip per layer.
-   *
-   * Supports f32, native-f16, and packed-f16 caches (the dual kernel mirrors the
-   * single-append kernel selected for the active kvMode). Numerically identical
-   * to the separate appends — WebKit-safe (the packed-f16 variant is the Safari
-   * path and uses pack2x16float, no `enable f16`).
+   * Number of RVQ codebooks. Default 2 (DAC.speech.v1.0). Parler-TTS's
+   * dac_44khz_8kbps uses 9 — the RVQDequant kernel loops over NCB so the only
+   * change is the codebook/out_proj tensor first-dim and the codes grid height.
    */
-  private fuseDualKVCacheAppendEntries;
+  numCodebooks?: number;
   /**
-   * Fuse the attention SigmoidGate (attn_out * sigmoid(gate)) into the INT4
-   * o_proj that consumes it: a GatedMatVecInt4 reads attn_out and gate directly,
-   * applies the sigmoid gate to its input vector, and runs the projection in ONE
-   * dispatch — removing the standalone SigmoidGate (one round-trip per
-   * full-attention layer).
-   *
-   * Numerically identical to SigmoidGate→MatVecInt4 (same gate formula, same INT4
-   * dequant + reduction). Slight extra ALU: the gated input is recomputed per
-   * output column, but A reads hit L1 and the saved submit+drain dominates on
-   * mobile. WebKit risk: low — reuses the proven INT4 matvec, only the A vector
-   * is built from two reads + a sigmoid (no new reduction/barrier pattern).
-   *
-   * Runs after the dual fusions so it only sees the post-attention SigmoidGate.
+   * Decoder upsampling rates (the DecoderBlock strides). Default [8,5,4,2]
+   * (DAC.speech.v1.0). Parler's dac_44khz uses [8,8,4,2] (hop 512). Channels
+   * still halve per stage from `decoderDim`.
    */
-  private fuseGatedOProjDecodeEntries;
+  decoderRates?: readonly number[];
+  /** First-conv output channels (decoder_dim). Default 1536. */
+  decoderDim?: number;
+  /** Quantizer out_proj output / first-conv input dim (latent_dim). Default 1024. */
+  latentDim?: number;
+}
+declare function generateDacSpeechDecoderGraph(opts: DacSpeechGraphOptions): ModelGraph;
+/**
+ * Final decoded PCM length (samples) for a T-frame code grid, via the DAC stage chain.
+ * `rates` defaults to DAC.speech.v1.0 ([8,5,4,2]); pass [8,8,4,2] for Parler's dac_44khz.
+ */
+declare function dacOutputLength(numFrames: number, rates?: readonly number[]): number;
+declare function generateOuteTtsBackboneGraph(rawConfig: Record<string, unknown>, dtype?: GraphDType, groupSize?: number, kvDtype?: KVDType): ModelGraph;
+//#endregion
+//#region src/gpu/architectures/qwen3_5_vision.d.ts
+/**
+ * Build the ViT graph. The graph is shaped by symbolic "N" (number of patches),
+ * resolved at run time from the input tensor's first dim — exactly like the LM's
+ * symbolic "T".
+ */
+declare function generateQwen3_5VisionGraph(rawConfig: Record<string, unknown>): ModelGraph;
+//#endregion
+//#region src/gpu/gepard-tts.d.ts
+/**
+ * Gepard-1.0 — native streaming text-to-speech engine for Gerbil's WebGPU backend.
+ *
+ * Gepard (nineninesix/gepard-1.0, Apache-2.0) is a frame-synchronous multihead
+ * codec-LM TTS. Unlike the token-serial Kani/Oute engines (which emit one codec
+ * token per forward), Gepard emits ONE WHOLE AUDIO FRAME per backbone forward:
+ *
+ *   1. BACKBONE (GPU): stock Qwen3.5 full-attention body (14 layers, hidden 1024)
+ *      run through generateGepardBackboneGraph — input is a host-written
+ *      `inputs_embeds` row, output is the last position's final-norm hidden state.
+ *   2. OVERLAY (host): 32 parallel classifier heads (cardinalities [8,7,6,6]×8,
+ *      216 logits total) + a binary stop head read the hidden state; the sampled
+ *      32 FSQ codes feed back through per-channel embeddings → concat → GELU MLP
+ *      → affine-free LayerNorm → × audio_embed_scale as the next step's input.
+ *   3. CODEC (GPU): NanoCodec 21.5 fps decoder (same validated CausalHiFiGAN
+ *      graph family as Kani's codec, rates [8,8,4,2,2], hop 1024) turns the
+ *      per-channel codes into 22.05 kHz PCM — decoded incrementally in chunks
+ *      with left-context lookback, so audio streams out while the model is
+ *      still generating (≈1.5 s of audio per 32-frame chunk).
+ *
+ * Mirrors gepard-inference (runner.py) semantics: adaptive text repetition,
+ * SOS-seeded first frame, stop-head termination, independent per-head sampling
+ * (temperature / top-k / windowed repetition penalty) in fp32. Voice cloning
+ * (the ref_compressor speaker prefix) is NOT wired yet — the default voice ships
+ * first; cloning is a documented follow-up.
+ */
+/** Backbone weight precision for the codec-LM. */
+type GepardDType = "q4" | "f32";
+interface GepardTTSOptions {
+  /** Backbone repo (default nineninesix/gepard-1.0, Apache-2.0). */
+  repo?: string;
+  /** NanoCodec repo (default the mlx-community 21.5 fps MLX mirror). */
+  codecRepo?: string;
+  revision?: string;
+  hfToken?: string;
+  cacheDir?: string;
   /**
-   * Fuse a standalone SwiGLU (silu(gate) * up) into the INT4 projection that
-   * consumes its output: a SwiGLUGatedMatVecInt4 reads gate and up directly,
-   * builds the gated input vector, and runs the projection in ONE dispatch.
-   * Targets the Mamba block's mamba_swiglu (silu(z) * norm_out) feeding out_proj
-   * — one round-trip saved per linear-attention layer.
-   *
-   * The MLP SwiGLU is already collapsed into a SwiGLUMatVec entry by
-   * fuseSwiGLUDecodeEntries (it has no surviving standalone SwiGLU node), so only
-   * the Mamba SwiGLU matches here. Numerically identical to SwiGLU→MatVecInt4;
-   * WebKit risk low (reuses the proven INT4 matvec, only the A vector changes).
+   * Backbone weight precision (default "q4"):
+   *   • "q4"  — group-wise INT4 (W4A16) on the Qwen3.5 linear projections
+   *             (backbone ~1.05 GB f32 → ~0.13 GB). Recommended default.
+   *   • "f32" — full precision (largest, highest fidelity).
+   * The overlay always runs f32 on the host; the codec decoder always runs f32.
    */
-  private fuseSwiGLUGatedProjDecodeEntries;
+  dtype?: GepardDType;
+  /** Max KV-cache length: text layout + 1 position per audio frame. Default 2048. */
+  maxSeqLen?: number;
+  onProgress?: (loaded: number, total: number, message: string) => void;
+}
+/** One streamed audio chunk (decoded incrementally during generation). */
+interface GepardAudioChunk {
+  /** Mono PCM in [-1, 1] for this chunk only. */
+  pcm: Float32Array;
+  /** Sample rate (22050). */
+  sampleRate: number;
+  /** Index of the first audio frame this chunk covers. */
+  frameIndex: number;
+  /** True for the last chunk of the utterance. */
+  isFinal: boolean;
+}
+interface GepardSpeakOptions {
+  /** Sampling temperature (default 0.4 — the reference production operating point). */
+  temperature?: number;
+  /** Top-k cutoff per head (default 0 = disabled). */
+  topK?: number;
+  /** Stop-head sigmoid threshold (default 0.5). */
+  stopThreshold?: number;
+  /** Max audio frames to generate (caps duration; default 2000, ~93 s). */
+  maxFrames?: number;
+  /** Per-head repetition penalty over a recent-frame window (default 1.0 = off). */
+  repetitionPenalty?: number;
+  /** Number of recent frames tracked for repetitionPenalty (default 32). */
+  repetitionWindow?: number;
   /**
-   * Fuse two adjacent per-row RMSNorms sharing hidden_size + eps into a single
-   * DualRMSNorm dispatch (e.g. the per-head q_norm and k_norm in full-attention
-   * decode). One workgroup still handles one row; the fused grid just spans both
-   * inputs' rows, so each row's reduction is unchanged — numerically identical to
-   * two separate RMSNorm dispatches. One round-trip saved per fused pair.
-   *
-   * WebKit risk: low — same single-workgroup reduction as the proven RMSNorm
-   * kernel, only the row→input routing is added.
+   * Streaming callback: called with each decoded audio chunk while generation is
+   * still running (frame-synchronous decode → real streaming, not post-hoc
+   * chunking). The final chunk carries `isFinal: true`. The returned SpeakResult
+   * still contains the full assembled PCM.
    */
+  onChunk?: (chunk: GepardAudioChunk) => void;
+}
+interface GepardSpeakResult {
+  /** Mono PCM in [-1, 1]. */
+  pcm: Float32Array;
+  /** Sample rate (22050). */
+  sampleRate: number;
+  /** Number of audio frames decoded. */
+  frames: number;
+  /** Audio duration in seconds. */
+  audioSeconds: number;
+}
+declare class GepardTTS {
+  private ctx;
+  private loaded;
+  private tokenizer;
+  private cfg;
+  private maxSeqLen;
+  private hidden;
+  /** Backbone executor (built once; reused across speak() calls). */
+  private backboneExec;
+  /** Cached codec executor for the steady-state window size (chunk + lookback). */
+  private codecExecCache;
+  private _destroyed;
+  /** The selected backbone precision ("q4" or "f32"). */
+  readonly dtype: GepardDType;
+  private audioEmbTables;
+  private projW0;
+  private projB0;
+  private projW2;
+  private projB2;
+  private audioEmbedScale;
+  private headW;
+  private headB;
+  private stopW;
+  private stopB;
+  private constructor();
+  static create(options?: GepardTTSOptions): Promise<GepardTTS>;
+  /** NanoCodec's fixed output sample rate (Hz). */
+  get sampleRate(): number;
+  /** Preset voices. Gepard ships one default voice (cloning is a follow-up). */
+  availableVoices(): string[];
+  /** Gather text-token rows from the raw BF16 embed table → f32 [T, hidden]. */
+  private embedTextTokens;
   /**
-   * Fuse [CausalConv1dSiLU|CausalConv1dGated → ConvStateUpdate] into one
-   * dispatch (decode entries only). At T=1 the conv read and the rolling-state
-   * write for a channel live in the same thread, so the fused kernel is
-   * race-free; prefill (T>1) keeps the two-dispatch path.
+   * Embed one audio frame (32 FSQ codes) through the overlay stack:
+   * per-channel lookup → concat → Linear→GELU→Linear → affine-free LayerNorm →
+   * × audio_embed_scale. Mirrors GepardModel._embed_audio.
    */
-  private fuseConvStateUpdateDecodeEntries;
+  private embedAudioFrame;
+  /** Stop-head probability for a hidden state. */
+  private stopProbability;
   /**
-   * Fuse [per-head q_norm RMSNorm, k_norm RMSNorm, in-place RoPE] into ONE
-   * DualRMSNormRoPE dispatch. Numerically identical (norm then rotate, same
-   * math); requires head_dim <= 256 and RoPE operating in-place on exactly the
-   * two norm outputs. Saves 2 dispatches per full-attention layer — a mobile
-   * (WebKit submit-per-dispatch) win, desktop-neutral.
+   * Sample one audio frame: all 32 heads independently in fp32 —
+   * windowed repetition penalty → temperature → top-k → softmax → multinomial.
+   * Mirrors GepardRunner._sample_frame / _sample_head_logits.
    */
+  private sampleFrame;
   /**
-   * Fuse [Add → RMSNorm] into a single ResidualRMSNorm dispatch: the add's sum
-   * is still materialized (sum_output — downstream residual chain reads it) and
-   * the norm result is written in the same dispatch. Numerically identical.
+   * Synthesize speech for `text`. Returns 22.05 kHz mono PCM; when
+   * `opts.onChunk` is set, audio streams out chunk-by-chunk during generation.
+   *
+   * Pipeline: adaptive-repetition text layout → prefill (host-gathered text
+   * embeddings) → frame-synchronous AR loop (one frame = 32 codes per forward,
+   * stop head decides termination) → incremental NanoCodec decode → PCM.
    */
-  private fuseAddRMSNormDecodeEntries;
-  private fuseDualRMSNormRoPEDecodeEntries;
-  private fuseDualRMSNormDecodeEntries;
+  speak(text: string, opts?: GepardSpeakOptions): Promise<GepardSpeakResult>;
   /**
-   * Gather buffer entries for a bind group, matching the kernel spec's binding layout.
-   * Uses the pre-allocated inputIdsBuffer for the "input_ids" tensor.
+   * Decode frames [from, to) of the utterance to PCM, re-decoding up to
+   * `GEPARD_CODEC_LOOKBACK_FRAMES` of left context as warm-up (discarded).
+   * The decoder is causal with a bounded receptive field, so chunked output
+   * matches a monolithic decode.
    */
-  private gatherBuffers;
-  /** Lazily allocate a scratch storage buffer at least `minBytes` large. */
-  private getBindingScratchBuffer;
+  decodeFrameRange(frames: Uint32Array[], from: number, to: number): Promise<Float32Array>;
+  /** Run the codec graph for one latent window → raw PCM (pre-clamp). */
+  private decodeLatentWindow;
+  destroy(): void;
 }
 //#endregion
 //#region src/gpu/moonshine-executor.d.ts
@@ -2252,6 +3161,16 @@ interface GenerateResult {
   totalTime: number;
   /** Why generation stopped. */
   finishReason: "eos" | "max_tokens" | "stop_sequence";
+  /**
+   * Decode-only wall time in ms (excludes prefill). Set by the batched path
+   * (generateBatch) so aggregate decode throughput is measurable directly.
+   */
+  decodeTime?: number;
+  /**
+   * Raw generated token ids, in order. Used by parity harnesses (e.g. the
+   * paged-KV token-exactness gate) to compare runs without decode ambiguity.
+   */
+  tokenIds?: number[];
   /** Thinking content if model produced it (future). */
   thinking?: string;
 }
@@ -2364,8 +3283,14 @@ declare class WebGPUEngine {
   private _outeVoice;
   /** Source of the runtime LoRA adapter currently applied on the static base, if any. */
   private _currentAdapter;
+  /** Named adapters registered for per-lane batched decode (GERBIL_BATCH_LORA). */
+  private _batchAdapters;
   /** Lazily-created Parler-TTS engine (Flan-T5 encoder + decoder LM + dac_44khz). */
   private _parlerTTS;
+  /** Lazily-created Gepard-1.0 engine (Qwen3.5 multihead codec-LM + NanoCodec 21.5 fps). */
+  private _gepardTTS;
+  /** Lazily-created continuous-batching scheduler (GERBIL_BATCH, Phase 5). */
+  private _scheduler;
   /**
    * WebKit group-size probe state. When true, a candidate group size is being
    * tried this page-load and must be promoted (or capped) after the FIRST
@@ -2423,6 +3348,17 @@ declare class WebGPUEngine {
   loadAdapter(source: string | null): Promise<void>;
   /** The runtime LoRA adapter currently applied on the base, or null. */
   getAdapter(): string | null;
+  /**
+   * Register a named LoRA adapter for per-lane batched decode (SGMV phase 1,
+   * `GERBIL_BATCH=N` + `GERBIL_BATCH_LORA=1`). The adapter's factors are
+   * fetched and packed into the executor's shared factor buffers ONCE; any
+   * number of batch lanes can then run it concurrently by passing its name in
+   * `generateBatch`'s per-lane `adapters` option. Registering the same name
+   * twice is a no-op.
+   */
+  registerAdapter(name: string, source: string): Promise<void>;
+  /** Names of the adapters registered for per-lane batched decode. */
+  getRegisteredAdapters(): string[];
   /**
    * Write a coarse crash-phase breadcrumb that survives a GPU-process kill / page
    * reload. The iPad harness reads `localStorage["gerbil-crash-phase"]` after a
@@ -2501,6 +3437,55 @@ declare class WebGPUEngine {
    * the same instance awaits this one (see {@link _genQueueTail}).
    */
   generate(prompt: string | ChatMessage[], options?: GenerateOptions): Promise<GenerateResult>;
+  /**
+   * Batched lockstep generation (GERBIL_BATCH=N — Phase 2 of the
+   * continuous-batching campaign, Dawn only).
+   *
+   * Prefills each prompt sequentially into its batch slot (KV into the slot's
+   * block-table row, SSM/conv state adopted into the slot's state-pool rows),
+   * then decodes all N sequences in lockstep: one batched dispatch stream per
+   * step produces one token per row. Greedy-only in Phase 2 (per-row GPU
+   * argmax); rows that hit EOS/stop keep decoding in lockstep with their
+   * output discarded until every row has finished — rows never interact, so
+   * per-row streams are token-exact vs single-sequence generation.
+   *
+   * Requires exactly `executor.batchSize` prompts (fixed lockstep batch; the
+   * Phase 3 scheduler will lift this).
+   */
+  generateBatch(prompts: Array<string | ChatMessage[]>, options?: GenerateOptions & {
+    maxTokensPerRow?: number[];
+    /**
+     * Per-lane adapter names (SGMV phase 1 — requires GERBIL_BATCH_LORA=1
+     * and prior {@link registerAdapter} calls). `adapters[i]` selects the
+     * adapter lane i decodes with; null/undefined = bare base. Lanes with
+     * different adapters (or none) decode concurrently over the shared base.
+     */
+    adapters?: Array<string | null | undefined>;
+  }): Promise<GenerateResult[]>;
+  /**
+   * Continuous-batching scheduler (GERBIL_BATCH=N — Phase 5 of the batching
+   * campaign, Dawn only). Returns the engine's request scheduler (created on
+   * first call): submit many requests with independent prompts/limits and the
+   * scheduler multiplexes them over the batch lanes with dynamic admission,
+   * immediate lane retirement, and chunked prefill. Greedy-only; per-request
+   * output is token-exact vs single-sequence generate().
+   */
+  createScheduler(): RequestScheduler;
+  /**
+   * Create a swarm — the MoTA mode-B primitive (docs/research/slm-swarms.md):
+   * named members (LoRA adapters on this engine's shared base, or null for the
+   * bare base), an optional plan that fans an input out into per-member
+   * sub-tasks, and an optional reduce that joins the results. `swarm.run()`
+   * decodes every sub-task CONCURRENTLY through the continuous-batching
+   * scheduler with per-request adapters — one batched pass, so the fan-out
+   * costs roughly the slowest member, not the sum.
+   *
+   * Every non-null member source is registered via {@link registerAdapter}
+   * (downloads in parallel; factors packed into shared GPU buffers once).
+   * Requires `GERBIL_BATCH=N` (N >= 2) + `GERBIL_BATCH_LORA=1` on the Dawn
+   * path; greedy-only like the scheduler underneath.
+   */
+  createSwarm<R = Record<string, ServeResult>>(options: SwarmOptions<R>): Promise<Swarm<R>>;
   /**
    * Resolve the end-of-turn stop token id, or null if the model has none.
    *
@@ -2652,6 +3637,21 @@ declare class WebGPUEngine {
      * default description is used.
      */
     describeVoice?: string;
+    /**
+     * Stop-head sigmoid threshold (Gepard only, default 0.5). Higher = later stop.
+     */
+    stopThreshold?: number;
+    /**
+     * Streaming audio callback (Gepard only). Gepard is frame-synchronous, so
+     * audio is decoded and delivered chunk-by-chunk WHILE generation runs — the
+     * callback fires with each ~1.5 s PCM chunk (the final one has isFinal:true).
+     */
+    onChunk?: (chunk: {
+      pcm: Float32Array;
+      sampleRate: number;
+      frameIndex: number;
+      isFinal: boolean;
+    }) => void;
   }): Promise<{
     pcm: Float32Array;
     sampleRate: number;
@@ -2666,6 +3666,14 @@ declare class WebGPUEngine {
   private speakParler;
   /** A random natural-language voice description for Parler-TTS (host template bank). */
   randomVoiceDescription(): string;
+  /**
+   * Gepard-1.0 speak path: lazily build the Gepard engine (stock Qwen3.5
+   * full-attention codec-LM + 32 host-side FSQ classifier heads + NanoCodec
+   * 21.5 fps decoder) and synthesize `text`. Frame-synchronous: when `onChunk`
+   * is set, audio streams out during generation. Single default voice for now
+   * (voice cloning via the ref-compressor is a documented follow-up).
+   */
+  private speakGepard;
   /**
    * OuteTTS speak path: lazily build the OuteTTS engine (loading the chosen preset
    * voice's speaker JSON + the folded DAC codec weights from the mirror), rebuilding
@@ -2845,5 +3853,5 @@ declare class WebGPUEngine {
   private _acquireGenLock;
 }
 //#endregion
-export { GEMMA4_IMAGE_PROCESSOR as $, generateDacSpeechDecoderGraph as A, AdapterConfig as At, generateNanoCodecDecoderGraph as B, SpeakOptions as Bt, TranscribeOptions as C, LoadedMoonshine as Ct, generateQwen3_5VisionGraph as D, quantizeKaniBackbone as Dt, Executor as E, loadMoonshine as Et, generateMoonshineEncoderGraph as F, fetchAdapter as Ft, generateGemma4VisionGraph as G, KVDType as Gt, Gemma4VisionGraphInfo as H, GPUDiagnosticResult as Ht, moonshineEncoderFrames as I, splitFusedQGateDelta as It, DEFAULT_MODELS as J, ModelCapabilities as Jt, patchGemma4VisionClips as K, KvMode as Kt, parseMoonshineConfig as L, KaniDType as Lt, parseOuteTtsConfig as M, LoRADelta as Mt, MOONSHINE_REMAINING_WORK as N, applyLoRAToStore as Nt, audioTokensToDacCodes as O, ChatMessage as Ot, generateMoonshineDecoderGraph as P, buildLoRADeltas as Pt, resolveDefaultRepo as Q, audioTokensToCodes as R, KaniTTS as Rt, MoonshineSTTOptions as S, LoadedKaniTTS as St, MoonshineEncoderExecutor as T, loadModel as Tt, dequantizeGemma4VisionProjection as U, initGPU as Ut, parseKaniConfig as V, SpeakResult as Vt, dequantizeMLXProjection as W, GraphDType as Wt, OUTETTS_PRESET_VOICES as X, OUTETTS_ASSETS as Y, createDefaultHFKeyMapper as Yt, isTTSRepo as Z, ParlerSpeakOptions as _, mropeFreqDims as _t, GenerateObjectOptions as a, VisionGridConfig as at, ParlerTTSOptions as b, smartResize as bt, GenerateResult as c, buildGemma4PosEmbeds as ct, ObjectSchema as d, buildMRoPECosSin as dt, Gemma4VisionGridConfig as et, ObjectValidator as f, buildMRoPEPositionIds as ft, VisionInputs as g, buildVisionPositionTensors as gt, VisionExecutor as h, buildRotaryCosSin as ht, EncodeImageResult as i, QWEN3_5_IMAGE_PROCESSOR as it, generateOuteTtsBackboneGraph as j, AdapterSource as jt, dacOutputLength as k, Tokenizer as kt, IntegrityCheckEntry as l, buildGemma4RotaryCosSin as lt, WebGPUEngineOptions as m, buildPositionIds as mt, AgentTool as n, ImageProcessorConfig as nt, GenerateObjectResult as o, VisionPositionTensors as ot, WebGPUEngine as p, buildPosEmbeds as pt, resolveGemma4VisionInfo as q, ModelArchConfig as qt, EmbedOptions as r, PreprocessedImage as rt, GenerateOptions as s, buildGemma4PoolMatrix as st, AgentStep as t, Gemma4VisionPositionTensors as tt, IntegrityCheckResult as u, buildGemma4VisionPositionTensors as ut, ParlerSpeakResult as v, preprocessImage as vt, TranscribeResult as w, loadKaniTTS as wt, MoonshineSTT as x, SamplingParams as xt, ParlerTTS as y, preprocessImageGemma4 as yt, generateKaniTtsGraph as z, KaniTTSOptions as zt };
-//# sourceMappingURL=index-h8TDu1qm.d.mts.map
+export { Gemma4VisionGraphInfo as $, LoRADelta as $t, GepardTTS as A, preprocessImageGemma4 as At, generateMoonshineEncoderGraph as B, ServeOptions as Bt, TranscribeOptions as C, buildMRoPEPositionIds as Ct, GepardDType as D, buildVisionPositionTensors as Dt, GepardAudioChunk as E, buildRotaryCosSin as Et, generateDacSpeechDecoderGraph as F, SwarmOptions as Ft, generateNanoCodecDecoderGraph as G, loadKaniTTS as Gt, parseMoonshineConfig as H, Executor as Ht, generateOuteTtsBackboneGraph as I, SwarmTask as It, buildGepardTextLayout as J, quantizeKaniBackbone as Jt, parseKaniConfig as K, loadModel as Kt, parseOuteTtsConfig as L, SwarmTaskOptions as Lt, generateQwen3_5VisionGraph as M, SamplingParams as Mt, audioTokensToDacCodes as N, Swarm as Nt, GepardSpeakOptions as O, mropeFreqDims as Ot, dacOutputLength as P, SwarmMemberResult as Pt, parseGepardConfig as Q, AdapterSource as Qt, MOONSHINE_REMAINING_WORK as R, RequestScheduler as Rt, MoonshineSTTOptions as S, buildMRoPECosSin as St, MoonshineEncoderExecutor as T, buildPositionIds as Tt, audioTokensToCodes as U, LoadedKaniTTS as Ut, moonshineEncoderFrames as V, ServeResult as Vt, generateKaniTtsGraph as W, LoadedMoonshine as Wt, gepardChannelLevels as X, Tokenizer as Xt, generateGepardBackboneGraph as Y, ChatMessage as Yt, gepardCodesToLatent as Z, AdapterConfig as Zt, ParlerSpeakOptions as _, VisionPositionTensors as _t, GenerateObjectOptions as a, KaniTTS as an, DEFAULT_MODELS as at, ParlerTTSOptions as b, buildGemma4RotaryCosSin as bt, GenerateResult as c, SpeakResult as cn, isTTSRepo as ct, ObjectSchema as d, GraphDType as dn, Gemma4VisionGridConfig as dt, applyLoRAToStore as en, dequantizeGemma4VisionProjection as et, ObjectValidator as f, KVDType as fn, Gemma4VisionPositionTensors as ft, VisionInputs as g, createDefaultHFKeyMapper as gn, VisionGridConfig as gt, VisionExecutor as h, ModelCapabilities as hn, QWEN3_5_IMAGE_PROCESSOR as ht, EncodeImageResult as i, KaniDType as in, resolveGemma4VisionInfo as it, GepardTTSOptions as j, smartResize as jt, GepardSpeakResult as k, preprocessImage as kt, IntegrityCheckEntry as l, GPUDiagnosticResult as ln, resolveDefaultRepo as lt, WebGPUEngineOptions as m, ModelArchConfig as mn, PreprocessedImage as mt, AgentTool as n, fetchAdapter as nn, generateGemma4VisionGraph as nt, GenerateObjectResult as o, KaniTTSOptions as on, OUTETTS_ASSETS as ot, WebGPUEngine as p, KvMode as pn, ImageProcessorConfig as pt, GepardConfig as q, loadMoonshine as qt, EmbedOptions as r, splitFusedQGateDelta as rn, patchGemma4VisionClips as rt, GenerateOptions as s, SpeakOptions as sn, OUTETTS_PRESET_VOICES as st, AgentStep as t, buildLoRADeltas as tn, dequantizeMLXProjection as tt, IntegrityCheckResult as u, initGPU as un, GEMMA4_IMAGE_PROCESSOR as ut, ParlerSpeakResult as v, buildGemma4PoolMatrix as vt, TranscribeResult as w, buildPosEmbeds as wt, MoonshineSTT as x, buildGemma4VisionPositionTensors as xt, ParlerTTS as y, buildGemma4PosEmbeds as yt, generateMoonshineDecoderGraph as z, SchedulerStats as zt };
+//# sourceMappingURL=index-Fj2XkP-o.d.mts.map