@simulatte/doppler 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to `@simulatte/doppler` are documented in this file.
+
+This changelog is package-facing and release-oriented. Entries before `0.1.7`
+were retrofitted from package version history, release commits, and release
+docs so the `0.1.x` line has one conventional npm-visible history surface.
+
+## [0.1.7] - 2026-03-10
+
+### Added
+
+- Added a conventional npm-facing changelog and included it in the published
+  package file list.
+- Added stronger release-claim, quickstart-registry, local-model-integrity,
+  and browser diagnostics regression coverage.
+- Added browser OPFS registry smoke workflows for text and embedding model
+  validation.
+
+### Changed
+
+- Tightened release-facing model claims around the verified quickstart/catalog
+  set and regenerated the support and release matrices from current metadata.
+- Synced the public quickstart registry from canonical catalog metadata instead
+  of maintaining it by hand.
+
+### Fixed
+
+- Fixed a tensor-loader buffer ownership bug that corrupted returned weight
+  buffers and broke Gemma 3 1B generation.
+- Fixed quickstart Hugging Face revision drift for registry-backed model IDs.
+- Fixed multiple CI contract drifts across onboarding, release metadata,
+  support matrices, and generated benchmark fixtures.
+
+## [0.1.6] - 2026-03-07
+
+### Added
+
+- Added stricter config and contract tests around runtime overrides, kernel-path
+  semantics, and release-support metadata.
+- Added distillation helper extraction coverage for training suite refactors.
+
+### Changed
+
+- Continued the execution-v0 and training orchestration refactor work so public
+  entrypoints read more like facades and less like inline policy code.
+- Refreshed package exports, repository metadata, and release-facing support
+  surfaces for the npm package.
+
+### Fixed
+
+- Preserved explicit `null` semantics for `runtime.inference.kernelPath` through
+  schema, runtime config, and harness paths.
+- Fixed CI drift around onboarding, registry verification aliases, release
+  matrix metadata, and kernel-path preset naming.
+
+## [0.1.5] - 2026-03-06
+
+### Added
+
+- Added diffusion kernel and contract work, plus additional Lean execution
+  contract sweep tooling.
+- Added public API reference inventory and stronger registry workflow tooling.
+
+### Changed
+
+- Expanded documentation around public APIs, registry workflow, hosted model
+  visibility, and release metadata.
+- Tightened package exports and release checks for the public package surface.
+
+### Fixed
+
+- Fixed hosted TranslateGemma visibility and registry metadata alignment across
+  docs, demos, and package surfaces.
+- Removed incorrect self-dependency metadata from the published package.
+
+## [0.1.4] - 2026-03-05
+
+### Added
+
+- Added Lean execution contract scripts and related package commands.
+- Added translation prompt validation and quickstart/demo polish.
+
+### Fixed
+
+- Fixed external resolution issues in conversion publication paths.
+- Fixed quickstart-facing package and demo issues ahead of publication.
+
+## [0.1.3] - 2026-03-05
+
+### Changed
+
+- Intermediate package metadata and dependency layout refresh during early npm
+  packaging work.
+
+## [0.1.2] - 2026-03-05
+
+### Changed
+
+- Aligned build scripts, tests, docs, and package conventions with the active
+  workspace and release process.
+- Refined README messaging and compatibility notes before npm publication.
+
+## [0.1.1] - 2026-03-05
+
+### Added
+
+- Added benchmark vendor comparison docs, runtime patch documentation, and
+  refreshed evidence/chart surfaces for the package release.
+
+### Changed
+
+- Moved vendor benchmark dependencies to development dependencies and kept the
+  runtime package dependency surface leaner.
+- Refreshed package metadata, exports, and README/API positioning for the first
+  public npm publishing cycle.
+
+## [0.1.0] - 2025-12-23
+
+### Added
+
+- Initial npm package release for Doppler.
+- Browser and Node command surfaces, CLI entrypoint, loader/storage pipeline,
+  RDRR manifest handling, config schemas/presets, WebGPU kernel registry, text
+  inference pipeline, conversion tooling, benchmark tooling, tests, and demo
+  infrastructure.

package/README.md

@@ -2,13 +2,7 @@
 
 Inference and training on raw WebGPU. Pure JS + WGSL.
 
-**[Live Demo](https://d4da.com)** · **[npm](https://www.npmjs.com/package/@simulatte/doppler)** · **[simulatte.world](https://simulatte.world)**
-
-## Install
-
-```bash
-npm install @simulatte/doppler
-```
+![Phase-latency comparison on one workload across models](https://raw.githubusercontent.com/clocksmith/doppler/main/benchmarks/vendors/results/compare_1b_multi-workload_favorable_phases.svg)
 
 ## Quick start
 
@@ -17,13 +11,25 @@ import { doppler } from '@simulatte/doppler';
 
 const model = await doppler.load('gemma3-270m');
 
-for await (const token of model.generate('Hello, world')) {
+for await (const token of model.generate('Describe WebGPU briefly')) {
   process.stdout.write(token);
 }
 ```
 
+Browser-first WebGPU inference and training with explicit manifest-driven
+runtime behavior. Built for local models, streamed generation, adapter
+hot-swap, and direct JS → WGSL → WebGPU execution.
+
 Registry IDs resolve to hosted RDRR artifacts from `Clocksmith/rdrr` by default. Tokens stream from a native `AsyncGenerator`. See [more examples](#more-examples) below or the canonical [Root API guide](https://github.com/clocksmith/doppler/blob/main/docs/api/root.md).
 
+## Install
+
+```bash
+npm install @simulatte/doppler
+```
+
+**[Live Demo](https://d4da.com)** · **[npm](https://www.npmjs.com/package/@simulatte/doppler)** · **[docs](https://github.com/clocksmith/doppler/blob/main/docs/INDEX.md)** · **[Project site](https://simulatte.world)**
+
 ## Why Doppler
 
 **JS → WGSL → WebGPU.** Direct JavaScript orchestration into native WebGPU kernels, avoiding ONNX runtimes, WASM blobs, and bridge layers.
@@ -36,8 +42,6 @@ Registry IDs resolve to hosted RDRR artifacts from `Clocksmith/rdrr` by default.
 
 ## Evidence
 
-![Phase-latency comparison on one workload across models](https://raw.githubusercontent.com/clocksmith/doppler/main/benchmarks/vendors/results/compare_1b_multi-workload_favorable_phases.svg)
-
 Snapshot artifacts:
 - [g3-1b-p064-d064-t0-k1.compare.json](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/fixtures/g3-1b-p064-d064-t0-k1.compare.json)
 - [lfm2-5-1-2b-p064-d064-t0-k1.compare.json](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/fixtures/lfm2-5-1-2b-p064-d064-t0-k1.compare.json)
@@ -83,19 +87,8 @@ for await (const token of doppler('Hello', { model: 'gemma3-270m' })) {
 - Architecture: [docs/architecture.md](https://github.com/clocksmith/doppler/blob/main/docs/architecture.md)
 - Generated model support table: [docs/model-support-matrix.md](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md)
 
-## Current model support
-
-Verified right now:
-- `gemma-3-270m-it-wq4k-ef16-hf16`
-- `gemma-3-1b-it-wq4k-ef16-hf16`
-- `google-embeddinggemma-300m-wq4k-ef16`
-- `translategemma-4b-it-wq4k-ef16-hf16`
-
-Known failing right now:
-- `qwen-3-5-0-8b-wq4k-ef16-hf16-f16`
-- `qwen-3-5-2b-wq4k-ef16-hf16-f16`
-
-For the generated status table, including `loads but unverified` and `everything else`, see [docs/model-support-matrix.md](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md).
+Current model support is generated from the catalog and conversion registry.
+See [docs/model-support-matrix.md](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md) for the canonical verified, failing, and unverified status table.
 
 ## Environment requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simulatte/doppler",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Browser-native WebGPU inference engine for local intent and inference loops",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -54,6 +54,8 @@
     "api:docs:sync": "node tools/sync-api-docs.js",
     "api:docs:check": "node tools/sync-api-docs.js --check",
     "verify:model": "node tools/doppler-cli.js verify",
+    "quickstart:sync": "node tools/sync-quickstart-registry.js",
+    "quickstart:check": "node tools/sync-quickstart-registry.js --check",
     "onboarding:check": "node tools/onboarding-tooling.js check",
     "onboarding:check:strict": "node tools/onboarding-tooling.js check --strict",
     "onboarding:scaffold": "node tools/onboarding-tooling.js scaffold",
@@ -73,12 +75,21 @@
     "external:rdrr:index": "node tools/sync-external-rdrr-index.js",
     "external:rdrr:index:check": "node tools/sync-external-rdrr-index.js --check",
     "verify:embeddinggemma-300m": "node tools/run-registry-verify.js embeddinggemma-300m",
+    "verify:gemma-3-1b-it-f16": "node tools/run-registry-verify.js gemma-3-1b-it-f16",
+    "verify:gemma-3-1b-it-f16-af32": "node tools/run-registry-verify.js gemma-3-1b-it-f16-af32",
+    "verify:gemma-3-1b-it-q4k-ehf16-af32": "node tools/run-registry-verify.js gemma-3-1b-it-q4k-ehf16-af32",
+    "verify:gemma-3-1b-it-wq4k-ef16-hf16": "node tools/run-registry-verify.js gemma-3-1b-it-wq4k-ef16-hf16",
+    "verify:gemma-3-270m-it-q4k-ehf16-af32": "node tools/run-registry-verify.js gemma-3-270m-it-q4k-ehf16-af32",
     "verify:gemma-3-270m-it-wq4k-ef16": "node tools/run-registry-verify.js gemma-3-270m-it-wq4k-ef16",
     "verify:gemma-3-270m-it-wq4k-ef16-hf16": "node tools/run-registry-verify.js gemma-3-270m-it-wq4k-ef16-hf16",
     "verify:gemma-3-270m-it-wq4k-ef16-hf16-f32": "node tools/run-registry-verify.js gemma-3-270m-it-wq4k-ef16-hf16-f32",
+    "verify:gemma3-1b": "node tools/run-registry-verify.js gemma3-1b",
+    "verify:gemma3-1b-f16": "node tools/run-registry-verify.js gemma3-1b-f16",
     "verify:gemma3-270m": "node tools/run-registry-verify.js gemma3-270m",
     "verify:google-embeddinggemma-300m": "node tools/run-registry-verify.js google-embeddinggemma-300m",
+    "verify:google-embeddinggemma-300m-q4k-ehf16-af32": "node tools/run-registry-verify.js google-embeddinggemma-300m-q4k-ehf16-af32",
     "verify:google-embeddinggemma-300m-wq4k-ef16": "node tools/run-registry-verify.js google-embeddinggemma-300m-wq4k-ef16",
+    "verify:google-gemma-3-1b-it": "node tools/run-registry-verify.js google-gemma-3-1b-it",
     "verify:google-gemma-3-270m-it": "node tools/run-registry-verify.js google-gemma-3-270m-it",
     "verify:google-translategemma-4b-it": "node tools/run-registry-verify.js google-translategemma-4b-it",
     "verify:qwen-3-5-0-8b": "node tools/run-registry-verify.js qwen-3-5-0-8b",
@@ -104,6 +115,7 @@
     },
     "./tooling": {
       "types": "./src/tooling-exports.d.ts",
+      "browser": "./src/tooling-exports.browser.js",
       "import": "./src/tooling-exports.js"
     },
     "./internal": {
@@ -149,6 +161,7 @@
     "src",
     "src/gpu/kernels/*.wgsl",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE",
     "BRANDING.md",

package/src/adapters/adapter-registry.js

@@ -9,6 +9,12 @@ import { DEFAULT_ADAPTER_REGISTRY_CONFIG } from '../config/schema/index.js';
 
 const { dbName: DB_NAME, dbVersion: DB_VERSION, storeName: STORE_NAME } = DEFAULT_ADAPTER_REGISTRY_CONFIG;
 
+function isNodeRuntime() {
+  return typeof process !== 'undefined'
+    && !!process.versions?.node
+    && typeof window === 'undefined';
+}
+
 
 class IndexedDBStorage {
   #db = null;
@@ -163,8 +169,13 @@ export class AdapterRegistry {
       this.#storage = storage;
     } else if (typeof indexedDB !== 'undefined') {
       this.#storage = new IndexedDBStorage();
-    } else {
+    } else if (isNodeRuntime()) {
       this.#storage = new MemoryStorage();
+    } else {
+      throw new Error(
+        'AdapterRegistry requires IndexedDB in browser environments. ' +
+        'Pass explicit storage or use createMemoryRegistry() for tests.'
+      );
     }
   }
 

package/src/adapters/lora-loader.js

@@ -82,6 +82,20 @@ async function computeSHA256(data) {
   return Array.from(hashArray).map(b => b.toString(16).padStart(2, '0')).join('');
 }
 
+function assertCompleteAdapterLayers(adapter) {
+  for (const [layerIndex, layer] of adapter.layers.entries()) {
+    for (const [moduleName, weights] of Object.entries(layer)) {
+      const hasA = weights?.a instanceof Float32Array && weights.a.length > 0;
+      const hasB = weights?.b instanceof Float32Array && weights.b.length > 0;
+      if (!hasA || !hasB) {
+        throw new Error(
+          `LoRA adapter layer ${layerIndex} module ${moduleName} is incomplete; both lora_a and lora_b tensors are required.`
+        );
+      }
+    }
+  }
+}
+
 // ============================================================================
 // Core Loading Functions
 // ============================================================================
@@ -156,14 +170,14 @@ export async function loadLoRAWeights(path, options = {}) {
   if (manifest.checksum && !options.skipVerify) {
     const algorithm = manifest.checksumAlgorithm;
     if (algorithm !== 'sha256') {
-      log.warn('LoRA', `Unsupported checksum algorithm: ${algorithm}, skipping verification`);
+      throw new Error(`Unsupported LoRA checksum algorithm: ${algorithm}`);
     } else if (manifest.weightsPath) {
       // Compute checksum of the weights file
       const weightsData = await fetchWithBase(manifest.weightsPath);
       const computedHash = await computeSHA256(weightsData);
       checksumValid = computedHash.toLowerCase() === manifest.checksum.toLowerCase();
       if (!checksumValid) {
-        log.warn('LoRA', `Checksum mismatch: expected ${manifest.checksum}, got ${computedHash}`);
+        throw new Error(`LoRA checksum mismatch: expected ${manifest.checksum}, got ${computedHash}`);
       }
     } else if (manifest.tensors && manifest.tensors.length > 0) {
       // For inline tensors, compute checksum over concatenated tensor data
@@ -187,7 +201,7 @@ export async function loadLoRAWeights(path, options = {}) {
         const computedHash = await computeSHA256(combined.buffer);
         checksumValid = computedHash.toLowerCase() === manifest.checksum.toLowerCase();
         if (!checksumValid) {
-          log.warn('LoRA', `Checksum mismatch: expected ${manifest.checksum}, got ${computedHash}`);
+          throw new Error(`LoRA checksum mismatch: expected ${manifest.checksum}, got ${computedHash}`);
         }
       }
     }
@@ -223,8 +237,7 @@ export async function loadLoRAFromManifest(manifest, options = {}) {
   for (const tensor of tensors) {
     const parsed = parseTensorName(tensor.name);
     if (!parsed) {
-      log.warn('LoRA', `Skipping unrecognized tensor: ${tensor.name}`);
-      continue;
+      throw new Error(`Unrecognized LoRA tensor name: ${tensor.name}`);
     }
 
     const data = await toFloat32Array(tensor, options);
@@ -257,6 +270,7 @@ export async function loadLoRAFromManifest(manifest, options = {}) {
     }
   }
 
+  assertCompleteAdapterLayers(adapter);
   return adapter;
 }
 
@@ -312,7 +326,9 @@ export async function loadLoRAFromSafetensors(data, manifest) {
     if (tensorName === '__metadata__') continue;
 
     const parsed = parseTensorName(tensorName);
-    if (!parsed) continue;
+    if (!parsed) {
+      throw new Error(`Unrecognized LoRA safetensors tensor name: ${tensorName}`);
+    }
 
     const [start, end] = tensorInfo.data_offsets;
     const tensorData = new Uint8Array(data, dataOffset + start, end - start);
@@ -359,6 +375,7 @@ export async function loadLoRAFromSafetensors(data, manifest) {
     adapter.layers.set(parsed.layer, layer);
   }
 
+  assertCompleteAdapterLayers(adapter);
   return adapter;
 }
 

package/src/bridge/extension-client.d.ts

@@ -90,6 +90,11 @@ export declare class ExtensionBridgeClient {
    */
   getStatus(): BridgeStatusType;
 
+  /**
+   * Get the connected extension target, if any.
+   */
+  getExtensionId(): string | null;
+
   /**
    * Check if connected
    */

package/src/bridge/extension-client.js

@@ -64,6 +64,16 @@ export class ExtensionBridgeClient {
       throw new Error('Chrome extension API not available');
     }
 
+    if (this.#status === BridgeStatus.CONNECTING) {
+      throw new Error('Bridge client connection already in progress');
+    }
+    if (this.#status === BridgeStatus.CONNECTED) {
+      if ((extensionId ?? null) !== this.#extensionId) {
+        throw new Error('Bridge client already connected to a different extension target');
+      }
+      return;
+    }
+
     this.#extensionId = extensionId;
     this.#status = BridgeStatus.CONNECTING;
     this.#notifyStatusChange();
@@ -209,6 +219,11 @@ export class ExtensionBridgeClient {
 
   
   #handleMessage(message) {
+    if (message?.type === 'error') {
+      this.#handleExplicitError(message);
+      return;
+    }
+
     if (message.type !== 'binary' || !message.data) {
       log.warn('ExtensionBridge', `Unexpected message type: ${message.type}`);
       return;
@@ -308,6 +323,27 @@ export class ExtensionBridgeClient {
     }
   }
 
+  #handleExplicitError(message) {
+    const text = typeof message?.message === 'string' && message.message.length > 0
+      ? message.message
+      : 'Native bridge error';
+    const error = new Error(text);
+
+    this.#port = null;
+    this.#status = BridgeStatus.ERROR;
+    this.#notifyStatusChange();
+
+    for (const [, pending] of this.#pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    }
+    this.#pendingRequests.clear();
+
+    if (this.onError) {
+      this.onError(error);
+    }
+  }
+
   
   #handleDisconnect() {
     const error = chrome.runtime?.lastError;
@@ -340,6 +376,10 @@ export class ExtensionBridgeClient {
     return this.#status;
   }
 
+  getExtensionId() {
+    return this.#extensionId;
+  }
+
   
   isConnected() {
     return this.#status === BridgeStatus.CONNECTED;

package/src/bridge/index.d.ts

@@ -64,5 +64,6 @@ export declare function createBridgeClient(
 export declare function readFileNative(
   path: string,
   offset?: number,
-  length?: number
+  length?: number,
+  extensionId?: string | null
 ): Promise<Uint8Array>;

package/src/bridge/index.js

@@ -27,24 +27,26 @@ export {
 
 
 export async function createBridgeClient(extensionId = null) {
-  const { ExtensionBridgeClient, isBridgeAvailable } = await import('./extension-client.js');
+  const { getBridgeClient, isBridgeAvailable } = await import('./extension-client.js');
 
   if (!isBridgeAvailable()) {
     throw new Error('Native bridge not available - Chrome extension API required');
   }
 
-  const client = new ExtensionBridgeClient();
+  const client = getBridgeClient();
   await client.connect(extensionId);
   return client;
 }
 
 
-export async function readFileNative(path, offset = 0, length = 0) {
+export async function readFileNative(path, offset = 0, length = 0, extensionId = null) {
   const { getBridgeClient } = await import('./extension-client.js');
   const client = getBridgeClient();
 
   if (!client.isConnected()) {
-    await client.connect();
+    await client.connect(extensionId);
+  } else if ((extensionId ?? null) !== (client.getExtensionId?.() ?? null)) {
+    throw new Error('Bridge client already connected to a different extension target');
   }
 
   return client.read(path, offset, length);

package/src/browser/browser-converter.js

@@ -160,6 +160,18 @@ function normalizePath(path) {
   return String(path || '').replace(/\\/g, '/');
 }
 
+function attachRelativePath(file, relativePath) {
+  if (!file || !relativePath) return;
+  try {
+    Object.defineProperty(file, 'relativePath', {
+      value: relativePath,
+      configurable: true,
+    });
+  } catch {
+    // Ignore if File is non-extensible in this environment.
+  }
+}
+
 function getBaseName(path) {
   const normalized = normalizePath(path);
   if (!normalized) return '';
@@ -924,8 +936,16 @@ export async function pickModelFiles() {
 
 async function collectFilesFromDirectory(
   dirHandle,
-  files = []
+  files = [],
+  basePath = '',
+  depth = 0
 ) {
+  if (depth > 4) {
+    throw new Error(
+      `Model directory exceeds supported depth (4) near "${basePath || dirHandle?.name || '.'}". ` +
+      'Choose a shallower directory root or flatten the model files.'
+    );
+  }
   const entries = dirHandle.values();
   for await (const entry of entries) {
     if (entry.kind === 'file') {
@@ -937,8 +957,13 @@ async function collectFilesFromDirectory(
         file.name.endsWith('.json') ||
         file.name === 'tokenizer.model'
       ) {
+        const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        attachRelativePath(file, relativePath);
         files.push(file);
       }
+    } else if (entry.kind === 'directory') {
+      const nextBasePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+      await collectFilesFromDirectory(entry, files, nextBasePath, depth + 1);
     }
   }
   return files;

package/src/browser/file-picker.js

@@ -140,6 +140,12 @@ async function collectModelFilesFromDirectory(
       const nextBasePath = basePath ? `${basePath}/${entry.name}` : entry.name;
       const subFiles = await collectModelFilesFromDirectory(subDirHandle, nextBasePath, maxDepth - 1);
       files.push(...subFiles);
+    } else if (entry.kind === 'directory') {
+      const nextBasePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+      throw new Error(
+        `Model directory exceeds supported depth (${MODEL_DIRECTORY_MAX_DEPTH}) near "${nextBasePath}". ` +
+        'Choose a shallower directory root or flatten the model files.'
+      );
     }
   }
 

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);
   }