@simulatte/doppler 0.1.6 → 0.1.7

package/src/tooling/node-source-runtime.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import {
   HEADER_READ_SIZE,
   createConverterConfig,
+  DEFAULT_EXECUTION_V0_SESSION_DEFAULTS,
 } from '../config/schema/index.js';
 import { extractArchitecture } from '../converter/core.js';
 import {
@@ -15,6 +16,7 @@ import { parseTransformerModel } from '../converter/parsers/transformer.js';
 import { parseGGUFHeader } from '../formats/gguf/types.js';
 import { parseSafetensorsHeader } from '../formats/safetensors/types.js';
 import { log } from '../debug/index.js';
+import { computeHash } from '../storage/shard-manager.js';
 import {
   buildSourceRuntimeBundle,
   createSourceStorageContext,
@@ -33,6 +35,13 @@ const SOURCE_RUNTIME_EXECUTION_OVERRIDE = {
   steps: [],
 };
 
+function cloneExecutionV0SessionDefaults() {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(DEFAULT_EXECUTION_V0_SESSION_DEFAULTS);
+  }
+  return JSON.parse(JSON.stringify(DEFAULT_EXECUTION_V0_SESSION_DEFAULTS));
+}
+
 function toArrayBuffer(value, label) {
   if (value instanceof ArrayBuffer) {
     return value;
@@ -105,6 +114,16 @@ async function readJson(filePath, label) {
   }
 }
 
+async function readFileBytes(filePath, label) {
+  try {
+    const bytes = await fs.readFile(filePath);
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read ${label} "${filePath}": ${message}`);
+  }
+}
+
 async function readRange(filePath, offset, length) {
   if (!Number.isFinite(offset) || !Number.isFinite(length) || length <= 0) {
     return new ArrayBuffer(0);
@@ -206,6 +225,37 @@ async function parseSafetensorsInput(inputDir) {
     const stats = await getPathStats(sourcePath, `source shard (${sourcePath})`);
     sourceFiles.push({ path: sourcePath, size: Number(stats.size) });
   }
+  const auxiliaryFiles = [
+    { path: configPath, size: Number((await getPathStats(configPath, 'config.json')).size), kind: 'config' },
+    ...(hasIndex
+      ? [{
+        path: path.join(inputDir, 'model.safetensors.index.json'),
+        size: Number((await getPathStats(path.join(inputDir, 'model.safetensors.index.json'), 'model.safetensors.index.json')).size),
+        kind: 'safetensors_index',
+      }]
+      : []),
+    ...(tokenizerJson
+      ? [{
+        path: tokenizerJsonPath,
+        size: Number((await getPathStats(tokenizerJsonPath, 'tokenizer.json')).size),
+        kind: 'tokenizer_json',
+      }]
+      : []),
+    ...(tokenizerConfig
+      ? [{
+        path: tokenizerConfigPath,
+        size: Number((await getPathStats(tokenizerConfigPath, 'tokenizer_config.json')).size),
+        kind: 'tokenizer_config',
+      }]
+      : []),
+    ...(hasTokenizerModel
+      ? [{
+        path: tokenizerModelPath,
+        size: Number((await getPathStats(tokenizerModelPath, 'tokenizer.model')).size),
+        kind: 'tokenizer_model',
+      }]
+      : []),
+  ];
 
   return {
     sourceKind: 'safetensors',
@@ -220,8 +270,10 @@ async function parseSafetensorsInput(inputDir) {
     tokenizerConfig,
     tokenizerModelName: hasTokenizerModel ? 'tokenizer.model' : null,
     tokenizerJsonPath: tokenizerJsonPath,
+    tokenizerConfigPath: tokenizerConfigPath,
     tokenizerModelPath: hasTokenizerModel ? tokenizerModelPath : null,
     sourceFiles,
+    auxiliaryFiles,
   };
 }
 
@@ -283,8 +335,10 @@ async function parseGgufInput(ggufPath) {
     tokenizerConfig: null,
     tokenizerModelName: null,
     tokenizerJsonPath: null,
+    tokenizerConfigPath: null,
     tokenizerModelPath: null,
     sourceFiles: [{ path: ggufPath, size: fileSize }],
+    auxiliaryFiles: [],
   };
 }
 
@@ -357,11 +411,29 @@ function buildNodeFileReaders() {
   };
 }
 
+async function addHashesToFileEntries(entries, hashAlgorithm) {
+  const normalized = [];
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const filePath = normalizePath(entry?.path);
+    if (!filePath) continue;
+    const bytes = await readFileBytes(filePath, `source asset (${filePath})`);
+    normalized.push({
+      ...entry,
+      path: filePath,
+      size: Number.isFinite(entry?.size) ? Math.max(0, Math.floor(Number(entry.size))) : bytes.byteLength,
+      hash: await computeHash(new Uint8Array(bytes), hashAlgorithm),
+      hashAlgorithm,
+    });
+  }
+  return normalized;
+}
+
 export async function resolveNodeSourceRuntimeBundle(options = {}) {
   const inputPath = normalizePath(options.inputPath);
   if (!inputPath) {
     throw new Error('node source runtime: inputPath is required.');
   }
+  const verifyHashes = options.verifyHashes === true;
   const resolvedInputPath = path.resolve(inputPath);
   const stats = await getPathStats(resolvedInputPath, 'inputPath');
 
@@ -405,6 +477,7 @@ export async function resolveNodeSourceRuntimeBundle(options = {}) {
       modelBaseId: options.modelId || null,
     },
     inference: {
+      sessionDefaults: cloneExecutionV0SessionDefaults(),
       execution: SOURCE_RUNTIME_EXECUTION_OVERRIDE,
     },
   });
@@ -425,22 +498,30 @@ export async function resolveNodeSourceRuntimeBundle(options = {}) {
     parsed.sourceKind,
     parsed.sourcePathForModelId
   );
+  const hashAlgorithm = converterConfig.manifest.hashAlgorithm;
+  const sourceFiles = await addHashesToFileEntries(parsed.sourceFiles, hashAlgorithm);
+  const auxiliaryFiles = await addHashesToFileEntries(parsed.auxiliaryFiles, hashAlgorithm);
   const { manifest, shardSources } = await buildSourceRuntimeBundle({
     modelId,
     modelName: modelId,
     modelType: plan.modelType,
+    sourceKind: parsed.sourceKind,
     architecture: parsed.architecture,
     architectureHint: parsed.architectureHint,
     rawConfig: parsed.config,
     inference: plan.manifestInference,
     tensors: parsed.tensors,
-    sourceFiles: parsed.sourceFiles,
+    sourceFiles,
+    auxiliaryFiles,
     sourceQuantization: parsed.sourceQuantization,
     quantizationInfo: plan.quantizationInfo,
-    hashAlgorithm: converterConfig.manifest.hashAlgorithm,
+    hashAlgorithm,
     tokenizerJson: parsed.tokenizerJson,
     tokenizerConfig: parsed.tokenizerConfig,
     tokenizerModelName: parsed.tokenizerModelName,
+    tokenizerJsonPath: parsed.tokenizerJsonPath,
+    tokenizerConfigPath: parsed.tokenizerConfigPath,
+    tokenizerModelPath: parsed.tokenizerModelPath,
   });
 
   const readers = buildNodeFileReaders();
@@ -452,7 +533,7 @@ export async function resolveNodeSourceRuntimeBundle(options = {}) {
     readBinary: readers.readBinary,
     tokenizerJsonPath: parsed.tokenizerJsonPath,
     tokenizerModelPath: parsed.tokenizerModelPath,
-    verifyHashes: false,
+    verifyHashes,
   });
 
   log.info(

package/src/tooling/node-webgpu.js

@@ -3,9 +3,12 @@ import { dirname, isAbsolute, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const DEFAULT_DOE_PROVIDER_CREATE_ARGS = 'enable-dawn-features=allow_unsafe_apis';
+const DOE_PROVIDER_CREATE_ARGS_ENV = 'FAWN_WEBGPU_CREATE_ARGS';
 
 function hasNavigatorGpu() {
-  return typeof globalThis.navigator !== 'undefined' && !!globalThis.navigator?.gpu;
+  return typeof globalThis.navigator !== 'undefined'
+    && !!globalThis.navigator?.gpu
+    && typeof globalThis.navigator.gpu.requestAdapter === 'function';
 }
 
 function hasGpuEnums() {
@@ -51,18 +54,12 @@ function resolveDefaultWebgpuModuleSpecifiers() {
   return ['@simulatte/webgpu', 'webgpu'];
 }
 
-function resolveWebgpuModuleSpecifiers() {
+function resolveExplicitWebgpuModuleSpecifier() {
   const fromEnv = process.env.DOPPLER_NODE_WEBGPU_MODULE;
   if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
-    return {
-      explicit: true,
-      specifiers: [resolveCandidateModuleSpecifier(fromEnv.trim())],
-    };
+    return resolveCandidateModuleSpecifier(fromEnv.trim());
   }
-  return {
-    explicit: false,
-    specifiers: resolveDefaultWebgpuModuleSpecifiers(),
-  };
+  return null;
 }
 
 function isDoeWebgpuSpecifier(specifier) {
@@ -76,15 +73,15 @@ function isDoeWebgpuSpecifier(specifier) {
 
 async function importWithProviderOverride(specifier) {
   const shouldApplyCreateArgsDefault = isDoeWebgpuSpecifier(specifier)
-    && !(typeof process.env.FAWN_WEBGPU_CREATE_ARGS === 'string' && process.env.FAWN_WEBGPU_CREATE_ARGS.trim().length > 0);
+    && !(typeof process.env[DOE_PROVIDER_CREATE_ARGS_ENV] === 'string' && process.env[DOE_PROVIDER_CREATE_ARGS_ENV].trim().length > 0);
   if (!shouldApplyCreateArgsDefault) {
     return import(specifier);
   }
-  process.env.FAWN_WEBGPU_CREATE_ARGS = DEFAULT_DOE_PROVIDER_CREATE_ARGS;
+  process.env[DOE_PROVIDER_CREATE_ARGS_ENV] = DEFAULT_DOE_PROVIDER_CREATE_ARGS;
   try {
     return await import(specifier);
   } finally {
-    delete process.env.FAWN_WEBGPU_CREATE_ARGS;
+    delete process.env[DOE_PROVIDER_CREATE_ARGS_ENV];
   }
 }
 
@@ -237,27 +234,33 @@ function installWebgpuFromModule(mod) {
 }
 
 export async function bootstrapNodeWebGPU() {
+  const explicitSpecifier = resolveExplicitWebgpuModuleSpecifier();
+  if (explicitSpecifier) {
+    try {
+      const mod = await importWithProviderOverride(explicitSpecifier);
+      if (installWebgpuFromModule(mod)) {
+        return { ok: true, provider: explicitSpecifier };
+      }
+      return { ok: false, provider: explicitSpecifier };
+    } catch {
+      return { ok: false, provider: explicitSpecifier };
+    }
+  }
+
   if (hasNavigatorGpu() && hasGpuEnums()) {
     return { ok: true, provider: 'pre-installed' };
   }
 
-  const { specifiers, explicit } = resolveWebgpuModuleSpecifiers();
-  for (const specifier of specifiers) {
+  for (const specifier of resolveDefaultWebgpuModuleSpecifiers()) {
     let mod;
     try {
       mod = await importWithProviderOverride(specifier);
     } catch {
-      if (explicit) {
-        return { ok: false, provider: null };
-      }
       continue;
     }
     if (installWebgpuFromModule(mod)) {
       return { ok: true, provider: specifier };
     }
-    if (explicit) {
-      return { ok: false, provider: null };
-    }
   }
 
   return { ok: false, provider: null };

package/src/tooling/opfs-cache.js

@@ -8,6 +8,10 @@ import { downloadModel } from '../storage/downloader.js';
 import { isOPFSAvailable } from '../storage/quota.js';
 import { parseManifest, getManifestUrl } from '../formats/rdrr/index.js';
 import { log } from '../debug/index.js';
+import {
+  resolveSourceArtifact,
+  verifyStoredSourceArtifact,
+} from '../storage/source-artifact-store.js';
 
 const MODULE = 'OPFSCache';
 
@@ -43,6 +47,7 @@ function hasSameShardSet(aManifest, bManifest) {
 }
 
 function buildManifestFingerprint(manifest) {
+  const sourceArtifactFingerprint = resolveSourceArtifact(manifest)?.fingerprint ?? null;
   const inference = manifest?.inference ?? {};
   const layerPattern = inference?.layerPattern ?? {};
   const quantizationInfo = manifest?.quantizationInfo ?? {};
@@ -75,6 +80,7 @@ function buildManifestFingerprint(manifest) {
       },
     },
     shards,
+    sourceArtifactFingerprint,
   });
 }
 
@@ -119,16 +125,27 @@ export async function ensureModelCached(modelId, modelBaseUrl) {
         if (!cachedManifestText || !cachedManifest) {
           log.warn(MODULE, `Cache miss: "${modelId}" has no readable manifest in OPFS; re-importing`);
         } else {
+          const cachedSourceArtifact = resolveSourceArtifact(cachedManifest);
+          const sourceIntegrity = cachedSourceArtifact
+            ? await verifyStoredSourceArtifact(cachedManifest, { checkHashes: false })
+            : null;
+          const sourceIntegrityValid = !sourceIntegrity || sourceIntegrity.valid;
+          if (sourceIntegrity && !sourceIntegrity.valid) {
+            log.warn(
+              MODULE,
+              `Cache stale: "${modelId}" direct-source assets are incomplete (${sourceIntegrity.missingFiles.join(', ')})`
+            );
+          }
           const cachedFingerprint = buildManifestFingerprint(cachedManifest);
           const remoteFingerprint = buildManifestFingerprint(remoteManifest);
-          if (cachedFingerprint === remoteFingerprint) {
+          if (sourceIntegrityValid && cachedFingerprint === remoteFingerprint) {
             log.info(MODULE, `Cache hit: "${modelId}"`);
             return { cached: true, fromCache: true, modelId, error: null };
           }
 
           const sameShards = hasSameShardSet(cachedManifest, remoteManifest);
           const sameHashAlgorithm = (cachedManifest?.hashAlgorithm ?? null) === (remoteManifest?.hashAlgorithm ?? null);
-          if (sameShards && sameHashAlgorithm) {
+          if (sourceIntegrityValid && sameShards && sameHashAlgorithm) {
             await openModelStore(modelId);
             await saveManifest(remoteManifestText);
             log.info(MODULE, `Cache manifest refreshed: "${modelId}" (shards unchanged)`);
@@ -138,8 +155,8 @@ export async function ensureModelCached(modelId, modelBaseUrl) {
         }
       } catch (error) {
         const message = toErrorMessage(error);
-        log.warn(MODULE, `Cache validation unavailable (${message}); using cached model "${modelId}"`);
-        return { cached: true, fromCache: true, modelId, error: null };
+        log.warn(MODULE, `Cache validation failed (${message}); refusing cached model "${modelId}"`);
+        return { cached: false, fromCache: false, modelId, error: message };
       }
     }
   } catch (error) {

package/src/tooling/runtime-input-composition.d.ts

@@ -0,0 +1,38 @@
+export interface RuntimeCompositionBridge {
+  getRuntimeConfig: () => Record<string, unknown> | null;
+  setRuntimeConfig: (runtimeConfig: Record<string, unknown> | null) => void;
+}
+
+export interface RuntimeInputCompositionHandlers {
+  loadRuntimeConfigFromRef?: (
+    ref: string,
+    options?: Record<string, unknown>
+  ) => Promise<Record<string, unknown> | null>;
+  applyRuntimePreset?: (
+    runtimePreset: string,
+    options?: Record<string, unknown>
+  ) => Promise<void>;
+  applyRuntimeConfigFromUrl?: (
+    runtimeConfigUrl: string,
+    options?: Record<string, unknown>
+  ) => Promise<void>;
+}
+
+export interface OrderedRuntimeInputs {
+  configChain?: string[] | null;
+  runtimePreset?: string | null;
+  runtimeConfigUrl?: string | null;
+  runtimeConfig?: Record<string, unknown> | null;
+  runtimeContractPatch?: Record<string, unknown> | null | (() => Record<string, unknown> | null);
+}
+
+export declare function resolveRuntimeFromConfig(
+  config: Record<string, unknown> | null | undefined
+): Record<string, unknown> | null;
+
+export declare function applyOrderedRuntimeInputs(
+  runtimeBridge: RuntimeCompositionBridge,
+  inputs?: OrderedRuntimeInputs,
+  handlers?: RuntimeInputCompositionHandlers,
+  options?: Record<string, unknown>
+): Promise<void>;

package/src/tooling/runtime-input-composition.js

@@ -0,0 +1,86 @@
+import { mergeRuntimeValues } from '../config/runtime-merge.js';
+
+export function resolveRuntimeFromConfig(config) {
+  if (!config || typeof config !== 'object') return null;
+  if (config.runtime && typeof config.runtime === 'object') return config.runtime;
+  if (config.shared || config.loading || config.inference || config.emulation) return config;
+  return null;
+}
+
+function mergeRuntimePatch(runtimeBridge, patch) {
+  if (!patch) return;
+  const mergedRuntime = mergeRuntimeValues(runtimeBridge.getRuntimeConfig(), patch);
+  runtimeBridge.setRuntimeConfig(mergedRuntime);
+}
+
+function requireRuntimeBridge(runtimeBridge) {
+  if (!runtimeBridge?.setRuntimeConfig) {
+    throw new Error('runtime bridge must provide setRuntimeConfig().');
+  }
+  if (typeof runtimeBridge.getRuntimeConfig !== 'function') {
+    throw new Error('runtime bridge must provide getRuntimeConfig().');
+  }
+}
+
+async function applyConfigChain(configChain, runtimeBridge, loadRuntimeConfigFromRef, options) {
+  if (!Array.isArray(configChain) || configChain.length === 0) {
+    return;
+  }
+  if (typeof loadRuntimeConfigFromRef !== 'function') {
+    throw new Error('runtime input composition does not support configChain on this surface.');
+  }
+  for (const ref of configChain) {
+    const loaded = await loadRuntimeConfigFromRef(ref, options);
+    const runtime = resolveRuntimeFromConfig(loaded);
+    if (!runtime) {
+      throw new Error(`Loaded runtime config "${ref}" is missing runtime fields.`);
+    }
+    mergeRuntimePatch(runtimeBridge, runtime);
+  }
+}
+
+async function applyRuntimePreset(runtimePreset, applyPreset, options) {
+  if (!runtimePreset) {
+    return;
+  }
+  if (typeof applyPreset !== 'function') {
+    throw new Error('runtime input composition does not support runtimePreset on this surface.');
+  }
+  await applyPreset(runtimePreset, options);
+}
+
+async function applyRuntimeConfigUrl(runtimeConfigUrl, applyConfigFromUrl, options) {
+  if (!runtimeConfigUrl) {
+    return;
+  }
+  if (typeof applyConfigFromUrl !== 'function') {
+    throw new Error('runtime input composition does not support runtimeConfigUrl on this surface.');
+  }
+  await applyConfigFromUrl(runtimeConfigUrl, options);
+}
+
+export async function applyOrderedRuntimeInputs(runtimeBridge, inputs = {}, handlers = {}, options = {}) {
+  requireRuntimeBridge(runtimeBridge);
+
+  await applyConfigChain(
+    inputs.configChain,
+    runtimeBridge,
+    handlers.loadRuntimeConfigFromRef,
+    options
+  );
+  await applyRuntimePreset(inputs.runtimePreset, handlers.applyRuntimePreset, options);
+  await applyRuntimeConfigUrl(inputs.runtimeConfigUrl, handlers.applyRuntimeConfigFromUrl, options);
+
+  if (inputs.runtimeConfig) {
+    const runtime = resolveRuntimeFromConfig(inputs.runtimeConfig);
+    if (!runtime) {
+      throw new Error('runtimeConfig is missing runtime fields');
+    }
+    mergeRuntimePatch(runtimeBridge, runtime);
+  }
+
+  const runtimeContractPatch = typeof inputs.runtimeContractPatch === 'function'
+    ? inputs.runtimeContractPatch()
+    : (inputs.runtimeContractPatch ?? null);
+  mergeRuntimePatch(runtimeBridge, runtimeContractPatch);
+}

package/src/tooling/source-runtime-bundle.d.ts

@@ -3,6 +3,8 @@ import type { RDRRManifest } from '../formats/rdrr/index.js';
 export declare const DIRECT_SOURCE_RUNTIME_MODE: 'direct-source';
 export declare const DIRECT_SOURCE_RUNTIME_SCHEMA_VERSION: 1;
 export declare const DIRECT_SOURCE_RUNTIME_SCHEMA: 'direct-source/v1';
+export declare const DIRECT_SOURCE_PATH_RUNTIME_LOCAL: 'runtime-local';
+export declare const DIRECT_SOURCE_PATH_ARTIFACT_RELATIVE: 'artifact-relative';
 
 export interface SourceRuntimeTensor {
   name: string;
@@ -17,6 +19,9 @@ export interface SourceRuntimeTensor {
 export interface SourceRuntimeFile {
   path: string;
   size: number;
+  hash?: string | null;
+  hashAlgorithm?: string | null;
+  kind?: string | null;
 }
 
 export interface SourceRuntimeShardSource {
@@ -24,18 +29,40 @@ export interface SourceRuntimeShardSource {
   path: string;
   filename: string;
   size: number;
+  hash: string;
+  hashAlgorithm: string;
+}
+
+export interface SourceRuntimeTokenizerMetadata {
+  jsonPath: string | null;
+  configPath: string | null;
+  modelPath: string | null;
+}
+
+export interface SourceRuntimeMetadata {
+  mode: 'direct-source';
+  schema: 'direct-source/v1';
+  schemaVersion: 1;
+  sourceKind: string | null;
+  hashAlgorithm: string;
+  pathSemantics: 'runtime-local' | 'artifact-relative';
+  sourceFiles: SourceRuntimeShardSource[];
+  auxiliaryFiles: SourceRuntimeFile[];
+  tokenizer: SourceRuntimeTokenizerMetadata;
 }
 
 export interface BuildSourceRuntimeBundleOptions {
   modelId: string;
   modelName?: string | null;
   modelType: string;
+  sourceKind?: string | null;
   architecture: Record<string, unknown> | string | null;
   architectureHint?: string | null;
   rawConfig?: Record<string, unknown> | null;
   inference: Record<string, unknown>;
   tensors: SourceRuntimeTensor[];
   sourceFiles?: SourceRuntimeFile[] | null;
+  auxiliaryFiles?: SourceRuntimeFile[] | null;
   resolveSourceSize?: ((path: string) => Promise<number> | number) | null;
   sourceQuantization?: string | null;
   quantizationInfo?: Record<string, unknown> | null;
@@ -44,6 +71,9 @@ export interface BuildSourceRuntimeBundleOptions {
   tokenizerJson?: Record<string, unknown> | null;
   tokenizerConfig?: Record<string, unknown> | null;
   tokenizerModelName?: string | null;
+  tokenizerJsonPath?: string | null;
+  tokenizerConfigPath?: string | null;
+  tokenizerModelPath?: string | null;
   eosTokenId?: number | number[] | null;
   convertedAt?: string | null;
   conversionInfo?: Record<string, unknown> | null;
@@ -58,9 +88,13 @@ export declare function buildSourceRuntimeBundle(
   options: BuildSourceRuntimeBundleOptions
 ): Promise<BuildSourceRuntimeBundleResult>;
 
+export declare function getSourceRuntimeMetadata(
+  manifest: RDRRManifest | Record<string, unknown> | null | undefined
+): SourceRuntimeMetadata | null;
+
 export interface CreateSourceStorageContextOptions {
   manifest: RDRRManifest;
-  shardSources: SourceRuntimeShardSource[];
+  shardSources?: SourceRuntimeShardSource[] | null;
   readRange: (
     path: string,
     offset: number,
@@ -75,23 +109,24 @@ export interface CreateSourceStorageContextOptions {
   readText?: (path: string) => Promise<string | Record<string, unknown> | null | undefined>;
   readBinary?: (path: string) => Promise<ArrayBuffer | Uint8Array>;
   tokenizerJsonPath?: string | null;
+  tokenizerConfigPath?: string | null;
   tokenizerModelPath?: string | null;
   verifyHashes?: boolean;
 }
 
 export interface SourceStorageContext {
   loadShard: (index: number) => Promise<ArrayBuffer | Uint8Array>;
-  loadShardRange: (
+  loadShardRange: ((
     index: number,
     offset?: number,
     length?: number | null
-  ) => Promise<ArrayBuffer | Uint8Array>;
-  streamShardRange: (
+  ) => Promise<ArrayBuffer | Uint8Array>) | null;
+  streamShardRange: ((
     index: number,
     offset?: number,
     length?: number | null,
     options?: { chunkBytes?: number }
-  ) => AsyncIterable<Uint8Array>;
+  ) => AsyncIterable<Uint8Array>) | null;
   loadTokenizerJson: (() => Promise<Record<string, unknown> | null>) | null;
   loadTokenizerModel: ((pathHint?: string) => Promise<ArrayBuffer | null>) | null;
   verifyHashes: boolean;