@simulatte/doppler 0.1.5 → 0.1.7

package/src/hotswap/runtime.js

@@ -6,18 +6,40 @@ function normalizeRolloutPolicy(policy) {
     ? policy.rollout
     : {};
   const rawMode = String(rollout.mode || 'shadow').trim().toLowerCase().replace(/_/g, '-');
-  const mode = rawMode === 'default' || rawMode === 'canary' || rawMode === 'opt-in' || rawMode === 'shadow'
-    ? rawMode
-    : 'shadow';
-  const canaryPercent = Number.isFinite(rollout.canaryPercent)
-    ? Math.min(100, Math.max(0, Number(rollout.canaryPercent)))
-    : 0;
+  if (rawMode !== 'default' && rawMode !== 'canary' && rawMode !== 'opt-in' && rawMode !== 'shadow') {
+    throw new Error(
+      `hotswap.rollout.mode must be one of default, canary, opt-in, shadow (received "${rollout.mode}")`
+    );
+  }
+  let canaryPercent = 0;
+  if (rollout.canaryPercent !== undefined && rollout.canaryPercent !== null) {
+    const parsedCanaryPercent = Number(rollout.canaryPercent);
+    if (!Number.isFinite(parsedCanaryPercent) || parsedCanaryPercent < 0 || parsedCanaryPercent > 100) {
+      throw new Error('hotswap.rollout.canaryPercent must be a number between 0 and 100 when provided.');
+    }
+    canaryPercent = parsedCanaryPercent;
+  }
+  if (rollout.cohortSalt !== undefined && rollout.cohortSalt !== null && typeof rollout.cohortSalt !== 'string') {
+    throw new Error('hotswap.rollout.cohortSalt must be a string when provided.');
+  }
   const cohortSalt = String(rollout.cohortSalt || 'doppler-hotswap-v1').trim() || 'doppler-hotswap-v1';
+  if (rollout.optInAllowlist !== undefined && rollout.optInAllowlist !== null && !Array.isArray(rollout.optInAllowlist)) {
+    throw new Error('hotswap.rollout.optInAllowlist must be an array of strings when provided.');
+  }
   const optInAllowlist = Array.isArray(rollout.optInAllowlist)
-    ? rollout.optInAllowlist.map((entry) => String(entry || '').trim()).filter(Boolean)
+    ? rollout.optInAllowlist.map((entry, index) => {
+      if (typeof entry !== 'string') {
+        throw new Error(`hotswap.rollout.optInAllowlist[${index}] must be a string.`);
+      }
+      const normalized = entry.trim();
+      if (!normalized) {
+        throw new Error(`hotswap.rollout.optInAllowlist[${index}] must not be empty.`);
+      }
+      return normalized;
+    })
     : [];
   return {
-    mode,
+    mode: rawMode,
     canaryPercent,
     cohortSalt,
     optInAllowlist,

package/src/index-browser.d.ts

@@ -9,6 +9,20 @@ export {
 export { MultiModelLoader } from './loader/multi-model-loader.js';
 
 export { InferencePipeline, EmbeddingPipeline, createPipeline } from './generation/index.js';
+export {
+  StructuredJsonHeadPipeline,
+  isStructuredJsonHeadModelType,
+  createStructuredJsonHeadPipeline,
+  DreamStructuredPipeline,
+  isDreamStructuredModelType,
+  createDreamStructuredPipeline,
+} from './generation/index.js';
+export {
+  EnergyRowHeadPipeline,
+  createEnergyRowHeadPipeline,
+  DreamEnergyHeadPipeline,
+  createDreamEnergyHeadPipeline,
+} from './inference/pipelines/energy-head/row-head-pipeline.js';
 export { KVCache } from './inference/kv-cache.js';
 export { Tokenizer } from './inference/tokenizer.js';
 export { SpeculativeDecoder } from './inference/speculative.js';
@@ -25,6 +39,22 @@ export {
   mergeMultipleLogits,
 } from './gpu/kernels/logit-merge.js';
 
+export type { RDRRManifest, ShardInfo } from './formats/rdrr/index.js';
+export type { TensorLocation, LoadProgress, LoadOptions, LoaderStats } from './loader/doppler-loader.js';
+export type { AdapterSource } from './loader/multi-model-loader.js';
+export type { ParsedModelConfig } from './generation/index.js';
+export type { SamplingOptions } from './generation/index.js';
+export type {
+  GenerateOptions,
+  GenerationResult,
+  KVCacheSnapshot,
+  LayerWeights,
+  ExpertWeights,
+  RouterWeights,
+} from './generation/index.js';
+export type { LoRAAdapter, LoRAModuleName } from './generation/index.js';
+export type { ExpertNode, ExpertTask } from './inference/multi-model-network.js';
+
 export {
   ADAPTER_MANIFEST_SCHEMA,
   validateManifest as validateAdapterManifest,
@@ -45,4 +75,18 @@ export {
   createMemoryRegistry,
 } from './adapters/index.js';
 
+export type {
+  AdapterManifest,
+  AdapterMetadata,
+  AdapterTensorSpec,
+  LoRALoadOptions,
+  LoRAWeightsResult,
+  AdapterState,
+  EnableAdapterOptions,
+  AdapterStackOptions,
+  AdapterManagerEvents,
+  AdapterRegistryEntry,
+  AdapterQueryOptions,
+} from './adapters/index.js';
+
 export * from './tooling-exports.browser.js';

package/src/index-browser.js

@@ -11,6 +11,20 @@ export { MultiModelLoader } from './loader/multi-model-loader.js';
 
 // Inference pipeline
 export { InferencePipeline, EmbeddingPipeline, createPipeline } from './generation/index.js';
+export {
+  StructuredJsonHeadPipeline,
+  isStructuredJsonHeadModelType,
+  createStructuredJsonHeadPipeline,
+  DreamStructuredPipeline,
+  isDreamStructuredModelType,
+  createDreamStructuredPipeline,
+} from './generation/index.js';
+export {
+  EnergyRowHeadPipeline,
+  createEnergyRowHeadPipeline,
+  DreamEnergyHeadPipeline,
+  createDreamEnergyHeadPipeline,
+} from './inference/pipelines/energy-head/row-head-pipeline.js';
 export { KVCache } from './inference/kv-cache.js';
 export { Tokenizer } from './inference/tokenizer.js';
 export { SpeculativeDecoder } from './inference/speculative.js';

package/src/inference/browser-harness-contract-helpers.d.ts

@@ -0,0 +1,5 @@
+export declare function buildSuiteContractMetrics(
+  suite: string,
+  baseMetrics: Record<string, unknown>,
+  manifest: Record<string, unknown> | null | undefined
+): Record<string, unknown>;

package/src/inference/browser-harness-contract-helpers.js

@@ -0,0 +1,28 @@
+import { getInferenceLayerPatternContractArtifact } from '../rules/rule-registry.js';
+import { isPlainObject } from '../utils/plain-object.js';
+import { validateBrowserSuiteMetrics } from '../config/schema/browser-suite-metrics.schema.js';
+import { buildExecutionContractArtifact } from '../config/execution-contract-check.js';
+import { buildManifestRequiredInferenceFieldsArtifact } from '../config/required-inference-fields-contract-check.js';
+
+export function buildSuiteContractMetrics(suite, baseMetrics, manifest) {
+  const executionContractArtifact = buildExecutionContractArtifact(manifest);
+  const executionV0GraphContractArtifact = executionContractArtifact?.executionV0?.graph ?? null;
+  const layerPatternContractArtifact = getInferenceLayerPatternContractArtifact();
+  const requiredInferenceFieldsArtifact = manifest?.modelType === 'transformer'
+    && isPlainObject(manifest?.inference?.attention)
+    ? buildManifestRequiredInferenceFieldsArtifact(
+      manifest?.inference ?? null,
+      `${manifest?.modelId ?? 'unknown'}.inference`
+    )
+    : null;
+  return validateBrowserSuiteMetrics({
+    ...baseMetrics,
+    schemaVersion: 1,
+    source: 'doppler',
+    suite,
+    ...(executionContractArtifact ? { executionContractArtifact } : {}),
+    executionV0GraphContractArtifact,
+    layerPatternContractArtifact,
+    requiredInferenceFieldsArtifact,
+  });
+}

package/src/inference/browser-harness-diffusion-energy-suites.d.ts

@@ -0,0 +1,2 @@
+export declare function runDiffusionSuite(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function runEnergySuite(options?: Record<string, unknown>): Promise<Record<string, unknown>>;

package/src/inference/browser-harness-diffusion-energy-suites.js

@@ -0,0 +1,269 @@
+import { getRuntimeConfig } from '../config/runtime.js';
+import { computeSampleStats } from '../debug/stats.js';
+import { initializeSuiteModel, resolveDeviceInfo } from './browser-harness-model-helpers.js';
+import { buildSuiteContractMetrics } from './browser-harness-contract-helpers.js';
+import { resolvePrompt } from './browser-harness-text-helpers.js';
+import {
+  buildSuiteSummary,
+  normalizeCacheMode,
+  normalizeLoadMode,
+  safeStatsValue,
+  buildDiffusionPerformanceArtifact,
+  buildCanonicalTiming,
+  buildTimingDiagnostics,
+} from './browser-harness-suite-helpers.js';
+
+export async function runDiffusionSuite(options = {}) {
+  const startTime = performance.now();
+  const runtimeConfig = getRuntimeConfig();
+  const captureOutput = options.captureOutput === true;
+  const cacheMode = normalizeCacheMode(options.cacheMode);
+  const loadMode = normalizeLoadMode(options.loadMode, !options.modelUrl);
+  const benchConfig = runtimeConfig.shared?.benchmark?.run || {};
+  const warmupRuns = Math.max(0, Math.floor(benchConfig.warmupRuns ?? 0));
+  const timedRuns = Math.max(1, Math.floor(benchConfig.timedRuns ?? 1));
+
+  const diffusionConfig = runtimeConfig.inference?.diffusion;
+  if (!diffusionConfig) {
+    throw new Error('runtime.inference.diffusion must be set for diffusion harness runs.');
+  }
+  const scheduler = diffusionConfig.scheduler;
+  const latent = diffusionConfig.latent;
+  const prompt = resolvePrompt(runtimeConfig);
+  const negativePrompt = diffusionConfig.negativePrompt ?? '';
+
+  const width = Math.floor(latent?.width);
+  const height = Math.floor(latent?.height);
+  const steps = Math.floor(scheduler?.numSteps);
+  const guidanceScale = scheduler?.guidanceScale;
+
+  if (!Number.isFinite(width) || width <= 0) {
+    throw new Error('runtime.inference.diffusion.latent.width must be set for diffusion harness runs.');
+  }
+  if (!Number.isFinite(height) || height <= 0) {
+    throw new Error('runtime.inference.diffusion.latent.height must be set for diffusion harness runs.');
+  }
+  if (!Number.isFinite(steps) || steps <= 0) {
+    throw new Error('runtime.inference.diffusion.scheduler.numSteps must be set for diffusion harness runs.');
+  }
+  if (!Number.isFinite(guidanceScale) || guidanceScale <= 0) {
+    throw new Error('runtime.inference.diffusion.scheduler.guidanceScale must be set for diffusion harness runs.');
+  }
+
+  const harness = await initializeSuiteModel(options);
+  const totalMs = [];
+  const prefillMs = [];
+  const denoiseMs = [];
+  const vaeMs = [];
+  const prefillTokens = [];
+  const decodeTokens = [];
+  const gpuTotalMs = [];
+  const gpuPrefillMs = [];
+  const gpuDenoiseMs = [];
+  const gpuVaeMs = [];
+  let output = null;
+
+  for (let i = 0; i < warmupRuns + timedRuns; i++) {
+    harness.pipeline.reset?.();
+    const result = await harness.pipeline.generate({
+      prompt,
+      negativePrompt,
+      steps,
+      guidanceScale,
+      width,
+      height,
+    });
+    if (captureOutput && i === warmupRuns + timedRuns - 1) {
+      output = result;
+    }
+
+    if (i < warmupRuns) continue;
+
+    const stats = harness.pipeline.getStats?.() ?? {};
+    if (Number.isFinite(stats.totalTimeMs)) totalMs.push(stats.totalTimeMs);
+    if (Number.isFinite(stats.prefillTimeMs)) prefillMs.push(stats.prefillTimeMs);
+    if (Number.isFinite(stats.decodeTimeMs)) denoiseMs.push(stats.decodeTimeMs);
+    if (Number.isFinite(stats.vaeTimeMs)) vaeMs.push(stats.vaeTimeMs);
+    if (Number.isFinite(stats.prefillTokens)) prefillTokens.push(stats.prefillTokens);
+    if (Number.isFinite(stats.decodeTokens)) decodeTokens.push(stats.decodeTokens);
+
+    const gpu = stats.gpu ?? null;
+    if (gpu?.available) {
+      if (Number.isFinite(gpu.totalMs)) gpuTotalMs.push(gpu.totalMs);
+      if (Number.isFinite(gpu.prefillMs)) gpuPrefillMs.push(gpu.prefillMs);
+      if (Number.isFinite(gpu.denoiseMs)) gpuDenoiseMs.push(gpu.denoiseMs);
+      if (Number.isFinite(gpu.vaeMs)) gpuVaeMs.push(gpu.vaeMs);
+    }
+  }
+
+  const memoryStats = typeof harness.pipeline?.getMemoryStats === 'function'
+    ? harness.pipeline.getMemoryStats()
+    : null;
+
+  if (typeof harness.pipeline.unload === 'function' && !options.keepPipeline) {
+    await harness.pipeline.unload();
+  }
+
+  const results = [
+    {
+      name: 'diffusion',
+      passed: totalMs.length > 0,
+      duration: totalMs.reduce((sum, value) => sum + value, 0),
+      error: totalMs.length > 0 ? undefined : 'No diffusion runs completed',
+    },
+  ];
+
+  const summary = buildSuiteSummary('diffusion', results, startTime);
+  const cpuStats = {
+    totalMs: computeSampleStats(totalMs),
+    prefillMs: computeSampleStats(prefillMs),
+    denoiseMs: computeSampleStats(denoiseMs),
+    vaeMs: computeSampleStats(vaeMs),
+  };
+  const gpuStats = gpuTotalMs.length > 0
+    ? {
+      available: true,
+      totalMs: computeSampleStats(gpuTotalMs),
+      prefillMs: computeSampleStats(gpuPrefillMs),
+      denoiseMs: computeSampleStats(gpuDenoiseMs),
+      vaeMs: computeSampleStats(gpuVaeMs),
+    }
+    : { available: false };
+
+  const avgPrefillTokens = prefillTokens.length
+    ? Math.round(prefillTokens.reduce((a, b) => a + b, 0) / prefillTokens.length)
+    : 0;
+  const avgDecodeTokens = decodeTokens.length
+    ? Math.round(decodeTokens.reduce((a, b) => a + b, 0) / decodeTokens.length)
+    : 0;
+  const prefillMsMedian = safeStatsValue(cpuStats.prefillMs?.median);
+  const denoiseMsMedian = safeStatsValue(cpuStats.denoiseMs?.median);
+  const totalMsMedian = safeStatsValue(cpuStats.totalMs?.median);
+  const diffusionPerformanceArtifact = buildDiffusionPerformanceArtifact({
+    warmupRuns,
+    timedRuns,
+    width,
+    height,
+    steps,
+    guidanceScale,
+    avgPrefillTokens,
+    avgDecodeTokens,
+    cpuStats,
+    gpuStats,
+  });
+  const timing = buildCanonicalTiming({
+    modelLoadMs: 0,
+    firstTokenMs: null,
+    firstResponseMs: null,
+    prefillMs: prefillMsMedian,
+    decodeMs: denoiseMsMedian,
+    totalRunMs: totalMsMedian,
+    prefillTokensPerSec: diffusionPerformanceArtifact.throughput.prefillTokensPerSec,
+    decodeTokensPerSec: diffusionPerformanceArtifact.throughput.decodeTokensPerSec,
+    cacheMode,
+    loadMode,
+  });
+  const timingDiagnostics = buildTimingDiagnostics(timing, {
+    source: 'doppler',
+    prefillSemantics: 'internal_prefill_phase',
+  });
+  const metricsWithContracts = buildSuiteContractMetrics(
+    'diffusion',
+    {
+      warmupRuns,
+      timedRuns,
+      width,
+      height,
+      steps,
+      guidanceScale,
+      prompt,
+      avgPrefillTokens,
+      avgDecodeTokens,
+      latency: {
+        totalMs: cpuStats.totalMs,
+        prefillMs: cpuStats.prefillMs,
+        denoiseMs: cpuStats.denoiseMs,
+        vaeMs: cpuStats.vaeMs,
+      },
+      throughput: {
+        prefillTokensPerSec: diffusionPerformanceArtifact.throughput.prefillTokensPerSec,
+        decodeTokensPerSec: diffusionPerformanceArtifact.throughput.decodeTokensPerSec,
+        decodeStepsPerSec: diffusionPerformanceArtifact.throughput.decodeStepsPerSec,
+      },
+      cpu: cpuStats,
+      gpu: gpuStats,
+      performanceArtifact: diffusionPerformanceArtifact,
+    },
+    harness.manifest
+  );
+
+  return {
+    ...summary,
+    modelId: options.modelId || harness.manifest?.modelId || 'unknown',
+    cacheMode,
+    loadMode,
+    env: {
+      library: 'doppler',
+      runtime: 'browser',
+      device: 'webgpu',
+      browserUserAgent: typeof navigator !== 'undefined' ? (navigator.userAgent || null) : null,
+      browserPlatform: typeof navigator !== 'undefined' ? (navigator.platform || null) : null,
+      browserLanguage: typeof navigator !== 'undefined' ? (navigator.language || null) : null,
+      browserVendor: typeof navigator !== 'undefined' ? (navigator.vendor || null) : null,
+    },
+    timing,
+    timingDiagnostics,
+    output,
+    metrics: metricsWithContracts,
+    memoryStats,
+    deviceInfo: resolveDeviceInfo(),
+    pipeline: options.keepPipeline ? harness.pipeline : null,
+  };
+}
+
+export async function runEnergySuite(options = {}) {
+  const startTime = performance.now();
+  const harness = await initializeSuiteModel(options);
+  if (harness.manifest?.modelType !== 'energy') {
+    throw new Error('Energy suite requires an energy model manifest.');
+  }
+
+  const result = await harness.pipeline.generate();
+  const stats = harness.pipeline.getStats?.() ?? {};
+
+  const memoryStats = typeof harness.pipeline?.getMemoryStats === 'function'
+    ? harness.pipeline.getMemoryStats()
+    : null;
+
+  if (typeof harness.pipeline.unload === 'function' && !options.keepPipeline) {
+    await harness.pipeline.unload();
+  }
+
+  const results = [
+    {
+      name: 'energy',
+      passed: Number.isFinite(result.energy ?? NaN),
+      duration: result.totalTimeMs ?? Math.max(0, performance.now() - startTime),
+      error: Number.isFinite(result.energy ?? NaN) ? undefined : 'Energy did not converge',
+    },
+  ];
+
+  const summary = buildSuiteSummary('energy', results, startTime);
+  return {
+    ...summary,
+    modelId: options.modelId || harness.manifest?.modelId || 'unknown',
+    metrics: {
+      steps: result.steps,
+      energy: result.energy ?? null,
+      dtype: result.dtype,
+      shape: result.shape,
+      totalTimeMs: result.totalTimeMs ?? null,
+      energyHistory: result.energyHistory ?? [],
+      stateStats: result.stateStats ?? null,
+      readbackCount: stats.readbackCount ?? null,
+    },
+    memoryStats,
+    deviceInfo: resolveDeviceInfo(),
+    pipeline: options.keepPipeline ? harness.pipeline : null,
+  };
+}

package/src/inference/browser-harness-model-helpers.d.ts

@@ -0,0 +1,16 @@
+export declare function resolveDeviceInfo(): Record<string, unknown> | null;
+export declare function resolveKernelPathForModel(options?: Record<string, unknown>): Promise<{
+  modelId: string | null;
+  kernelPath: unknown;
+  source: string | null;
+} | null>;
+export declare function initializeInferenceFromStorage(
+  modelId: string,
+  options?: Record<string, unknown>
+): Promise<Record<string, unknown>>;
+export declare function initializeInferenceFromSourcePath(
+  sourcePath: string,
+  options?: Record<string, unknown>
+): Promise<Record<string, unknown>>;
+export declare function resolveHarnessOverride(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function initializeSuiteModel(options?: Record<string, unknown>): Promise<Record<string, unknown>>;

package/src/inference/browser-harness-model-helpers.js

@@ -0,0 +1,217 @@
+import { initializeInference } from './test-harness.js';
+import { setRuntimeConfig } from '../config/runtime.js';
+import { initDevice, getKernelCapabilities, getDevice } from '../gpu/device.js';
+import { createPipeline } from './pipelines/text.js';
+import { parseModelConfigFromManifest } from './pipelines/text/config.js';
+import { resolveKernelPathState, activateKernelPathState } from './pipelines/text/model-load.js';
+import { openModelStore, loadManifestFromStore } from '../storage/shard-manager.js';
+import { parseManifest } from '../formats/rdrr/index.js';
+import { resolveRuntime } from './browser-harness-runtime-helpers.js';
+import { normalizeLoadMode } from './browser-harness-suite-helpers.js';
+import { buildSourceArtifactFingerprint, createStoredSourceArtifactContext } from '../storage/source-artifact-store.js';
+
+const NODE_SOURCE_RUNTIME_MODULE_PATH = '../tooling/node-source-runtime.js';
+
+function isNodeRuntime() {
+  return typeof process !== 'undefined' && !!process.versions?.node;
+}
+
+function resolveSourceVerifyHashes(options = {}) {
+  const explicit = options?.runtime?.runtimeConfig?.loading?.shardCache?.verifyHashes;
+  if (explicit == null) {
+    return true;
+  }
+  return explicit === true;
+}
+
+export function resolveDeviceInfo() {
+  try {
+    return getKernelCapabilities();
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveKernelPathForModel(options = {}) {
+  const runtimeConfig = options.runtime?.runtimeConfig ?? null;
+  let manifest = null;
+  let manifestModelId = options.modelId || null;
+
+  if (options.modelId) {
+    await openModelStore(options.modelId);
+    const manifestText = await loadManifestFromStore();
+    if (manifestText) {
+      manifest = parseManifest(manifestText);
+      manifestModelId = manifest.modelId ?? options.modelId;
+    }
+  }
+
+  if (!manifest) return null;
+
+  const modelConfig = parseModelConfigFromManifest(manifest, runtimeConfig);
+  const kernelPathState = resolveKernelPathState({
+    manifest,
+    runtimeConfig,
+    modelConfig,
+  });
+  activateKernelPathState(kernelPathState);
+  return {
+    modelId: manifestModelId,
+    kernelPath: kernelPathState.resolvedKernelPath,
+    source: kernelPathState.kernelPathSource,
+  };
+}
+
+export async function initializeInferenceFromStorage(modelId, options = {}) {
+  const { onProgress } = options;
+  if (!modelId) {
+    throw new Error('modelId is required');
+  }
+
+  if (options.runtime?.runtimeConfig) {
+    setRuntimeConfig(options.runtime.runtimeConfig);
+  }
+
+  onProgress?.('storage', 0.05, 'Opening model store...');
+  await openModelStore(modelId);
+
+  onProgress?.('manifest', 0.1, 'Loading manifest...');
+  const manifestText = await loadManifestFromStore();
+  if (!manifestText) {
+    throw new Error('Manifest not found in storage');
+  }
+  const manifest = parseManifest(manifestText);
+
+  onProgress?.('gpu', 0.2, 'Initializing WebGPU...');
+  await initDevice();
+  const device = getDevice();
+  const capabilities = getKernelCapabilities();
+
+  onProgress?.('pipeline', 0.3, 'Creating pipeline...');
+  const storage = buildSourceArtifactFingerprint(manifest)
+    ? createStoredSourceArtifactContext(manifest, { verifyHashes: true })
+    : null;
+  const pipeline = await createPipeline(manifest, {
+    gpu: { device },
+    runtime: options.runtime,
+    ...(storage ? { storage } : {}),
+    onProgress,
+  });
+
+  return { pipeline, manifest, capabilities };
+}
+
+export async function initializeInferenceFromSourcePath(sourcePath, options = {}) {
+  const { onProgress } = options;
+  if (!sourcePath || typeof sourcePath !== 'string') {
+    throw new Error('modelUrl is required for loadMode=memory.');
+  }
+  if (!isNodeRuntime()) {
+    throw new Error('loadMode=memory source runtime is currently supported on Node only.');
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(sourcePath)) {
+    throw new Error(
+      'loadMode=memory expects a local filesystem path (Safetensors directory or .gguf file), not an URL.'
+    );
+  }
+
+  if (options.runtime?.runtimeConfig) {
+    setRuntimeConfig(options.runtime.runtimeConfig);
+  }
+
+  onProgress?.('source', 0.05, 'Preparing source runtime bundle...');
+  const { resolveNodeSourceRuntimeBundle } = await import(NODE_SOURCE_RUNTIME_MODULE_PATH);
+  const sourceBundle = await resolveNodeSourceRuntimeBundle({
+    inputPath: sourcePath,
+    modelId: options.modelId || null,
+    verifyHashes: resolveSourceVerifyHashes(options),
+  });
+  if (!sourceBundle) {
+    throw new Error(
+      `No source-runtime model detected at "${sourcePath}". ` +
+      'Expected a Safetensors directory or a .gguf file path.'
+    );
+  }
+
+  onProgress?.('gpu', 0.2, 'Initializing WebGPU...');
+  await initDevice();
+  const device = getDevice();
+  const capabilities = getKernelCapabilities();
+
+  onProgress?.('pipeline', 0.3, 'Creating pipeline...');
+  const pipeline = await createPipeline(sourceBundle.manifest, {
+    gpu: { device },
+    runtime: options.runtime,
+    storage: sourceBundle.storageContext,
+    onProgress,
+  });
+
+  return {
+    pipeline,
+    manifest: sourceBundle.manifest,
+    capabilities,
+  };
+}
+
+export async function resolveHarnessOverride(options = {}) {
+  const input = typeof options.harnessOverride === 'function'
+    ? await options.harnessOverride(options)
+    : options.harnessOverride;
+
+  if (!input || typeof input !== 'object') {
+    throw new Error('harnessOverride must resolve to an object.');
+  }
+
+  if (!input.pipeline || typeof input.pipeline.generate !== 'function') {
+    throw new Error('harnessOverride.pipeline.generate(request) is required.');
+  }
+
+  const manifest = input.manifest && typeof input.manifest === 'object'
+    ? input.manifest
+    : {
+      modelId: options.modelId || 'diffusion-harness-override',
+      modelType: 'diffusion',
+    };
+
+  const modelLoadMs = Number.isFinite(input.modelLoadMs)
+    ? Math.max(0, input.modelLoadMs)
+    : 0;
+
+  return {
+    ...input,
+    manifest,
+    modelLoadMs,
+  };
+}
+
+export async function initializeSuiteModel(options = {}) {
+  if (options.harnessOverride) {
+    if (options.runtime?.runtimeConfig) {
+      setRuntimeConfig(options.runtime.runtimeConfig);
+    }
+    return resolveHarnessOverride(options);
+  }
+  const loadStart = performance.now();
+  const runtime = resolveRuntime(options);
+  const loadMode = normalizeLoadMode(options.loadMode, !options.modelUrl);
+  let harness;
+  if (loadMode === 'memory') {
+    if (!options.modelUrl) {
+      throw new Error('loadMode=memory requires modelUrl to be a local model path.');
+    }
+    harness = await initializeInferenceFromSourcePath(options.modelUrl, { ...options, runtime });
+  } else if (options.modelId && !options.modelUrl) {
+    harness = await initializeInferenceFromStorage(options.modelId, { ...options, runtime });
+  } else {
+    if (!options.modelUrl) {
+      throw new Error('modelUrl is required for this suite');
+    }
+    harness = await initializeInference(options.modelUrl, {
+      runtime,
+      onProgress: options.onProgress,
+      log: options.log,
+    });
+  }
+  const modelLoadMs = Math.max(0, performance.now() - loadStart);
+  return { ...harness, modelLoadMs };
+}

package/src/inference/browser-harness-report-helpers.d.ts

@@ -0,0 +1,7 @@
+export declare function collectTrainingArtifactsFromSuiteResult(
+  suiteResult: Record<string, unknown>
+): {
+  ulArtifacts: Array<Record<string, unknown>>;
+  distillArtifacts: Array<Record<string, unknown>>;
+  checkpointResumeTimeline: Array<Record<string, unknown>>;
+};