@simulatte/doppler 0.1.5 → 0.1.7

package/src/memory/buffer-pool.js

@@ -1,6 +1,6 @@
 
 
-import { getDevice, getDeviceLimits } from '../gpu/device.js';
+import { getDevice, getDeviceEpoch, getDeviceLimits } from '../gpu/device.js';
 import { allowReadback, trackAllocation } from '../gpu/perf-guards.js';
 import { log, trace, isTraceEnabled } from '../debug/index.js';
 import { getRuntimeConfig } from '../config/runtime.js';
@@ -137,6 +137,12 @@ export class BufferPool {
   
   #debugMode;
 
+  // Device-scoped ownership for pooled buffers
+
+  #device;
+
+  #deviceEpoch;
+
   
   constructor(debugMode = false, schemaConfig) {
     if (!schemaConfig) {
@@ -153,6 +159,8 @@ export class BufferPool {
     this.#schemaConfig = schemaConfig;
     this.#pendingDestruction = new Set();
     this.#destructionScheduled = false;
+    this.#device = getDevice();
+    this.#deviceEpoch = getDeviceEpoch();
 
     this.#stats = {
       allocations: 0,
@@ -174,9 +182,32 @@ export class BufferPool {
     };
   }
 
+  #isEmpty() {
+    return this.#activeBuffers.size === 0
+      && this.#getTotalPooledCount() === 0
+      && this.#pendingDestruction.size === 0;
+  }
+
+  #getBoundDevice() {
+    const currentEpoch = getDeviceEpoch();
+    if (this.#deviceEpoch !== currentEpoch) {
+      if (!this.#isEmpty()) {
+        throw new Error(
+          `BufferPool belongs to stale device epoch ${this.#deviceEpoch}; ` +
+          `current epoch is ${currentEpoch}. Create a new pool.`
+        );
+      }
+      this.#deviceEpoch = currentEpoch;
+      this.#device = getDevice();
+    } else if (!this.#device) {
+      this.#device = getDevice();
+    }
+    return this.#device;
+  }
+
   
   acquire(size, usage = BufferUsage.STORAGE, label = 'pooled_buffer') {
-    const device = getDevice();
+    const device = this.#getBoundDevice();
     if (!device) {
       throw new Error('Device not initialized');
     }
@@ -274,25 +305,57 @@ export class BufferPool {
       log.warn('BufferPool', 'Releasing buffer not tracked as active');
       return;
     }
+    this.#releaseTrackedBuffer(buffer, true);
+  }
+
+  
+  discard(buffer) {
+    if (!this.#activeBuffers.has(buffer)) {
+      log.warn('BufferPool', 'Discarding buffer not tracked as active');
+      return;
+    }
+    this.#releaseTrackedBuffer(buffer, false);
+  }
+
+  
+  isActiveBuffer(buffer) {
+    return this.#activeBuffers.has(buffer);
+  }
+
+  
+  getRequestedSize(buffer) {
+    return this.#requestedSizes.get(buffer) ?? buffer.size;
+  }
 
+  #destroyPendingBuffers() {
+    const pending = Array.from(this.#pendingDestruction);
+    this.#pendingDestruction.clear();
+    for (const buffer of pending) {
+      try {
+        buffer.destroy();
+      } catch (error) {
+        log.warn('BufferPool', `Pending buffer destroy failed: ${error?.message ?? error}`);
+      }
+    }
+  }
+
+  #releaseTrackedBuffer(buffer, allowPooling) {
     this.#activeBuffers.delete(buffer);
     const requestedSize = this.#requestedSizes.get(buffer) ?? 0;
     this.#stats.currentBytesRequested -= requestedSize;
     this.#requestedSizes.delete(buffer);
 
-    // Remove metadata in debug mode
     if (this.#debugMode) {
       this.#bufferMetadata.delete(buffer);
     }
 
-    if (!this.#config.enablePooling) {
+    if (!allowPooling || !this.#config.enablePooling) {
       this.#deferDestroy(buffer);
       this.#stats.currentBytesAllocated -= buffer.size;
       this.#traceRelease(buffer, requestedSize, false);
       return;
     }
 
-    // Return to pool if there's room
     const bucket = buffer.size;
     const usage = buffer.usage;
 
@@ -312,7 +375,6 @@ export class BufferPool {
       bucketPool.push(buffer);
       pooled = true;
     } else {
-      // Pool is full; defer destruction until GPU work completes.
       this.#deferDestroy(buffer);
       this.#stats.currentBytesAllocated -= buffer.size;
     }
@@ -321,45 +383,29 @@ export class BufferPool {
   }
 
   
-  isActiveBuffer(buffer) {
-    return this.#activeBuffers.has(buffer);
-  }
-
-  
-  getRequestedSize(buffer) {
-    return this.#requestedSizes.get(buffer) ?? buffer.size;
-  }
-
-  
   #deferDestroy(buffer) {
     this.#pendingDestruction.add(buffer);
     if (this.#destructionScheduled) {
       return;
     }
-    const device = getDevice();
+    const device = this.#device;
     if (!device) {
       // No device context; destroy immediately as a fallback.
-      for (const pending of this.#pendingDestruction) {
-        pending.destroy();
-      }
-      this.#pendingDestruction.clear();
       this.#destructionScheduled = false;
+      this.#destroyPendingBuffers();
       return;
     }
 
     this.#destructionScheduled = true;
     device.queue.onSubmittedWorkDone()
       .then(() => {
-        for (const pending of this.#pendingDestruction) {
-          pending.destroy();
-        }
-        this.#pendingDestruction.clear();
         this.#destructionScheduled = false;
+        this.#destroyPendingBuffers();
       })
       .catch((err) => {
         log.warn('BufferPool', `Deferred destruction failed: ${ (err).message}`);
-        this.#pendingDestruction.clear();
         this.#destructionScheduled = false;
+        this.#destroyPendingBuffers();
       });
   }
 
@@ -536,7 +582,7 @@ export class BufferPool {
 
   
   uploadData(buffer, data, offset = 0) {
-    const device = getDevice();
+    const device = this.#getBoundDevice();
     if (!device) {
       throw new Error('Device not initialized');
     }
@@ -554,7 +600,7 @@ export class BufferPool {
       return new ArrayBuffer(0);
     }
 
-    const device = getDevice();
+    const device = this.#getBoundDevice();
     if (!device) {
       throw new Error('Device not initialized');
     }
@@ -583,21 +629,31 @@ export class BufferPool {
     const alignedSize = Math.ceil(size / 4) * 4;
     // Create staging buffer
     const staging = this.createStagingBuffer(alignedSize);
-
-    // Copy to staging
-    const encoder = device.createCommandEncoder({ label: 'readback_encoder' });
-    encoder.copyBufferToBuffer(buffer, offset, staging, 0, alignedSize);
-    device.queue.submit([encoder.finish()]);
-
-    // Map and read
-    await staging.mapAsync(RESOLVED_GPU_MAP_MODE.READ);
-    const data = staging.getMappedRange(0, alignedSize).slice(0, size);
-    staging.unmap();
-
-    // Release staging buffer
-    this.release(staging);
-
-    return data;
+    let mapped = false;
+
+    try {
+      // Copy to staging
+      const encoder = device.createCommandEncoder({ label: 'readback_encoder' });
+      encoder.copyBufferToBuffer(buffer, offset, staging, 0, alignedSize);
+      device.queue.submit([encoder.finish()]);
+
+      // Map and read
+      await staging.mapAsync(RESOLVED_GPU_MAP_MODE.READ);
+      mapped = true;
+      return staging.getMappedRange(0, alignedSize).slice(0, size);
+    } catch (error) {
+      if (this.#activeBuffers.has(staging)) {
+        this.#releaseTrackedBuffer(staging, false);
+      }
+      throw error;
+    } finally {
+      if (mapped) {
+        staging.unmap();
+        if (this.#activeBuffers.has(staging)) {
+          this.#releaseTrackedBuffer(staging, true);
+        }
+      }
+    }
   }
 
   
@@ -684,11 +740,17 @@ export class BufferPool {
 // Global buffer pool instance
 
 let globalPool = null;
+let globalPoolEpoch = -1;
 
 
 export function getBufferPool() {
-  if (!globalPool) {
+  const epoch = getDeviceEpoch();
+  if (!globalPool || globalPoolEpoch !== epoch) {
+    if (globalPool) {
+      globalPool.destroy();
+    }
     globalPool = new BufferPool(false, getRuntimeConfig().shared.bufferPool);
+    globalPoolEpoch = epoch;
   }
   return globalPool;
 }
@@ -707,6 +769,7 @@ export function destroyBufferPool() {
     globalPool.destroy();
     globalPool = null;
   }
+  globalPoolEpoch = -1;
 }
 
 // Convenience exports for common operations
@@ -722,6 +785,8 @@ export const acquireBuffer = (size, usage, label) =>
 
 export const releaseBuffer = (buffer) => getBufferPool().release(buffer);
 
+export const discardBuffer = (buffer) => getBufferPool().discard(buffer);
+
 export const isBufferActive = (buffer) =>
   getBufferPool().isActiveBuffer(buffer);
 

package/src/memory/unified-detect.js

@@ -114,7 +114,7 @@ function checkUnifiedIndicators(
 
 export async function detectUnifiedMemory() {
   // Need WebGPU for detection
-  if (!navigator.gpu) {
+  if (typeof navigator === 'undefined' || !navigator.gpu) {
     return {
       isUnified: false,
       reason: 'WebGPU not available',

package/src/rules/inference/kernel-path.rules.json

@@ -1,5 +1,13 @@
 {
   "autoSelect": [
+    {
+      "match": {
+        "allowCapabilityAutoSelection": true,
+        "hasSubgroups": true,
+        "kernelPathRef": "gemma3-q4k-dequant-f32a-nosubgroups"
+      },
+      "value": "gemma3-q4k-dequant-f32a-online"
+    },
     {
       "match": {
         "allowCapabilityAutoSelection": true,
@@ -8,13 +16,21 @@
       },
       "value": "gemma3-q4k-dequant-f32a-online"
     },
+    {
+      "match": {
+        "allowCapabilityAutoSelection": true,
+        "hasSubgroups": false,
+        "kernelPathRef": "gemma3-q4k-dequant-f32a"
+      },
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
+    },
     {
       "match": {
         "allowCapabilityAutoSelection": true,
         "hasSubgroups": false,
         "kernelPathRef": "gemma3-q4k-dequant-f16a-online"
       },
-      "value": "gemma3-q4k-dequant-f32a"
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": {
@@ -22,7 +38,7 @@
         "hasSubgroups": false,
         "kernelPathRef": "gemma3-q4k-dequant-f32a-online"
       },
-      "value": "gemma3-q4k-dequant-f32a"
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": {
@@ -30,7 +46,7 @@
         "hasSubgroups": false,
         "kernelPathRef": "lfm2-q4k-dequant-f32a-online"
       },
-      "value": "gemma3-q4k-dequant-f32a"
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": {
@@ -38,7 +54,7 @@
         "hasSubgroups": false,
         "kernelPathRef": "gemma2-q4k-dequant-f16a"
       },
-      "value": "gemma2-q4k-dequant-f32a"
+      "value": "gemma2-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": {
@@ -46,7 +62,7 @@
         "hasSubgroups": false,
         "kernelPathRef": "gemma2-q4k-fused-f32a"
       },
-      "value": "gemma2-q4k-dequant-f32a"
+      "value": "gemma2-q4k-dequant-f32a-nosubgroups"
     },
     { "match": {}, "value": { "context": "kernelPathRef" } }
   ],
@@ -57,11 +73,11 @@
     },
     {
       "match": { "kernelPathId": "gemma3-q4k-dequant-f16a-online" },
-      "value": "gemma3-q4k-dequant-f32a"
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": { "kernelPathId": "lfm2-q4k-dequant-f32a-online" },
-      "value": "gemma3-q4k-dequant-f32a"
+      "value": "gemma3-q4k-dequant-f32a-nosubgroups"
     },
     {
       "match": { "kernelPathId": "gemma2-f16-f16a" },
@@ -69,7 +85,7 @@
     },
     {
       "match": { "kernelPathId": "gemma2-q4k-dequant-f16a" },
-      "value": "gemma2-q4k-dequant-f32a"
+      "value": "gemma2-q4k-dequant-f32a-nosubgroups"
     },
     { "match": {}, "value": null }
   ]

package/src/rules/rule-registry.js

@@ -3,6 +3,24 @@ import { buildInferenceExecutionRulesContractArtifact } from './execution-rules-
 import { buildLayerPatternContractArtifact } from './layer-pattern-contract-check.js';
 import { loadJson } from '../utils/load-json.js';
 
+function cloneRuleValue(value) {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function deepFreeze(value, seen = new WeakSet()) {
+  if (!value || typeof value !== 'object' || seen.has(value)) {
+    return value;
+  }
+  seen.add(value);
+  for (const entry of Object.values(value)) {
+    deepFreeze(entry, seen);
+  }
+  return Object.freeze(value);
+}
+
 const attentionRules = await loadJson('./kernels/attention.rules.json', import.meta.url, 'Failed to load rules');
 const conv2dRules = await loadJson('./kernels/conv2d.rules.json', import.meta.url, 'Failed to load rules');
 const depthwiseConv2dRules = await loadJson('./kernels/depthwise-conv2d.rules.json', import.meta.url, 'Failed to load rules');
@@ -160,7 +178,7 @@ export function registerRuleGroup(domain, group, rules) {
   if (!RULE_SETS[domain]) {
     RULE_SETS[domain] = {};
   }
-  RULE_SETS[domain][group] = rules;
+  RULE_SETS[domain][group] = deepFreeze(cloneRuleValue(rules));
 }
 
 export function getInferenceExecutionRulesContractArtifact() {
@@ -213,3 +231,9 @@ function applyTemplate(template, context) {
     return String(context[key]);
   });
 }
+
+for (const domainRules of Object.values(RULE_SETS)) {
+  for (const rules of Object.values(domainRules)) {
+    deepFreeze(rules);
+  }
+}

package/src/rules/tooling/command-runtime.rules.json

@@ -27,6 +27,24 @@
         "intent": "verify"
       }
     },
+    {
+      "match": {
+        "command": "lora"
+      },
+      "value": {
+        "suite": null,
+        "intent": null
+      }
+    },
+    {
+      "match": {
+        "command": "distill"
+      },
+      "value": {
+        "suite": null,
+        "intent": null
+      }
+    },
     {
       "match": {},
       "value": {

package/src/storage/backends/opfs-store.js

@@ -34,10 +34,13 @@ export function createOpfsStore(config) {
   let modelsDir = null;
   let currentModelDir = null;
   let currentModelId = null;
-  // SyncAccessHandle is typically only available in dedicated workers, but we
-  // allow an optimistic attempt anywhere and fall back gracefully if the
-  // browser rejects it (NotAllowedError / InvalidStateError).
-  const syncAccessEnabled = !!useSyncAccessHandle
+  const syncAccessRequested = useSyncAccessHandle === true;
+  if (syncAccessRequested && typeof FileSystemSyncAccessHandle === 'undefined') {
+    throw new Error(
+      'OPFS sync access handles were explicitly requested but are unavailable in this runtime.'
+    );
+  }
+  const syncAccessEnabled = syncAccessRequested
     && typeof FileSystemSyncAccessHandle !== 'undefined';
   const handleLimiter = syncAccessEnabled ? createLimiter(maxConcurrentHandles) : null;
 
@@ -84,7 +87,9 @@ export function createOpfsStore(config) {
     } catch (error) {
       handleLimiter.release();
       if (error?.name === 'InvalidStateError' || error?.name === 'NotAllowedError') {
-        return null;
+        throw new Error(
+          `OPFS sync access handles were explicitly requested but could not be opened: ${error.name}.`
+        );
       }
       throw error;
     }
@@ -96,6 +101,44 @@ export function createOpfsStore(config) {
     }
   }
 
+  function normalizePathSegments(filename) {
+    const normalized = String(filename || '').replace(/\\/g, '/').trim();
+    if (!normalized) {
+      throw new Error('Filename is required');
+    }
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.length === 0) {
+      throw new Error('Filename is required');
+    }
+    for (const part of parts) {
+      if (part === '.' || part === '..') {
+        throw new Error(`Invalid relative storage path: ${filename}`);
+      }
+    }
+    return parts;
+  }
+
+  async function resolveDirectoryForPath(filename, options = {}) {
+    await ensureModelDir();
+    const parts = normalizePathSegments(filename);
+    const leafName = parts.pop();
+    let dir = currentModelDir;
+    for (const part of parts) {
+      dir = await dir.getDirectoryHandle(part, { create: options.createDirs === true });
+    }
+    return {
+      dir,
+      leafName,
+    };
+  }
+
+  async function getFileHandle(filename, options = {}) {
+    const { dir, leafName } = await resolveDirectoryForPath(filename, {
+      createDirs: options.create === true,
+    });
+    return dir.getFileHandle(leafName, { create: options.create === true });
+  }
+
   function normalizeWriteStreamOptions(options = {}) {
     const append = options?.append === true;
     const expectedOffsetRaw = options?.expectedOffset;
@@ -112,8 +155,7 @@ export function createOpfsStore(config) {
   }
 
   async function getFileSize(filename) {
-    await ensureModelDir();
-    const fileHandle = await currentModelDir.getFileHandle(filename);
+    const fileHandle = await getFileHandle(filename, { create: false });
     const access = await openSyncAccessHandle(fileHandle);
     if (access) {
       try {
@@ -127,8 +169,7 @@ export function createOpfsStore(config) {
   }
 
   async function readFile(filename) {
-    await ensureModelDir();
-    const fileHandle = await currentModelDir.getFileHandle(filename);
+    const fileHandle = await getFileHandle(filename, { create: false });
     const access = await openSyncAccessHandle(fileHandle);
     if (access) {
       try {
@@ -154,8 +195,7 @@ export function createOpfsStore(config) {
   }
 
   async function readFileRange(filename, offset = 0, length = null) {
-    await ensureModelDir();
-    const fileHandle = await currentModelDir.getFileHandle(filename);
+    const fileHandle = await getFileHandle(filename, { create: false });
     const access = await openSyncAccessHandle(fileHandle);
 
     const startRaw = Number(offset);
@@ -197,8 +237,7 @@ export function createOpfsStore(config) {
     const startRaw = Number(offset);
     const start = Number.isFinite(startRaw) ? Math.max(0, Math.floor(startRaw)) : 0;
 
-    await ensureModelDir();
-    const fileHandle = await currentModelDir.getFileHandle(filename);
+    const fileHandle = await getFileHandle(filename, { create: false });
     const access = await openSyncAccessHandle(fileHandle);
 
     if (access) {
@@ -236,9 +275,8 @@ export function createOpfsStore(config) {
   }
 
   async function readText(filename) {
-    await ensureModelDir();
     try {
-      const fileHandle = await currentModelDir.getFileHandle(filename);
+      const fileHandle = await getFileHandle(filename, { create: false });
       const file = await fileHandle.getFile();
       return await file.text();
     } catch (error) {
@@ -250,8 +288,7 @@ export function createOpfsStore(config) {
   }
 
   async function writeFile(filename, data) {
-    await ensureModelDir();
-    const fileHandle = await currentModelDir.getFileHandle(filename, { create: true });
+    const fileHandle = await getFileHandle(filename, { create: true });
     const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
     const access = await openSyncAccessHandle(fileHandle);
     if (access) {
@@ -271,9 +308,8 @@ export function createOpfsStore(config) {
   }
 
   async function createWriteStream(filename, options = {}) {
-    await ensureModelDir();
     const { append, expectedOffset } = normalizeWriteStreamOptions(options);
-    const fileHandle = await currentModelDir.getFileHandle(filename, { create: true });
+    const fileHandle = await getFileHandle(filename, { create: true });
     const existingSize = await getFileSize(filename).catch((error) => {
       if (error?.name === 'NotFoundError') {
         return 0;
@@ -347,9 +383,9 @@ export function createOpfsStore(config) {
   }
 
   async function deleteFile(filename) {
-    await ensureModelDir();
+    const { dir, leafName } = await resolveDirectoryForPath(filename, { createDirs: false });
     try {
-      await currentModelDir.removeEntry(filename);
+      await dir.removeEntry(leafName);
       return true;
     } catch (error) {
       if (error.name === 'NotFoundError') {
@@ -362,11 +398,19 @@ export function createOpfsStore(config) {
   async function listFiles() {
     await ensureModelDir();
     const files = [];
-    for await (const [name, handle] of currentModelDir.entries()) {
-      if (handle.kind === 'file') {
-        files.push(name);
+    async function walk(dir, prefix = '') {
+      for await (const [name, handle] of dir.entries()) {
+        const relativePath = prefix ? `${prefix}/${name}` : name;
+        if (handle.kind === 'file') {
+          files.push(relativePath);
+          continue;
+        }
+        if (handle.kind === 'directory') {
+          await walk(handle, relativePath);
+        }
       }
     }
+    await walk(currentModelDir);
     return files;
   }