@simulatte/doppler 0.1.0

package/src/inference/pipelines/text/kernel-path-auto-select.d.ts

@@ -0,0 +1,12 @@
+import type { KernelPathRef } from '../../../config/schema/index.js';
+import type { KernelPathPolicy, KernelPathSource } from '../../../config/kernel-path-loader.js';
+import type { KernelCapabilities } from '../../../gpu/device.js';
+
+export function resolveKernelPathPolicy(policy?: Partial<KernelPathPolicy> | null): KernelPathPolicy;
+
+export function resolveCapabilityKernelPathRef(
+  configuredKernelPathRef: KernelPathRef,
+  kernelPathSource: KernelPathSource,
+  capabilities?: Partial<KernelCapabilities> | null,
+  kernelPathPolicy?: Partial<KernelPathPolicy> | null
+): KernelPathRef;

package/src/inference/pipelines/text/kernel-path-auto-select.js

@@ -0,0 +1,90 @@
+import { selectRuleValue } from '../../../rules/rule-registry.js';
+
+const DEFAULT_KERNEL_PATH_POLICY = Object.freeze({
+  mode: 'locked',
+  sourceScope: Object.freeze(['model', 'manifest']),
+  onIncompatible: 'error',
+});
+
+function normalizeKernelPathSource(source) {
+  const normalized = String(source ?? '').trim().toLowerCase();
+  if (normalized === 'runtime') {
+    return 'config';
+  }
+  if (normalized === 'execution_v0' || normalized === 'execution-v0') {
+    return 'execution-v0';
+  }
+  return normalized || 'none';
+}
+
+function normalizeKernelPathPolicyMode(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (normalized === 'capability-aware') {
+    return 'capability-aware';
+  }
+  return 'locked';
+}
+
+function normalizeKernelPathPolicySourceScope(value) {
+  if (!Array.isArray(value)) {
+    return [...DEFAULT_KERNEL_PATH_POLICY.sourceScope];
+  }
+  const normalized = new Set();
+  for (const source of value) {
+    const normalizedSource = normalizeKernelPathSource(source);
+    if (normalizedSource === 'none') continue;
+    normalized.add(normalizedSource);
+  }
+  if (normalized.size === 0) {
+    return [...DEFAULT_KERNEL_PATH_POLICY.sourceScope];
+  }
+  return [...normalized];
+}
+
+function normalizeKernelPathPolicyOnIncompatible(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (normalized === 'remap') {
+    return 'remap';
+  }
+  return 'error';
+}
+
+export function resolveKernelPathPolicy(policy) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    return {
+      mode: DEFAULT_KERNEL_PATH_POLICY.mode,
+      sourceScope: [...DEFAULT_KERNEL_PATH_POLICY.sourceScope],
+      allowSources: [...DEFAULT_KERNEL_PATH_POLICY.sourceScope],
+      onIncompatible: DEFAULT_KERNEL_PATH_POLICY.onIncompatible,
+    };
+  }
+
+  const sourceScope = normalizeKernelPathPolicySourceScope(
+    policy.sourceScope ?? policy.allowSources
+  );
+
+  return {
+    mode: normalizeKernelPathPolicyMode(policy.mode),
+    sourceScope,
+    allowSources: [...sourceScope],
+    onIncompatible: normalizeKernelPathPolicyOnIncompatible(policy.onIncompatible),
+  };
+}
+
+export function resolveCapabilityKernelPathRef(configuredKernelPathRef, kernelPathSource, capabilities, kernelPathPolicy = null) {
+  if (typeof configuredKernelPathRef !== 'string') {
+    return configuredKernelPathRef;
+  }
+
+  const normalizedPolicy = resolveKernelPathPolicy(kernelPathPolicy);
+  const hasSubgroups = capabilities?.hasSubgroups === true;
+  const normalizedSource = normalizeKernelPathSource(kernelPathSource);
+  const allowCapabilityAutoSelection = normalizedPolicy.mode === 'capability-aware'
+    && normalizedPolicy.sourceScope.includes(normalizedSource);
+
+  return selectRuleValue('inference', 'kernelPath', 'autoSelect', {
+    kernelPathRef: configuredKernelPathRef,
+    hasSubgroups,
+    allowCapabilityAutoSelection,
+  });
+}

package/src/inference/pipelines/text/kernel-trace.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Kernel Pipeline Tracer - systematic debugging for GPU inference.
+ *
+ * @module inference/pipelines/text/kernel-trace
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Snapshot of a tensor's statistics (no full data, just stats).
+ */
+export interface TensorSnapshot {
+  shape: number[];
+  dtype: string;
+  stats: {
+    min: number;
+    max: number;
+    maxAbs: number;
+    mean: number;
+    std: number;
+  };
+  sample: number[];
+  hasNaN: boolean;
+  hasInf: boolean;
+}
+
+/**
+ * A single step in the kernel pipeline.
+ */
+export interface KernelStep {
+  name: string;
+  label: string;
+  layer: number;
+  inputs: TensorSnapshot[];
+  output: TensorSnapshot;
+  variant?: string;
+  timeMs?: number;
+}
+
+/**
+ * Detected anomaly in the pipeline.
+ */
+export interface Anomaly {
+  type: 'nan' | 'inf' | 'explosion' | 'collapse';
+  severity: 'critical' | 'warning';
+  stepIdx: number;
+  step: KernelStep;
+  message: string;
+  factor?: number;
+}
+
+/**
+ * Options for enabling tracing.
+ */
+export interface TraceOptions {
+  layers?: number[];
+  breakOnAnomaly?: boolean;
+  explosionThreshold?: number;
+  collapseThreshold?: number;
+  maxSteps?: number;
+}
+
+// ============================================================================
+// Tensor Snapshot Utility
+// ============================================================================
+
+/**
+ * Create a snapshot of a GPU tensor (requires readback - expensive!).
+ */
+export function snapshotTensor(
+  buffer: GPUBuffer,
+  shape?: number[],
+  dtype?: string
+): Promise<TensorSnapshot>;
+
+/**
+ * Create a snapshot from a Float32Array (CPU data).
+ */
+export function snapshotFromArray(
+  arr: Float32Array,
+  shape: number[],
+  dtype?: string
+): TensorSnapshot;
+
+// ============================================================================
+// KernelTrace Class
+// ============================================================================
+
+/**
+ * Global kernel pipeline tracer.
+ */
+declare class KernelTrace {
+  get enabled(): boolean;
+  enable(options?: TraceOptions): void;
+  disable(): void;
+  clear(): void;
+  shouldTraceLayer(layerIdx: number): boolean;
+  recordStep(step: KernelStep): void;
+  findAnomaly(): Anomaly | null;
+  getAnomalies(): Anomaly[];
+  lastStep(): KernelStep | null;
+  getLastNSteps(n: number): KernelStep[];
+  getSteps(): KernelStep[];
+  getTimeline(): string;
+  toJSON(): string;
+  dumpLastNSteps(n?: number): void;
+}
+
+/**
+ * Global kernel trace instance.
+ */
+export const kernelTrace: KernelTrace;
+
+// ============================================================================
+// Convenience: Record Step Helper
+// ============================================================================
+
+/**
+ * Helper to record a step if tracing is enabled.
+ */
+export function traceStep(
+  name: string,
+  label: string,
+  layer: number,
+  outputBuffer: GPUBuffer,
+  outputShape: number[],
+  options?: {
+    inputs?: GPUBuffer[];
+    inputShapes?: number[][];
+    variant?: string;
+    timeMs?: number;
+  }
+): Promise<void>;
+
+/**
+ * Sync version for when you already have the data as Float32Array.
+ */
+export function traceStepSync(
+  name: string,
+  label: string,
+  layer: number,
+  outputData: Float32Array,
+  outputShape: number[],
+  options?: {
+    variant?: string;
+    timeMs?: number;
+  }
+): void;

package/src/inference/pipelines/text/kernel-trace.js

@@ -0,0 +1,324 @@
+
+import { log, trace } from '../../../debug/index.js';
+import { snapshotTensor as snapshotTensorImpl, snapshotFromArray as snapshotFromArrayImpl } from '../../../debug/tensor.js';
+
+// ============================================================================
+// Tensor Snapshot Utility
+// ============================================================================
+
+
+export async function snapshotTensor(buffer, shape, dtype = 'f32') {
+  return snapshotTensorImpl(buffer, shape, dtype);
+}
+
+
+export function snapshotFromArray(arr, shape, dtype = 'f32') {
+  return snapshotFromArrayImpl(arr, shape, dtype);
+}
+
+// ============================================================================
+// KernelTrace Class
+// ============================================================================
+
+
+class KernelTrace {
+  constructor() {
+    
+    this._steps = [];
+    
+    this._enabled = false;
+    
+    this._options = {};
+    
+    this._anomalies = [];
+  }
+
+  
+  get enabled() {
+    return this._enabled;
+  }
+
+  
+  enable(options = {}) {
+    this._enabled = true;
+    // Caller should pass resolved runtime config values; inline defaults match schema
+    this._options = {
+      layers: options.layers ?? [],
+      breakOnAnomaly: options.breakOnAnomaly ?? true,
+      explosionThreshold: options.explosionThreshold ?? 10,
+      collapseThreshold: options.collapseThreshold ?? 1e-6,
+      maxSteps: options.maxSteps ?? 100,
+    };
+    this._steps = [];
+    this._anomalies = [];
+    log.info('Trace', 'Kernel tracing enabled', this._options);
+  }
+
+  
+  disable() {
+    this._enabled = false;
+    this._steps = [];
+    this._anomalies = [];
+  }
+
+  
+  clear() {
+    this._steps = [];
+    this._anomalies = [];
+  }
+
+  
+  shouldTraceLayer(layerIdx) {
+    if (!this._enabled) return false;
+    if (!this._options.layers?.length) return true;
+    return this._options.layers.includes(layerIdx);
+  }
+
+  
+  recordStep(step) {
+    if (!this._enabled) return;
+
+    // Check layer filter
+    if (step.layer >= 0 && !this.shouldTraceLayer(step.layer)) return;
+
+    // Add to steps (circular buffer)
+    if (this._steps.length >= this._options.maxSteps) {
+      this._steps.shift();
+    }
+    this._steps.push(step);
+
+    // Check for anomalies
+    const anomaly = this._detectAnomaly(step, this._steps.length - 1);
+    if (anomaly) {
+      this._anomalies.push(anomaly);
+      this._logAnomaly(anomaly);
+
+      if (this._options.breakOnAnomaly) {
+        throw new Error(`[TRACE] Anomaly detected: ${anomaly.message}`);
+      }
+    }
+  }
+
+  
+  _detectAnomaly(step, stepIdx) {
+    const { output } = step;
+
+    // Critical: NaN
+    if (output.hasNaN) {
+      return {
+        type: 'nan',
+        severity: 'critical',
+        stepIdx,
+        step,
+        message: `NaN detected in ${step.label}`,
+      };
+    }
+
+    // Critical: Inf
+    if (output.hasInf) {
+      return {
+        type: 'inf',
+        severity: 'critical',
+        stepIdx,
+        step,
+        message: `Inf detected in ${step.label}`,
+      };
+    }
+
+    // Warning: Value explosion (compare to previous step)
+    if (stepIdx > 0) {
+      const prevStep = this._steps[stepIdx - 1];
+      const prevMaxAbs = prevStep.output.stats.maxAbs;
+      const currMaxAbs = output.stats.maxAbs;
+      const threshold = this._options.explosionThreshold;
+
+      if (prevMaxAbs > 0 && currMaxAbs > prevMaxAbs * threshold) {
+        return {
+          type: 'explosion',
+          severity: 'warning',
+          stepIdx,
+          step,
+          message: `Value explosion at ${step.label}: ${prevMaxAbs.toFixed(2)} -> ${currMaxAbs.toFixed(2)} (${(currMaxAbs / prevMaxAbs).toFixed(1)}x)`,
+          factor: currMaxAbs / prevMaxAbs,
+        };
+      }
+    }
+
+    // Warning: Collapse to zeros
+    const collapseThreshold = this._options.collapseThreshold;
+    if (output.stats.maxAbs < collapseThreshold && output.shape.reduce((a, b) => a * b, 1) > 0) {
+      return {
+        type: 'collapse',
+        severity: 'warning',
+        stepIdx,
+        step,
+        message: `Value collapse at ${step.label}: maxAbs=${output.stats.maxAbs.toExponential(2)}`,
+      };
+    }
+
+    return null;
+  }
+
+  
+  _logAnomaly(anomaly) {
+    const marker = anomaly.severity === 'critical' ? '[CRITICAL]' : '[WARNING]';
+    const logFn = anomaly.severity === 'critical' ? log.error : log.warn;
+    logFn('Trace', `${marker} ${anomaly.message}`);
+    trace.kernels(`Step: ${anomaly.step.name} (${anomaly.step.label})`);
+    trace.kernels(`Output: shape=${JSON.stringify(anomaly.step.output.shape)}`);
+    trace.kernels(`Stats: min=${anomaly.step.output.stats.min.toFixed(4)}, max=${anomaly.step.output.stats.max.toFixed(4)}, maxAbs=${anomaly.step.output.stats.maxAbs.toFixed(4)}`);
+    trace.kernels(`Sample: [${anomaly.step.output.sample.slice(0, 5).map(v => v.toFixed(4)).join(', ')}]`);
+  }
+
+  
+  findAnomaly() {
+    return this._anomalies.length > 0 ? this._anomalies[0] : null;
+  }
+
+  
+  getAnomalies() {
+    return [...this._anomalies];
+  }
+
+  
+  lastStep() {
+    return this._steps.length > 0 ? this._steps[this._steps.length - 1] : null;
+  }
+
+  
+  getLastNSteps(n) {
+    return this._steps.slice(-n);
+  }
+
+  
+  getSteps() {
+    return [...this._steps];
+  }
+
+  
+  getTimeline() {
+    if (this._steps.length === 0) return '[TRACE] No steps recorded';
+
+    
+    const lines = [];
+    lines.push('+-----------------------------------------------------------------+');
+    lines.push('| KERNEL PIPELINE TRACE                                           |');
+    lines.push('+-----------------------------------------------------------------+');
+
+    for (let i = 0; i < this._steps.length; i++) {
+      const step = this._steps[i];
+      const anomaly = this._anomalies.find(a => a.stepIdx === i);
+
+      // Format: name.label [shape] min=X max=Y
+      const shapeStr = `[${step.output.shape.join(',')}]`;
+      const statsStr = `min=${step.output.stats.min.toFixed(2)} max=${step.output.stats.max.toFixed(2)}`;
+      const labelPadded = step.label.padEnd(20).slice(0, 20);
+      const shapePadded = shapeStr.padEnd(15).slice(0, 15);
+
+      let line = `| ${labelPadded} ${shapePadded} ${statsStr}`;
+
+      // Add anomaly marker
+      if (anomaly) {
+        const marker = anomaly.severity === 'critical' ? '[!]' : '[*]';
+        line += ` ${marker} ${anomaly.type.toUpperCase()}`;
+      }
+
+      // Pad to box width
+      line = line.padEnd(66) + '|';
+      lines.push(line);
+    }
+
+    lines.push('+-----------------------------------------------------------------+');
+
+    // Anomaly summary
+    if (this._anomalies.length > 0) {
+      lines.push('');
+      const firstAnomaly = this._anomalies[0];
+      const marker = firstAnomaly.severity === 'critical' ? '[CRITICAL]' : '[WARNING]';
+      lines.push(`${marker} ANOMALY DETECTED at ${firstAnomaly.step.label}`);
+      lines.push(`   ${firstAnomaly.message}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  
+  toJSON() {
+    return JSON.stringify({
+      steps: this._steps,
+      anomalies: this._anomalies,
+      options: this._options,
+    }, null, 2);
+  }
+
+  
+  dumpLastNSteps(n = 5) {
+    const steps = this.getLastNSteps(n);
+    log.info('Trace', `Last ${steps.length} steps:`);
+    for (const step of steps) {
+      trace.kernels(`  ${step.label}:`);
+      trace.kernels(`    name: ${step.name}, variant: ${step.variant ?? 'default'}`);
+      trace.kernels(`    output: ${JSON.stringify(step.output.shape)}, maxAbs=${step.output.stats.maxAbs.toFixed(4)}`);
+      trace.kernels(`    sample: [${step.output.sample.slice(0, 8).map(v => v.toFixed(4)).join(', ')}]`);
+      if (step.output.hasNaN) log.warn('Trace', `    [!] HAS NaN`);
+      if (step.output.hasInf) log.warn('Trace', `    [!] HAS Inf`);
+    }
+  }
+}
+
+// ============================================================================
+// Global Singleton
+// ============================================================================
+
+
+export const kernelTrace = new KernelTrace();
+
+// ============================================================================
+// Convenience: Record Step Helper
+// ============================================================================
+
+
+export async function traceStep(name, label, layer, outputBuffer, outputShape, options) {
+  if (!kernelTrace.enabled) return;
+  if (layer >= 0 && !kernelTrace.shouldTraceLayer(layer)) return;
+
+  const output = await snapshotTensor(outputBuffer, outputShape);
+
+  // Snapshot inputs if provided (expensive - only do if tracing)
+  
+  const inputs = [];
+  if (options?.inputs && options?.inputShapes) {
+    for (let i = 0; i < options.inputs.length; i++) {
+      const snap = await snapshotTensor(options.inputs[i], options.inputShapes[i]);
+      inputs.push(snap);
+    }
+  }
+
+  kernelTrace.recordStep({
+    name,
+    label,
+    layer,
+    inputs,
+    output,
+    variant: options?.variant,
+    timeMs: options?.timeMs,
+  });
+}
+
+
+export function traceStepSync(name, label, layer, outputData, outputShape, options) {
+  if (!kernelTrace.enabled) return;
+  if (layer >= 0 && !kernelTrace.shouldTraceLayer(layer)) return;
+
+  const output = snapshotFromArray(outputData, outputShape);
+
+  kernelTrace.recordStep({
+    name,
+    label,
+    layer,
+    inputs: [],
+    output,
+    variant: options?.variant,
+    timeMs: options?.timeMs,
+  });
+}

package/src/inference/pipelines/text/layer-plan.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Layer pipeline plan compiler.
+ *
+ * Converts JSON-configured step lists into normalized, validated plans
+ * for execution inside processLayer.
+ *
+ * @module inference/pipelines/text/layer-plan
+ */
+
+import type {
+  LayerPipelineSchema,
+  LayerPipelineOp,
+  LayerPipelinePhase,
+  LayerPipelineNormWeight,
+  LayerPipelineDtype,
+  ProbeStage,
+} from '../../../config/schema/index.js';
+
+export interface CompiledLayerPipelineStep {
+  op: LayerPipelineOp;
+  phase: LayerPipelinePhase;
+  src: string;
+  dst: string;
+  name?: string;
+  weight?: LayerPipelineNormWeight;
+  residual?: string | null;
+  a?: string;
+  b?: string;
+  variant?: 'auto' | 'dense' | 'moe';
+  skipInputNorm?: boolean;
+  fromDtype?: LayerPipelineDtype | null;
+  toDtype?: LayerPipelineDtype;
+  inputDtype?: LayerPipelineDtype;
+  outputDtype?: LayerPipelineDtype;
+  probeStage?: ProbeStage;
+}
+
+export interface LayerPipelineOverride {
+  layers: number[];
+  steps: CompiledLayerPipelineStep[];
+}
+
+export interface CompiledLayerPipeline {
+  steps: CompiledLayerPipelineStep[];
+  overrides: LayerPipelineOverride[];
+  source: 'model' | 'runtime';
+}
+
+export function compileLayerPipeline(
+  plan: LayerPipelineSchema,
+  numLayers: number
+): Omit<CompiledLayerPipeline, 'source'>;
+
+export function resolveLayerPipeline(
+  modelPlan: LayerPipelineSchema | null | undefined,
+  runtimePlan: LayerPipelineSchema | null | undefined,
+  numLayers: number
+): CompiledLayerPipeline | null;
+
+export function getLayerPlanSteps(plan: CompiledLayerPipeline, layerIdx: number): CompiledLayerPipelineStep[];
+
+export function filterLayerPlanStepsByPhase(
+  steps: CompiledLayerPipelineStep[],
+  isPrefill: boolean
+): CompiledLayerPipelineStep[];