@simulatte/doppler 0.1.5 → 0.1.7

package/src/formats/gguf/types.js

@@ -94,6 +94,8 @@ export const GGML_TYPE_SIZE = {
 const GGUF_MAGIC = 0x46554747;
 const GGUF_VERSION_MIN = 2;
 const GGUF_VERSION_MAX = 3;
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
 
 const {
   contextLength: DEFAULT_GGUF_CONTEXT_LENGTH,
@@ -102,6 +104,13 @@ const {
   ropeFreqBase: DEFAULT_ROPE_FREQ_BASE,
 } = DEFAULT_GGUF_PARSER_DEFAULTS;
 
+function toSafeInteger(value, label) {
+  if (value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
+    throw new Error(`GGUF ${label} exceeds JavaScript safe integer range: ${value.toString()}`);
+  }
+  return Number(value);
+}
+
 class GGUFReader {
   constructor(buffer) {
     this.view = new DataView(buffer);
@@ -144,18 +153,26 @@ class GGUFReader {
     return value;
   }
 
-  readUint64() {
-    const low = this.view.getUint32(this.offset, true);
-    const high = this.view.getUint32(this.offset + 4, true);
+  readUint64BigInt() {
+    const low = BigInt(this.view.getUint32(this.offset, true));
+    const high = BigInt(this.view.getUint32(this.offset + 4, true));
     this.offset += 8;
-    return high * 0x100000000 + low;
+    return (high << 32n) | low;
   }
 
-  readInt64() {
-    const low = this.view.getUint32(this.offset, true);
-    const high = this.view.getInt32(this.offset + 4, true);
+  readUint64(label = 'u64 value') {
+    return toSafeInteger(this.readUint64BigInt(), label);
+  }
+
+  readInt64BigInt() {
+    const low = BigInt(this.view.getUint32(this.offset, true));
+    const high = BigInt(this.view.getInt32(this.offset + 4, true));
     this.offset += 8;
-    return high * 0x100000000 + low;
+    return (high << 32n) | low;
+  }
+
+  readInt64(label = 'i64 value') {
+    return toSafeInteger(this.readInt64BigInt(), label);
   }
 
   readFloat32() {
@@ -175,7 +192,7 @@ class GGUFReader {
   }
 
   readString() {
-    const length = this.readUint64();
+    const length = this.readUint64('string length');
     const bytes = new Uint8Array(this.view.buffer, this.offset, length);
     this.offset += length;
     return new TextDecoder().decode(bytes);
@@ -196,9 +213,9 @@ class GGUFReader {
       case GGUFValueType.INT32:
         return this.readInt32();
       case GGUFValueType.UINT64:
-        return this.readUint64();
+        return this.readUint64('metadata uint64');
       case GGUFValueType.INT64:
-        return this.readInt64();
+        return this.readInt64('metadata int64');
       case GGUFValueType.FLOAT32:
         return this.readFloat32();
       case GGUFValueType.FLOAT64:
@@ -216,7 +233,7 @@ class GGUFReader {
 
   readArray() {
     const elementType = this.readUint32();
-    const length = this.readUint64();
+    const length = this.readUint64('array length');
     if (length > 10000000) {
       throw new Error(`Array too long: ${length}`);
     }
@@ -331,8 +348,8 @@ export function parseGGUF(buffer) {
     throw new Error(`Unsupported GGUF version: ${version}`);
   }
 
-  const tensorCount = reader.readUint64();
-  const metadataKVCount = reader.readUint64();
+  const tensorCount = reader.readUint64('tensor count');
+  const metadataKVCount = reader.readUint64('metadata count');
 
   const metadata = {};
   for (let i = 0; i < metadataKVCount; i++) {
@@ -351,10 +368,10 @@ export function parseGGUF(buffer) {
     const nDims = reader.readUint32();
     const shape = [];
     for (let d = 0; d < nDims; d++) {
-      shape.push(reader.readUint64());
+      shape.push(reader.readUint64(`tensor "${name}" shape[${d}]`));
     }
     const type = reader.readUint32();
-    const offset = reader.readUint64();
+    const offset = reader.readUint64(`tensor "${name}" offset`);
 
     tensors.push({
       name,

package/src/formats/rdrr/groups.d.ts

@@ -6,7 +6,7 @@
  * @module formats/rdrr/groups
  */
 
-import type { ComponentGroup } from './types.js';
+import type { ComponentGroup, RDRRManifest } from './types.js';
 
 export declare function getGroup(groupId: string): ComponentGroup | null;
 
@@ -16,11 +16,19 @@ export declare function getShardsForGroup(groupId: string): number[];
 
 export declare function getTensorsForGroup(groupId: string): string[];
 
-export declare function getShardsForExpert(layerIdx: number, expertIdx: number): number[];
+export declare function getShardsForExpert(
+  layerIdx: number,
+  expertIdx: number,
+  manifest?: RDRRManifest | null
+): number[];
 
-export declare function getTensorsForExpert(layerIdx: number, expertIdx: number): string[];
+export declare function getTensorsForExpert(
+  layerIdx: number,
+  expertIdx: number,
+  manifest?: RDRRManifest | null
+): string[];
 
-export declare function getExpertBytes(): number;
+export declare function getExpertBytes(manifest?: RDRRManifest | null): number;
 
 export declare function getLayerGroupIds(): string[];
 

package/src/formats/rdrr/groups.js

@@ -19,8 +19,7 @@ export function getTensorsForGroup(groupId) {
   return getManifest()?.groups?.[groupId]?.tensors ?? [];
 }
 
-export function getShardsForExpert(layerIdx, expertIdx) {
-  const manifest = getManifest();
+export function getShardsForExpert(layerIdx, expertIdx, manifest = getManifest()) {
   const groupId = `layer.${layerIdx}.expert.${expertIdx}`;
   const group = manifest?.groups?.[groupId];
   if (group) {
@@ -29,8 +28,7 @@ export function getShardsForExpert(layerIdx, expertIdx) {
   throw new Error(`Missing expert group mapping: ${groupId}`);
 }
 
-export function getTensorsForExpert(layerIdx, expertIdx) {
-  const manifest = getManifest();
+export function getTensorsForExpert(layerIdx, expertIdx, manifest = getManifest()) {
   const groupId = `layer.${layerIdx}.expert.${expertIdx}`;
   const group = manifest?.groups?.[groupId];
   if (group) {
@@ -39,8 +37,7 @@ export function getTensorsForExpert(layerIdx, expertIdx) {
   throw new Error(`Missing expert group mapping: ${groupId}`);
 }
 
-export function getExpertBytes() {
-  const manifest = getManifest();
+export function getExpertBytes(manifest = getManifest()) {
   const expertGroups = Object.entries(manifest?.groups || {})
     .filter(([id]) => id.includes('.expert.'));
 

package/src/formats/rdrr/parsing.js

@@ -44,9 +44,13 @@ export function parseManifest(jsonString) {
 export function parseTensorMap(jsonString) {
   try {
     const tensorMap = JSON.parse(jsonString);
+    const normalizedTensorMap = {};
 
     for (const [name, loc] of Object.entries(tensorMap)) {
-      if (typeof loc.shard !== 'number') {
+      const shardIndex = typeof loc.shardIndex === 'number'
+        ? loc.shardIndex
+        : loc.shard;
+      if (typeof shardIndex !== 'number') {
         throw new Error(`Tensor '${name}' missing shard index`);
       }
       if (typeof loc.offset !== 'number') {
@@ -61,9 +65,42 @@ export function parseTensorMap(jsonString) {
       if (typeof loc.role !== 'string') {
         throw new Error(`Tensor '${name}' missing role`);
       }
+
+      let spans = undefined;
+      if (loc.spans !== undefined) {
+        if (!Array.isArray(loc.spans)) {
+          throw new Error(`Tensor '${name}' has invalid spans array`);
+        }
+        spans = loc.spans.map((span, spanIndex) => {
+          const spanShardIndex = typeof span?.shardIndex === 'number'
+            ? span.shardIndex
+            : span?.shard;
+          if (typeof spanShardIndex !== 'number') {
+            throw new Error(`Tensor '${name}' span[${spanIndex}] missing shard index`);
+          }
+          if (typeof span?.offset !== 'number') {
+            throw new Error(`Tensor '${name}' span[${spanIndex}] missing offset`);
+          }
+          if (typeof span?.size !== 'number') {
+            throw new Error(`Tensor '${name}' span[${spanIndex}] missing size`);
+          }
+          return {
+            shardIndex: spanShardIndex,
+            offset: span.offset,
+            size: span.size,
+          };
+        });
+      }
+
+      normalizedTensorMap[name] = {
+        ...loc,
+        shard: shardIndex,
+        shardIndex,
+        spans,
+      };
     }
 
-    return tensorMap;
+    return normalizedTensorMap;
   } catch (e) {
     if (e instanceof Error && e.message.includes('Tensor')) {
       throw e;

package/src/formats/rdrr/types.d.ts

@@ -75,13 +75,14 @@ export interface ComponentGroup extends ComponentGroupSchema {}
 
 export interface TensorLocation {
   shard: number;
+  shardIndex?: number;
   offset: number;
   size: number;
   shape: number[];
   dtype: string;
   role: TensorRole;
   group?: string;
-  spans?: Array<{ shardIndex: number; offset: number; size: number }>;
+  spans?: Array<{ shard?: number; shardIndex?: number; offset: number; size: number }>;
   layout?: WeightLayout;
   originalShape?: number[];
 }

package/src/gpu/command-recorder.js

@@ -3,7 +3,7 @@
 import { getDevice, hasFeature, FEATURES } from './device.js';
 import { allowReadback, trackAllocation } from './perf-guards.js';
 import { getUniformCache } from './uniform-cache.js';
-import { isBufferActive, releaseBuffer } from '../memory/buffer-pool.js';
+import { isBufferActive, releaseBuffer, discardBuffer } from '../memory/buffer-pool.js';
 import { log } from '../debug/index.js';
 import { getRuntimeConfig } from '../config/runtime.js';
 
@@ -93,6 +93,9 @@ export class CommandRecorder {
 
   
   #initProfiling() {
+    let querySet = null;
+    let queryBuffer = null;
+    let readbackBuffer = null;
     try {
       const runtimeProfiler = getRuntimeConfig().shared?.debug?.profiler;
       if (!runtimeProfiler) {
@@ -119,25 +122,31 @@ export class CommandRecorder {
         didLogQueryFallback = true;
       }
 
-      this.#querySet = this.device.createQuerySet({
+      querySet = this.device.createQuerySet({
         type: 'timestamp',
         count: this.#queryCapacity,
       });
 
       // Buffer to hold query results (8 bytes per timestamp = BigUint64)
-      this.#queryBuffer = this.device.createBuffer({
+      queryBuffer = this.device.createBuffer({
         label: `${this.label}_query_buffer`,
         size: this.#queryCapacity * 8,
         usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
       });
 
       // Readback buffer
-      this.#readbackBuffer = this.device.createBuffer({
+      readbackBuffer = this.device.createBuffer({
         label: `${this.label}_readback_buffer`,
         size: this.#queryCapacity * 8,
         usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
       });
+      this.#querySet = querySet;
+      this.#queryBuffer = queryBuffer;
+      this.#readbackBuffer = readbackBuffer;
     } catch (e) {
+      readbackBuffer?.destroy();
+      queryBuffer?.destroy();
+      querySet?.destroy();
       log.warn('CommandRecorder', `Failed to initialize profiling: ${e}`);
       this.#profilingEnabled = false;
     }
@@ -277,39 +286,57 @@ export class CommandRecorder {
     }
   }
 
+  #finalizeTrackedBuffers(buffersToDestroy, buffersToRelease, discardPooled) {
+    for (const buffer of buffersToDestroy) {
+      buffer.destroy();
+    }
+    for (const buffer of buffersToRelease) {
+      if (discardPooled) {
+        discardBuffer(buffer);
+      } else {
+        releaseBuffer(buffer);
+      }
+    }
+    getUniformCache().flushPendingDestruction();
+  }
+
+  #takeTrackedBuffers() {
+    const buffersToDestroy = this.#tempBuffers;
+    const buffersToRelease = this.#pooledBuffers;
+    this.#tempBuffers = [];
+    this.#pooledBuffers = [];
+    this.#tempBufferSet.clear();
+    this.#pooledBufferSet.clear();
+    return { buffersToDestroy, buffersToRelease };
+  }
+
   
   submit() {
     if (this.#submitted) {
       throw new Error('[CommandRecorder] Already submitted');
     }
 
-    // Submit commands
     const submitStart = performance.now();
-    this.device.queue.submit([this.#encoder.finish()]);
+    const { buffersToDestroy, buffersToRelease } = this.#takeTrackedBuffers();
+    try {
+      this.device.queue.submit([this.#encoder.finish()]);
+    } catch (error) {
+      this.#submitted = true;
+      this.#submitStartMs = submitStart;
+      this.#finalizeTrackedBuffers(buffersToDestroy, buffersToRelease, false);
+      this.#destroyProfilingResources();
+      throw error;
+    }
+
     this.#submitted = true;
     this.#submitStartMs = submitStart;
 
-    const buffersToDestroy = this.#tempBuffers;
-    const buffersToRelease = this.#pooledBuffers;
-    this.#tempBuffers = [];
-    this.#pooledBuffers = [];
-    this.#tempBufferSet.clear();
-    this.#pooledBufferSet.clear();
-
     this.#cleanupPromise = this.device.queue.onSubmittedWorkDone().then(() => {
       this.#submitLatencyMs = performance.now() - submitStart;
-      // Destroy buffers created directly by the recorder
-      for (const buffer of buffersToDestroy) {
-        buffer.destroy();
-      }
-      // Release pooled buffers back to the pool
-      for (const buffer of buffersToRelease) {
-        releaseBuffer(buffer);
-      }
-      // Safe to destroy evicted uniform buffers now that GPU work is complete
-      getUniformCache().flushPendingDestruction();
+      this.#finalizeTrackedBuffers(buffersToDestroy, buffersToRelease, false);
     }).catch((err) => {
       log.warn('CommandRecorder', `Deferred cleanup failed: ${ (err).message}`);
+      this.#finalizeTrackedBuffers(buffersToDestroy, buffersToRelease, true);
     });
   }
 
@@ -370,55 +397,53 @@ export class CommandRecorder {
     }
 
     if (this.#profileEntries.length === 0) {
+      this.#destroyProfilingResources();
       return {};
     }
 
-    // Wait for GPU work to complete
-    await this.device.queue.onSubmittedWorkDone();
+    let mapped = false;
 
-    // Resolve queries to buffer
-    const maxIndex = Math.max(...this.#profileEntries.map(e => e.endQueryIndex)) + 1;
-    const resolveEncoder = this.device.createCommandEncoder({ label: 'profile_resolve' });
-    resolveEncoder.resolveQuerySet(this.#querySet, 0, maxIndex, this.#queryBuffer, 0);
-    resolveEncoder.copyBufferToBuffer(this.#queryBuffer, 0, this.#readbackBuffer, 0, maxIndex * 8);
-    this.device.queue.submit([resolveEncoder.finish()]);
-
-    if (!allowReadback('CommandRecorder.resolveProfileTimings')) {
-      return null;
-    }
-
-    // Read back timestamps
-    await this.#readbackBuffer.mapAsync(GPUMapMode.READ);
-    const timestamps = new BigUint64Array(this.#readbackBuffer.getMappedRange());
+    try {
+      await this.device.queue.onSubmittedWorkDone();
 
-    // Aggregate timings by label
-    
-    const timings = {};
+      const maxIndex = Math.max(...this.#profileEntries.map(e => e.endQueryIndex)) + 1;
+      const resolveEncoder = this.device.createCommandEncoder({ label: 'profile_resolve' });
+      resolveEncoder.resolveQuerySet(this.#querySet, 0, maxIndex, this.#queryBuffer, 0);
+      resolveEncoder.copyBufferToBuffer(this.#queryBuffer, 0, this.#readbackBuffer, 0, maxIndex * 8);
+      this.device.queue.submit([resolveEncoder.finish()]);
 
-    for (const entry of this.#profileEntries) {
-      const startNs = timestamps[entry.startQueryIndex];
-      const endNs = timestamps[entry.endQueryIndex];
-      const durationMs = Number(endNs - startNs) / 1_000_000;
+      if (!allowReadback('CommandRecorder.resolveProfileTimings')) {
+        return null;
+      }
 
-      // Skip invalid timings
-      if (durationMs < 0 || durationMs > 60000) {
-        continue;
+      await this.#readbackBuffer.mapAsync(GPUMapMode.READ);
+      mapped = true;
+      const timestamps = new BigUint64Array(this.#readbackBuffer.getMappedRange());
+      const timings = {};
+
+      for (const entry of this.#profileEntries) {
+        const startNs = timestamps[entry.startQueryIndex];
+        const endNs = timestamps[entry.endQueryIndex];
+        const durationMs = Number(endNs - startNs) / 1_000_000;
+
+        if (durationMs < 0 || durationMs > 60000) {
+          continue;
+        }
+
+        if (timings[entry.label] !== undefined) {
+          timings[entry.label] += durationMs;
+        } else {
+          timings[entry.label] = durationMs;
+        }
       }
 
-      // Aggregate by label
-      if (timings[entry.label] !== undefined) {
-        timings[entry.label] += durationMs;
-      } else {
-        timings[entry.label] = durationMs;
+      return timings;
+    } finally {
+      if (mapped && this.#readbackBuffer) {
+        this.#readbackBuffer.unmap();
       }
+      this.#destroyProfilingResources();
     }
-
-    this.#readbackBuffer.unmap();
-
-    // Clean up profiling resources after use
-    this.#destroyProfilingResources();
-
-    return timings;
   }
 
   

package/src/gpu/device.d.ts

@@ -82,6 +82,7 @@ export function initDevice(): Promise<GPUDevice>;
 
 /**
  * Register an externally created GPU device for pipeline use.
+ * The active device epoch advances and loss handling is attached to the device.
  */
 export function setDevice(
   device: GPUDevice | null,

package/src/gpu/device.js

@@ -28,6 +28,126 @@ function advanceDeviceEpoch() {
   deviceEpoch += 1;
 }
 
+function clearActiveDeviceState() {
+  gpuDevice = null;
+  kernelCapabilities = null;
+  resolvedPlatformConfig = null;
+  platformInitialized = false;
+}
+
+function isValidGPUBuffer(value) {
+  if (!value) {
+    return false;
+  }
+  if (value.__dopplerFakeGPUBuffer === true) {
+    return true;
+  }
+  if (
+    typeof value === 'object'
+    && value.constructor?.name === 'FakeBuffer'
+    && typeof value.size === 'number'
+    && typeof value.usage === 'number'
+    && typeof value.destroy === 'function'
+  ) {
+    return true;
+  }
+  if (typeof GPUBuffer === 'undefined') {
+    return true;
+  }
+  return value instanceof GPUBuffer;
+}
+
+function isUsableGPUDevice(device) {
+  return !!(
+    device
+    && typeof device.createBuffer === 'function'
+    && typeof device.createBindGroup === 'function'
+    && typeof device.createCommandEncoder === 'function'
+    && typeof device.createShaderModule === 'function'
+    && device.queue
+    && typeof device.queue.submit === 'function'
+  );
+}
+
+function describeBindGroupBufferValue(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof GPUBuffer !== 'undefined' && value instanceof GPUBuffer) return 'GPUBuffer';
+  if (typeof value === 'object') {
+    return value.constructor?.name || 'object';
+  }
+  return typeof value;
+}
+
+function validateBindGroupDescriptor(descriptor) {
+  const label = descriptor?.label || 'unlabeled_bind_group';
+  const entries = Array.isArray(descriptor?.entries) ? descriptor.entries : [];
+  for (const entry of entries) {
+    const resource = entry?.resource;
+    if (!resource || typeof resource !== 'object' || !('buffer' in resource)) {
+      continue;
+    }
+    if (isValidGPUBuffer(resource.buffer)) {
+      continue;
+    }
+    throw new Error(
+      `[${label}] binding ${entry.binding} requires a GPUBuffer; ` +
+      `got ${describeBindGroupBufferValue(resource.buffer)}.`
+    );
+  }
+}
+
+function wrapDeviceCreateBindGroup(device) {
+  if (!device || device.__dopplerBindGroupValidationWrapped) {
+    return device;
+  }
+  const originalCreateBindGroup = device.createBindGroup.bind(device);
+  device.createBindGroup = (descriptor) => {
+    validateBindGroupDescriptor(descriptor);
+    return originalCreateBindGroup(descriptor);
+  };
+  Object.defineProperty(device, '__dopplerBindGroupValidationWrapped', {
+    value: true,
+    configurable: true,
+    enumerable: false,
+    writable: false,
+  });
+  return device;
+}
+
+function registerDeviceLostHandler(device) {
+  if (!device || device.__dopplerLossHandlerRegistered) {
+    return device;
+  }
+
+  if (device.lost && typeof device.lost.then === 'function') {
+    const trackedDevice = device;
+    device.lost.then((info) => {
+      if (gpuDevice !== trackedDevice) {
+        return;
+      }
+      log.error('GPU', 'Device lost: ' + info.message + ', Reason: ' + info.reason);
+      clearActiveDeviceState();
+      advanceDeviceEpoch();
+    }).catch((error) => {
+      if (gpuDevice !== trackedDevice) {
+        return;
+      }
+      log.warn('GPU', 'Device lost handler failed: ' + (error?.message ?? error));
+      clearActiveDeviceState();
+      advanceDeviceEpoch();
+    });
+  }
+
+  Object.defineProperty(device, '__dopplerLossHandlerRegistered', {
+    value: true,
+    configurable: true,
+    enumerable: false,
+    writable: false,
+  });
+  return device;
+}
+
 
 export const FEATURES =  ({
   SHADER_F16: 'shader-f16',
@@ -163,7 +283,11 @@ async function initializePlatformAndRegistry(adapter) {
 export async function initDevice() {
   // Return cached device if available
   if (gpuDevice) {
-    return gpuDevice;
+    if (isUsableGPUDevice(gpuDevice)) {
+      return gpuDevice;
+    }
+    clearActiveDeviceState();
+    advanceDeviceEpoch();
   }
 
   if (!isWebGPUAvailable()) {
@@ -201,18 +325,10 @@ export async function initDevice() {
   if (!gpuDevice) {
     throw createDopplerError(ERROR_CODES.GPU_DEVICE_FAILED, 'Failed to create WebGPU device');
   }
+  wrapDeviceCreateBindGroup(gpuDevice);
+  registerDeviceLostHandler(gpuDevice);
   advanceDeviceEpoch();
 
-  // Set up device lost handler
-  gpuDevice.lost.then((info) => {
-    log.error('GPU', 'Device lost: ' + info.message + ', Reason: ' + info.reason);
-    gpuDevice = null;
-    kernelCapabilities = null;
-    resolvedPlatformConfig = null;
-    platformInitialized = false;
-    advanceDeviceEpoch();
-  });
-
   // Wrap queue for submit tracking (when enabled)
   wrapQueueForTracking(gpuDevice.queue);
 
@@ -244,15 +360,14 @@ export async function initDevice() {
 
 export function setDevice(device, options = {}) {
   if (!device) {
-    gpuDevice = null;
-    kernelCapabilities = null;
-    resolvedPlatformConfig = null;
-    platformInitialized = false;
+    clearActiveDeviceState();
     advanceDeviceEpoch();
     return;
   }
 
   gpuDevice = device;
+  wrapDeviceCreateBindGroup(gpuDevice);
+  registerDeviceLostHandler(gpuDevice);
   advanceDeviceEpoch();
   wrapQueueForTracking(gpuDevice.queue);
 
@@ -314,10 +429,7 @@ export function isPlatformInitialized() {
 export function destroyDevice() {
   if (gpuDevice) {
     gpuDevice.destroy();
-    gpuDevice = null;
-    kernelCapabilities = null;
-    resolvedPlatformConfig = null;
-    platformInitialized = false;
+    clearActiveDeviceState();
     advanceDeviceEpoch();
   }
 }