@simulatte/doppler 0.1.6 → 0.1.8

package/src/tooling/node-converter.js

@@ -52,6 +52,7 @@ function normalizeExecutionConfig(value, defaults) {
   const useGpuCast = value.useGpuCast == null
     ? defaults.useGpuCast === true
     : value.useGpuCast === true;
+  const gpuCastRequestedExplicitly = value.useGpuCast === true;
   if (value.useGpuCast != null && typeof value.useGpuCast !== 'boolean') {
     throw new Error('node convert: execution.useGpuCast must be a boolean when provided.');
   }
@@ -69,6 +70,7 @@ function normalizeExecutionConfig(value, defaults) {
     rowChunkMinTensorBytes,
     maxInFlightJobs,
     useGpuCast,
+    gpuCastRequestedExplicitly,
     gpuCastMinTensorBytes,
   };
 }
@@ -222,6 +224,7 @@ function createNodeGpuTensorTransformer(options) {
   const {
     runtime,
     gpuCastMinTensorBytes,
+    requireGpuCast,
     resolveTensorTargetQuant,
   } = options;
   const {
@@ -276,6 +279,11 @@ function createNodeGpuTensorTransformer(options) {
     try {
       const device = getDevice();
       if (!device) {
+        if (requireGpuCast) {
+          throw new Error(
+            `node convert: execution.useGpuCast failed for tensor "${tensor.name}": GPU device is unavailable.`
+          );
+        }
         return null;
       }
       inputBuffer = acquireBuffer(tensorData.byteLength, undefined, `convert_gpu_cast_in_${tensor.name}`);
@@ -292,6 +300,11 @@ function createNodeGpuTensorTransformer(options) {
 
       const readback = await getBufferPool().readBuffer(outputBuffer, outputBytes);
       if (!(readback instanceof ArrayBuffer) || readback.byteLength !== outputBytes) {
+        if (requireGpuCast) {
+          throw new Error(
+            `node convert: execution.useGpuCast failed for tensor "${tensor.name}": invalid GPU readback.`
+          );
+        }
         return null;
       }
       reportProgress?.(tensorData.byteLength, tensorData.byteLength);
@@ -301,6 +314,10 @@ function createNodeGpuTensorTransformer(options) {
         outLayout: null,
       };
     } catch (error) {
+      if (requireGpuCast) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`node convert: execution.useGpuCast failed for tensor "${tensor.name}": ${message}`);
+      }
       if (!warnedFallback) {
         warnedFallback = true;
         const message = error instanceof Error ? error.message : String(error);
@@ -858,6 +875,7 @@ export async function convertSafetensorsDirectory(options) {
   let sourceQuantization = null;
   let tokenizerJson = null;
   let tokenizerConfig = null;
+  let generationConfig = null;
   let hasTokenizerModel = false;
   let tokenizerModelPath = null;
   let diffusionAuxFiles = [];
@@ -1084,6 +1102,7 @@ export async function convertSafetensorsDirectory(options) {
       },
     });
     config = parsedTransformer.config;
+    generationConfig = parsedTransformer.generationConfig ?? null;
     tensors = parsedTransformer.tensors;
     architectureHint = parsedTransformer.architectureHint;
     architecture = extractArchitecture(config, null);
@@ -1152,6 +1171,7 @@ export async function convertSafetensorsDirectory(options) {
     quantization: targetQuantization,
     tokenizerJson,
     tokenizerConfig,
+    generationConfig,
     tokenizerModel: hasTokenizerModel ? 'tokenizer.model' : null,
   };
 
@@ -1168,10 +1188,19 @@ export async function convertSafetensorsDirectory(options) {
   let result = null;
   try {
     if (executionPlan.useGpuCast) {
-      const gpuRuntime = await loadNodeGpuCastRuntime();
+      let gpuRuntime;
+      try {
+        gpuRuntime = await loadNodeGpuCastRuntime();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `node convert: execution.useGpuCast requires a WebGPU-capable Node runtime. ${message}`
+        );
+      }
       gpuTensorTransformer = createNodeGpuTensorTransformer({
         runtime: gpuRuntime,
         gpuCastMinTensorBytes: executionPlan.gpuCastMinTensorBytes,
+        requireGpuCast: executionPlan.gpuCastRequestedExplicitly === true,
         resolveTensorTargetQuant,
       });
     }

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

@@ -4,6 +4,7 @@ import type { PipelineStorageContext } from '../inference/pipelines/text/init.js
 export interface ResolveNodeSourceRuntimeBundleOptions {
   inputPath: string;
   modelId?: string | null;
+  verifyHashes?: boolean;
 }
 
 export interface NodeSourceRuntimeBundle {
@@ -16,4 +17,3 @@ export interface NodeSourceRuntimeBundle {
 export declare function resolveNodeSourceRuntimeBundle(
   options: ResolveNodeSourceRuntimeBundleOptions
 ): Promise<NodeSourceRuntimeBundle | null>;
-

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,62 @@ function buildNodeFileReaders() {
   };
 }
 
+// Source dtype → compute precision mapping for source-runtime inference.
+// BF16/F32 sources require f32 compute (BF16 has no native WebGPU support).
+// Quantized formats require f32 compute for dequantization accuracy.
+// F16 sources can use f16 compute directly.
+const SOURCE_QUANT_COMPUTE_MAP = {
+  'F16': 'f16',
+  'BF16': 'f32',
+  'F32': 'f32',
+  'Q4_K': 'f32',
+  'Q4_K_M': 'f32',
+  'Q6_K': 'f32',
+};
+const SOURCE_COMPUTE_DEFAULT = 'f16';
+
+function resolveSourceRuntimeComputePrecision(tensors, sourceQuantization) {
+  const dtypes = new Set();
+  for (const tensor of Array.isArray(tensors) ? tensors : []) {
+    const dtype = String(tensor?.dtype || '').trim().toUpperCase();
+    if (dtype) {
+      dtypes.add(dtype);
+    }
+  }
+  // If any tensor requires f32 compute, use f32 for all.
+  for (const dtype of dtypes) {
+    if (SOURCE_QUANT_COMPUTE_MAP[dtype] === 'f32') {
+      return 'f32';
+    }
+  }
+
+  const normalized = String(sourceQuantization || '').trim().toUpperCase();
+  return SOURCE_QUANT_COMPUTE_MAP[normalized] ?? SOURCE_COMPUTE_DEFAULT;
+}
+
+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');
 
@@ -401,10 +506,14 @@ export async function resolveNodeSourceRuntimeBundle(options = {}) {
   assertSupportedSourceDtypes(parsed.tensors, parsed.sourceKind);
 
   const converterConfig = createConverterConfig({
+    quantization: {
+      computePrecision: resolveSourceRuntimeComputePrecision(parsed.tensors, parsed.sourceQuantization),
+    },
     output: {
       modelBaseId: options.modelId || null,
     },
     inference: {
+      sessionDefaults: cloneExecutionV0SessionDefaults(),
       execution: SOURCE_RUNTIME_EXECUTION_OVERRIDE,
     },
   });
@@ -425,22 +534,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 +569,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);
+}