@simulatte/doppler 0.1.7 → 0.1.9

package/src/config/presets/runtime/experiments/bench/gemma3-bench-q4k.json

@@ -1,7 +1,8 @@
 {
   "id": "experiments/bench/gemma3-bench-q4k",
   "name": "gemma3-bench-q4k",
-  "intent": "investigate",
+  "description": "Benchmark run for Gemma 3 1B Q4K — calibration-mode throughput measurement.",
+  "intent": "calibrate",
   "stability": "experimental",
   "owner": "doppler-core",
   "createdAtUtc": "2026-02-25T00:00:00Z",

package/src/config/presets/runtime/experiments/verify/lfm2-verify.json

@@ -0,0 +1,46 @@
+{
+  "id": "experiments/verify/lfm2-verify",
+  "name": "lfm2-verify",
+  "intent": "verify",
+  "stability": "experimental",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-16T00:00:00Z",
+  "extends": "modes/bench",
+  "model": "lfm2-5-1-2b-instruct-q4k-ehf16-af32",
+  "runtime": {
+    "shared": {
+      "tooling": {
+        "intent": "verify"
+      },
+      "debug": {
+        "logLevel": {
+          "defaultLogLevel": "warn"
+        },
+        "trace": {
+          "enabled": false
+        },
+        "profiler": {
+          "enabled": false
+        }
+      }
+    },
+    "inference": {
+      "prompt": {
+        "messages": [
+          {
+            "role": "user",
+            "content": "What color is the sky on a clear day?"
+          }
+        ]
+      },
+      "batching": {
+        "maxTokens": 32
+      },
+      "sampling": {
+        "temperature": 0,
+        "topK": 1,
+        "topP": 1
+      }
+    }
+  }
+}

package/src/config/presets/runtime/experiments/verify/translategemma-verify.json

@@ -0,0 +1,39 @@
+{
+  "id": "experiments/verify/translategemma-verify",
+  "name": "translategemma-verify",
+  "intent": "verify",
+  "stability": "experimental",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-16T00:00:00Z",
+  "extends": "modes/bench",
+  "model": "translategemma-4b-it-q4k-ehf16-af32",
+  "runtime": {
+    "shared": {
+      "tooling": {
+        "intent": "verify"
+      },
+      "debug": {
+        "logLevel": {
+          "defaultLogLevel": "warn"
+        },
+        "trace": {
+          "enabled": false
+        },
+        "profiler": {
+          "enabled": false
+        }
+      }
+    },
+    "inference": {
+      "prompt": "Hello from Doppler.",
+      "batching": {
+        "maxTokens": 32
+      },
+      "sampling": {
+        "temperature": 0,
+        "topK": 1,
+        "topP": 1
+      }
+    }
+  }
+}

package/src/config/presets/runtime/model/qwen3-5-layer-probe.json

@@ -0,0 +1,52 @@
+{
+  "id": "model/qwen3-5-layer-probe",
+  "name": "qwen3-5-layer-probe",
+  "description": "Probe all 24 layer outputs in Qwen 3.5 to isolate where the hidden state distribution collapses.",
+  "intent": "investigate",
+  "stability": "canonical",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-13T00:00:00Z",
+  "extends": "modes/debug",
+  "runtime": {
+    "inference": {
+      "prompt": "What color is the sky on a clear day? Answer in one word.",
+      "batching": {
+        "maxTokens": 1
+      },
+      "sampling": {
+        "temperature": 0
+      }
+    },
+    "shared": {
+      "debug": {
+        "trace": {
+          "enabled": true,
+          "categories": ["attn", "ffn", "logits"],
+          "layers": null,
+          "maxDecodeSteps": 1
+        },
+        "probes": [
+          {
+            "id": "embed",
+            "stage": "embed_out",
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 512, 513]
+          },
+          {
+            "id": "layer_out",
+            "stage": "layer_out",
+            "layers": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3]
+          },
+          {
+            "id": "logits",
+            "stage": "logits_final",
+            "tokens": [-1],
+            "dims": [271, 0, 1, 2, 3, 496, 138]
+          }
+        ]
+      }
+    }
+  }
+}

package/src/config/presets/runtime/model/qwen3-5-linear-attn-debug.json

@@ -0,0 +1,90 @@
+{
+  "id": "model/qwen3-5-linear-attn-debug",
+  "name": "qwen3-5-linear-attn-debug",
+  "description": "Probe linear attention intermediates in Qwen 3.5 layer 0 for comparison with HF reference.",
+  "intent": "investigate",
+  "stability": "canonical",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-13T00:00:00Z",
+  "extends": "modes/debug",
+  "runtime": {
+    "inference": {
+      "prompt": "Hello",
+      "batching": {
+        "maxTokens": 1
+      },
+      "sampling": {
+        "temperature": 0
+      },
+      "chatTemplate": {
+        "enabled": false
+      }
+    },
+    "shared": {
+      "debug": {
+        "trace": {
+          "enabled": true,
+          "categories": ["attn", "logits"],
+          "layers": null,
+          "maxDecodeSteps": 1
+        },
+        "probes": [
+          {
+            "id": "embed",
+            "stage": "embed_out",
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "qkv",
+            "stage": "linear_qkv_proj",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "z",
+            "stage": "linear_z_proj",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "a",
+            "stage": "linear_a_proj",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "b",
+            "stage": "linear_b_proj",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "core",
+            "stage": "linear_core_out",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "layer0",
+            "stage": "layer_out",
+            "layers": [0],
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3, 4, 5, 6, 7]
+          },
+          {
+            "id": "logits",
+            "stage": "logits_final",
+            "tokens": [-1],
+            "dims": [0, 1, 2, 3]
+          }
+        ]
+      }
+    }
+  }
+}

package/src/config/presets/runtime/modes/trace-layers.json

@@ -6,6 +6,7 @@
   "stability": "canonical",
   "owner": "doppler-core",
   "createdAtUtc": "2026-02-25T00:00:00Z",
+  "extends": "default",
   "runtime": {
     "shared": {
       "tooling": {

package/src/config/presets/runtime/tiers/gemma4-16gb.json

@@ -0,0 +1,69 @@
+{
+  "id": "tiers/gemma4-16gb",
+  "name": "Gemma 4 — 16 GB tier (constrained)",
+  "description": "Gemma 4 MoE runtime tier for 16 GB GPU memory. Aggressively constrained: short context, minimal expert cache, hard budget enforcement. Fail-closed if budget is not met.",
+  "intent": "investigate",
+  "stability": "experimental",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-17T00:00:00Z",
+  "extends": "default",
+  "runtime": {
+    "shared": {
+      "bufferPool": {
+        "budget": {
+          "maxTotalBytes": 13958643712,
+          "highWatermarkRatio": 0.85,
+          "emergencyTrimTargetRatio": 0.7,
+          "hardFailOnBudgetExceeded": true
+        }
+      }
+    },
+    "loading": {
+      "expertCache": {
+        "defaultSizeBytes": 1073741824,
+        "maxBufferPercentage": 0.15,
+        "evictionHighWatermark": 0.8,
+        "emergencyTrimToRatio": 0.65
+      },
+      "prefetch": {
+        "enabled": true,
+        "layersAhead": 1,
+        "maxShards": 4
+      },
+      "memoryManagement": {
+        "flushIntervalLayers": 1,
+        "flushThresholdBytes": 134217728
+      }
+    },
+    "inference": {
+      "kvcache": {
+        "layout": "contiguous",
+        "maxSeqLen": 2048,
+        "kvDtype": "f16",
+        "pageSize": 128,
+        "tiering": {
+          "mode": "off"
+        }
+      },
+      "moe": {
+        "routing": {
+          "routerDtype": "f32"
+        },
+        "cache": {
+          "dequantCacheMaxEntries": 2
+        }
+      },
+      "compute": {
+        "activationDtype": "f32"
+      },
+      "batching": {
+        "maxTokens": 512
+      },
+      "session": {
+        "kvcache": {
+          "kvDtype": "f16"
+        }
+      }
+    }
+  }
+}

package/src/config/presets/runtime/tiers/gemma4-24gb.json

@@ -0,0 +1,66 @@
+{
+  "id": "tiers/gemma4-24gb",
+  "name": "Gemma 4 — 24 GB tier",
+  "description": "Gemma 4 MoE runtime tier for 24 GB GPU memory. Moderate expert cache, contiguous KV, reduced context length.",
+  "intent": "investigate",
+  "stability": "experimental",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-17T00:00:00Z",
+  "extends": "default",
+  "runtime": {
+    "shared": {
+      "bufferPool": {
+        "budget": {
+          "maxTotalBytes": 21474836480,
+          "highWatermarkRatio": 0.9,
+          "emergencyTrimTargetRatio": 0.75,
+          "hardFailOnBudgetExceeded": true
+        }
+      }
+    },
+    "loading": {
+      "expertCache": {
+        "defaultSizeBytes": 3221225472,
+        "maxBufferPercentage": 0.2,
+        "evictionHighWatermark": 0.85,
+        "emergencyTrimToRatio": 0.7
+      },
+      "prefetch": {
+        "enabled": true,
+        "layersAhead": 1,
+        "maxShards": 8
+      },
+      "memoryManagement": {
+        "flushIntervalLayers": 2,
+        "flushThresholdBytes": 268435456
+      }
+    },
+    "inference": {
+      "kvcache": {
+        "layout": "contiguous",
+        "maxSeqLen": 4096,
+        "kvDtype": "f16",
+        "pageSize": 256,
+        "tiering": {
+          "mode": "off"
+        }
+      },
+      "moe": {
+        "routing": {
+          "routerDtype": "f32"
+        },
+        "cache": {
+          "dequantCacheMaxEntries": 64
+        }
+      },
+      "compute": {
+        "activationDtype": "f32"
+      },
+      "session": {
+        "kvcache": {
+          "kvDtype": "f16"
+        }
+      }
+    }
+  }
+}

package/src/config/presets/runtime/tiers/gemma4-32gb.json

@@ -0,0 +1,66 @@
+{
+  "id": "tiers/gemma4-32gb",
+  "name": "Gemma 4 — 32 GB tier",
+  "description": "Gemma 4 MoE runtime tier for 32 GB GPU memory. Generous expert cache, contiguous KV, full-length context.",
+  "intent": "investigate",
+  "stability": "experimental",
+  "owner": "doppler-core",
+  "createdAtUtc": "2026-03-17T00:00:00Z",
+  "extends": "default",
+  "runtime": {
+    "shared": {
+      "bufferPool": {
+        "budget": {
+          "maxTotalBytes": 30064771072,
+          "highWatermarkRatio": 0.9,
+          "emergencyTrimTargetRatio": 0.75,
+          "hardFailOnBudgetExceeded": true
+        }
+      }
+    },
+    "loading": {
+      "expertCache": {
+        "defaultSizeBytes": 6442450944,
+        "maxBufferPercentage": 0.25,
+        "evictionHighWatermark": 0.9,
+        "emergencyTrimToRatio": 0.75
+      },
+      "prefetch": {
+        "enabled": true,
+        "layersAhead": 2,
+        "maxShards": 16
+      },
+      "memoryManagement": {
+        "flushIntervalLayers": 4,
+        "flushThresholdBytes": 536870912
+      }
+    },
+    "inference": {
+      "kvcache": {
+        "layout": "contiguous",
+        "maxSeqLen": 8192,
+        "kvDtype": "f16",
+        "pageSize": 256,
+        "tiering": {
+          "mode": "off"
+        }
+      },
+      "moe": {
+        "routing": {
+          "routerDtype": "f32"
+        },
+        "cache": {
+          "dequantCacheMaxEntries": 128
+        }
+      },
+      "compute": {
+        "activationDtype": "f32"
+      },
+      "session": {
+        "kvcache": {
+          "kvDtype": "f16"
+        }
+      }
+    }
+  }
+}

package/src/config/runtime.js

@@ -58,4 +58,7 @@ function assertNoDeprecatedRuntimeKeys(overrides) {
   if (inference?.sampling?.maxTokens !== undefined) {
     throw new Error('sampling.maxTokens is removed; use inference.batching.maxTokens');
   }
+  if (inference?.session?.maxNewTokens !== undefined) {
+    throw new Error('inference.session.maxNewTokens is not a supported runtime config key; use inference.batching.maxTokens');
+  }
 }

package/src/config/schema/conversion.schema.d.ts

@@ -32,6 +32,7 @@ export interface ParsedModelSchema {
   config: RawModelConfigSchema;
   architecture?: string;
   quantization?: string;
+  generationConfig?: unknown;
   tokenizerJson?: unknown;
   tokenizerConfig?: unknown;
   tokenizerModel?: unknown;

package/src/config/schema/debug.schema.d.ts

@@ -131,6 +131,44 @@ export interface PipelineDebugConfigSchema {
 /** Default pipeline debug configuration */
 export declare const DEFAULT_PIPELINE_DEBUG_CONFIG: PipelineDebugConfigSchema;
 
+/** Loader debug configuration (Q4K dequant and related probes). */
+export interface LoaderDebugConfigSchema {
+  /** Enable loader debug behavior (default: false) */
+  enabled: boolean;
+  /** Force GPU dequant for Q4K tensors even when CPU fallback is eligible. */
+  forceGpuDequant: boolean;
+  /** Prefer CPU dequant for F32 output when eligible (default: false, GPU is preferred). */
+  preferCpuDequant: boolean;
+  /** Throw when CPU dequant fallback is taken. */
+  failOnCpuDequantPath: boolean;
+  /** Enable dtype-aware GPU-vs-CPU parity checks during Q4K dequant. */
+  runQ4KDequantParity: boolean;
+  /** Number of values to read back for parity checks. */
+  q4kDequantParitySamples: number;
+}
+
+/** Default loader debug configuration. */
+export declare const DEFAULT_LOADER_DEBUG_CONFIG: LoaderDebugConfigSchema;
+
+/** Matmul debug configuration (attention split/shape diagnostics). */
+export interface MatmulDebugConfigSchema {
+  /** Enable matmul debug behavior (default: false) */
+  enabled: boolean;
+  /** Force split (non-fused) Q/K/V projection path for diagnostics. */
+  forceSplitQKV: boolean;
+  /** Validate B tensor layout/buffer bytes for attention projection roles. */
+  validateAttentionWeightBuffer: boolean;
+  /** Throw if validation fails due small B tensor. */
+  failOnSmallAttentionWeightBuffer: boolean;
+  /** Emit attention B-buffer diagnostics. */
+  logAttentionWeightBuffer: boolean;
+  /** Log first-8 projection output values for layer 0 decode (diagnostic). */
+  logProjectionValues: boolean;
+}
+
+/** Default matmul debug configuration. */
+export declare const DEFAULT_MATMUL_DEBUG_CONFIG: MatmulDebugConfigSchema;
+
 /**
  * Profiler configuration.
  */
@@ -241,6 +279,8 @@ export interface DebugConfigSchema {
   logLevel: LogLevelConfigSchema;
   trace: TraceConfigSchema;
   pipeline: PipelineDebugConfigSchema;
+  loader: LoaderDebugConfigSchema;
+  matmul: MatmulDebugConfigSchema;
   probes: ProbeConfigSchema[];
   profiler: ProfilerConfigSchema;
   perfGuards: PerfGuardsConfigSchema;

package/src/config/schema/debug.schema.js

@@ -38,6 +38,32 @@ export const DEFAULT_TRACE_CONFIG = {
   file: null,
 };
 
+// =============================================================================
+// Loader Debug Config
+// =============================================================================
+
+export const DEFAULT_LOADER_DEBUG_CONFIG = {
+  enabled: false,
+  forceGpuDequant: false,
+  preferCpuDequant: false,
+  failOnCpuDequantPath: false,
+  runQ4KDequantParity: false,
+  q4kDequantParitySamples: 256,
+};
+
+// =============================================================================
+// Kernel Debug Config
+// =============================================================================
+
+export const DEFAULT_MATMUL_DEBUG_CONFIG = {
+  enabled: false,
+  forceSplitQKV: false,
+  validateAttentionWeightBuffer: false,
+  failOnSmallAttentionWeightBuffer: false,
+  logAttentionWeightBuffer: false,
+  logProjectionValues: false,
+};
+
 // =============================================================================
 // Kernel Trace Config (kernel-trace.js anomaly detection)
 // =============================================================================
@@ -100,6 +126,8 @@ export const DEFAULT_DEBUG_CONFIG = {
   logLevel: DEFAULT_LOG_LEVEL_CONFIG,
   trace: DEFAULT_TRACE_CONFIG,
   pipeline: DEFAULT_PIPELINE_DEBUG_CONFIG,
+  loader: DEFAULT_LOADER_DEBUG_CONFIG,
+  matmul: DEFAULT_MATMUL_DEBUG_CONFIG,
   probes: [],
   profiler: DEFAULT_PROFILER_CONFIG,
   perfGuards: DEFAULT_PERF_GUARDS_CONFIG,

package/src/config/schema/index.js

@@ -217,6 +217,8 @@ export {
   DEFAULT_LOG_HISTORY_CONFIG,
   DEFAULT_LOG_LEVEL_CONFIG,
   DEFAULT_TRACE_CONFIG,
+  DEFAULT_LOADER_DEBUG_CONFIG,
+  DEFAULT_MATMUL_DEBUG_CONFIG,
   DEFAULT_KERNEL_TRACE_CONFIG,
   DEFAULT_PIPELINE_DEBUG_CONFIG,
   DEFAULT_PROFILER_CONFIG,

package/src/config/schema/inference-defaults.schema.js

@@ -93,7 +93,7 @@ export const DEFAULT_TOKENIZER_DEFAULTS = {
 // =============================================================================
 
 export const DEFAULT_CHAT_TEMPLATE_CONFIG = {
-  enabled: false,
+  enabled: undefined,
 };
 
 export const DEFAULT_KERNEL_PATH_POLICY = {

package/src/config/schema/kernel-path.schema.d.ts

@@ -160,6 +160,7 @@ export type BuiltinKernelPathId =
   | 'gemma3-f16-fused-f32a-online-streamingprefill' // Gemma 3 F16 fused FFN online path with streaming prefill attention
   | 'gemma3-q4k-dequant-f16a-online' // Gemma 3 Q4K dequant online path (F16 activations)
   | 'gemma3-q4k-dequant-f32a-online' // Gemma 3 Q4K dequant online path with F32 activations
+  | 'gemma3-q4k-dequant-f32w-f32a-online' // Gemma 3 Q4K path with F32 projection weights and F32 activations
   | 'gemma3-q4k-dequant-f32a-nosubgroups' // Gemma 3 Q4K dequant path with no subgroup requirement
   | 'gemma3-q4k-dequant-f32a' // Legacy alias for gemma3-q4k-dequant-f32a-nosubgroups
   | 'lfm2-q4k-dequant-f32a-online' // LFM2 Q4K path with F32 activations and fast prefill

package/src/config/schema/manifest.schema.d.ts

@@ -163,7 +163,7 @@ export interface ArchitectureSchema {
  * Use `null` to indicate "not applicable" (e.g., no softcapping).
  */
 export interface ManifestAttentionSchema {
-  /** Query pre-attention scalar (Gemma 2: 256, standard: sqrt(headDim)) */
+  /** Query pre-attention scalar: attnScale = 1/sqrt(scalar). Standard = headDim. */
   queryPreAttnScalar: number;
   /** Attention logit softcapping (Gemma 2: 50, null = disabled) */
   attnLogitSoftcapping: number | null;

package/src/config/schema/manifest.schema.js

@@ -40,7 +40,7 @@ export const DEFAULT_MANIFEST_INFERENCE = {
   schema: null,
   presetId: null,
   attention: {
-    queryPreAttnScalar: 8,  // sqrt(64) for standard 64-dim heads
+    queryPreAttnScalar: 64, // headDim for standard 64-dim heads; attnScale = 1/sqrt(scalar)
     attnLogitSoftcapping: null,  // No softcapping (null = disabled)
     slidingWindow: null,  // Full attention (null = no sliding window)
     queryKeyNorm: false,

package/src/config/schema/memory-limits.schema.js

@@ -40,8 +40,8 @@ export const DEFAULT_SEGMENT_ALLOCATION_CONFIG = {
 // =============================================================================
 
 export const DEFAULT_EMULATED_STORAGE_CONFIG = {
-  vramBudgetBytes: 2 * GB,
-  ramBudgetBytes: 8 * GB,
+  vramBudgetBytes: 4 * GB,
+  ramBudgetBytes: 16 * GB,
 };
 
 // =============================================================================

package/src/config/schema/storage.schema.js

@@ -16,7 +16,7 @@ export const DEFAULT_QUOTA_CONFIG = {
 
 export const DEFAULT_VRAM_ESTIMATION_CONFIG = {
   unifiedMemoryRatio: 0.5, // 50% of system RAM
-  fallbackVramBytes: 2 * GB,
+  fallbackVramBytes: 4 * GB,
   lowVramHeadroomBytes: 500 * MB,
 };
 
@@ -35,7 +35,7 @@ export const DEFAULT_STORAGE_ALIGNMENT_CONFIG = {
 export const DEFAULT_STORAGE_BACKEND_CONFIG = {
   backend: 'auto', // auto | opfs | indexeddb | memory
   opfs: {
-    useSyncAccessHandle: true,
+    useSyncAccessHandle: false,
     maxConcurrentHandles: 2,
   },
   indexeddb: {