@simulatte/doppler 0.1.8 → 0.2.0

package/src/gpu/readback-utils.d.ts

@@ -1,16 +0,0 @@
-export interface ReadbackBufferEntry {
-  buffer: GPUBuffer;
-  destroy?: boolean;
-  offset?: number;
-  size?: number;
-}
-
-export function withMappedReadBuffer<T>(
-  buffer: GPUBuffer,
-  read: (range: ArrayBuffer) => T | Promise<T>,
-): Promise<T>;
-
-export function withMappedReadBuffers<T>(
-  entries: ReadonlyArray<ReadbackBufferEntry>,
-  read: (ranges: Array<ArrayBuffer>) => T | Promise<T>,
-): Promise<T>;

package/src/gpu/readback-utils.js

@@ -1,41 +0,0 @@
-export async function withMappedReadBuffer(buffer, read) {
-  let mapped = false;
-  try {
-    await buffer.mapAsync(GPUMapMode.READ);
-    mapped = true;
-    return await read(buffer.getMappedRange());
-  } finally {
-    if (mapped) {
-      buffer.unmap();
-    }
-  }
-}
-
-export async function withMappedReadBuffers(entries, read) {
-  const mappedEntries = [];
-  try {
-    await Promise.all(entries.map(async (entry) => {
-      await entry.buffer.mapAsync(GPUMapMode.READ);
-      mappedEntries.push(entry);
-    }));
-    const ranges = entries.map((entry) => {
-      if (entry.offset != null || entry.size != null) {
-        return entry.buffer.getMappedRange(
-          entry.offset ?? 0,
-          entry.size ?? (entry.buffer.size - (entry.offset ?? 0))
-        );
-      }
-      return entry.buffer.getMappedRange();
-    });
-    return await read(ranges);
-  } finally {
-    for (let index = mappedEntries.length - 1; index >= 0; index -= 1) {
-      mappedEntries[index].buffer.unmap();
-    }
-    for (const entry of entries) {
-      if (entry.destroy === true) {
-        entry.buffer.destroy();
-      }
-    }
-  }
-}

package/src/gpu/submit-tracker.d.ts

@@ -1,111 +0,0 @@
-/**
- * Submit Tracker - Measures GPU submit overhead for optimization benchmarking.
- *
- * @module gpu/submit-tracker
- */
-
-/** Whether to track submits (disable in production for perf) */
-export let TRACK_SUBMITS: boolean;
-
-/** Submit statistics */
-export interface SubmitStats {
-  /** Number of queue.submit() calls */
-  count: number;
-  /** Total time spent in submit calls (ms) */
-  totalMs: number;
-  /** Average time per submit (ms) */
-  avgMs: number;
-  /** Max time for a single submit (ms) */
-  maxMs: number;
-  /** Min time for a single submit (ms) */
-  minMs: number;
-  /** Submit timestamps for detailed analysis */
-  timestamps: number[];
-  /** Submit counts by source */
-  bySource?: Map<string, number>;
-}
-
-/** Phase-based submit statistics */
-export interface PhaseSubmitStats {
-  prefill: SubmitStats;
-  decode: SubmitStats;
-  other: SubmitStats;
-}
-
-/** Current phase for submit tracking */
-export type SubmitPhase = 'prefill' | 'decode' | 'other';
-
-/**
- * Enable/disable submit tracking.
- * @param enabled - Whether to track submits
- */
-export function setTrackSubmits(enabled: boolean): void;
-
-/**
- * Reset submit statistics.
- * Call before starting a new measurement.
- */
-export function resetSubmitStats(): void;
-
-/**
- * Set the current phase for submit tracking.
- * @param phase - The phase to track ('prefill', 'decode', or 'other')
- */
-export function setSubmitPhase(phase: SubmitPhase): void;
-
-/**
- * Record a submit call.
- * Call this from a wrapper around queue.submit().
- * @param durationMs - Time spent in this submit call
- * @param source - Optional source identifier (e.g., "pipeline.ts:prefill", "layer.ts:attention")
- */
-export function recordSubmit(durationMs: number, source?: string): void;
-
-/**
- * Get current submit statistics.
- * @returns Submit statistics
- */
-export function getSubmitStats(): SubmitStats;
-
-/**
- * Get submit statistics for a specific phase.
- * @param phase - The phase to get stats for
- * @returns Submit statistics for the phase
- */
-export function getPhaseSubmitStats(phase: SubmitPhase): SubmitStats;
-
-/**
- * Get submit statistics for all phases.
- * @returns Submit statistics by phase
- */
-export function getAllPhaseSubmitStats(): PhaseSubmitStats;
-
-/**
- * Log submit statistics summary.
- * @param label - Label for the log output
- */
-export function logSubmitStats(label?: string): void;
-
-/**
- * Log submit statistics for all phases.
- * @param label - Label for the log output
- */
-export function logAllPhaseSubmitStats(label?: string): void;
-
-/**
- * Wrap a GPU queue to track submit calls.
- * @param queue - GPU queue to wrap
- * @returns Wrapped queue with tracking
- */
-export function wrapQueueForTracking(queue: GPUQueue): GPUQueue;
-
-/**
- * Estimate submit overhead savings from batching.
- * @param currentStats - Current submit stats (unbatched)
- * @param targetSubmits - Target number of submits after batching
- * @returns Estimated time savings in ms
- */
-export function estimateBatchingSavings(
-  currentStats: SubmitStats,
-  targetSubmits?: number
-): { savedSubmits: number; estimatedSavingsMs: number };

package/src/gpu/submit-tracker.js

@@ -1,242 +0,0 @@
-
-
-import { trackSubmit } from './perf-guards.js';
-import { log, trace } from '../debug/index.js';
-
-
-export let TRACK_SUBMITS = false;
-
-
-let submitCount = 0;
-
-let submitTimes = [];
-let totalSubmitMs = 0;
-let maxSubmitMs = 0;
-let minSubmitMs = Infinity;
-
-let submitSources = new Map();
-
-
-
-
-let currentPhase = 'other';
-
-const WRAPPED_QUEUE_SENTINEL = Symbol.for('doppler.submitTrackerWrapped');
-
-
-const phaseStats = {
-  prefill: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-  decode: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-  other: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-};
-
-
-export function setTrackSubmits(enabled) {
-  TRACK_SUBMITS = enabled;
-  if (enabled) {
-    resetSubmitStats();
-    log.debug('SubmitTracker', 'Enabled');
-  } else {
-    log.debug('SubmitTracker', 'Disabled');
-  }
-}
-
-
-export function resetSubmitStats() {
-  submitCount = 0;
-  submitTimes = [];
-  totalSubmitMs = 0;
-  maxSubmitMs = 0;
-  minSubmitMs = Infinity;
-  submitSources = new Map();
-  currentPhase = 'other';
-
-  // Reset phase stats
-  for (const phase of  (['prefill', 'decode', 'other'])) {
-    phaseStats[phase] = { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() };
-  }
-}
-
-
-export function setSubmitPhase(phase) {
-  currentPhase = phase;
-}
-
-
-export function recordSubmit(durationMs, source) {
-  if (!TRACK_SUBMITS) return;
-
-  // Global stats
-  submitCount++;
-  submitTimes.push(durationMs);
-  totalSubmitMs += durationMs;
-  maxSubmitMs = Math.max(maxSubmitMs, durationMs);
-  minSubmitMs = Math.min(minSubmitMs, durationMs);
-
-  // Track by source
-  if (source) {
-    submitSources.set(source, (submitSources.get(source) || 0) + 1);
-  }
-
-  // Phase-specific stats
-  const ps = phaseStats[currentPhase];
-  ps.count++;
-  ps.times.push(durationMs);
-  ps.totalMs += durationMs;
-  ps.maxMs = Math.max(ps.maxMs, durationMs);
-  ps.minMs = Math.min(ps.minMs, durationMs);
-
-  // Track source in phase stats
-  if (source) {
-    ps.sources.set(source, (ps.sources.get(source) || 0) + 1);
-  }
-}
-
-
-export function getSubmitStats() {
-  return {
-    count: submitCount,
-    totalMs: totalSubmitMs,
-    avgMs: submitCount > 0 ? totalSubmitMs / submitCount : 0,
-    maxMs: maxSubmitMs,
-    minMs: minSubmitMs === Infinity ? 0 : minSubmitMs,
-    timestamps: [...submitTimes],
-    bySource: new Map(submitSources),
-  };
-}
-
-
-export function getPhaseSubmitStats(phase) {
-  const ps = phaseStats[phase];
-  return {
-    count: ps.count,
-    totalMs: ps.totalMs,
-    avgMs: ps.count > 0 ? ps.totalMs / ps.count : 0,
-    maxMs: ps.maxMs,
-    minMs: ps.minMs === Infinity ? 0 : ps.minMs,
-    timestamps: [...ps.times],
-    bySource: new Map(ps.sources),
-  };
-}
-
-
-export function getAllPhaseSubmitStats() {
-  return {
-    prefill: getPhaseSubmitStats('prefill'),
-    decode: getPhaseSubmitStats('decode'),
-    other: getPhaseSubmitStats('other'),
-  };
-}
-
-
-export function logSubmitStats(label = 'Forward pass') {
-  const stats = getSubmitStats();
-  trace.perf(
-    `SubmitTracker ${label}: ${stats.count} submits, ` +
-    `total=${stats.totalMs.toFixed(2)}ms, ` +
-    `avg=${stats.avgMs.toFixed(3)}ms, ` +
-    `range=[${stats.minMs.toFixed(3)}-${stats.maxMs.toFixed(3)}ms]`
-  );
-
-  // Log by source if available
-  if (stats.bySource && stats.bySource.size > 0) {
-    trace.perf('SubmitTracker: Submits by source:');
-    const sorted = Array.from(stats.bySource.entries()).sort((a, b) => b[1] - a[1]);
-    for (const [source, count] of sorted) {
-      const pct = ((count / stats.count) * 100).toFixed(1);
-      trace.perf(`  ${source}: ${count} (${pct}%)`);
-    }
-  }
-}
-
-
-export function logAllPhaseSubmitStats(label = 'All phases') {
-  const allStats = getAllPhaseSubmitStats();
-  trace.perf(`SubmitTracker ${label}:`);
-
-  for (const phase of  (['prefill', 'decode', 'other'])) {
-    const stats = allStats[phase];
-    if (stats.count === 0) continue;
-
-    trace.perf(
-      `  ${phase}: ${stats.count} submits, ` +
-      `total=${stats.totalMs.toFixed(2)}ms, ` +
-      `avg=${stats.avgMs.toFixed(3)}ms`
-    );
-
-    // Log by source for this phase
-    if (stats.bySource && stats.bySource.size > 0) {
-      const sorted = Array.from(stats.bySource.entries()).sort((a, b) => b[1] - a[1]);
-      for (const [source, count] of sorted) {
-        const pct = ((count / stats.count) * 100).toFixed(1);
-        trace.perf(`    ${source}: ${count} (${pct}%)`);
-      }
-    }
-  }
-}
-
-
-function extractSourceFromStack() {
-  const stack = new Error().stack;
-  if (!stack) return 'unknown';
-
-  const lines = stack.split('\n');
-  // Skip first 3 lines: Error, extractSourceFromStack, queue.submit wrapper
-  for (let i = 3; i < lines.length; i++) {
-    const line = lines[i];
-    // Match file:line pattern in stack trace
-    // Example: "at functionName (http://localhost:8080/path/to/file.ts:123:45)"
-    const match = line.match(/\/([^\/]+\.(?:js|ts)):(\d+):/);
-    if (match) {
-      return `${match[1]}:${match[2]}`;
-    }
-  }
-  return 'unknown';
-}
-
-
-export function wrapQueueForTracking(queue) {
-  if (!queue || queue[WRAPPED_QUEUE_SENTINEL] === true) {
-    return queue;
-  }
-
-  const originalSubmit = queue.submit.bind(queue);
-
-   (queue).submit = function( commandBuffers) {
-    const start = TRACK_SUBMITS ? performance.now() : 0;
-    const result = originalSubmit(commandBuffers);
-    trackSubmit();
-
-    if (!TRACK_SUBMITS) {
-      return result;
-    }
-
-    const duration = performance.now() - start;
-    recordSubmit(duration, extractSourceFromStack());
-    return result;
-  };
-
-  Object.defineProperty(queue, WRAPPED_QUEUE_SENTINEL, {
-    value: true,
-    configurable: true,
-    enumerable: false,
-    writable: false,
-  });
-
-  return queue;
-}
-
-
-export function estimateBatchingSavings(
-  currentStats,
-  targetSubmits = 1
-) {
-  const savedSubmits = Math.max(0, currentStats.count - targetSubmits);
-  // Each submit has overhead, estimate savings based on average submit time
-  const estimatedSavingsMs = savedSubmits * currentStats.avgMs;
-
-  return {
-    savedSubmits,
-    estimatedSavingsMs,
-  };
-}

package/src/gpu/tensor.d.ts

@@ -1,69 +0,0 @@
-/**
- * Tensor Abstraction
- *
- * Wraps GPUBuffer with explicit dtype and shape metadata.
- * Ensures dtype flows through the pipeline structurally rather than
- * being tracked in a separate WeakMap.
- */
-
-export type TensorDtype = 'f16' | 'f32';
-
-/**
- * A tensor with explicit dtype and shape.
- * Use this instead of raw GPUBuffer for dtype-sensitive operations.
- */
-export interface Tensor {
-  readonly buffer: GPUBuffer;
-  readonly dtype: TensorDtype;
-  readonly shape: readonly number[];
-  readonly label?: string;
-}
-
-/**
- * Create a tensor from a buffer with explicit dtype.
- */
-export function createTensor(
-  buffer: GPUBuffer,
-  dtype: TensorDtype,
-  shape: number[],
-  label?: string
-): Tensor;
-
-/**
- * Assert tensor has expected dtype, throw if mismatch.
- */
-export function assertDtype(
-  tensor: Tensor,
-  expected: TensorDtype,
-  operation: string
-): void;
-
-/**
- * Assert tensor has expected shape, throw if mismatch.
- */
-export function assertShape(
-  tensor: Tensor,
-  expected: readonly number[],
-  operation: string
-): void;
-
-/**
- * Get bytes per element for dtype.
- */
-export function dtypeBytes(dtype: TensorDtype): number;
-
-/**
- * Compute total byte size for a tensor.
- */
-export function tensorBytes(shape: readonly number[], dtype: TensorDtype): number;
-
-/**
- * Check if two tensors have compatible dtypes for an operation.
- */
-export function dtypesMatch(a: Tensor, b: Tensor): boolean;
-
-/**
- * Determine output dtype for a binary operation.
- * F16 only if both inputs are F16.
- */
-export function inferOutputDtype(a: Tensor, b: Tensor): TensorDtype;

package/src/gpu/tensor.js

@@ -1,75 +0,0 @@
-
-
-
-import { selectRuleValue } from '../rules/rule-registry.js';
-
-
-export function createTensor(
-  buffer,
-  dtype,
-  shape,
-  label
-) {
-  return {
-    buffer,
-    dtype,
-    shape: Object.freeze([...shape]),
-    label,
-  };
-}
-
-
-export function assertDtype(
-  tensor,
-  expected,
-  operation
-) {
-  if (tensor.dtype !== expected) {
-    throw new Error(
-      `${operation}: expected ${expected} tensor, got ${tensor.dtype}` +
-      (tensor.label ? ` (${tensor.label})` : '')
-    );
-  }
-}
-
-
-export function assertShape(
-  tensor,
-  expected,
-  operation
-) {
-  if (tensor.shape.length !== expected.length) {
-    throw new Error(
-      `${operation}: expected ${expected.length}D tensor, got ${tensor.shape.length}D` +
-      (tensor.label ? ` (${tensor.label})` : '')
-    );
-  }
-  for (let i = 0; i < expected.length; i++) {
-    if (expected[i] !== -1 && tensor.shape[i] !== expected[i]) {
-      throw new Error(
-        `${operation}: shape mismatch at dim ${i}: expected ${expected[i]}, got ${tensor.shape[i]}` +
-        (tensor.label ? ` (${tensor.label})` : '')
-      );
-    }
-  }
-}
-
-
-export function dtypeBytes(dtype) {
-  return dtype === 'f16' ? 2 : 4;
-}
-
-
-export function tensorBytes(shape, dtype) {
-  return shape.reduce((a, b) => a * b, 1) * dtypeBytes(dtype);
-}
-
-
-export function dtypesMatch(a, b) {
-  return a.dtype === b.dtype;
-}
-
-
-export function inferOutputDtype(a, b) {
-  return selectRuleValue('shared', 'dtype', 'bothF16', { aDtype: a.dtype, bDtype: b.dtype });
-}

package/src/gpu/uniform-cache.d.ts

@@ -1,109 +0,0 @@
-/**
- * Uniform Buffer Cache
- *
- * Caches small uniform buffers by content hash to avoid repeated allocations.
- * WebLLM-inspired optimization: uniform buffers with identical contents are reused
- * across kernel dispatches instead of being created fresh and destroyed each time.
- */
-
-interface UniformCacheEntry {
-  buffer: GPUBuffer;
-  bytes: Uint8Array;
-  lastUsed: number;
-  refCount: number;
-}
-
-interface UniformCacheStats {
-  hits: number;
-  misses: number;
-  evictions: number;
-  currentSize: number;
-}
-
-/**
- * Uniform Buffer Cache
- *
- * Provides content-addressed caching for uniform buffers. Buffers with
- * identical contents share the same GPU buffer, reducing allocation overhead.
- *
- * IMPORTANT: Evicted buffers are NOT destroyed immediately. They are queued
- * for deferred destruction to avoid use-after-destroy bugs when command
- * buffers reference cached uniforms that get evicted before submit.
- * Call flushPendingDestruction() after GPU work completes.
- */
-export declare class UniformBufferCache {
-  private cache: Map<string, UniformCacheEntry>;
-  private stats: UniformCacheStats;
-  private pendingDestruction: GPUBuffer[];
-  private readonly maxEntries: number;
-  private readonly maxAgeMs: number;
-
-  constructor(maxEntries?: number, maxAgeMs?: number);
-
-  /**
-   * Get or create a uniform buffer with the given contents.
-   * Returns a cached buffer if one exists with identical data.
-   */
-  getOrCreate(data: ArrayBuffer | SharedArrayBuffer, label: string): GPUBuffer;
-
-  /**
-   * Release a reference to a cached buffer.
-   * Buffer is NOT destroyed - it stays in cache for reuse.
-   * Call this instead of buffer.destroy() for cached uniforms.
-   */
-  release(buffer: GPUBuffer): void;
-
-  /**
-   * Evict stale entries (older than maxAgeMs).
-   * Buffers are queued for deferred destruction.
-   */
-  evictStale(): number;
-
-  /**
-   * Clear all cached buffers.
-   * Also flushes any pending destruction queue.
-   */
-  clear(): void;
-
-  /**
-   * Destroy all buffers in the pending destruction queue.
-   * Call this after GPU work completes (e.g., after onSubmittedWorkDone).
-   *
-   * This is critical for avoiding use-after-destroy bugs: when the uniform
-   * cache evicts a buffer that's still referenced by a pending command buffer,
-   * the buffer is queued here instead of being destroyed immediately.
-   */
-  flushPendingDestruction(): number;
-
-  /**
-   * Get the number of buffers pending destruction.
-   */
-  getPendingDestructionCount(): number;
-
-  /**
-   * Check if a buffer is managed by this cache
-   */
-  isCached(buffer: GPUBuffer): boolean;
-
-  /**
-   * Get cache statistics
-   */
-  getStats(): UniformCacheStats & { hitRate: string; pendingDestruction: number };
-}
-
-/**
- * Release or destroy a uniform buffer appropriately.
- * If the buffer is cached, releases it back to the cache.
- * If not cached, destroys it directly.
- */
-export function releaseUniformBuffer(buffer: GPUBuffer): void;
-
-/**
- * Get the global uniform buffer cache instance
- */
-export function getUniformCache(): UniformBufferCache;
-
-/**
- * Reset the global uniform cache (useful for testing or device loss)
- */
-export function resetUniformCache(): void;