@simulatte/doppler 0.1.5 → 0.1.7

package/src/tooling/node-command-runner.js

@@ -18,6 +18,7 @@ import {
   getActiveKernelPathSource,
   setActiveKernelPath,
 } from '../config/kernel-path-loader.js';
+import { runTrainingOperatorCommand } from '../training/operator-command.js';
 
 function asOptionalPlainObject(value, label) {
   if (value == null) return null;
@@ -27,6 +28,28 @@ function asOptionalPlainObject(value, label) {
   return value;
 }
 
+function assertNoUnsupportedRuntimeInputs(request) {
+  const runtimeFields = [];
+  if (Array.isArray(request?.configChain) && request.configChain.length > 0) {
+    runtimeFields.push('configChain');
+  }
+  if (typeof request?.runtimePreset === 'string' && request.runtimePreset.trim()) {
+    runtimeFields.push('runtimePreset');
+  }
+  if (typeof request?.runtimeConfigUrl === 'string' && request.runtimeConfigUrl.trim()) {
+    runtimeFields.push('runtimeConfigUrl');
+  }
+  if (request?.runtimeConfig != null) {
+    runtimeFields.push('runtimeConfig');
+  }
+  if (runtimeFields.length > 0) {
+    throw new Error(
+      `${request.command} does not support runtime input fields on the node operator surface: ` +
+      `${runtimeFields.join(', ')}. Put those settings into the workload/config asset instead.`
+    );
+  }
+}
+
 let runtimeModulesPromise = null;
 
 async function loadRuntimeModules() {
@@ -50,16 +73,19 @@ export function hasNodeWebGPUSupport() {
 }
 
 async function assertNodeWebGPUSupport() {
+  let bootstrapProvider = null;
   if (!hasNodeWebGPUSupport()) {
     const bootstrap = await bootstrapNodeWebGPU();
-    if (bootstrap.ok && bootstrap.provider) {
-      console.error(`[surface] node WebGPU provider: ${bootstrap.provider}`);
+    if (bootstrap.provider) {
+      bootstrapProvider = bootstrap.provider;
     }
   }
 
   if (hasNodeWebGPUSupport()) return;
   throw new Error(
-    'node command: WebGPU runtime is incomplete in Node. Run in browser relay, or run under a WebGPU-enabled Node build.'
+    'node command: WebGPU runtime is incomplete in Node.' +
+    (bootstrapProvider ? ` Provider resolution stopped at "${bootstrapProvider}".` : '') +
+    ' Run in browser relay, or run under a WebGPU-enabled Node build.'
   );
 }
 
@@ -90,6 +116,21 @@ export async function runNodeCommand(commandRequest, options = {}) {
       });
     }
 
+    if (request.command === 'lora' || request.command === 'distill') {
+      const gpuOptionalActions = new Set(['compare', 'quality-gate', 'subsets']);
+      installNodeFileFetchShim();
+      assertNoUnsupportedRuntimeInputs(request);
+      if (!gpuOptionalActions.has(request.action)) {
+        await assertNodeWebGPUSupport();
+      }
+      const result = await runTrainingOperatorCommand(request);
+      return createToolingSuccessEnvelope({
+        surface: 'node',
+        request,
+        result,
+      });
+    }
+
     await assertNodeWebGPUSupport();
     const modules = await loadRuntimeModules();
     const runtimeBridge = {

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);
@@ -1168,10 +1185,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,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

@@ -2,21 +2,13 @@ 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-doe',
-);
 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() {
@@ -59,110 +51,37 @@ function resolveCandidateModuleSpecifier(candidate) {
 }
 
 function resolveDefaultWebgpuModuleSpecifiers() {
-  const specifiers = [];
-  const localCandidates = [
-    resolve(process.cwd(), '..', 'fawn', 'nursery', 'webgpu-doe'),
-    DEFAULT_LOCAL_DOE_PROVIDER_PATH,
-  ];
-  for (const localCandidate of localCandidates) {
-    const resolvedPath = resolveNodeModuleFilePath(localCandidate);
-    if (resolvedPath) {
-      specifiers.push(pathToFileURL(resolvedPath).href);
-    }
-  }
-  specifiers.push('@simulatte/webgpu-doe');
-  specifiers.push('webgpu');
-  return [...new Set(specifiers)];
+  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 {
-    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 resolveCandidateModuleSpecifier(fromEnv.trim());
   }
   return null;
 }
 
 function isDoeWebgpuSpecifier(specifier) {
-  if (specifier === '@simulatte/webgpu-doe') {
+  if (specifier === '@simulatte/webgpu') {
     return true;
   }
-  if (typeof specifier !== 'string') {
-    return false;
-  }
-  if (specifier.includes('/webgpu-doe/')) {
-    return true;
-  }
-  return specifier.includes('webgpu-doe') && 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 (!isDoeWebgpuSpecifier(specifier)) {
-    return null;
-  }
-  return resolveWorkspaceWebgpuProviderPath();
+  return typeof specifier === 'string'
+    && specifier.startsWith('file://')
+    && specifier.includes('@simulatte/webgpu');
 }
 
 async function importWithProviderOverride(specifier) {
-  const providerOverride = resolveDoeProviderOverride(specifier);
   const shouldApplyCreateArgsDefault = isDoeWebgpuSpecifier(specifier)
-    && !(typeof process.env.FAWN_WEBGPU_CREATE_ARGS === 'string' && process.env.FAWN_WEBGPU_CREATE_ARGS.trim().length > 0);
-  if (!providerOverride) {
-    if (!shouldApplyCreateArgsDefault) {
-      return import(specifier);
-    }
-    process.env.FAWN_WEBGPU_CREATE_ARGS = DEFAULT_DOE_PROVIDER_CREATE_ARGS;
-    try {
-      return await import(specifier);
-    } finally {
-      delete process.env.FAWN_WEBGPU_CREATE_ARGS;
-    }
-  }
-  const hadProvider = Object.prototype.hasOwnProperty.call(process.env, 'FAWN_WEBGPU_NODE_PROVIDER_MODULE');
-  const previousProvider = process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE;
-  const hadCreateArgs = Object.prototype.hasOwnProperty.call(process.env, 'FAWN_WEBGPU_CREATE_ARGS');
-  const previousCreateArgs = process.env.FAWN_WEBGPU_CREATE_ARGS;
-  process.env.FAWN_WEBGPU_NODE_PROVIDER_MODULE = providerOverride;
-  if (!hadCreateArgs) {
-    process.env.FAWN_WEBGPU_CREATE_ARGS = DEFAULT_DOE_PROVIDER_CREATE_ARGS;
+    && !(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[DOE_PROVIDER_CREATE_ARGS_ENV] = DEFAULT_DOE_PROVIDER_CREATE_ARGS;
   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;
-    }
-    if (hadCreateArgs) {
-      process.env.FAWN_WEBGPU_CREATE_ARGS = previousCreateArgs;
-    } else {
-      delete process.env.FAWN_WEBGPU_CREATE_ARGS;
-    }
+    delete process.env[DOE_PROVIDER_CREATE_ARGS_ENV];
   }
 }
 
@@ -315,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>;