@simulatte/doppler 0.1.0

package/src/config/schema/memory-limits.schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Memory Limits Config Schema
+ *
+ * Configuration for memory capability detection and heap management.
+ * These settings control heap test sizes, segment allocation, and
+ * fallback limits for both Memory64 and segmented heap strategies.
+ *
+ * @module config/schema/memory-limits
+ */
+
+/**
+ * Configuration for heap size testing.
+ *
+ * Controls the sizes probed when detecting maximum WASM heap size
+ * and the fallback when all probes fail.
+ */
+export interface HeapTestingConfigSchema {
+  /** Sizes to test for maximum heap, in descending order (bytes) */
+  heapTestSizes: number[];
+
+  /** Fallback maximum heap size when all probes fail (bytes) */
+  fallbackMaxHeapBytes: number;
+}
+
+/** Default heap testing configuration */
+export declare const DEFAULT_HEAP_TESTING_CONFIG: HeapTestingConfigSchema;
+
+/**
+ * Configuration for segment size testing.
+ *
+ * Controls the sizes probed when detecting maximum ArrayBuffer size
+ * for segmented heap mode.
+ */
+export interface SegmentTestingConfigSchema {
+  /** Sizes to test for maximum segment, in descending order (bytes) */
+  segmentTestSizes: number[];
+
+  /** Safe segment size to use as default (bytes) */
+  safeSegmentSizeBytes: number;
+}
+
+/** Default segment testing configuration */
+export declare const DEFAULT_SEGMENT_TESTING_CONFIG: SegmentTestingConfigSchema;
+
+/**
+ * Configuration for virtual address space.
+ *
+ * Controls the target address space size used to calculate
+ * recommended segment count.
+ */
+export interface AddressSpaceConfigSchema {
+  /** Target virtual address space size (bytes) */
+  targetAddressSpaceBytes: number;
+}
+
+/** Default address space configuration */
+export declare const DEFAULT_ADDRESS_SPACE_CONFIG: AddressSpaceConfigSchema;
+
+/**
+ * Configuration for segment allocation.
+ *
+ * Controls fallback behavior when segment allocation fails.
+ */
+export interface SegmentAllocationConfigSchema {
+  /** Fallback segment size for Memory64 init failure (bytes) */
+  fallbackSegmentSizeBytes: number;
+
+  /** Fallback sizes to try when segment allocation fails, in descending order (bytes) */
+  segmentFallbackSizes: number[];
+}
+
+/** Default segment allocation configuration */
+export declare const DEFAULT_SEGMENT_ALLOCATION_CONFIG: SegmentAllocationConfigSchema;
+
+/**
+ * Configuration for emulated storage budgets.
+ *
+ * Controls default VRAM and RAM budgets for the EmulatedVramStore
+ * tiered storage system.
+ */
+export interface EmulatedStorageConfigSchema {
+  /** Default VRAM budget (bytes) */
+  vramBudgetBytes: number;
+
+  /** Default RAM budget (bytes) */
+  ramBudgetBytes: number;
+}
+
+/** Default emulated storage configuration */
+export declare const DEFAULT_EMULATED_STORAGE_CONFIG: EmulatedStorageConfigSchema;
+
+/**
+ * Complete memory limits configuration schema.
+ *
+ * Combines heap testing, segment testing, address space,
+ * segment allocation, and emulated storage settings.
+ */
+export interface MemoryLimitsConfigSchema {
+  heapTesting: HeapTestingConfigSchema;
+  segmentTesting: SegmentTestingConfigSchema;
+  addressSpace: AddressSpaceConfigSchema;
+  segmentAllocation: SegmentAllocationConfigSchema;
+  emulatedStorage: EmulatedStorageConfigSchema;
+}
+
+/** Default memory limits configuration */
+export declare const DEFAULT_MEMORY_LIMITS_CONFIG: MemoryLimitsConfigSchema;

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

@@ -0,0 +1,57 @@
+import { MB, GB } from './units.schema.js';
+
+// =============================================================================
+// Heap Testing Config
+// =============================================================================
+
+export const DEFAULT_HEAP_TESTING_CONFIG = {
+  heapTestSizes: [16 * GB, 8 * GB, 4 * GB, 2 * GB, 1 * GB],
+  fallbackMaxHeapBytes: 1 * GB,
+};
+
+// =============================================================================
+// Segment Testing Config
+// =============================================================================
+
+export const DEFAULT_SEGMENT_TESTING_CONFIG = {
+  segmentTestSizes: [1 * GB, 512 * MB, 256 * MB, 128 * MB],
+  safeSegmentSizeBytes: 256 * MB,
+};
+
+// =============================================================================
+// Address Space Config
+// =============================================================================
+
+export const DEFAULT_ADDRESS_SPACE_CONFIG = {
+  targetAddressSpaceBytes: 8 * GB,
+};
+
+// =============================================================================
+// Segment Allocation Config
+// =============================================================================
+
+export const DEFAULT_SEGMENT_ALLOCATION_CONFIG = {
+  fallbackSegmentSizeBytes: 4 * GB,
+  segmentFallbackSizes: [512 * MB, 256 * MB, 128 * MB],
+};
+
+// =============================================================================
+// Emulated Storage Config
+// =============================================================================
+
+export const DEFAULT_EMULATED_STORAGE_CONFIG = {
+  vramBudgetBytes: 2 * GB,
+  ramBudgetBytes: 8 * GB,
+};
+
+// =============================================================================
+// Complete Memory Limits Config
+// =============================================================================
+
+export const DEFAULT_MEMORY_LIMITS_CONFIG = {
+  heapTesting: DEFAULT_HEAP_TESTING_CONFIG,
+  segmentTesting: DEFAULT_SEGMENT_TESTING_CONFIG,
+  addressSpace: DEFAULT_ADDRESS_SPACE_CONFIG,
+  segmentAllocation: DEFAULT_SEGMENT_ALLOCATION_CONFIG,
+  emulatedStorage: DEFAULT_EMULATED_STORAGE_CONFIG,
+};

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

@@ -0,0 +1,78 @@
+/**
+ * MoE Config Schema
+ *
+ * Configuration for Mixture of Experts routing and caching.
+ * These are runtime settings that affect how MoE layers execute.
+ *
+ * @module config/schema/moe
+ */
+
+/** Supported data types for router computation */
+export type RouterDtype = 'f16' | 'f32';
+
+/**
+ * Configuration for MoE routing behavior.
+ *
+ * Controls how tokens are routed to experts during inference.
+ */
+export interface MoERoutingConfigSchema {
+  /** Number of experts in the MoE layer */
+  numExperts: number;
+
+  /** Number of experts to activate per token (top-K routing) */
+  topK: number;
+
+  /** Normalize expert weights after routing */
+  normalizeWeights: boolean;
+
+  /** Data type for router computation */
+  routerDtype: RouterDtype;
+
+  /**
+   * Max tokens per expert (0 = auto).
+   * Used to size MoE gather/scatter buffers.
+   */
+  maxTokensPerExpert: number;
+
+  /** Headroom multiplier for auto maxTokensPerExpert */
+  maxTokensPerExpertHeadroom: number;
+
+  /** Minimum maxTokensPerExpert when auto-tuning */
+  maxTokensPerExpertMin: number;
+
+  /**
+   * Hard cap for maxTokensPerExpert (0 = no cap).
+   * Useful to limit buffer sizes on constrained devices.
+   */
+  maxTokensPerExpertCap: number;
+}
+
+/** Default MoE routing configuration */
+export declare const DEFAULT_MOE_ROUTING_CONFIG: MoERoutingConfigSchema;
+
+/**
+ * Configuration for MoE dequantization caching.
+ *
+ * Controls the LRU cache for dequantized expert weights to avoid
+ * redundant dequantization when experts are reused across tokens.
+ */
+export interface MoECacheConfigSchema {
+  /** Maximum number of dequantized expert entries to cache */
+  dequantCacheMaxEntries: number;
+}
+
+/** Default MoE cache configuration */
+export declare const DEFAULT_MOE_CACHE_CONFIG: MoECacheConfigSchema;
+
+/**
+ * Complete MoE runtime configuration schema.
+ *
+ * Controls all aspects of MoE inference behavior.
+ */
+export interface MoERuntimeConfigSchema {
+  routing: MoERoutingConfigSchema;
+  cache: MoECacheConfigSchema;
+}
+
+/** Default MoE runtime configuration */
+export declare const DEFAULT_MOE_RUNTIME_CONFIG: MoERuntimeConfigSchema;

package/src/config/schema/moe.schema.js

@@ -0,0 +1,31 @@
+// =============================================================================
+// MoE Routing Config
+// =============================================================================
+
+export const DEFAULT_MOE_ROUTING_CONFIG = {
+  numExperts: 8,
+  topK: 2,
+  normalizeWeights: true,
+  routerDtype: 'f32',
+  maxTokensPerExpert: 0,
+  maxTokensPerExpertHeadroom: 2.0,
+  maxTokensPerExpertMin: 4,
+  maxTokensPerExpertCap: 0,
+};
+
+// =============================================================================
+// MoE Cache Config
+// =============================================================================
+
+export const DEFAULT_MOE_CACHE_CONFIG = {
+  dequantCacheMaxEntries: 128,
+};
+
+// =============================================================================
+// Complete MoE Runtime Config
+// =============================================================================
+
+export const DEFAULT_MOE_RUNTIME_CONFIG = {
+  routing: DEFAULT_MOE_ROUTING_CONFIG,
+  cache: DEFAULT_MOE_CACHE_CONFIG,
+};

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

@@ -0,0 +1,121 @@
+/**
+ * Platform Config Schema Definitions
+ *
+ * Defines the structure for device-family platform configurations.
+ * Platforms provide detection metadata and memory hints for GPU families.
+ *
+ * Note: GPU capabilities (hasSubgroups, hasF16, etc.) are detected at runtime,
+ * not stored in config. Platforms assume those capabilities are available.
+ *
+ * @module config/schema/platform
+ */
+
+/**
+ * Patterns for detecting which platform to use based on GPU adapter info.
+ */
+export interface PlatformDetectionSchema {
+  /** Vendor string pattern (e.g., "apple", "nvidia", "amd") */
+  vendor?: string;
+
+  /** Architecture pattern (e.g., "gpu-family-apple-9") */
+  architecture?: string;
+
+  /** Device name pattern (e.g., "M3", "RTX 4090") */
+  device?: string;
+
+  /** WebGPU adapter description pattern */
+  description?: string;
+}
+
+/**
+ * Memory-related hints for this platform.
+ */
+export interface MemoryHintsSchema {
+  /** Whether to prefer unified memory strategies (Apple Silicon) */
+  preferUnifiedMemory?: boolean;
+
+  /** Optimal buffer alignment in bytes */
+  bufferAlignment?: number;
+
+  /** Optimal shard size for this platform */
+  optimalShardSize?: number;
+
+  /** Maximum recommended buffer pool size */
+  maxBufferPoolSize?: number;
+}
+
+/**
+ * Complete platform configuration for a GPU device family.
+ */
+export interface PlatformSchema {
+  /** Unique identifier (e.g., "apple-m3", "nvidia-rtx40") */
+  id: string;
+
+  /** Human-readable name */
+  name: string;
+
+  /** Detection patterns to match this platform */
+  detection: PlatformDetectionSchema;
+
+  /** Memory hints */
+  memoryHints?: MemoryHintsSchema;
+
+  /** Whether this is a fallback/generic platform */
+  isGeneric?: boolean;
+
+  /** Notes about this platform */
+  notes?: string;
+}
+
+/**
+ * GPU capabilities detected at runtime.
+ * These are NOT stored in config files - they come from WebGPU adapter.
+ */
+export interface RuntimeCapabilities {
+  /** Whether shader-f16 feature is available */
+  hasF16: boolean;
+
+  /** Whether subgroups feature is available */
+  hasSubgroups: boolean;
+
+  /** Subgroup size (if subgroups available) */
+  subgroupSize?: number;
+
+  /** Maximum workgroup size per dimension */
+  maxWorkgroupSize: number;
+
+  /** Maximum compute workgroup storage (shared memory) in bytes */
+  maxSharedMemory: number;
+
+  /** Maximum storage buffer binding size */
+  maxStorageBufferBindingSize: number;
+
+  /** Maximum buffer size */
+  maxBufferSize: number;
+}
+
+/**
+ * Platform config with runtime capabilities merged in.
+ * This is what GPU kernel selection consumes.
+ */
+export interface ResolvedPlatformConfig {
+  /** Platform configuration */
+  platform: PlatformSchema;
+
+  /** Runtime-detected GPU capabilities */
+  capabilities: RuntimeCapabilities;
+}
+
+/**
+ * Collection of all available platform configs.
+ */
+export interface PlatformRegistrySchema {
+  /** Schema version */
+  version: string;
+
+  /** All platform configs by ID */
+  platforms: Record<string, PlatformSchema>;
+
+  /** ID of the generic/fallback platform */
+  fallbackId: string;
+}

package/src/config/schema/platform.schema.js

@@ -0,0 +1 @@
+// This file only contains type definitions - no runtime exports

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

@@ -0,0 +1,124 @@
+/**
+ * Preset Schema Definitions
+ *
+ * Model family presets for config-as-code architecture.
+ * Presets define defaults that can be overridden by manifest config.
+ *
+ * @module config/schema/preset
+ */
+
+import type { ModelType, ArchitectureSchema } from './manifest.schema.js';
+import type {
+  InferenceConfigSchema,
+  TokenizerConfigSchema,
+  SamplingSchema,
+} from './inference.schema.js';
+import type { LoadingConfigSchema } from './loading.schema.js';
+
+/** Kernel path map for conversion defaults (weights quantization -> activation dtype). */
+export type KernelPathMapSchema = Record<string, string | Record<string, string>>;
+
+export type PresetInferenceSchema = InferenceConfigSchema & {
+  kernelPaths?: KernelPathMapSchema;
+};
+
+/** Model family preset */
+export interface PresetSchema {
+  /** Preset identifier */
+  id: string;
+
+  /** Human-readable name */
+  name?: string;
+
+  /** Parent preset to extend */
+  extends?: string;
+
+  /** Model type hint */
+  modelType?: ModelType;
+
+  /** Architecture parameter overrides */
+  architecture?: Partial<ArchitectureSchema>;
+
+  /** Inference behavior */
+  inference?: PresetInferenceSchema;
+
+  /** Tokenizer configuration */
+  tokenizer?: TokenizerConfigSchema;
+
+  /** Default sampling parameters */
+  sampling?: SamplingSchema;
+
+  /** Tensor name patterns for this model family */
+  tensorPatterns?: TensorPatternSchema;
+
+  /** Model family detection patterns */
+  detection?: DetectionPatternSchema;
+
+  /** Loading behavior configuration */
+  loading?: Partial<LoadingConfigSchema>;
+}
+
+/** Tensor naming patterns for model family */
+export interface TensorPatternSchema {
+  /** Embedding tensor patterns */
+  embedding?: string[];
+  /** LM head patterns */
+  lmHead?: string[];
+  /** Layer patterns (with {layer} placeholder) */
+  layer?: string[];
+  /** Attention patterns */
+  attention?: {
+    qProj?: string[];
+    kProj?: string[];
+    vProj?: string[];
+    oProj?: string[];
+    qkv?: string[];  // Fused QKV
+  };
+  /** FFN patterns */
+  ffn?: {
+    gate?: string[];
+    up?: string[];
+    down?: string[];
+    gateUp?: string[];  // Fused gate+up
+  };
+  /** Norm patterns */
+  norm?: {
+    input?: string[];
+    postAttn?: string[];
+    final?: string[];
+  };
+}
+
+/** Patterns for detecting model family */
+export interface DetectionPatternSchema {
+  /** Architecture name patterns (regex) */
+  architecturePatterns?: string[];
+  /** Model type patterns */
+  modelTypePatterns?: string[];
+  /** Config field patterns */
+  configPatterns?: Record<string, unknown>;
+}
+
+/** Fully resolved configuration (preset + manifest merged) */
+export interface ResolvedConfigSchema {
+  /** Source preset ID */
+  preset: string;
+
+  /** Model type */
+  modelType: ModelType;
+
+  /** Architecture parameters */
+  architecture: ArchitectureSchema;
+
+  /** Inference configuration */
+  inference: Required<InferenceConfigSchema>;
+
+  /** Tokenizer configuration */
+  tokenizer: TokenizerConfigSchema;
+
+  /** Sampling defaults */
+  sampling: SamplingSchema;
+
+  /** Loading behavior configuration */
+  loading: LoadingConfigSchema;
+}

package/src/config/schema/preset.schema.js

@@ -0,0 +1 @@
+// This file only contains type definitions - no runtime exports

package/src/config/schema/quantization-defaults.schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Quantization Defaults Config Schema
+ *
+ * Default quantization settings for the model converter.
+ * Controls the target precision for different weight groups when not explicitly specified.
+ *
+ * @module config/schema/quantization-defaults
+ */
+
+/** Supported weight quantization types */
+export type WeightQuantType = 'f16' | 'f32' | 'q4k' | 'q6k' | 'q8_0';
+
+/** Supported embedding quantization types */
+export type EmbeddingQuantType = 'f16' | 'f32';
+
+/**
+ * Default quantization settings for model conversion.
+ *
+ * These defaults are used when no explicit quantization is specified
+ * for a particular weight group during conversion.
+ */
+export interface QuantizationDefaultsSchema {
+  /** Default dtype for vision encoder weights (default: 'f16') */
+  visionDtype: EmbeddingQuantType;
+
+  /** Default dtype for audio encoder weights (default: 'f16') */
+  audioDtype: EmbeddingQuantType;
+
+  /** Default dtype for projector weights in multimodal models (default: 'f16') */
+  projectorDtype: EmbeddingQuantType;
+}
+
+/** Default quantization configuration */
+export declare const DEFAULT_QUANTIZATION_DEFAULTS: QuantizationDefaultsSchema;

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

@@ -0,0 +1,5 @@
+export const DEFAULT_QUANTIZATION_DEFAULTS = {
+  visionDtype: 'f16',
+  audioDtype: 'f16',
+  projectorDtype: 'f16',
+};

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

@@ -0,0 +1,10 @@
+export declare const QK_K: number;
+export declare const Q4K_BLOCK_BYTES: number;
+export declare const Q6K_BLOCK_BYTES: number;
+export declare const Q8_0_BLOCK_BYTES: number;
+export declare const Q8_0_BLOCK_SIZE: number;
+export declare const K_SCALE_SIZE: number;
+export declare const QK4_K_BLOCK_SIZE: number;
+
+export declare function padToQ4KBlock(size: number): number;
+export declare function q4kBlockCount(numElements: number): number;

package/src/config/schema/quantization.schema.js

@@ -0,0 +1,33 @@
+
+// Q4K super-block size (invariant - format spec constant)
+// WGSL kernels also define this as `const QK_K: u32 = 256u;`
+// JS and WGSL must agree on this value.
+export const QK_K = 256;
+
+// Q4K block size in bytes (144 bytes per 256-element super-block)
+export const Q4K_BLOCK_BYTES = 144;
+
+// Q6K block size in bytes (210 bytes per 256-element super-block)
+export const Q6K_BLOCK_BYTES = 210;
+
+// Q8_0 block size in bytes (34 bytes per 32-element block)
+export const Q8_0_BLOCK_BYTES = 34;
+
+// Q8_0 block size in elements
+export const Q8_0_BLOCK_SIZE = 32;
+
+// K_SCALE_SIZE for Q4K (12 bytes for scales/mins metadata)
+export const K_SCALE_SIZE = 12;
+
+// Q4K block size in bytes (same as Q4K_BLOCK_BYTES, exported for compatibility)
+export const QK4_K_BLOCK_SIZE = Q4K_BLOCK_BYTES;
+
+// Pad size to Q4K super-block alignment
+export function padToQ4KBlock(size) {
+  return Math.ceil(size / QK_K) * QK_K;
+}
+
+// Calculate number of Q4K blocks for a given number of elements
+export function q4kBlockCount(numElements) {
+  return Math.ceil(numElements / QK_K);
+}

package/src/config/schema/shared-runtime.schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared Runtime Config Schema Definitions
+ *
+ * Cross-cutting configuration shared between model loading and inference.
+ *
+ * @module config/schema/shared-runtime
+ */
+
+import type { DebugConfigSchema } from './debug.schema.js';
+import type { BenchmarkConfig } from './benchmark.schema.js';
+import type { KernelThresholdsConfigSchema } from './kernel-thresholds.schema.js';
+import type { BufferPoolConfigSchema } from './buffer-pool.schema.js';
+import type { GpuCacheConfigSchema } from './gpu-cache.schema.js';
+import type { MemoryLimitsConfigSchema } from './memory-limits.schema.js';
+import type { TunerConfigSchema } from './tuner.schema.js';
+import type { KernelWarmupConfigSchema } from './kernel-warmup.schema.js';
+import type { HotSwapConfigSchema } from './hotswap.schema.js';
+import type { IntentBundleConfigSchema } from './intent-bundle.schema.js';
+import type { BridgeConfigSchema } from './bridge.schema.js';
+import type { PlatformSchema } from './platform.schema.js';
+import type { HarnessConfigSchema } from './harness.schema.js';
+import type { ToolingConfigSchema } from './tooling.schema.js';
+import type { EcosystemConfigSchema } from './ecosystem.schema.js';
+
+/**
+ * Kernel registry configuration (source/override).
+ */
+export interface KernelRegistryConfigSchema {
+  /** Optional URL override for kernel registry JSON */
+  url?: string | null;
+}
+
+/** Default kernel registry configuration */
+export declare const DEFAULT_KERNEL_REGISTRY_CONFIG: KernelRegistryConfigSchema;
+
+/**
+ * Shared runtime configuration schema.
+ */
+export interface SharedRuntimeConfigSchema {
+  /** Unified debug/log/trace configuration */
+  debug: DebugConfigSchema;
+  /** Benchmarking configuration defaults */
+  benchmark: BenchmarkConfig;
+  /** Harness configuration (CLI/test runner) */
+  harness: HarnessConfigSchema;
+  /** Tooling intent and diagnostics policy */
+  tooling: ToolingConfigSchema;
+  /** Ecosystem/platform-layer policy contract */
+  ecosystem: EcosystemConfigSchema;
+  /** Optional platform override (auto-detect when null) */
+  platform: Partial<PlatformSchema> | null;
+  /** Kernel registry source config */
+  kernelRegistry: KernelRegistryConfigSchema;
+  /** Kernel selection thresholds */
+  kernelThresholds: KernelThresholdsConfigSchema;
+  /** Kernel prewarm and auto-tuning settings */
+  kernelWarmup: KernelWarmupConfigSchema;
+  /** GPU buffer pool sizing */
+  bufferPool: BufferPoolConfigSchema;
+  /** Uniform cache limits */
+  gpuCache: GpuCacheConfigSchema;
+  /** WASM heap and segment limits */
+  memory: MemoryLimitsConfigSchema;
+  /** Kernel autotuning settings */
+  tuner: TunerConfigSchema;
+  /** Hot-swap security policy */
+  hotSwap: HotSwapConfigSchema;
+  /** Intent bundle gating policy */
+  intentBundle: IntentBundleConfigSchema;
+  /** Native bridge settings (Tier 2) */
+  bridge: BridgeConfigSchema;
+}
+
+/** Default shared runtime configuration */
+export declare const DEFAULT_SHARED_RUNTIME_CONFIG: SharedRuntimeConfigSchema;