@simulatte/doppler 0.1.0

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

@@ -0,0 +1,199 @@
+/**
+ * Kernel Registry Schema Definitions
+ *
+ * Defines the structure for kernel metadata: variants, bindings, uniforms,
+ * workgroup sizes, and GPU feature requirements.
+ *
+ * @module config/schema/kernel-registry
+ */
+
+/**
+ * GPU features that a kernel variant may require.
+ * These map to WebGPU adapter features.
+ */
+export type GpuFeature = 'shader-f16' | 'subgroups' | 'subgroups-f16';
+
+/**
+ * WebGPU buffer binding types.
+ */
+export type BindingType = 'uniform' | 'storage' | 'read-only-storage';
+
+/**
+ * A single buffer binding in a kernel's bind group layout.
+ */
+export interface BindingSchema {
+  /** Binding index in the bind group */
+  index: number;
+
+  /** Human-readable name for debugging */
+  name: string;
+
+  /** Buffer type (uniform, storage, read-only-storage) */
+  type: BindingType;
+
+  /** Optional: whether this binding is optional (can be null) */
+  optional?: boolean;
+}
+
+/**
+ * Primitive types for uniform struct fields.
+ */
+export type UniformFieldType = 'u32' | 'i32' | 'f32' | 'f16';
+
+/**
+ * A field in a uniform buffer struct.
+ */
+export interface UniformFieldSchema {
+  /** Field name (matches WGSL struct field) */
+  name: string;
+
+  /** Data type */
+  type: UniformFieldType;
+
+  /** Byte offset in the uniform buffer */
+  offset: number;
+}
+
+/**
+ * Complete uniform buffer schema for a kernel.
+ */
+export interface UniformsSchema {
+  /** Total size in bytes (must be 16-byte aligned for WebGPU) */
+  size: number;
+
+  /** Fields in the uniform struct */
+  fields: UniformFieldSchema[];
+}
+
+/**
+ * WGSL override constants that can be set at pipeline creation.
+ */
+export interface WgslOverridesSchema {
+  [constantName: string]: number;
+}
+
+/**
+ * A single kernel variant (e.g., matmul/f16, matmul/q4_fused).
+ */
+export interface KernelVariantSchema {
+  /** WGSL shader filename (relative to kernels directory) */
+  wgsl: string;
+
+  /** Entry point function name in the shader */
+  entryPoint: string;
+
+  /** Workgroup size [x, y, z] */
+  workgroup: [number, number, number];
+
+  /** GPU features required to use this variant */
+  requires?: GpuFeature[];
+
+  /** Estimated shared memory usage in bytes */
+  sharedMemory?: number;
+
+  /** WGSL override constants to set at pipeline creation */
+  wgslOverrides?: WgslOverridesSchema;
+
+  /** Output data type for kernels that write F16 buffers */
+  outputDtype?: string;
+
+  /** Variant-specific metadata for dispatch planning */
+  variantMetadata?: Record<string, number | boolean | string>;
+
+  /** Additional bindings beyond the base operation bindings */
+  bindingsOverride?: BindingSchema[];
+
+  /** Override uniform schema (if different from base) */
+  uniformsOverride?: UniformsSchema;
+
+  /** Human-readable description */
+  description?: string;
+}
+
+/**
+ * An operation (e.g., matmul, attention, rmsnorm) with all its variants.
+ */
+export interface OperationSchema {
+  /** Base bindings shared by all variants */
+  baseBindings: BindingSchema[];
+
+  /** Base uniforms shared by all variants */
+  baseUniforms: UniformsSchema;
+
+  /** Available variants for this operation */
+  variants: Record<string, KernelVariantSchema>;
+
+  /** Human-readable description of the operation */
+  description?: string;
+}
+
+/**
+ * Complete kernel registry with all operations and their variants.
+ */
+export interface KernelRegistrySchema {
+  /** Schema version for compatibility checking */
+  version: string;
+
+  /** All kernel operations */
+  operations: Record<string, OperationSchema>;
+}
+
+/**
+ * Fully resolved kernel configuration after merging base and variant.
+ */
+export interface ResolvedKernelConfig {
+  /** Operation name */
+  operation: string;
+
+  /** Variant name */
+  variant: string;
+
+  /** WGSL shader filename */
+  wgsl: string;
+
+  /** Entry point function name */
+  entryPoint: string;
+
+  /** Workgroup size [x, y, z] */
+  workgroup: [number, number, number];
+
+  /** GPU features required */
+  requires: GpuFeature[];
+
+  /** All bindings (base + override merged) */
+  bindings: BindingSchema[];
+
+  /** Uniform schema (base or overridden) */
+  uniforms: UniformsSchema;
+
+  /** WGSL override constants */
+  wgslOverrides: WgslOverridesSchema;
+
+  /** Estimated shared memory usage in bytes */
+  sharedMemory: number;
+
+  /** Output data type for kernels that write F16 buffers */
+  outputDtype: string | null;
+
+  /** Variant-specific metadata for dispatch planning */
+  variantMetadata: Record<string, number | boolean | string> | null;
+}
+
+/**
+ * Merge base and variant bindings.
+ * Variant bindings with matching indices override base bindings.
+ */
+export declare function mergeBindings(
+  base: BindingSchema[],
+  override?: BindingSchema[]
+): BindingSchema[];
+
+/**
+ * Resolve a kernel variant to a complete configuration.
+ */
+export declare function resolveKernelConfig(
+  operation: string,
+  variant: string,
+  opSchema: OperationSchema,
+  variantSchema: KernelVariantSchema
+): ResolvedKernelConfig;

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

@@ -0,0 +1,46 @@
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+export function mergeBindings(
+  base,
+  override
+) {
+  if (!override || override.length === 0) {
+    return [...base];
+  }
+
+  const result = [...base];
+  for (const binding of override) {
+    const existingIdx = result.findIndex(b => b.index === binding.index);
+    if (existingIdx >= 0) {
+      result[existingIdx] = binding;
+    } else {
+      result.push(binding);
+    }
+  }
+
+  return result.sort((a, b) => a.index - b.index);
+}
+
+export function resolveKernelConfig(
+  operation,
+  variant,
+  opSchema,
+  variantSchema
+) {
+  return {
+    operation,
+    variant,
+    wgsl: variantSchema.wgsl,
+    entryPoint: variantSchema.entryPoint,
+    workgroup: variantSchema.workgroup,
+    requires: variantSchema.requires ?? [],
+    bindings: mergeBindings(opSchema.baseBindings, variantSchema.bindingsOverride),
+    uniforms: variantSchema.uniformsOverride ?? opSchema.baseUniforms,
+    wgslOverrides: variantSchema.wgslOverrides ?? {},
+    sharedMemory: variantSchema.sharedMemory ?? 0,
+    outputDtype: variantSchema.outputDtype ?? null,
+    variantMetadata: variantSchema.variantMetadata ?? null,
+  };
+}

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

@@ -0,0 +1,302 @@
+/**
+ * Kernel Thresholds Schema
+ *
+ * Centralized configuration for kernel selection thresholds and magic numbers.
+ * These values control when variant selection switches between kernel implementations.
+ *
+ * @module config/schema/kernel-thresholds
+ */
+
+/**
+ * Thresholds for matrix multiplication kernel variant selection.
+ */
+export interface MatmulThresholdsSchema {
+  /**
+   * N dimension threshold for selecting multicol GEMV variants.
+   * When N >= threshold, use multicol variant for reduced workgroup count.
+   * @default 256
+   */
+  multicolThreshold: number;
+
+  /**
+   * Minimum prefill rows required before selecting the tiled f16 matmul variant.
+   * For very short prefill batches, base f16 matmul can be faster than tiled.
+   * @default 32
+   */
+  tiledPrefillMinRows: number;
+}
+
+export declare const DEFAULT_MATMUL_THRESHOLDS: MatmulThresholdsSchema;
+
+/**
+ * Thresholds for RMSNorm kernel variant selection.
+ */
+export interface RmsnormThresholdsSchema {
+  /**
+   * Hidden size threshold for selecting small vs default variant.
+   * When hiddenSize <= threshold, use small variant (single workgroup).
+   * @default 256
+   */
+  smallThreshold: number;
+}
+
+export declare const DEFAULT_RMSNORM_THRESHOLDS: RmsnormThresholdsSchema;
+
+/**
+ * Thresholds for softmax kernel variant selection.
+ */
+export interface SoftmaxThresholdsSchema {
+  /**
+   * Inner size threshold for selecting small vs default variant.
+   * When innerSize <= threshold, use small variant.
+   * @default 256
+   */
+  smallThreshold: number;
+}
+
+export declare const DEFAULT_SOFTMAX_THRESHOLDS: SoftmaxThresholdsSchema;
+
+/**
+ * Thresholds for fused FFN kernel variant selection.
+ */
+export interface FfnThresholdsSchema {
+  /**
+   * Intermediate size threshold for selecting multi-output variant.
+   * When intermediateSize <= threshold, use multi variant.
+   * @default 1024
+   */
+  multiOutputThreshold: number;
+}
+
+export declare const DEFAULT_FFN_THRESHOLDS: FfnThresholdsSchema;
+
+/**
+ * Thresholds for sampling kernel selection.
+ */
+export interface SampleThresholdsSchema {
+  /**
+   * Vocab size threshold for argmax reduce variant selection.
+   * When vocabSize > threshold, use argmax_reduce.
+   * @default 65536
+   */
+  argmaxReduceVocabThreshold: number;
+
+  /**
+   * Max topK for single-pass sampling.
+   * When topK <= threshold, use single-pass sampling.
+   * @default 100
+   */
+  singlePassTopKThreshold: number;
+}
+
+export declare const DEFAULT_SAMPLE_THRESHOLDS: SampleThresholdsSchema;
+
+/**
+ * Default values for RoPE (Rotary Position Embedding) kernel.
+ */
+export interface RopeDefaultsSchema {
+  /**
+   * Default theta value for RoPE frequency computation.
+   * Most models use 10000.0; some (Gemma 3) use higher values.
+   * @default 10000.0
+   */
+  defaultTheta: number;
+
+  /**
+   * Default uniform buffer size in bytes for RoPE params.
+   * @default 32
+   */
+  uniformSize: number;
+
+  /**
+   * Default start position for RoPE.
+   * @default 0
+   */
+  defaultStartPos: number;
+}
+
+export declare const DEFAULT_ROPE_DEFAULTS: RopeDefaultsSchema;
+
+/**
+ * Defaults for kernel tuner limits when device limits are unavailable.
+ */
+export interface TunerLimitsSchema {
+  maxComputeWorkgroupSizeX: number;
+  maxComputeWorkgroupSizeY: number;
+  maxComputeInvocationsPerWorkgroup: number;
+}
+
+export declare const DEFAULT_TUNER_LIMITS: TunerLimitsSchema;
+
+/**
+ * Thresholds for attention kernel variant selection.
+ */
+export interface AttentionThresholdsSchema {
+  /**
+   * Maximum KV length before switching from chunked to streaming attention.
+   * Used by decode_chunked_f16kv variant.
+   * @default 2048
+   */
+  chunkedMaxKVLen: number;
+
+  /**
+   * Minimum head dimension for chunked attention kernel eligibility.
+   * Chunked kernels require headDim >= this value.
+   * @default 128
+   */
+  minHeadDimForChunked: number;
+
+  /**
+   * Head dimension thresholds for tier selection.
+   * tier3: headDim <= 64, tier2: headDim <= 128, tier1: headDim <= 256
+   */
+  tierHeadDimLimits: {
+    tier3: number;
+    tier2: number;
+    tier1: number;
+  };
+
+  /**
+   * Minimum shared memory requirements per tier (in bytes).
+   */
+  tierMinSharedMemory: {
+    tier3: number;
+    tier2: number;
+    tier1: number;
+  };
+
+  /**
+   * Maximum head dimension for large tiled attention.
+   * @default 64
+   */
+  largeMaxHeadDim: number;
+
+  /**
+   * Maximum head dimension for small tiled attention.
+   * @default 256
+   */
+  smallMaxHeadDim: number;
+
+  /**
+   * Maximum head dimension for subgroup attention.
+   * @default 256
+   */
+  subgroupMaxHeadDim: number;
+
+  /**
+   * Shared memory requirement for large tiled attention (F32 KV).
+   * @default 20480
+   */
+  largeSharedF32: number;
+
+  /**
+   * Shared memory requirement for large tiled attention (F16 KV).
+   * @default 49152
+   */
+  largeSharedF16: number;
+
+  /**
+   * Shared memory requirement for small tiled attention (F32 KV).
+   * @default 8192
+   */
+  smallSharedF32: number;
+
+  /**
+   * Shared memory requirement for small tiled attention (F16 KV).
+   * @default 4096
+   */
+  smallSharedF16: number;
+
+  /**
+   * Shared memory requirement for subgroup attention.
+   * @default 8192
+   */
+  subgroupShared: number;
+}
+
+export declare const DEFAULT_ATTENTION_THRESHOLDS: AttentionThresholdsSchema;
+
+/**
+ * Thresholds for fused matmul+norm kernel variant selection.
+ */
+export interface FusedMatmulThresholdsSchema {
+  /**
+   * Maximum N dimension for "medium" (multi-column) fused variant.
+   * Beyond this, fall back to separate kernels or alternative dispatch.
+   * @default 4096
+   */
+  maxMediumN: number;
+
+  /**
+   * Maximum K dimension for fused GEMV+RMSNorm selection.
+   * When K exceeds this threshold, prefer separate kernels for better throughput.
+   * @default 8192
+   */
+  maxMediumK: number;
+
+  /**
+   * Columns per workgroup for multi-column dispatch.
+   * Each workgroup processes this many output columns.
+   * @default 4
+   */
+  colsPerWg: number;
+}
+
+export declare const DEFAULT_FUSED_MATMUL_THRESHOLDS: FusedMatmulThresholdsSchema;
+
+/**
+ * Configuration for cast kernel dispatch.
+ */
+export interface CastThresholdsSchema {
+  /**
+   * Maximum workgroups per dimension before falling back to 2D dispatch.
+   * @default 65535
+   */
+  maxWorkgroupsPerDim: number;
+}
+
+export declare const DEFAULT_CAST_THRESHOLDS: CastThresholdsSchema;
+
+/**
+ * Bytes per element for each data type.
+ */
+export declare const DTYPE_SIZES: Record<string, number>;
+
+/**
+ * Get byte size for a dtype string.
+ * Throws if dtype is unknown.
+ */
+export declare function getDtypeSize(dtype: string): number;
+
+/**
+ * All kernel thresholds in a single configuration object.
+ */
+export interface KernelThresholdsConfigSchema {
+  matmul: MatmulThresholdsSchema;
+  rmsnorm: RmsnormThresholdsSchema;
+  softmax: SoftmaxThresholdsSchema;
+  ffn: FfnThresholdsSchema;
+  sample: SampleThresholdsSchema;
+  rope: RopeDefaultsSchema;
+  attention: AttentionThresholdsSchema;
+  fusedMatmul: FusedMatmulThresholdsSchema;
+  cast: CastThresholdsSchema;
+  tuner: TunerLimitsSchema;
+}
+
+export declare const DEFAULT_KERNEL_THRESHOLDS: KernelThresholdsConfigSchema;
+
+/**
+ * Get the current kernel thresholds configuration.
+ */
+export declare function getKernelThresholds(): KernelThresholdsConfigSchema;
+
+/**
+ * Override kernel thresholds (merges with current config).
+ */
+export declare function setKernelThresholds(overrides: Partial<KernelThresholdsConfigSchema>): void;
+
+/**
+ * Reset kernel thresholds to defaults.
+ */
+export declare function resetKernelThresholds(): void;