@simulatte/doppler 0.1.0

package/src/tooling/node-webgpu.js

@@ -0,0 +1,321 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DOPPLER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const DEFAULT_LOCAL_DOE_PROVIDER_PATH = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  '..',
+  'fawn',
+  'nursery',
+  'webgpu-core',
+);
+
+function hasNavigatorGpu() {
+  return typeof globalThis.navigator !== 'undefined' && !!globalThis.navigator?.gpu;
+}
+
+function hasGpuEnums() {
+  return typeof globalThis.GPUBufferUsage !== 'undefined' && typeof globalThis.GPUShaderStage !== 'undefined';
+}
+
+function setGlobalIfMissing(name, value) {
+  if (value === undefined || value === null) return;
+  if (globalThis[name] !== undefined) return;
+  Object.defineProperty(globalThis, name, {
+    value,
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+}
+
+function installGlobalsFromModule(mod) {
+  const globals = mod?.globals;
+  if (!globals || typeof globals !== 'object') return;
+  for (const [name, value] of Object.entries(globals)) {
+    setGlobalIfMissing(name, value);
+  }
+}
+
+function resolveCandidateModuleSpecifier(candidate) {
+  if (candidate.startsWith('file://')) {
+    return candidate;
+  }
+  if (candidate.startsWith('.') || candidate.startsWith('/') || candidate.includes('/')) {
+    const normalizedPath = isAbsolute(candidate)
+      ? candidate
+      : resolve(process.cwd(), candidate);
+    const resolvedFilePath = resolveNodeModuleFilePath(normalizedPath);
+    if (resolvedFilePath) {
+      return pathToFileURL(resolvedFilePath).href;
+    }
+  }
+  return candidate;
+}
+
+function resolveDefaultWebgpuModuleSpecifiers() {
+  const specifiers = [];
+  const localCandidates = [
+    resolve(process.cwd(), '..', 'fawn', 'nursery', 'webgpu-core'),
+    DEFAULT_LOCAL_DOE_PROVIDER_PATH,
+  ];
+  for (const localCandidate of localCandidates) {
+    const resolvedPath = resolveNodeModuleFilePath(localCandidate);
+    if (resolvedPath) {
+      specifiers.push(pathToFileURL(resolvedPath).href);
+    }
+  }
+  specifiers.push('@doe/webgpu-core');
+  specifiers.push('webgpu');
+  return [...new Set(specifiers)];
+}
+
+function resolveWebgpuModuleSpecifiers() {
+  const fromEnv = process.env.DOPPLER_NODE_WEBGPU_MODULE;
+  if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
+    return {
+      explicit: true,
+      specifiers: [resolveCandidateModuleSpecifier(fromEnv.trim())],
+    };
+  }
+  return {
+    explicit: false,
+    specifiers: resolveDefaultWebgpuModuleSpecifiers(),
+  };
+}
+
+function resolveWorkspaceWebgpuProviderPath() {
+  const candidates = [
+    resolve(process.cwd(), 'node_modules', 'webgpu'),
+    resolve(DOPPLER_ROOT, 'node_modules', 'webgpu'),
+  ];
+  for (const candidate of candidates) {
+    const resolvedPath = resolveNodeModuleFilePath(candidate);
+    if (resolvedPath) {
+      return resolvedPath;
+    }
+  }
+  return null;
+}
+
+function isDoeWebgpuCoreSpecifier(specifier) {
+  if (specifier === '@doe/webgpu-core') {
+    return true;
+  }
+  if (typeof specifier !== 'string') {
+    return false;
+  }
+  if (specifier.includes('/webgpu-core/')) {
+    return true;
+  }
+  return specifier.includes('webgpu-core') && specifier.startsWith('file://');
+}
+
+function resolveDoeProviderOverride(specifier) {
+  const explicitProvider = process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE;
+  if (typeof explicitProvider === 'string' && explicitProvider.trim().length > 0) {
+    return null;
+  }
+  if (!isDoeWebgpuCoreSpecifier(specifier)) {
+    return null;
+  }
+  return resolveWorkspaceWebgpuProviderPath();
+}
+
+async function importWithProviderOverride(specifier) {
+  const providerOverride = resolveDoeProviderOverride(specifier);
+  if (!providerOverride) {
+    return import(specifier);
+  }
+  const hadProvider = Object.prototype.hasOwnProperty.call(process.env, 'FAWN_WEBGPU_NODE_PROVIDER_MODULE');
+  const previousProvider = process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE;
+  process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE = providerOverride;
+  try {
+    return await import(specifier);
+  } finally {
+    if (hadProvider) {
+      process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE = previousProvider;
+    } else {
+      delete process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE;
+    }
+  }
+}
+
+function resolveNodeModuleFilePath(candidatePath) {
+  if (!existsSync(candidatePath)) return null;
+  const stat = statSync(candidatePath);
+  if (stat.isFile()) {
+    return candidatePath;
+  }
+  if (!stat.isDirectory()) {
+    return null;
+  }
+  const packageJsonPath = resolve(candidatePath, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+      if (typeof pkg.main === 'string' && pkg.main.trim()) {
+        const mainPath = resolve(candidatePath, pkg.main);
+        if (existsSync(mainPath)) {
+          return mainPath;
+        }
+      }
+      const nodeExportPath = resolveExportsPath(pkg.exports, candidatePath);
+      if (nodeExportPath) {
+        return nodeExportPath;
+      }
+    } catch {
+      // Ignore malformed package.json and fall through to file candidates.
+    }
+  }
+  const fallbackPaths = [
+    resolve(candidatePath, 'index.js'),
+    resolve(candidatePath, 'src/index.js'),
+    resolve(candidatePath, 'src/node-runtime.js'),
+  ];
+  for (const fallbackPath of fallbackPaths) {
+    if (existsSync(fallbackPath)) {
+      return fallbackPath;
+    }
+  }
+  return null;
+}
+
+function resolveExportsPath(exportsField, rootPath) {
+  if (!exportsField) return null;
+  if (typeof exportsField === 'string') {
+    const candidate = resolve(rootPath, exportsField);
+    return existsSync(candidate) ? candidate : null;
+  }
+  if (typeof exportsField !== 'object' || Array.isArray(exportsField)) {
+    return null;
+  }
+  if (typeof exportsField['./node'] === 'string') {
+    const nodePath = resolve(rootPath, exportsField['./node']);
+    if (existsSync(nodePath)) {
+      return nodePath;
+    }
+  }
+  const dot = exportsField['.'];
+  if (typeof dot === 'string') {
+    const dotPath = resolve(rootPath, dot);
+    if (existsSync(dotPath)) {
+      return dotPath;
+    }
+  } else if (dot && typeof dot === 'object') {
+    const preferred = dot.default || dot.node || dot.import;
+    if (typeof preferred === 'string') {
+      const preferredPath = resolve(rootPath, preferred);
+      if (existsSync(preferredPath)) {
+        return preferredPath;
+      }
+    }
+  }
+  return null;
+}
+
+function installNavigatorGpu(gpu) {
+  if (!gpu || typeof gpu.requestAdapter !== 'function') return false;
+  if (typeof globalThis.navigator === 'undefined') {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { gpu },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+    return true;
+  }
+
+  if (!globalThis.navigator.gpu) {
+    Object.defineProperty(globalThis.navigator, 'gpu', {
+      value: gpu,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+  return true;
+}
+
+function resolveGpuFromModule(mod) {
+  if (!mod) return null;
+
+  const fromModule = mod.gpu || mod.webgpu || mod.default?.gpu || mod.default?.webgpu;
+  if (fromModule && typeof fromModule.requestAdapter === 'function') {
+    return fromModule;
+  }
+
+  const factory = mod.create || mod.default?.create;
+  if (typeof factory === 'function') {
+    let created = null;
+    try {
+      created = factory([]);
+    } catch {
+      try {
+        created = factory();
+      } catch {
+        created = null;
+      }
+    }
+    if (created) {
+      if (typeof created.requestAdapter === 'function') {
+        return created;
+      }
+      if (created.gpu && typeof created.gpu.requestAdapter === 'function') {
+        return created.gpu;
+      }
+    }
+  }
+
+  if (mod.default && typeof mod.default.requestAdapter === 'function') {
+    return mod.default;
+  }
+
+  return null;
+}
+
+function installWebgpuFromModule(mod) {
+  const gpu = resolveGpuFromModule(mod);
+  if (!installNavigatorGpu(gpu)) {
+    return false;
+  }
+
+  installGlobalsFromModule(mod);
+  setGlobalIfMissing('GPUBufferUsage', mod.GPUBufferUsage || mod.default?.GPUBufferUsage || mod.globals?.GPUBufferUsage);
+  setGlobalIfMissing('GPUShaderStage', mod.GPUShaderStage || mod.default?.GPUShaderStage || mod.globals?.GPUShaderStage);
+  setGlobalIfMissing('GPUMapMode', mod.GPUMapMode || mod.default?.GPUMapMode || mod.globals?.GPUMapMode);
+  setGlobalIfMissing('GPUTextureUsage', mod.GPUTextureUsage || mod.default?.GPUTextureUsage || mod.globals?.GPUTextureUsage);
+
+  return hasNavigatorGpu() && hasGpuEnums();
+}
+
+export async function bootstrapNodeWebGPU() {
+  if (hasNavigatorGpu() && hasGpuEnums()) {
+    return { ok: true, provider: 'pre-installed' };
+  }
+
+  const { specifiers, explicit } = resolveWebgpuModuleSpecifiers();
+  for (const specifier of specifiers) {
+    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.d.ts

@@ -0,0 +1,11 @@
+export interface EnsureModelCachedResult {
+  cached: boolean;
+  fromCache: boolean;
+  modelId: string;
+  error: string | null;
+}
+
+export declare function ensureModelCached(
+  modelId: string,
+  modelBaseUrl: string
+): Promise<EnsureModelCachedResult>;

package/src/tooling/opfs-cache.js

@@ -0,0 +1,174 @@
+import {
+  modelExists,
+  openModelStore,
+  loadManifestFromStore,
+  saveManifest,
+} from '../storage/shard-manager.js';
+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';
+
+const MODULE = 'OPFSCache';
+
+function toErrorMessage(error) {
+  if (error instanceof Error && typeof error.message === 'string' && error.message.length > 0) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function normalizeShardDescriptor(shard) {
+  return {
+    filename: typeof shard?.filename === 'string' ? shard.filename : null,
+    size: Number.isFinite(shard?.size) ? shard.size : null,
+    hash: typeof shard?.hash === 'string' ? shard.hash : null,
+  };
+}
+
+function hasSameShardSet(aManifest, bManifest) {
+  const aShards = Array.isArray(aManifest?.shards) ? aManifest.shards : [];
+  const bShards = Array.isArray(bManifest?.shards) ? bManifest.shards : [];
+  if (aShards.length !== bShards.length) {
+    return false;
+  }
+  for (let i = 0; i < aShards.length; i += 1) {
+    const a = normalizeShardDescriptor(aShards[i]);
+    const b = normalizeShardDescriptor(bShards[i]);
+    if (a.filename !== b.filename || a.size !== b.size || a.hash !== b.hash) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function buildManifestFingerprint(manifest) {
+  const inference = manifest?.inference ?? {};
+  const layerPattern = inference?.layerPattern ?? {};
+  const quantizationInfo = manifest?.quantizationInfo ?? {};
+  const shards = Array.isArray(manifest?.shards)
+    ? manifest.shards.map(normalizeShardDescriptor)
+    : [];
+  return JSON.stringify({
+    modelId: manifest?.modelId ?? null,
+    modelHash: manifest?.modelHash ?? null,
+    hashAlgorithm: manifest?.hashAlgorithm ?? null,
+    quantization: manifest?.quantization ?? null,
+    quantizationInfo: {
+      weights: quantizationInfo.weights ?? null,
+      embeddings: quantizationInfo.embeddings ?? null,
+      compute: quantizationInfo.compute ?? null,
+      variantTag: quantizationInfo.variantTag ?? null,
+      layout: quantizationInfo.layout ?? null,
+    },
+    inference: {
+      presetId: inference.presetId ?? null,
+      defaultKernelPath: inference.defaultKernelPath ?? null,
+      layerPattern: {
+        type: layerPattern.type ?? null,
+        globalPattern: layerPattern.globalPattern ?? null,
+        period: layerPattern.period ?? null,
+        offset: layerPattern.offset ?? null,
+        layerTypes: Array.isArray(layerPattern.layerTypes)
+          ? [...layerPattern.layerTypes]
+          : null,
+      },
+    },
+    shards,
+  });
+}
+
+async function fetchRemoteManifest(modelBaseUrl) {
+  const manifestUrl = getManifestUrl(modelBaseUrl);
+  const response = await fetch(manifestUrl, { cache: 'no-store' });
+  if (!response.ok) {
+    throw new Error(`manifest fetch failed (${response.status})`);
+  }
+  const text = await response.text();
+  return { text, manifest: parseManifest(text) };
+}
+
+async function loadCachedManifest(modelId) {
+  await openModelStore(modelId);
+  const text = await loadManifestFromStore();
+  if (!text) {
+    return { text: null, manifest: null };
+  }
+  return { text, manifest: parseManifest(text) };
+}
+
+export async function ensureModelCached(modelId, modelBaseUrl) {
+  if (!modelId || !modelBaseUrl) {
+    return { cached: false, fromCache: false, modelId, error: 'missing-args' };
+  }
+
+  if (!isOPFSAvailable()) {
+    log.warn(MODULE, 'OPFS not available in this browser');
+    return { cached: false, fromCache: false, modelId, error: 'opfs-unavailable' };
+  }
+
+  try {
+    const exists = await modelExists(modelId);
+    if (exists) {
+      try {
+        const [{ text: remoteManifestText, manifest: remoteManifest }, { text: cachedManifestText, manifest: cachedManifest }] = await Promise.all([
+          fetchRemoteManifest(modelBaseUrl),
+          loadCachedManifest(modelId),
+        ]);
+
+        if (!cachedManifestText || !cachedManifest) {
+          log.warn(MODULE, `Cache miss: "${modelId}" has no readable manifest in OPFS; re-importing`);
+        } else {
+          const cachedFingerprint = buildManifestFingerprint(cachedManifest);
+          const remoteFingerprint = buildManifestFingerprint(remoteManifest);
+          if (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) {
+            await openModelStore(modelId);
+            await saveManifest(remoteManifestText);
+            log.info(MODULE, `Cache manifest refreshed: "${modelId}" (shards unchanged)`);
+            return { cached: true, fromCache: false, modelId, error: null };
+          }
+          log.info(MODULE, `Cache stale: "${modelId}" manifest/shards changed; re-importing`);
+        }
+      } 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 };
+      }
+    }
+  } catch (error) {
+    const message = toErrorMessage(error);
+    log.warn(MODULE, `Cache check failed: ${message}`);
+    return { cached: false, fromCache: false, modelId, error: message };
+  }
+
+  log.info(MODULE, `Cache miss: "${modelId}". Importing from ${modelBaseUrl}...`);
+
+  try {
+    const success = await downloadModel(modelBaseUrl, (progress) => {
+      if (!progress) return;
+      const shard = Number.isFinite(progress.completedShards) ? progress.completedShards : '?';
+      const total = Number.isFinite(progress.totalShards) ? progress.totalShards : '?';
+      const mb = Number.isFinite(progress.downloadedBytes)
+        ? (progress.downloadedBytes / (1024 * 1024)).toFixed(1)
+        : '?';
+      log.verbose(MODULE, `Shard ${shard}/${total} (${mb} MB)`);
+    });
+
+    if (success) {
+      log.info(MODULE, `Import complete: "${modelId}"`);
+      return { cached: true, fromCache: false, modelId, error: null };
+    }
+    return { cached: false, fromCache: false, modelId, error: 'download-incomplete' };
+  } catch (error) {
+    const message = toErrorMessage(error);
+    log.error(MODULE, `Import failed: ${message}`);
+    return { cached: false, fromCache: false, modelId, error: message };
+  }
+}

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

@@ -0,0 +1,102 @@
+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 interface SourceRuntimeTensor {
+  name: string;
+  shape: number[];
+  dtype: string;
+  size: number;
+  offset: number;
+  sourcePath: string;
+  layout?: string | null;
+}
+
+export interface SourceRuntimeFile {
+  path: string;
+  size: number;
+}
+
+export interface SourceRuntimeShardSource {
+  index: number;
+  path: string;
+  filename: string;
+  size: number;
+}
+
+export interface BuildSourceRuntimeBundleOptions {
+  modelId: string;
+  modelName?: string | null;
+  modelType: string;
+  architecture: Record<string, unknown> | string | null;
+  architectureHint?: string | null;
+  rawConfig?: Record<string, unknown> | null;
+  inference: Record<string, unknown>;
+  tensors: SourceRuntimeTensor[];
+  sourceFiles?: SourceRuntimeFile[] | null;
+  resolveSourceSize?: ((path: string) => Promise<number> | number) | null;
+  sourceQuantization?: string | null;
+  quantizationInfo?: Record<string, unknown> | null;
+  manifestQuantization?: string | null;
+  hashAlgorithm?: string | null;
+  tokenizerJson?: Record<string, unknown> | null;
+  tokenizerConfig?: Record<string, unknown> | null;
+  tokenizerModelName?: string | null;
+  eosTokenId?: number | number[] | null;
+  convertedAt?: string | null;
+  conversionInfo?: Record<string, unknown> | null;
+}
+
+export interface BuildSourceRuntimeBundleResult {
+  manifest: RDRRManifest;
+  shardSources: SourceRuntimeShardSource[];
+}
+
+export declare function buildSourceRuntimeBundle(
+  options: BuildSourceRuntimeBundleOptions
+): Promise<BuildSourceRuntimeBundleResult>;
+
+export interface CreateSourceStorageContextOptions {
+  manifest: RDRRManifest;
+  shardSources: SourceRuntimeShardSource[];
+  readRange: (
+    path: string,
+    offset: number,
+    length: number
+  ) => Promise<ArrayBuffer | Uint8Array>;
+  streamRange?: (
+    path: string,
+    offset: number,
+    length: number,
+    options?: { chunkBytes?: number }
+  ) => AsyncIterable<ArrayBuffer | Uint8Array>;
+  readText?: (path: string) => Promise<string | Record<string, unknown> | null | undefined>;
+  readBinary?: (path: string) => Promise<ArrayBuffer | Uint8Array>;
+  tokenizerJsonPath?: string | null;
+  tokenizerModelPath?: string | null;
+  verifyHashes?: boolean;
+}
+
+export interface SourceStorageContext {
+  loadShard: (index: number) => Promise<ArrayBuffer | Uint8Array>;
+  loadShardRange: (
+    index: number,
+    offset?: number,
+    length?: number | null
+  ) => Promise<ArrayBuffer | Uint8Array>;
+  streamShardRange: (
+    index: number,
+    offset?: number,
+    length?: number | null,
+    options?: { chunkBytes?: number }
+  ) => AsyncIterable<Uint8Array>;
+  loadTokenizerJson: (() => Promise<Record<string, unknown> | null>) | null;
+  loadTokenizerModel: ((pathHint?: string) => Promise<ArrayBuffer | null>) | null;
+  verifyHashes: boolean;
+}
+
+export declare function createSourceStorageContext(
+  options: CreateSourceStorageContextOptions
+): SourceStorageContext;