@simulatte/doppler 0.1.0

package/src/config/schema/kernel-thresholds.schema.js

@@ -0,0 +1,187 @@
+// =============================================================================
+// Matmul Thresholds
+// =============================================================================
+
+export const DEFAULT_MATMUL_THRESHOLDS = {
+  multicolThreshold: 256,
+  tiledPrefillMinRows: 32,
+};
+
+// =============================================================================
+// RMSNorm Thresholds
+// =============================================================================
+
+export const DEFAULT_RMSNORM_THRESHOLDS = {
+  smallThreshold: 256,
+};
+
+// =============================================================================
+// Softmax Thresholds
+// =============================================================================
+
+export const DEFAULT_SOFTMAX_THRESHOLDS = {
+  smallThreshold: 256,
+};
+
+// =============================================================================
+// FFN Thresholds
+// =============================================================================
+
+export const DEFAULT_FFN_THRESHOLDS = {
+  multiOutputThreshold: 1024,
+};
+
+// =============================================================================
+// Sample Thresholds
+// =============================================================================
+
+export const DEFAULT_SAMPLE_THRESHOLDS = {
+  argmaxReduceVocabThreshold: 65536,
+  singlePassTopKThreshold: 100,
+};
+
+// =============================================================================
+// RoPE Thresholds
+// =============================================================================
+
+export const DEFAULT_ROPE_DEFAULTS = {
+  defaultTheta: 10000.0,
+  uniformSize: 32,
+  defaultStartPos: 0,
+};
+
+// =============================================================================
+// Kernel Tuning Defaults
+// =============================================================================
+
+export const DEFAULT_TUNER_LIMITS = {
+  maxComputeWorkgroupSizeX: 256,
+  maxComputeWorkgroupSizeY: 256,
+  maxComputeInvocationsPerWorkgroup: 256,
+};
+
+// =============================================================================
+// Attention Thresholds
+// =============================================================================
+
+export const DEFAULT_ATTENTION_THRESHOLDS = {
+  chunkedMaxKVLen: 2048,
+  minHeadDimForChunked: 128,
+  tierHeadDimLimits: {
+    tier3: 64,
+    tier2: 128,
+    tier1: 256,
+  },
+  tierMinSharedMemory: {
+    tier3: 16384,  // 16KB for small models
+    tier2: 32768,  // 32KB for medium models
+    tier1: 65536,  // 64KB for large models
+  },
+  largeMaxHeadDim: 64,
+  smallMaxHeadDim: 256,
+  subgroupMaxHeadDim: 256,
+  largeSharedF32: 20480,
+  largeSharedF16: 49152,
+  smallSharedF32: 8192,
+  smallSharedF16: 4096,
+  subgroupShared: 8192,
+};
+
+// =============================================================================
+// Fused Matmul Thresholds
+// =============================================================================
+
+export const DEFAULT_FUSED_MATMUL_THRESHOLDS = {
+  maxMediumN: 4096,
+  maxMediumK: 8192,
+  colsPerWg: 4,
+};
+
+// =============================================================================
+// Cast Thresholds
+// =============================================================================
+
+export const DEFAULT_CAST_THRESHOLDS = {
+  maxWorkgroupsPerDim: 65535,
+};
+
+// =============================================================================
+// Dtype Size Constants
+// =============================================================================
+
+export const DTYPE_SIZES = {
+  f32: 4,
+  float32: 4,
+  f16: 2,
+  float16: 2,
+  bf16: 2,
+  bfloat16: 2,
+  i32: 4,
+  int32: 4,
+  u32: 4,
+  uint32: 4,
+  i16: 2,
+  int16: 2,
+  u16: 2,
+  uint16: 2,
+  i8: 1,
+  int8: 1,
+  u8: 1,
+  uint8: 1,
+};
+
+export function getDtypeSize(dtype) {
+  const size = DTYPE_SIZES[dtype?.toLowerCase()];
+  if (size === undefined) {
+    throw new Error(`Unknown dtype: "${dtype}". Valid: ${Object.keys(DTYPE_SIZES).join(', ')}`);
+  }
+  return size;
+}
+
+// =============================================================================
+// Combined Kernel Thresholds
+// =============================================================================
+
+export const DEFAULT_KERNEL_THRESHOLDS = {
+  matmul: DEFAULT_MATMUL_THRESHOLDS,
+  rmsnorm: DEFAULT_RMSNORM_THRESHOLDS,
+  softmax: DEFAULT_SOFTMAX_THRESHOLDS,
+  ffn: DEFAULT_FFN_THRESHOLDS,
+  sample: DEFAULT_SAMPLE_THRESHOLDS,
+  rope: DEFAULT_ROPE_DEFAULTS,
+  attention: DEFAULT_ATTENTION_THRESHOLDS,
+  fusedMatmul: DEFAULT_FUSED_MATMUL_THRESHOLDS,
+  cast: DEFAULT_CAST_THRESHOLDS,
+  tuner: DEFAULT_TUNER_LIMITS,
+};
+
+// =============================================================================
+// Runtime Access
+// =============================================================================
+
+let currentThresholds = { ...DEFAULT_KERNEL_THRESHOLDS };
+
+export function getKernelThresholds() {
+  return currentThresholds;
+}
+
+export function setKernelThresholds(overrides) {
+  currentThresholds = {
+    ...currentThresholds,
+    ...overrides,
+    matmul: { ...currentThresholds.matmul, ...overrides.matmul },
+    rmsnorm: { ...currentThresholds.rmsnorm, ...overrides.rmsnorm },
+    softmax: { ...currentThresholds.softmax, ...overrides.softmax },
+    ffn: { ...currentThresholds.ffn, ...overrides.ffn },
+    sample: { ...currentThresholds.sample, ...overrides.sample },
+    rope: { ...currentThresholds.rope, ...overrides.rope },
+    attention: { ...currentThresholds.attention, ...overrides.attention },
+    fusedMatmul: { ...currentThresholds.fusedMatmul, ...overrides.fusedMatmul },
+    cast: { ...currentThresholds.cast, ...overrides.cast },
+    tuner: { ...currentThresholds.tuner, ...overrides.tuner },
+  };
+}
+
+export function resetKernelThresholds() {
+  currentThresholds = { ...DEFAULT_KERNEL_THRESHOLDS };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Kernel Warmup Config Schema
+ *
+ * Controls optional kernel prewarming and auto-tuning.
+ *
+ * @module config/schema/kernel-warmup
+ */
+
+export interface KernelWarmupConfigSchema {
+  /** Precompile pipelines for all supported kernel variants. */
+  prewarm: boolean;
+  /** Prewarm scheduling mode (parallel or sequential). */
+  prewarmMode: 'parallel' | 'sequential';
+  /** Auto-tune kernel workgroup sizes for the active model config. */
+  autoTune: boolean;
+}
+
+/** Default kernel warmup configuration */
+export declare const DEFAULT_KERNEL_WARMUP_CONFIG: KernelWarmupConfigSchema;

package/src/config/schema/kernel-warmup.schema.js

@@ -0,0 +1,5 @@
+export const DEFAULT_KERNEL_WARMUP_CONFIG = {
+  prewarm: false,
+  prewarmMode: 'parallel',
+  autoTune: false,
+};

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

@@ -0,0 +1,131 @@
+/**
+ * KV Cache Config Schema
+ *
+ * Configuration for key-value cache: dtype, layout, sizing.
+ * Controls memory allocation and access patterns for transformer attention.
+ *
+ * @module config/schema/kvcache
+ */
+
+/**
+ * Data type for KV cache storage.
+ *
+ * - 'f16': Half precision (2 bytes per element, lower memory, slight accuracy loss)
+ * - 'f32': Full precision (4 bytes per element, higher memory, full accuracy)
+ */
+export type KVDtype = 'f16' | 'f32';
+
+/**
+ * Memory layout for KV cache.
+ *
+ * - 'contiguous': Single contiguous buffer per layer (simpler, better for short sequences)
+ * - 'paged': Page-based allocation (better memory efficiency for variable sequences)
+ * - 'tiered': Hot ring + cold paged tiers
+ * - 'bdpa': Basis-decomposed paged layout (experimental)
+ */
+export type KVLayout = 'contiguous' | 'paged' | 'tiered' | 'bdpa';
+
+/**
+ * Tiered KV cache mode.
+ *
+ * - 'off': Disable tiering (use layout directly)
+ * - 'fp16': Hot ring + cold FP16 pages
+ * - 'int8': Cold tier compressed to int8
+ * - 'int4': Cold tier compressed to int4 (experimental)
+ */
+export type KVTieringMode = 'off' | 'fp16' | 'int8' | 'int4';
+
+/**
+ * Cold tier compression mode.
+ *
+ * - 'none': Keep cold tier in FP16/FP32
+ * - 'int8': Block-wise int8 compression
+ * - 'int4': Block-wise int4 compression
+ */
+export type KVCompressionMode = 'none' | 'int8' | 'int4';
+
+/**
+ * Gating mode for tiered compression.
+ *
+ * - 'auto': Use device heuristics to enable/disable compression
+ * - 'force_on': Always enable compression
+ * - 'force_off': Always disable compression
+ */
+export type KVTieringGatingMode = 'auto' | 'force_on' | 'force_off';
+
+export interface KVTieringCompressionSchema {
+  /** Compression mode for cold tier */
+  mode: KVCompressionMode;
+  /** Compression block size (tokens). Currently only 1 is supported. */
+  blockSize: number;
+}
+
+export interface KVTieringGatingSchema {
+  /** Compression gating strategy */
+  mode: KVTieringGatingMode;
+  /** Minimum ALU/BW ratio to enable compression (0 disables gating) */
+  minAluBwRatio: number;
+}
+
+export interface KVTieringConfigSchema {
+  /** Tiering mode */
+  mode: KVTieringMode;
+  /** Number of tokens kept hot in ring buffer */
+  hotWindow: number;
+  /** Page size for cold tier paging */
+  coldPageSize: number;
+  /** Cold tier dtype before compression */
+  coldDtype: KVDtype;
+  /** Cold tier compression settings */
+  compression: KVTieringCompressionSchema;
+  /** Compression gating settings */
+  gating: KVTieringGatingSchema;
+}
+
+/**
+ * Configuration for the key-value cache.
+ *
+ * The KV cache stores computed key and value tensors from attention layers
+ * to avoid recomputation during autoregressive decoding. These settings
+ * control memory allocation, precision, and layout strategies.
+ */
+export interface KVCacheConfigSchema {
+  /** Maximum sequence length the cache can hold */
+  maxSeqLen: number;
+
+  /** Max sequence length cap when GPU paged layout is unavailable */
+  gpuPagedFallbackMaxSeqLen: number;
+
+  /** Data type for cache storage */
+  kvDtype: KVDtype;
+
+  /**
+   * Force F32 KV cache when attention logit softcapping is enabled.
+   * Default false keeps F16 KV cache when supported.
+   */
+  forceF32Softcap: boolean;
+
+  /** Memory layout strategy */
+  layout: KVLayout;
+
+  /** Page size for paged layout (number of tokens per page) */
+  pageSize: number;
+
+  /** Basis vocabulary size used by basis-decomposed paged cache layouts (experimental). */
+  bdpaVocabSize: number;
+
+  /** Sliding window size for sliding window attention models */
+  windowSize: number;
+
+  /** Tiered cache configuration (hot ring + cold pages) */
+  tiering: KVTieringConfigSchema;
+}
+
+/** Default KV cache configuration */
+export declare const DEFAULT_KVCACHE_CONFIG: KVCacheConfigSchema;
+
+/**
+ * Sequence length threshold for automatic paged layout selection.
+ * Above this threshold, paged layout is preferred for memory efficiency.
+ */
+export declare const PAGED_LAYOUT_SEQ_LEN_THRESHOLD: number;

package/src/config/schema/kvcache.schema.js

@@ -0,0 +1,31 @@
+// =============================================================================
+// Default Config
+// =============================================================================
+
+export const DEFAULT_KVCACHE_CONFIG = {
+  maxSeqLen: 4096,
+  gpuPagedFallbackMaxSeqLen: 4096,
+  kvDtype: 'f16',
+  forceF32Softcap: false,
+  layout: 'contiguous',
+  pageSize: 256,
+  // Basis-decomposed paged KV cache controls (BDPA experimental layout)
+  bdpaVocabSize: 2048,
+  windowSize: 1024,
+  tiering: {
+    mode: 'off',
+    hotWindow: 1024,
+    coldPageSize: 256,
+    coldDtype: 'f16',
+    compression: {
+      mode: 'none',
+      blockSize: 1,
+    },
+    gating: {
+      mode: 'auto',
+      minAluBwRatio: 0.0,
+    },
+  },
+};
+
+export const PAGED_LAYOUT_SEQ_LEN_THRESHOLD = 8192;

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

@@ -0,0 +1,153 @@
+/**
+ * Loading Config Schema Definitions
+ *
+ * Configuration for model loading behavior: shard caching, memory management,
+ * and storage settings. These values were previously hardcoded across the codebase.
+ *
+ * @module config/schema/loading
+ */
+
+import type { DistributionConfigSchema } from './distribution.schema.js';
+import type { StorageFullConfigSchema } from './storage.schema.js';
+
+/**
+ * Default Q4K layout when manifest doesn't specify one (backwards compatibility).
+ * 'row' = row-wise layout, compatible with fused Q4K kernels
+ * 'col' = column-wise layout, requires dequantization
+ */
+export declare const DEFAULT_Q4K_LAYOUT: 'row';
+
+/**
+ * Configuration for the shard LRU cache.
+ *
+ * The cache stores recently-used model shards to avoid redundant disk/network reads.
+ * Different loading scenarios need different cache sizes:
+ * - OPFS (disk): Small cache (2 shards) since disk reads are fast
+ * - Network: Large cache (16 shards) to avoid re-fetching over network
+ * - MoE: Dynamic sizing based on experts per token
+ */
+export interface ShardCacheConfigSchema {
+  /** Max entries when loading from OPFS (disk reads are fast) */
+  opfsEntries: number;
+
+  /** Max entries when loading from network (avoid re-fetching) */
+  networkEntries: number;
+
+  /** Max entries for MoE models (caps the dynamic formula) */
+  moeMaxEntries: number;
+
+  /** Verify shard hashes when loading into cache */
+  verifyHashes: boolean;
+
+  /** Max concurrent shard loads (0 = unlimited) */
+  maxConcurrentLoads: number;
+}
+
+/** Default shard cache configuration */
+export declare const DEFAULT_SHARD_CACHE_CONFIG: ShardCacheConfigSchema;
+
+/**
+ * Configuration for memory management during model loading.
+ *
+ * Controls when to flush caches and GPU queues to manage memory pressure.
+ */
+export interface MemoryManagementConfigSchema {
+  /** Flush shard cache every N layers during loading */
+  flushIntervalLayers: number;
+
+  /** Flush shard cache when it exceeds this size in bytes */
+  flushThresholdBytes: number;
+
+  /** Flush GPU queue every N layers (releases Chrome staging memory) */
+  gpuQueueFlushLayers: number;
+
+  /** Log memory stats every N milliseconds during loading */
+  logIntervalMs: number;
+}
+
+/** Default memory management configuration */
+export declare const DEFAULT_MEMORY_MANAGEMENT_CONFIG: MemoryManagementConfigSchema;
+
+/**
+ * Configuration for speculative shard prefetching across layers.
+ */
+export interface PrefetchConfigSchema {
+  /** Enable prefetching of upcoming layer shards */
+  enabled: boolean;
+
+  /** Number of layers ahead to prefetch */
+  layersAhead: number;
+
+  /** Max shards to prefetch per layer step (0 = no limit) */
+  maxShards: number;
+}
+
+/** Default prefetch configuration */
+export declare const DEFAULT_PREFETCH_CONFIG: PrefetchConfigSchema;
+
+/**
+ * Configuration for OPFS directory paths.
+ *
+ * Note: This is distinct from StorageFullConfigSchema (in storage.schema.js)
+ * which handles quota, VRAM estimation, and alignment settings.
+ */
+export interface OpfsPathConfigSchema {
+  /** Root directory name in OPFS for model storage */
+  opfsRootDir: string;
+}
+
+/** Default OPFS path configuration */
+export declare const DEFAULT_OPFS_PATH_CONFIG: OpfsPathConfigSchema;
+
+/**
+ * Configuration for the MoE expert LRU cache.
+ *
+ * Controls how much VRAM is allocated for caching expert weights.
+ */
+export interface ExpertCacheConfigSchema {
+  /** Default maximum cache size in bytes */
+  defaultSizeBytes: number;
+
+  /** Maximum percentage of adapter's maxBufferSize to use (0-1) */
+  maxBufferPercentage: number;
+
+  /** Fallback maxBufferSize when adapter limits are unavailable */
+  maxBufferFallbackBytes: number;
+
+  /** Watermark ratio (0-1) that triggers eager eviction before hard limit */
+  evictionHighWatermark: number;
+
+  /** Target ratio (0-1) after emergency trim when over max size */
+  emergencyTrimToRatio: number;
+
+  /** GPT-OSS packed expert pager controls */
+  gptOssPager: {
+    enabled: boolean;
+    maxResidentLayers: number;
+  };
+}
+
+/** Default expert cache configuration */
+export declare const DEFAULT_EXPERT_CACHE_CONFIG: ExpertCacheConfigSchema;
+
+/**
+ * Complete loading configuration schema.
+ *
+ * Controls all aspects of model loading behavior.
+ */
+export interface LoadingConfigSchema {
+  /** OPFS quota, VRAM estimation, alignment */
+  storage: StorageFullConfigSchema;
+  /** Network/download settings */
+  distribution: DistributionConfigSchema;
+  shardCache: ShardCacheConfigSchema;
+  memoryManagement: MemoryManagementConfigSchema;
+  prefetch: PrefetchConfigSchema;
+  opfsPath: OpfsPathConfigSchema;
+  expertCache: ExpertCacheConfigSchema;
+  /** Allow F16->F32 upcast for non-matmul weights (norms, softcap) */
+  allowF32UpcastNonMatmul: boolean;
+}
+
+/** Default loading configuration */
+export declare const DEFAULT_LOADING_CONFIG: LoadingConfigSchema;

package/src/config/schema/loading.schema.js

@@ -0,0 +1,84 @@
+import { DEFAULT_DISTRIBUTION_CONFIG } from './distribution.schema.js';
+import { DEFAULT_STORAGE_FULL_CONFIG } from './storage.schema.js';
+import { MB, GB } from './units.schema.js';
+
+// =============================================================================
+// Q4K Layout Default
+// =============================================================================
+
+// Default Q4K layout when manifest doesn't specify one (backwards compatibility).
+// 'row' = row-wise layout, compatible with fused Q4K kernels
+// 'col' = column-wise layout, requires dequantization
+export const DEFAULT_Q4K_LAYOUT = 'row';
+
+// =============================================================================
+// Shard Cache Config
+// =============================================================================
+
+export const DEFAULT_SHARD_CACHE_CONFIG = {
+  opfsEntries: 2,
+  networkEntries: 16,
+  moeMaxEntries: 16,
+  verifyHashes: true,
+  maxConcurrentLoads: 0,
+};
+
+// =============================================================================
+// Memory Management Config
+// =============================================================================
+
+export const DEFAULT_MEMORY_MANAGEMENT_CONFIG = {
+  flushIntervalLayers: 4,
+  flushThresholdBytes: 256 * MB,
+  gpuQueueFlushLayers: 4,
+  logIntervalMs: 30000, // 30 seconds
+};
+
+// =============================================================================
+// Prefetch Config
+// =============================================================================
+
+export const DEFAULT_PREFETCH_CONFIG = {
+  enabled: true,
+  layersAhead: 1,
+  maxShards: 8,
+};
+
+// =============================================================================
+// OPFS Path Config
+// =============================================================================
+
+export const DEFAULT_OPFS_PATH_CONFIG = {
+  opfsRootDir: 'doppler-models',
+};
+
+// =============================================================================
+// Expert Cache Config
+// =============================================================================
+
+export const DEFAULT_EXPERT_CACHE_CONFIG = {
+  defaultSizeBytes: 2 * GB,
+  maxBufferPercentage: 0.25, // 25% of max buffer
+  maxBufferFallbackBytes: 256 * MB,
+  evictionHighWatermark: 0.9,
+  emergencyTrimToRatio: 0.75,
+  gptOssPager: {
+    enabled: true,
+    maxResidentLayers: 2,
+  },
+};
+
+// =============================================================================
+// Complete Loading Config
+// =============================================================================
+
+export const DEFAULT_LOADING_CONFIG = {
+  storage: DEFAULT_STORAGE_FULL_CONFIG,
+  distribution: DEFAULT_DISTRIBUTION_CONFIG,
+  shardCache: DEFAULT_SHARD_CACHE_CONFIG,
+  memoryManagement: DEFAULT_MEMORY_MANAGEMENT_CONFIG,
+  prefetch: DEFAULT_PREFETCH_CONFIG,
+  opfsPath: DEFAULT_OPFS_PATH_CONFIG,
+  expertCache: DEFAULT_EXPERT_CACHE_CONFIG,
+  allowF32UpcastNonMatmul: false,
+};

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

@@ -0,0 +1,12 @@
+/**
+ * LoRA configuration schema.
+ */
+
+export interface LoraConfigSchema {
+  rank: number;
+  alpha: number;
+  dropout: number;
+  targetModules: string[];
+}
+
+export declare const DEFAULT_LORA_CONFIG: LoraConfigSchema;

package/src/config/schema/lora.schema.js

@@ -0,0 +1,12 @@
+import { VALID_LORA_TARGET_MODULES } from './adapter.schema.js';
+
+// =============================================================================
+// LoRA Defaults
+// =============================================================================
+
+export const DEFAULT_LORA_CONFIG = {
+  rank: 16,
+  alpha: 32,
+  dropout: 0.0,
+  targetModules: [...VALID_LORA_TARGET_MODULES],
+};