@simulatte/doppler 0.1.5 → 0.1.7

package/src/browser/safetensors-parser-browser.js

@@ -53,6 +53,78 @@ async function readTextFromSource(source) {
   return new TextDecoder().decode(buffer);
 }
 
+function resolveIndexedShardLayout(indexJson, fileMap) {
+  const weightMap = indexJson?.weight_map;
+  if (!weightMap || typeof weightMap !== 'object') {
+    throw new Error('Safetensors index JSON must include a weight_map object for sharded parsing.');
+  }
+
+  const referencedShards = new Set();
+  for (const [tensorName, shardNameRaw] of Object.entries(weightMap)) {
+    if (typeof tensorName !== 'string' || !tensorName.trim()) {
+      throw new Error('Safetensors index JSON weight_map contains an invalid tensor name.');
+    }
+    if (typeof shardNameRaw !== 'string' || !shardNameRaw.trim()) {
+      throw new Error(`Safetensors index JSON weight_map entry for "${tensorName}" must reference a shard filename.`);
+    }
+    referencedShards.add(shardNameRaw);
+  }
+
+  if (referencedShards.size === 0) {
+    throw new Error('Safetensors index JSON weight_map must reference at least one shard.');
+  }
+
+  const missingShards = [...referencedShards].filter((shardName) => !fileMap.has(shardName));
+  if (missingShards.length > 0) {
+    throw new Error(
+      `Safetensors sharded parse is missing indexed shard files: ${missingShards.join(', ')}`
+    );
+  }
+
+  const extraShards = [...fileMap.keys()].filter((shardName) => !referencedShards.has(shardName));
+  if (extraShards.length > 0) {
+    throw new Error(
+      `Safetensors sharded parse received shard files not referenced by index JSON: ${extraShards.join(', ')}`
+    );
+  }
+
+  return {
+    weightMap,
+    referencedShards,
+  };
+}
+
+function validateParsedShardsAgainstIndex(parsedShards, weightMap) {
+  const seenTensorNames = new Set();
+  for (const parsedShard of parsedShards) {
+    for (const tensor of parsedShard.parsed.tensors) {
+      seenTensorNames.add(tensor.name);
+      const mappedShard = weightMap[tensor.name];
+      if (typeof mappedShard !== 'string' || !mappedShard.trim()) {
+        throw new Error(
+          `Safetensors index JSON is missing a weight_map entry for tensor "${tensor.name}".`
+        );
+      }
+      if (mappedShard !== parsedShard.source.name) {
+        throw new Error(
+          `Safetensors index JSON routes tensor "${tensor.name}" to "${mappedShard}", ` +
+          `but it was found in "${parsedShard.source.name}".`
+        );
+      }
+    }
+  }
+
+  const missingTensorMappings = Object.entries(weightMap)
+    .filter(([tensorName]) => !seenTensorNames.has(tensorName))
+    .map(([tensorName]) => tensorName);
+  if (missingTensorMappings.length > 0) {
+    throw new Error(
+      `Safetensors index JSON references tensors not found in provided shard files: ` +
+      `${missingTensorMappings.join(', ')}`
+    );
+  }
+}
+
 export async function parseSafetensorsFile(file) {
   const source = normalizeTensorSource(file);
   const headerSizeBuffer = await source.readRange(0, 8);
@@ -108,8 +180,15 @@ export async function parseSafetensorsSharded(
     metadata = indexJson.metadata || {};
   }
 
-  const safetensorsSources = sources
+  let safetensorsSources = sources
     .filter((source) => source.name.endsWith('.safetensors'));
+  let weightMap = null;
+  if (indexJson) {
+    const indexedLayout = resolveIndexedShardLayout(indexJson, fileMap);
+    weightMap = indexedLayout.weightMap;
+    safetensorsSources = safetensorsSources
+      .filter((source) => indexedLayout.referencedShards.has(source.name));
+  }
   const parsedShards = await Promise.all(
     safetensorsSources.map(async (source) => {
       const parsed = await parseSafetensorsFile(source);
@@ -135,6 +214,10 @@ export async function parseSafetensorsSharded(
     }
   }
 
+  if (weightMap) {
+    validateParsedShardsAgainstIndex(parsedShards, weightMap);
+  }
+
   return {
     metadata,
     shards,

package/src/browser/shard-io-browser.js

@@ -1,7 +1,7 @@
 
 
 import { generateShardFilename } from '../formats/rdrr/index.js';
-import { createStreamingHasher } from '../storage/shard-manager.js';
+import { createStreamingHasher, getOpfsPathConfig } from '../storage/shard-manager.js';
 
 
 export class BrowserShardIO {
@@ -13,7 +13,7 @@ export class BrowserShardIO {
   
   static async create(modelId, options = {}) {
     const opfsRoot = await navigator.storage.getDirectory();
-    const modelsDir = await opfsRoot.getDirectoryHandle('models', { create: true });
+    const modelsDir = await opfsRoot.getDirectoryHandle(getOpfsPathConfig().opfsRootDir, { create: true });
     const modelDir = await modelsDir.getDirectoryHandle(modelId, { create: true });
     return new BrowserShardIO(modelDir, options);
   }

package/src/browser/tensor-source-download.js

@@ -229,9 +229,15 @@ export async function createRemoteTensorSource(url, options = {}) {
   try {
     const source = await createHttpTensorSource(url, options);
     return { source, size: source.size, supportsRange: true };
-  } catch (_error) {
+  } catch (error) {
     if (options.allowDownloadFallback === false) {
-      throw _error;
+      throw error;
+    }
+    if (options.allowDownloadFallback !== true) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `HTTP tensor source failed for "${url}" and download fallback is not explicitly enabled: ${message}`
+      );
     }
     const downloaded = await createDownloadTensorSource(url, options);
     return { ...downloaded, supportsRange: false };

package/src/browser/tensor-source-http.d.ts

@@ -13,6 +13,7 @@ export interface HttpRangeProbe {
   size: number | null;
   acceptRanges: string | null;
   contentEncoding: string | null;
+  error?: string | null;
 }
 
 export interface HttpTensorSourceOptions {

package/src/browser/tensor-source-http.js

@@ -61,7 +61,7 @@ export async function probeHttpRange(url, options = {}) {
       acceptRanges,
       contentEncoding,
     };
-  } catch (_error) {
+  } catch (error) {
     return {
       ok: false,
       status: 0,
@@ -69,6 +69,7 @@ export async function probeHttpRange(url, options = {}) {
       size: null,
       acceptRanges: null,
       contentEncoding: null,
+      error: error instanceof Error ? error.message : String(error),
     };
   }
 }
@@ -76,6 +77,9 @@ export async function probeHttpRange(url, options = {}) {
 export async function createHttpTensorSource(url, options = {}) {
   const { headers, signal, name: overrideName } = options;
   const probe = await probeHttpRange(url, { headers, signal });
+  if (!probe.ok && probe.status === 0 && probe.error) {
+    throw new Error(`HTTP tensor source probe failed for "${url}": ${probe.error}`);
+  }
   if (!probe.supportsRange || probe.size == null) {
     throw new Error('HTTP range requests not supported for tensor source');
   }

package/src/client/doppler-api.browser.js

@@ -227,9 +227,7 @@ async function* dopplerGenerate(prompt, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler() requires options.model.');
   }
-  if (options.runtimeConfig !== undefined || options.runtimePreset !== undefined) {
-    throw new Error('doppler() does not accept load-affecting options. Use doppler.load(model, options) instead.');
-  }
+  assertNoLoadAffectingOptions('doppler()', options);
   const model = await getCachedModel(options.model, { onProgress: options.onProgress });
   yield* model.generate(prompt, options);
 }
@@ -240,10 +238,26 @@ export function doppler(prompt, options) {
 
 doppler.load = load;
 
+function assertNoLoadAffectingOptions(apiName, options) {
+  if (!options || typeof options !== 'object') {
+    return;
+  }
+  if (
+    options.runtimeConfig !== undefined
+    || options.runtimePreset !== undefined
+    || options.runtimeConfigUrl !== undefined
+  ) {
+    throw new Error(
+      `${apiName} does not accept load-affecting options. Use doppler.load(model, options) instead.`
+    );
+  }
+}
+
 doppler.text = async function text(prompt, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler.text() requires options.model.');
   }
+  assertNoLoadAffectingOptions('doppler.text()', options);
   const model = await getCachedModel(options.model, { onProgress: options.onProgress });
   return model.generateText(prompt, options);
 };
@@ -252,6 +266,7 @@ doppler.chat = function chat(messages, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler.chat() requires options.model.');
   }
+  assertNoLoadAffectingOptions('doppler.chat()', options);
   return (async function* run() {
     const model = await getCachedModel(options.model, { onProgress: options.onProgress });
     yield* model.chat(messages, options);
@@ -262,6 +277,7 @@ doppler.chatText = async function chatText(messages, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler.chatText() requires options.model.');
   }
+  assertNoLoadAffectingOptions('doppler.chatText()', options);
   const model = await getCachedModel(options.model, { onProgress: options.onProgress });
   return model.chatText(messages, options);
 };
@@ -284,5 +300,5 @@ doppler.evictAll = async function evictAll() {
 
 doppler.listModels = async function listModels() {
   const models = await listQuickstartModels();
-  return models.map((entry) => entry.aliases[0] || entry.modelId);
+  return models.map((entry) => entry.modelId);
 };

package/src/client/doppler-api.js

@@ -128,6 +128,21 @@ async function collectText(iterable) {
   return output;
 }
 
+function assertNoLoadAffectingOptions(apiName, options) {
+  if (!options || typeof options !== 'object') {
+    return;
+  }
+  if (
+    options.runtimeConfig !== undefined
+    || options.runtimePreset !== undefined
+    || options.runtimeConfigUrl !== undefined
+  ) {
+    throw new Error(
+      `${apiName} does not accept load-affecting options. Use doppler.load(model, options) instead.`
+    );
+  }
+}
+
 function createModelHandle(pipeline, resolved) {
   return {
     generate(prompt, options = {}) {
@@ -246,9 +261,7 @@ async function* dopplerGenerate(prompt, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler() requires options.model.');
   }
-  if (options.runtimeConfig !== undefined || options.runtimePreset !== undefined) {
-    throw new Error('doppler() does not accept load-affecting options. Use doppler.load(model, options) instead.');
-  }
+  assertNoLoadAffectingOptions('doppler()', options);
   const model = await getCachedModel(options.model, { onProgress: options.onProgress });
   yield* model.generate(prompt, options);
 }
@@ -259,12 +272,14 @@ export function doppler(prompt, options) {
 
 doppler.load = load;
 doppler.text = async function text(prompt, options) {
+  assertNoLoadAffectingOptions('doppler.text()', options);
   return collectText(doppler(prompt, options));
 };
 doppler.chat = function chat(messages, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler.chat() requires options.model.');
   }
+  assertNoLoadAffectingOptions('doppler.chat()', options);
   return (async function* () {
     const model = await getCachedModel(options.model, { onProgress: options.onProgress });
     yield* model.chat(messages, options);
@@ -274,6 +289,7 @@ doppler.chatText = async function chatText(messages, options = {}) {
   if (!options || typeof options !== 'object' || options.model == null) {
     throw new Error('doppler.chatText() requires options.model.');
   }
+  assertNoLoadAffectingOptions('doppler.chatText()', options);
   const model = await getCachedModel(options.model, { onProgress: options.onProgress });
   return model.chatText(messages, options);
 };

package/src/client/doppler-provider/generation.js

@@ -11,6 +11,15 @@ import { getPipeline } from './model-manager.js';
 
 export { formatGemmaChat, formatLlama3Chat, formatGptOssChat };
 
+function assertSupportedGenerateOptions(options = {}) {
+  if (Array.isArray(options?.stopTokens) && options.stopTokens.length > 0) {
+    throw new Error(
+      'Doppler provider generate options do not support stopTokens on this surface. ' +
+      'Use stopSequences instead.'
+    );
+  }
+}
+
 function resolveChatTemplate(pipeline, options) {
   const override = options?.useChatTemplate;
   const runtimeEnabled = pipeline?.runtimeConfig?.inference?.chatTemplate?.enabled;
@@ -21,6 +30,7 @@ function resolveChatTemplate(pipeline, options) {
 }
 
 export async function* generate(prompt, options = {}) {
+  assertSupportedGenerateOptions(options);
   const pipeline = getPipeline();
   if (!pipeline) {
     throw new Error('No model loaded. Call loadModel() first.');
@@ -52,6 +62,7 @@ export async function* generate(prompt, options = {}) {
 }
 
 export async function prefillKV(prompt, options = {}) {
+  assertSupportedGenerateOptions(options);
   const pipeline = getPipeline();
   if (!pipeline) {
     throw new Error('No model loaded. Call loadModel() first.');
@@ -61,6 +72,7 @@ export async function prefillKV(prompt, options = {}) {
 }
 
 export async function* generateWithPrefixKV(prefix, prompt, options = {}) {
+  assertSupportedGenerateOptions(options);
   const pipeline = getPipeline();
   if (!pipeline) {
     throw new Error('No model loaded. Call loadModel() first.');

package/src/client/doppler-provider/model-manager.d.ts

@@ -10,6 +10,16 @@ export declare function getPipeline(): InferencePipeline | null;
 
 export declare function getCurrentModelId(): string | null;
 
+export declare function verifyExplicitModelUrlMatch(
+  localManifest: RDRRManifest | Record<string, unknown> | null | undefined,
+  modelUrl: string | null | undefined,
+  fetchRemoteManifest?: (modelUrl: string) => Promise<RDRRManifest | Record<string, unknown> | null>
+): Promise<void>;
+
+export declare function shouldAutoTuneKernels(
+  runtimeConfig?: Record<string, unknown> | null
+): boolean;
+
 export declare function extractTextModelConfig(manifest: RDRRManifest): TextModelConfig;
 
 export declare function readOPFSFile(path: string): Promise<ArrayBuffer>;

package/src/client/doppler-provider/model-manager.js

@@ -20,6 +20,12 @@ import { log } from '../../debug/index.js';
 import { DopplerCapabilities } from './types.js';
 import { GB, HEADER_READ_SIZE } from '../../config/schema/index.js';
 import { resolveBridgeSourceRuntimeBundle } from './source-runtime.js';
+import { getRuntimeConfig } from '../../config/runtime.js';
+import {
+  buildSourceArtifactFingerprint,
+  createStoredSourceArtifactContext,
+  verifyStoredSourceArtifact,
+} from '../../storage/source-artifact-store.js';
 
 let pipeline = null;
 let currentModelId = null;
@@ -34,6 +40,9 @@ function manifestsDiffer(localManifest, remoteManifest) {
   const localShards = Array.isArray(localManifest.shards) ? localManifest.shards : [];
   const remoteShards = Array.isArray(remoteManifest.shards) ? remoteManifest.shards : [];
   if (localShards.length !== remoteShards.length) return true;
+  if (buildSourceArtifactFingerprint(localManifest) !== buildSourceArtifactFingerprint(remoteManifest)) {
+    return true;
+  }
 
   for (let i = 0; i < localShards.length; i++) {
     const local = localShards[i];
@@ -61,6 +70,34 @@ async function tryFetchRemoteManifest(modelUrl) {
   return manifest;
 }
 
+export async function verifyExplicitModelUrlMatch(
+  localManifest,
+  modelUrl,
+  fetchRemoteManifest = tryFetchRemoteManifest
+) {
+  if (!localManifest || !modelUrl) {
+    return;
+  }
+  let remoteManifest = null;
+  try {
+    remoteManifest = await fetchRemoteManifest(modelUrl);
+  } catch (error) {
+    throw new Error(
+      `Could not compare cached manifest with explicit modelUrl "${modelUrl}": ${error.message}`
+    );
+  }
+  if (remoteManifest && manifestsDiffer(localManifest, remoteManifest)) {
+    throw new Error(
+      `Explicit modelUrl "${modelUrl}" does not match the cached manifest for "${localManifest.modelId ?? 'unknown'}". ` +
+      'Clear the cache or load the matching source explicitly.'
+    );
+  }
+}
+
+export function shouldAutoTuneKernels(runtimeConfig = getRuntimeConfig()) {
+  return runtimeConfig?.shared?.kernelWarmup?.autoTune === true;
+}
+
 export function getPipeline() {
   return pipeline;
 }
@@ -69,6 +106,14 @@ export function getCurrentModelId() {
   return currentModelId;
 }
 
+function requireManifestQuantization(manifest) {
+  const quantization = String(manifest?.quantization ?? '').trim();
+  if (!quantization) {
+    throw new Error('Manifest is missing quantization; re-convert the model.');
+  }
+  return quantization.toUpperCase();
+}
+
 export function extractTextModelConfig(manifest) {
   const arch = (manifest.architecture && typeof manifest.architecture === 'object')
     ? manifest.architecture
@@ -86,12 +131,12 @@ export function extractTextModelConfig(manifest) {
     headDim: arch.headDim,
     vocabSize: arch.vocabSize,
     maxSeqLen: arch.maxSeqLen,
-    quantization: (manifest?.quantization || 'f16').toUpperCase(),
+    quantization: requireManifestQuantization(manifest),
   };
 }
 
 function estimateDequantizedWeightsBytes(manifest) {
-  const q = (manifest?.quantization || '').toUpperCase();
+  const q = requireManifestQuantization(manifest);
   const total = manifest?.totalSize || 0;
   if (q.startsWith('Q4')) {
     return total * 8;
@@ -243,6 +288,24 @@ export async function loadModel(modelId, modelUrl = null, onProgress = null, loc
           manifest = parseManifest(manifestJson);
           log.info('DopplerProvider', `Loaded manifest via bridge: ${manifest.modelId}`);
           if (onProgress) onProgress({ stage: 'manifest', message: 'Manifest loaded via bridge' });
+          const persistedSourceBundle = await resolveBridgeSourceRuntimeBundle({
+            bridgeClient,
+            localPath,
+            modelId,
+            manifest,
+            verifyHashes: true,
+            onProgress: (progress) => onProgress?.(progress),
+          });
+          if (persistedSourceBundle) {
+            bridgeStorageContext = persistedSourceBundle.storageContext;
+            bridgeSourceMode = true;
+            if (onProgress) {
+              onProgress({
+                stage: 'manifest',
+                message: `Direct-source manifest ready (${persistedSourceBundle.sourceKind} artifact mode)`,
+              });
+            }
+          }
         } catch (manifestError) {
           log.warn(
             'DopplerProvider',
@@ -252,6 +315,7 @@ export async function loadModel(modelId, modelUrl = null, onProgress = null, loc
             bridgeClient,
             localPath,
             modelId,
+            verifyHashes: true,
             onProgress: (progress) => onProgress?.(progress),
           });
           if (!sourceBundle) {
@@ -286,25 +350,26 @@ export async function loadModel(modelId, modelUrl = null, onProgress = null, loc
 
       let integrity = { valid: false, missingShards: [] };
       if (manifest) {
-        integrity = await verifyIntegrity({ checkHashes: false }).catch(() => ({
-          valid: false,
-          missingShards: [],
-        }));
+        const sourceArtifactFingerprint = buildSourceArtifactFingerprint(manifest);
+        if (sourceArtifactFingerprint) {
+          const sourceIntegrity = await verifyStoredSourceArtifact(manifest, { checkHashes: false }).catch(() => ({
+            valid: false,
+            missingFiles: [],
+          }));
+          integrity = {
+            valid: sourceIntegrity.valid,
+            missingShards: Array.isArray(sourceIntegrity.missingFiles) ? sourceIntegrity.missingFiles : [],
+          };
+        } else {
+          integrity = await verifyIntegrity({ checkHashes: false }).catch(() => ({
+            valid: false,
+            missingShards: [],
+          }));
+        }
       }
 
       if (integrity.valid && manifest && modelUrl) {
-        try {
-          const remoteManifest = await tryFetchRemoteManifest(modelUrl);
-          if (remoteManifest && manifestsDiffer(manifest, remoteManifest)) {
-            log.info('DopplerProvider', 'Cached model differs from source URL manifest; refreshing cache');
-            integrity = { valid: false, missingShards: [] };
-          }
-        } catch (error) {
-          log.warn(
-            'DopplerProvider',
-            `Could not compare cached manifest with source URL (${error.message}); using cached model`
-          );
-        }
+        await verifyExplicitModelUrlMatch(manifest, modelUrl);
       }
 
       if (!integrity.valid && modelUrl) {
@@ -365,7 +430,11 @@ export async function loadModel(modelId, modelUrl = null, onProgress = null, loc
       DopplerCapabilities.kernelsWarmed = true;
     }
 
-    if (!DopplerCapabilities.kernelsTuned && typeof setTimeout !== 'undefined') {
+    if (
+      !DopplerCapabilities.kernelsTuned
+      && shouldAutoTuneKernels()
+      && typeof setTimeout !== 'undefined'
+    ) {
       DopplerCapabilities.kernelsTuned = true;
       const tuneConfig = extractTextModelConfig(manifest);
       setTimeout(() => {
@@ -389,6 +458,9 @@ export async function loadModel(modelId, modelUrl = null, onProgress = null, loc
     const memCaps = await getMemoryCapabilities();
 
     let storageContext = bridgeStorageContext;
+    if (!storageContext && buildSourceArtifactFingerprint(manifest)) {
+      storageContext = createStoredSourceArtifactContext(manifest, { verifyHashes: true });
+    }
     if (!storageContext && useBridge && DopplerCapabilities.bridgeClient && DopplerCapabilities.localPath) {
       const bridgeClient = DopplerCapabilities.bridgeClient;
       const basePath = DopplerCapabilities.localPath.endsWith('/')

package/src/client/doppler-provider/source-runtime.d.ts

@@ -6,7 +6,9 @@ export interface ResolveBridgeSourceRuntimeBundleOptions {
   bridgeClient: ExtensionBridgeClient;
   localPath: string;
   modelId?: string | null;
+  manifest?: RDRRManifest | null;
   onProgress?: (info: { stage: string; message: string }) => void;
+  verifyHashes?: boolean;
 }
 
 export interface BridgeSourceRuntimeBundle {
@@ -19,4 +21,3 @@ export interface BridgeSourceRuntimeBundle {
 export declare function resolveBridgeSourceRuntimeBundle(
   options: ResolveBridgeSourceRuntimeBundleOptions
 ): Promise<BridgeSourceRuntimeBundle | null>;
-