@simulatte/doppler 0.1.6 → 0.1.8

package/src/loader/tensors/tensor-loader.js

@@ -16,6 +16,21 @@ import { selectRuleValue } from '../../rules/rule-registry.js';
 
 let loggedF32UpcastNonMatmul = false;
 
+function isGpuBufferInstance(value) {
+  return typeof GPUBuffer !== 'undefined' && value instanceof GPUBuffer;
+}
+
+function isReleasableBuffer(value) {
+  return typeof value === 'object' && value !== null && 'size' in value;
+}
+
+function releaseOwnedGpuBuffer(buffer, owned) {
+  if (!owned || !isReleasableBuffer(buffer)) {
+    return;
+  }
+  releaseBuffer(buffer);
+}
+
 function logF32UpcastNonMatmul(name, numElements, bufferSize) {
   if (loggedF32UpcastNonMatmul) {
     return;
@@ -152,66 +167,80 @@ export function convertF16ToF32CPU(f16Data) {
 
 export async function loadQ4KFused(shardData, location, name) {
   const device = getDevice();
-  const buffer = shardData instanceof GPUBuffer
+  const ownsBuffer = !isGpuBufferInstance(shardData);
+  const buffer = isGpuBufferInstance(shardData)
     ? shardData
     : acquireAlignedBuffer(location.size, `q4k_${name}`);
-  if (!(shardData instanceof GPUBuffer)) {
-    writeBufferAligned(device, buffer, shardData);
+  try {
+    if (ownsBuffer) {
+      writeBufferAligned(device, buffer, shardData);
+    }
+    return {
+      data: createWeightBuffer(buffer, 'q4k', 'row', location.shape, name),
+      allocatedBuffers: [buffer],
+    };
+  } catch (error) {
+    releaseOwnedGpuBuffer(buffer, ownsBuffer);
+    throw error;
   }
-
-  return {
-    data: createWeightBuffer(buffer, 'q4k', 'row', location.shape, name),
-    allocatedBuffers: [buffer],
-  };
 }
 
 
 export async function loadQ4KDequant(shardData, location, name, config) {
   const device = getDevice();
-  const quantBuffer = shardData instanceof GPUBuffer
+  let ownsQuantBuffer = !isGpuBufferInstance(shardData);
+  const quantBuffer = isGpuBufferInstance(shardData)
     ? shardData
     : acquireAlignedBuffer(location.size, `quant_${name}`);
-  if (!(shardData instanceof GPUBuffer)) {
-    writeBufferAligned(device, quantBuffer, shardData);
-  }
-
-  const outputDtype = getQ4KOutputDtype(location, config);
-
-  // Check if this is a 2D matrix with K (columns) not aligned to QK_K (256).
-  // If so, we need row-wise dequant to produce proper row-major output.
-  const is2DMatrix = Array.isArray(location.shape) && location.shape.length === 2;
-  const K = is2DMatrix ? location.shape[1] : 0;
-  const needsRowwise = is2DMatrix && K > 0 && K % QK_K !== 0;
+  let dequantized = null;
+  try {
+    if (ownsQuantBuffer) {
+      writeBufferAligned(device, quantBuffer, shardData);
+    }
 
-  let dequantizedTensor;
-  if (needsRowwise) {
-    const rows = location.shape[0];
-    debugTrace.loader(
-      `Dequantizing ${name} (row-wise): [${rows},${K}], K not 256-aligned, ` +
-      `outputDtype=${outputDtype}`
-    );
-    dequantizedTensor = await dequantizeRowwise(quantBuffer, rows, K, { outputDtype });
-  } else {
-    const numBlocks = Math.ceil(location.size / Q4K_BLOCK_BYTES);
-    debugTrace.loader(
-      `Dequantizing ${name}: size=${location.size}, numBlocks=${numBlocks}, ` +
-      `outputDtype=${outputDtype}, expectedOutput=${numBlocks * QK_K * (outputDtype === 'f16' ? 2 : 4)}`
-    );
-    dequantizedTensor = await dequantize(quantBuffer, numBlocks, { outputDtype });
-  }
-  const dequantized = dequantizedTensor.buffer;
+    const outputDtype = getQ4KOutputDtype(location, config);
+
+    const is2DMatrix = Array.isArray(location.shape) && location.shape.length === 2;
+    const K = is2DMatrix ? location.shape[1] : 0;
+    const needsRowwise = is2DMatrix && K > 0 && K % QK_K !== 0;
+
+    let dequantizedTensor;
+    if (needsRowwise) {
+      const rows = location.shape[0];
+      debugTrace.loader(
+        `Dequantizing ${name} (row-wise): [${rows},${K}], K not 256-aligned, ` +
+        `outputDtype=${outputDtype}`
+      );
+      dequantizedTensor = await dequantizeRowwise(quantBuffer, rows, K, { outputDtype });
+    } else {
+      const numBlocks = Math.ceil(location.size / Q4K_BLOCK_BYTES);
+      debugTrace.loader(
+        `Dequantizing ${name}: size=${location.size}, numBlocks=${numBlocks}, ` +
+        `outputDtype=${outputDtype}, expectedOutput=${numBlocks * QK_K * (outputDtype === 'f16' ? 2 : 4)}`
+      );
+      dequantizedTensor = await dequantize(quantBuffer, numBlocks, { outputDtype });
+    }
+    dequantized = dequantizedTensor.buffer;
 
-  debugTrace.loader(`Dequantized ${name}: resultSize=${dequantized.size}`);
-  releaseBuffer(quantBuffer);
+    debugTrace.loader(`Dequantized ${name}: resultSize=${dequantized.size}`);
+    releaseOwnedGpuBuffer(quantBuffer, ownsQuantBuffer);
+    ownsQuantBuffer = false;
 
-  const layout = getWeightLayout(location, config);
-  
-  const dtype = outputDtype;
+    const layout = getWeightLayout(location, config);
+    const dtype = outputDtype;
 
-  return {
-    data: createWeightBuffer(dequantized, dtype, layout, location.shape, name),
-    allocatedBuffers: [dequantized],
-  };
+    return {
+      data: createWeightBuffer(dequantized, dtype, layout, location.shape, name),
+      allocatedBuffers: [dequantized],
+    };
+  } catch (error) {
+    if (isReleasableBuffer(dequantized)) {
+      releaseBuffer(dequantized);
+    }
+    throw error;
+  } finally {
+    releaseOwnedGpuBuffer(quantBuffer, ownsQuantBuffer);
+  }
 }
 
 
@@ -219,97 +248,124 @@ export async function loadQ6K(shardData, location, name) {
   const device = getDevice();
 
   debugTrace.loader(`Loading Q6_K tensor "${name}", size=${location.size}`);
-  const quantBuffer = shardData instanceof GPUBuffer
+  let ownsQuantBuffer = !isGpuBufferInstance(shardData);
+  const quantBuffer = isGpuBufferInstance(shardData)
     ? shardData
     : acquireAlignedBuffer(location.size, `quant_${name}`);
-  if (!(shardData instanceof GPUBuffer)) {
-    writeBufferAligned(device, quantBuffer, shardData);
-  }
+  let dequantized = null;
+  try {
+    if (ownsQuantBuffer) {
+      writeBufferAligned(device, quantBuffer, shardData);
+    }
 
-  const numBlocks = Math.floor(location.size / Q6K_BLOCK_BYTES);
-  debugTrace.loader(
-    `Dequantizing Q6_K ${name}: size=${location.size}, numBlocks=${numBlocks}, ` +
-    `expectedOutput=${numBlocks * 256 * 2} (f16)`
-  );
+    const numBlocks = Math.floor(location.size / Q6K_BLOCK_BYTES);
+    debugTrace.loader(
+      `Dequantizing Q6_K ${name}: size=${location.size}, numBlocks=${numBlocks}, ` +
+      `expectedOutput=${numBlocks * 256 * 2} (f16)`
+    );
 
-  const dequantizedTensor = await dequantizeQ6K(quantBuffer, numBlocks, { outputDtype: 'f16' });
-  const dequantized = dequantizedTensor.buffer;
+    const dequantizedTensor = await dequantizeQ6K(quantBuffer, numBlocks, { outputDtype: 'f16' });
+    dequantized = dequantizedTensor.buffer;
 
-  debugTrace.loader(`Dequantized Q6_K ${name}: resultSize=${dequantized.size}`);
-  releaseBuffer(quantBuffer);
+    debugTrace.loader(`Dequantized Q6_K ${name}: resultSize=${dequantized.size}`);
+    releaseOwnedGpuBuffer(quantBuffer, ownsQuantBuffer);
+    ownsQuantBuffer = false;
+
+    const isMatmulWeight = shouldDequantizeToF16(location);
+    if (isMatmulWeight) {
+      return {
+        data: createWeightBuffer(dequantized, 'f16', 'row', location.shape, name),
+        allocatedBuffers: [dequantized],
+      };
+    }
 
-  const isMatmulWeight = shouldDequantizeToF16(location);
-  if (isMatmulWeight) {
     return {
-      data: createWeightBuffer(dequantized, 'f16', 'row', location.shape, name),
+      data: applyBufferLayout(dequantized, location, 'f16'),
       allocatedBuffers: [dequantized],
     };
+  } catch (error) {
+    if (isReleasableBuffer(dequantized)) {
+      releaseBuffer(dequantized);
+    }
+    throw error;
+  } finally {
+    releaseOwnedGpuBuffer(quantBuffer, ownsQuantBuffer);
   }
-
-  return {
-    data: applyBufferLayout(dequantized, location, 'f16'),
-    allocatedBuffers: [dequantized],
-  };
 }
 
 
 export async function loadBF16(shardData, location, name, config) {
   const device = getDevice();
-  const srcBuffer = shardData instanceof GPUBuffer
+  let ownsSrcBuffer = !isGpuBufferInstance(shardData);
+  const srcBuffer = isGpuBufferInstance(shardData)
     ? shardData
     : acquireAlignedBuffer(location.size, `${name}_bf16`);
-  if (!(shardData instanceof GPUBuffer)) {
-    writeBufferAligned(device, srcBuffer, shardData);
-  }
-
-  const numElements = location.size / 2;
-  const caps = config.gpuCapabilities || getKernelCapabilities();
-  const isMatmulWeight = shouldDequantizeToF16(location);
+  let resultBuffer = null;
+  try {
+    if (ownsSrcBuffer) {
+      writeBufferAligned(device, srcBuffer, shardData);
+    }
 
-  // For matmul weights with F16 support: BF16 -> F16 directly
-  if (caps?.hasF16 && isMatmulWeight) {
-    const f16Tensor = await runBF16ToF16(srcBuffer, [numElements], name);
-    releaseBuffer(srcBuffer);
-    debugTrace.loader(`BF16->F16 for matmul weight: ${name} (${numElements} elements)`);
+    const numElements = location.size / 2;
+    const caps = config.gpuCapabilities || getKernelCapabilities();
+    const isMatmulWeight = shouldDequantizeToF16(location);
+    const keepF32Weights = config.keepF32Weights === true;
 
-    
-    const layout = selectRuleValue('loader', 'weights', 'weightLayout', {
-      layout: location.layout ?? null,
-      useColumnWise: false,
-    });
-    return {
-      data: createWeightBuffer(f16Tensor.buffer, 'f16', layout, location.shape, name),
-      allocatedBuffers: [f16Tensor.buffer],
-    };
-  }
-
-  // Standard path: BF16 -> F32
-  const dstBuffer = await convertBF16ToF32GPU(srcBuffer, numElements, name);
-  releaseBuffer(srcBuffer);
+    if (caps?.hasF16 && isMatmulWeight && !keepF32Weights) {
+      const f16Tensor = await runBF16ToF16(srcBuffer, [numElements], name);
+      resultBuffer = f16Tensor.buffer;
+      releaseOwnedGpuBuffer(srcBuffer, ownsSrcBuffer);
+      ownsSrcBuffer = false;
+      debugTrace.loader(`BF16->F16 for matmul weight: ${name} (${numElements} elements)`);
 
-  if (dstBuffer instanceof GPUBuffer) {
-    if (isMatmulWeight) {
-      
       const layout = selectRuleValue('loader', 'weights', 'weightLayout', {
         layout: location.layout ?? null,
         useColumnWise: false,
       });
       return {
-        data: createWeightBuffer(dstBuffer, 'f32', layout, location.shape, name),
+        data: createWeightBuffer(f16Tensor.buffer, 'f16', layout, location.shape, name),
+        allocatedBuffers: [f16Tensor.buffer],
+      };
+    }
+
+    if (isMatmulWeight && keepF32Weights) {
+      debugTrace.loader(`Keeping BF16 matmul weight in f32: ${name} (keepF32Weights=true)`);
+    }
+
+    const dstBuffer = await convertBF16ToF32GPU(srcBuffer, numElements, name);
+    resultBuffer = dstBuffer;
+    releaseOwnedGpuBuffer(srcBuffer, ownsSrcBuffer);
+    ownsSrcBuffer = false;
+
+    if (isGpuBufferInstance(dstBuffer)) {
+      if (isMatmulWeight) {
+        const layout = selectRuleValue('loader', 'weights', 'weightLayout', {
+          layout: location.layout ?? null,
+          useColumnWise: false,
+        });
+        return {
+          data: createWeightBuffer(dstBuffer, 'f32', layout, location.shape, name),
+          allocatedBuffers: [dstBuffer],
+        };
+      }
+      return {
+        data: applyBufferLayout(dstBuffer, location, 'f32'),
         allocatedBuffers: [dstBuffer],
       };
     }
+
     return {
-      data: applyBufferLayout(dstBuffer, location, 'f32'),
-      allocatedBuffers: [dstBuffer],
+      data: dstBuffer,
+      allocatedBuffers: [],
     };
+  } catch (error) {
+    if (isReleasableBuffer(resultBuffer)) {
+      releaseBuffer(resultBuffer);
+    }
+    throw error;
+  } finally {
+    releaseOwnedGpuBuffer(srcBuffer, ownsSrcBuffer);
   }
-
-  // Float32Array returned (shouldn't happen in GPU path)
-  return {
-    data: dstBuffer,
-    allocatedBuffers: [],
-  };
 }
 
 
@@ -318,55 +374,69 @@ export async function loadFloat(shardData, location, name, config) {
     throw new Error('Tensor load config is required.');
   }
   const device = getDevice();
-  const buffer = shardData instanceof GPUBuffer
+  let ownsBuffer = !isGpuBufferInstance(shardData);
+  const buffer = isGpuBufferInstance(shardData)
     ? shardData
     : acquireAlignedBuffer(location.size, name);
-  if (!(shardData instanceof GPUBuffer)) {
-    writeBufferAligned(device, buffer, shardData);
-  }
-
-  const dtype = selectRuleValue('loader', 'weights', 'floatLocationDtype', {
-    locationDtype: location.dtype,
-  });
-  const layout = selectRuleValue('loader', 'weights', 'weightLayout', {
-    layout: location.layout ?? null,
-    useColumnWise: false,
-  });
-  const isMatmulWeight = shouldDequantizeToF16(location);
+  let resultBuffer = null;
+  try {
+    if (ownsBuffer) {
+      writeBufferAligned(device, buffer, shardData);
+    }
 
-  // Return WeightBuffer for matmul weights
-  if (isMatmulWeight) {
-    return {
-      data: createWeightBuffer(buffer, dtype, layout, location.shape, name),
-      allocatedBuffers: [buffer],
-    };
-  }
+    const dtype = selectRuleValue('loader', 'weights', 'floatLocationDtype', {
+      locationDtype: location.dtype,
+    });
+    const layout = selectRuleValue('loader', 'weights', 'weightLayout', {
+      layout: location.layout ?? null,
+      useColumnWise: false,
+    });
+    const isMatmulWeight = shouldDequantizeToF16(location);
 
-  // Non-matmul F16 weights need upcast to F32
-  if (dtype === 'f16') {
-    if (config.allowF32UpcastNonMatmul === false) {
+    if (isMatmulWeight) {
+      ownsBuffer = false;
       return {
-        data: applyBufferLayout(buffer, location, 'f16'),
+        data: createWeightBuffer(buffer, dtype, layout, location.shape, name),
         allocatedBuffers: [buffer],
       };
     }
-    const numElements = location.shape.reduce((a, b) => a * b, 1);
-    logF32UpcastNonMatmul(name, numElements, buffer.size);
-    debugTrace.loader(`F16->F32 upcast for non-matmul: ${name} (${numElements} elements, bufSize=${buffer.size})`);
-    const inputTensor = createTensor(buffer, 'f16', [numElements], `${name}_f16`);
-    const f32Tensor = await castF16ToF32(inputTensor);
-    debugTrace.loader(`F16->F32 complete: ${name} resultSize=${f32Tensor.buffer.size}`);
-    releaseBuffer(buffer);
+
+    if (dtype === 'f16') {
+      if (config.allowF32UpcastNonMatmul === false) {
+        ownsBuffer = false;
+        return {
+          data: applyBufferLayout(buffer, location, 'f16'),
+          allocatedBuffers: [buffer],
+        };
+      }
+      const numElements = location.shape.reduce((a, b) => a * b, 1);
+      logF32UpcastNonMatmul(name, numElements, buffer.size);
+      debugTrace.loader(`F16->F32 upcast for non-matmul: ${name} (${numElements} elements, bufSize=${buffer.size})`);
+      const inputTensor = createTensor(buffer, 'f16', [numElements], `${name}_f16`);
+      const f32Tensor = await castF16ToF32(inputTensor);
+      resultBuffer = f32Tensor.buffer;
+      debugTrace.loader(`F16->F32 complete: ${name} resultSize=${f32Tensor.buffer.size}`);
+      releaseOwnedGpuBuffer(buffer, ownsBuffer);
+      ownsBuffer = false;
+      return {
+        data: applyBufferLayout(f32Tensor.buffer, location, 'f32'),
+        allocatedBuffers: [f32Tensor.buffer],
+      };
+    }
+
+    ownsBuffer = false;
     return {
-      data: applyBufferLayout(f32Tensor.buffer, location, 'f32'),
-      allocatedBuffers: [f32Tensor.buffer],
+      data: applyBufferLayout(buffer, location, dtype),
+      allocatedBuffers: [buffer],
     };
+  } catch (error) {
+    if (isReleasableBuffer(resultBuffer)) {
+      releaseBuffer(resultBuffer);
+    }
+    throw error;
+  } finally {
+    releaseOwnedGpuBuffer(buffer, ownsBuffer);
   }
-
-  return {
-    data: applyBufferLayout(buffer, location, dtype),
-    allocatedBuffers: [buffer],
-  };
 }
 
 // ============================================================================

package/src/loader/tensors/tensor-reader.js

@@ -2,30 +2,84 @@
 
 import { trace } from '../../debug/index.js';
 
+function resolveSpanShardIndex(span, name, spanIndex) {
+  const shardIndex = typeof span?.shardIndex === 'number'
+    ? span.shardIndex
+    : span?.shard;
+  if (!Number.isInteger(shardIndex) || shardIndex < 0) {
+    throw new Error(
+      `[DopplerLoader] Tensor "${name}" span[${spanIndex}] has invalid shard index.`
+    );
+  }
+  return shardIndex;
+}
+
+function validateSpanField(value, field, name, spanIndex) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `[DopplerLoader] Tensor "${name}" span[${spanIndex}] has invalid ${field}.`
+    );
+  }
+  return value;
+}
+
+function getLocationSpans(location) {
+  if (!Array.isArray(location?.spans) || location.spans.length === 0) {
+    return null;
+  }
+  return location.spans;
+}
+
+function resolveLocationShardIndex(location, name) {
+  const shardIndex = typeof location?.shardIndex === 'number'
+    ? location.shardIndex
+    : location?.shard;
+  if (!Number.isInteger(shardIndex) || shardIndex < 0) {
+    throw new Error(`[DopplerLoader] Tensor "${name}" has invalid shard index.`);
+  }
+  return shardIndex;
+}
+
+function validateLocationField(location, field, name) {
+  const value = location?.[field];
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`[DopplerLoader] Tensor "${name}" has invalid ${field}.`);
+  }
+  return value;
+}
 
 export async function assembleShardData(location, name, loadShard, loadShardRange = null) {
-  if (location.spans) {
-    trace.loader(`Assembling tensor "${name}" from ${location.spans.length} spans`);
+  const spans = getLocationSpans(location);
+  if (spans) {
+    trace.loader(`Assembling tensor "${name}" from ${spans.length} spans`);
 
-    const chunks = await Promise.all(location.spans.map(async (span) => {
+    const chunks = await Promise.all(spans.map(async (span, spanIndex) => {
+      const shardIndex = resolveSpanShardIndex(span, name, spanIndex);
+      const offset = validateSpanField(span.offset, 'offset', name, spanIndex);
+      const size = validateSpanField(span.size, 'size', name, spanIndex);
       if (loadShardRange) {
-        const data = await loadShardRange(span.shardIndex, span.offset, span.size);
-        if (span.size > data.byteLength) {
+        const data = await loadShardRange(shardIndex, offset, size);
+        if (size > data.byteLength) {
           throw new Error(
-            `[DopplerLoader] Shard ${span.shardIndex} too small for tensor "${name}" span.`
+            `[DopplerLoader] Shard ${shardIndex} too small for tensor "${name}" span.`
           );
         }
-        return new Uint8Array(data, 0, span.size);
+        return new Uint8Array(data, 0, size);
       }
-      const data = await loadShard(span.shardIndex);
-      if (span.offset + span.size > data.byteLength) {
+      const data = await loadShard(shardIndex);
+      if (offset + size > data.byteLength) {
         throw new Error(
-          `[DopplerLoader] Shard ${span.shardIndex} too small for tensor "${name}" span.`
+          `[DopplerLoader] Shard ${shardIndex} too small for tensor "${name}" span.`
         );
       }
-      return new Uint8Array(data, span.offset, span.size);
+      return new Uint8Array(data, offset, size);
     }));
     const totalSize = chunks.reduce((s, c) => s + c.length, 0);
+    if (Number.isInteger(location?.size) && totalSize !== location.size) {
+      throw new Error(
+        `[DopplerLoader] Tensor "${name}" spans total ${totalSize} bytes, expected ${location.size}.`
+      );
+    }
     const combined = new Uint8Array(totalSize);
     let offset = 0;
     for (const chunk of chunks) {
@@ -36,21 +90,24 @@ export async function assembleShardData(location, name, loadShard, loadShardRang
   }
 
   // Single shard - use view to avoid copying
+  const shardIndex = resolveLocationShardIndex(location, name);
+  const offset = validateLocationField(location, 'offset', name);
+  const size = validateLocationField(location, 'size', name);
   if (loadShardRange) {
-    const slice = await loadShardRange(location.shardIndex, location.offset, location.size);
-    if (location.size > slice.byteLength) {
+    const slice = await loadShardRange(shardIndex, offset, size);
+    if (size > slice.byteLength) {
       throw new Error(
-        `[DopplerLoader] Shard ${location.shardIndex} too small for tensor "${name}" (offset=${location.offset}, size=${location.size}, shard=${slice.byteLength})`
+        `[DopplerLoader] Shard ${shardIndex} too small for tensor "${name}" (offset=${offset}, size=${size}, shard=${slice.byteLength})`
       );
     }
-    return new Uint8Array(slice, 0, location.size);
+    return new Uint8Array(slice, 0, size);
   }
 
-  const fullShard = await loadShard(location.shardIndex);
-  if (location.offset + location.size > fullShard.byteLength) {
+  const fullShard = await loadShard(shardIndex);
+  if (offset + size > fullShard.byteLength) {
     throw new Error(
-      `[DopplerLoader] Shard ${location.shardIndex} too small for tensor "${name}" (offset=${location.offset}, size=${location.size}, shard=${fullShard.byteLength})`
+      `[DopplerLoader] Shard ${shardIndex} too small for tensor "${name}" (offset=${offset}, size=${size}, shard=${fullShard.byteLength})`
     );
   }
-  return new Uint8Array(fullShard, location.offset, location.size);
+  return new Uint8Array(fullShard, offset, size);
 }

package/src/loader/weight-downcast.js

@@ -47,7 +47,7 @@ export async function maybeDowncastToF16(buf, options) {
   }
 
   // Handle raw GPUBuffer
-  if (buf instanceof GPUBuffer) {
+  if (typeof GPUBuffer !== 'undefined' && buf instanceof GPUBuffer) {
     return downcastGPUBuffer(buf, options);
   }
 

package/src/memory/buffer-pool.d.ts

@@ -80,6 +80,12 @@ export declare class BufferPool {
    */
   release(buffer: GPUBuffer): void;
 
+  /**
+   * Force-dispose an active buffer instead of returning it to the pool.
+   * Use for error paths where the buffer contents or device state may be invalid.
+   */
+  discard(buffer: GPUBuffer): void;
+
   /**
    * Check if a buffer is currently tracked as active by the pool
    */
@@ -159,7 +165,8 @@ export declare class BufferPool {
 }
 
 /**
- * Get the global buffer pool
+ * Get the global buffer pool for the current device epoch.
+ * If the active device has changed or was lost, a fresh global pool is created.
  */
 export function getBufferPool(): BufferPool;
 
@@ -179,6 +186,7 @@ export declare const createUploadBuffer: (size: number) => GPUBuffer;
 export declare const createUniformBuffer: (size: number) => GPUBuffer;
 export declare const acquireBuffer: (size: number, usage?: GPUBufferUsageFlags, label?: string) => GPUBuffer;
 export declare const releaseBuffer: (buffer: GPUBuffer) => void;
+export declare const discardBuffer: (buffer: GPUBuffer) => void;
 export declare const isBufferActive: (buffer: GPUBuffer) => boolean;
 export declare const getBufferRequestedSize: (buffer: GPUBuffer) => number;
 export declare const uploadData: (buffer: GPUBuffer, data: ArrayBuffer | ArrayBufferView, offset?: number) => void;