@simulatte/doppler 0.1.3 → 0.1.5

package/src/inference/pipelines/text/config.d.ts

@@ -210,6 +210,11 @@ export interface ManifestWithInference {
  */
 export function hasManifestInference(manifest: Manifest): manifest is Manifest & { inference: ManifestInferenceSchema };
 
+export function validateRequiredInferenceFields(
+  inf: ManifestInferenceSchema,
+  modelId: string
+): void;
+
 /**
  * Convert MergedConfig to ParsedModelConfig.
  */

package/src/inference/pipelines/text/config.js

@@ -129,7 +129,7 @@ export function hasManifestInference(manifest) {
 }
 
 
-function validateRequiredInferenceFields(inf, modelId) {
+export function validateRequiredInferenceFields(inf, modelId) {
   
   const errors = [];
 

package/src/inference/pipelines/text/execution-v0.js

@@ -1,4 +1,12 @@
 import { mergeRuntimeValues } from '../../../config/runtime-merge.js';
+import {
+  buildExecutionV0KernelProfileKey,
+  indexExecutionV0KernelProfiles,
+  normalizeExecutionV0Dtype,
+  resolveExecutionV0KernelProfile,
+  resolveExecutionV0KVIO,
+  resolveExecutionV0Precision,
+} from '../../../config/execution-v0-contract-check.js';
 import {
   EXECUTION_V0_SCHEMA_ID,
   DEFAULT_EXECUTION_V0_POLICIES,
@@ -59,13 +67,9 @@ function cloneJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
 
-function normalizeDtype(value, label) {
-  const normalized = String(value ?? '').trim().toLowerCase();
-  if (normalized !== 'f16' && normalized !== 'f32') {
-    throw new Error(`[ExecutionV0] ${label} must be "f16" or "f32"; got "${value}"`);
-  }
-  return normalized;
-}
+const normalizeDtype = normalizeExecutionV0Dtype;
+const resolvePrecision = resolveExecutionV0Precision;
+const resolveKVIO = resolveExecutionV0KVIO;
 
 function normalizePhase(value, label) {
   const normalized = String(value ?? '').trim().toLowerCase();
@@ -83,6 +87,17 @@ function normalizeSection(value, label) {
   return normalized;
 }
 
+function normalizeKVLayout(value, label) {
+  if (value == null) {
+    return null;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  return normalized;
+}
+
 function assertKernelRef(kernelRef, label) {
   if (!kernelRef) return;
   if (typeof kernelRef.id !== 'string' || kernelRef.id.trim().length === 0) {
@@ -106,10 +121,7 @@ function stepHasLayer(step, layerIdx) {
   return step.layers.includes(layerIdx);
 }
 
-function buildKernelProfileKey(kernelRef) {
-  if (!kernelRef) return null;
-  return `${kernelRef.id}|${kernelRef.version}|${kernelRef.digest}`;
-}
+const buildKernelProfileKey = buildExecutionV0KernelProfileKey;
 
 function normalizeSlot(value, label) {
   if (typeof value !== 'string' || value.trim().length === 0) {
@@ -201,90 +213,10 @@ function hasDefinedPath(root, pathSegments) {
   return current !== undefined;
 }
 
-function indexKernelProfiles(sessionDefaults) {
-  const byKey = new Map();
-  const profiles = sessionDefaults?.compute?.kernelProfiles ?? [];
-  for (const profile of profiles) {
-    assertKernelRef(profile.kernelRef, 'sessionDefaults.compute.kernelProfiles[].kernelRef');
-    byKey.set(buildKernelProfileKey(profile.kernelRef), profile);
-  }
-  return byKey;
-}
+const indexKernelProfiles = indexExecutionV0KernelProfiles;
 
 function resolveProfile(profileIndex, step) {
-  const key = buildKernelProfileKey(step.kernelRef);
-  if (!key) return null;
-  return profileIndex.get(key) ?? null;
-}
-
-function resolvePrecision(step, profile, sessionDefaults) {
-  const defaults = sessionDefaults.compute.defaults;
-  const precision = {
-    inputDtype: step.precision?.inputDtype
-      ?? profile?.precision?.inputDtype
-      ?? null,
-    mathDtype: step.precision?.mathDtype
-      ?? profile?.precision?.mathDtype
-      ?? defaults.mathDtype,
-    accumDtype: step.precision?.accumDtype
-      ?? profile?.precision?.accumDtype
-      ?? defaults.accumDtype,
-    outputDtype: step.precision?.outputDtype
-      ?? profile?.precision?.outputDtype
-      ?? defaults.outputDtype,
-  };
-  const sources = {
-    inputDtype: step.precision?.inputDtype != null
-      ? 'manifest'
-      : profile?.precision?.inputDtype != null
-        ? 'kernelProfile'
-        : 'derived',
-    mathDtype: step.precision?.mathDtype != null
-      ? 'manifest'
-      : profile?.precision?.mathDtype != null
-        ? 'kernelProfile'
-        : 'sessionDefault',
-    accumDtype: step.precision?.accumDtype != null
-      ? 'manifest'
-      : profile?.precision?.accumDtype != null
-        ? 'kernelProfile'
-        : 'sessionDefault',
-    outputDtype: step.precision?.outputDtype != null
-      ? 'manifest'
-      : profile?.precision?.outputDtype != null
-        ? 'kernelProfile'
-        : 'sessionDefault',
-  };
-  return { precision, sources };
-}
-
-function resolveKVIO(step, profile, sessionDefaults) {
-  if (step.kvIO) {
-    return {
-      value: {
-        readDtype: normalizeDtype(step.kvIO.readDtype, `${step.id}.kvIO.readDtype`),
-        writeDtype: normalizeDtype(step.kvIO.writeDtype, `${step.id}.kvIO.writeDtype`),
-      },
-      source: 'manifest',
-    };
-  }
-  if (profile?.kvIO) {
-    return {
-      value: {
-        readDtype: normalizeDtype(profile.kvIO.readDtype, `${step.id}.profile.kvIO.readDtype`),
-        writeDtype: normalizeDtype(profile.kvIO.writeDtype, `${step.id}.profile.kvIO.writeDtype`),
-      },
-      source: 'kernelProfile',
-    };
-  }
-  const kvDtype = normalizeDtype(
-    sessionDefaults?.kvcache?.kvDtype ?? sessionDefaults.compute.defaults.activationDtype,
-    `${step.id}.sessionDefaults.kvcache.kvDtype`
-  );
-  return {
-    value: { readDtype: kvDtype, writeDtype: kvDtype },
-    source: 'sessionDefault',
-  };
+  return resolveExecutionV0KernelProfile(profileIndex, step);
 }
 
 function validateStepShape(step, index) {
@@ -704,12 +636,20 @@ function normalizeRuntimeSessionForExecutionV0(runtimeSession, manifestInference
   const manifestProfiles = manifestSessionDefaults?.compute?.kernelProfiles;
   const hasManifestProfiles = Array.isArray(manifestProfiles) && manifestProfiles.length > 0;
   const manifestComputeDefaults = manifestSessionDefaults?.compute?.defaults ?? null;
+  const hasManifestKVCache = manifestSessionDefaults?.kvcache != null;
+  const hasManifestDecodeLoop = manifestSessionDefaults?.decodeLoop != null;
 
-  if (!runtimeSession || !runtimeSession.compute) {
+  if (!runtimeSession || typeof runtimeSession !== 'object') {
     return runtimeSession;
   }
 
-  let compute = runtimeSession.compute;
+  let compute = runtimeSession.compute ?? null;
+  let kvcache = Object.prototype.hasOwnProperty.call(runtimeSession, 'kvcache')
+    ? runtimeSession.kvcache
+    : undefined;
+  let decodeLoop = Object.prototype.hasOwnProperty.call(runtimeSession, 'decodeLoop')
+    ? runtimeSession.decodeLoop
+    : undefined;
   let changed = false;
 
   // Strip preset compute dtype defaults when manifest provides model-specific values.
@@ -736,19 +676,39 @@ function normalizeRuntimeSessionForExecutionV0(runtimeSession, manifestInference
     }
   }
 
+  // Strip preset nulls so manifest session defaults can win.
+  if (kvcache === null && hasManifestKVCache) {
+    kvcache = undefined;
+    changed = true;
+  }
+
+  if (decodeLoop === null && hasManifestDecodeLoop) {
+    decodeLoop = undefined;
+    changed = true;
+  }
+
   if (!changed) {
     return runtimeSession;
   }
 
+  const nextRuntimeSession = { ...runtimeSession };
   if (!compute) {
-    const { compute: _removed, ...rest } = runtimeSession;
-    return Object.keys(rest).length === 0 ? {} : rest;
+    delete nextRuntimeSession.compute;
+  } else {
+    nextRuntimeSession.compute = compute;
+  }
+  if (kvcache === undefined) {
+    delete nextRuntimeSession.kvcache;
+  } else {
+    nextRuntimeSession.kvcache = kvcache;
+  }
+  if (decodeLoop === undefined) {
+    delete nextRuntimeSession.decodeLoop;
+  } else {
+    nextRuntimeSession.decodeLoop = decodeLoop;
   }
 
-  return {
-    ...runtimeSession,
-    compute,
-  };
+  return Object.keys(nextRuntimeSession).length === 0 ? {} : nextRuntimeSession;
 }
 
 function validatePhaseBoundaryCompatibility(options) {
@@ -790,6 +750,25 @@ function validatePhaseBoundaryCompatibility(options) {
   }
 }
 
+function assertKVLayoutExecutionCompatibility(steps, sessionDefaults) {
+  const kvLayout = normalizeKVLayout(sessionDefaults?.kvcache?.layout, 'sessionDefaults.kvcache.layout');
+  if (kvLayout !== 'bdpa') {
+    return;
+  }
+  const incompatibleStep = steps.find((step) => (
+    step?.op === 'attention'
+    && isPhaseMatch(normalizePhase(step.phase, `${step.id}.phase`), 'prefill')
+  ));
+  if (!incompatibleStep) {
+    return;
+  }
+  throw new Error(
+    `[ExecutionV0] sessionDefaults.kvcache.layout="bdpa" is decode-only, ` +
+    `but step "${incompatibleStep.id}" declares prefill attention. ` +
+    'Use a non-BDPA KV layout for prefill-capable models or remove prefill attention from the execution contract.'
+  );
+}
+
 function toKernelPathStep(step) {
   if (step.op === 'cast') return null;
   if (!step.kernel) return null;
@@ -818,6 +797,65 @@ function buildLayerPhaseSteps(steps, phase, layerIdx) {
     .filter((step) => step != null);
 }
 
+function getInlineKernelPathSteps(path) {
+  return [
+    ...(path?.preLayer ?? []),
+    ...(path?.decode?.steps ?? []),
+    ...(path?.prefill?.steps ?? []),
+    ...(path?.postLayer ?? []),
+    ...(path?.sampling ?? []),
+    ...(path?.layerOverrides?.flatMap((override) => override.steps ?? []) ?? []),
+  ];
+}
+
+function assertInlineKernelPathSessionCompatibility(path, sessionDefaults) {
+  if (!path) {
+    return;
+  }
+  const activationDtype = normalizeDtype(
+    path.activationDtype ?? sessionDefaults?.compute?.defaults?.activationDtype ?? 'f16',
+    'inlineKernelPath.activationDtype'
+  );
+  const kvDtype = normalizeDtype(
+    path.kvDtype ?? sessionDefaults?.kvcache?.kvDtype ?? activationDtype,
+    'inlineKernelPath.kvDtype'
+  );
+
+  for (const step of getInlineKernelPathSteps(path)) {
+    const kernel = String(step?.kernel ?? '').trim();
+    if (!kernel.startsWith('attention')) {
+      continue;
+    }
+    if (kernel.includes('_f16kv')) {
+      if (activationDtype !== 'f32' || kvDtype !== 'f16') {
+        throw new Error(
+          `[ExecutionV0] Inline kernelPath attention kernel "${kernel}" requires ` +
+          `activationDtype="f32" and kvcache.kvDtype="f16", but resolved ` +
+          `activationDtype="${activationDtype}" and kvcache.kvDtype="${kvDtype}".`
+        );
+      }
+      continue;
+    }
+    if (kernel.includes('_f16')) {
+      if (activationDtype !== 'f16' || kvDtype !== 'f16') {
+        throw new Error(
+          `[ExecutionV0] Inline kernelPath attention kernel "${kernel}" requires ` +
+          `activationDtype="f16" and kvcache.kvDtype="f16", but resolved ` +
+          `activationDtype="${activationDtype}" and kvcache.kvDtype="${kvDtype}".`
+        );
+      }
+      continue;
+    }
+    if (activationDtype !== 'f32' || kvDtype !== 'f32') {
+      throw new Error(
+        `[ExecutionV0] Inline kernelPath attention kernel "${kernel}" requires ` +
+        `activationDtype="f32" and kvcache.kvDtype="f32", but resolved ` +
+        `activationDtype="${activationDtype}" and kvcache.kvDtype="${kvDtype}".`
+      );
+    }
+  }
+}
+
 function buildInlineKernelPath(steps, sessionDefaults, modelId, numLayers) {
   const activationDtype = normalizeDtype(
     sessionDefaults?.compute?.defaults?.activationDtype ?? 'f16',
@@ -884,6 +922,7 @@ function buildInlineKernelPath(steps, sessionDefaults, modelId, numLayers) {
     path.sampling = sampling;
   }
 
+  assertInlineKernelPathSessionCompatibility(path, sessionDefaults);
   return path;
 }
 
@@ -1003,6 +1042,7 @@ export function compileExecutionV0(options = {}) {
   const patchedSteps = applyExecutionPatchAtomic(baseSteps, runtimeInference.executionPatch ?? null);
   patchedSteps.forEach(validateStepShape);
   validateUniqueStepIds(patchedSteps);
+  assertKVLayoutExecutionCompatibility(patchedSteps, resolvedSession);
   const runtimePatchMeta = indexRuntimePatchMeta(runtimeInference.executionPatch ?? null);
 
   const manifestSessionDefaults = manifestInference.sessionDefaults ?? {};

package/src/inference/pipelines/text/init.js

@@ -49,6 +49,35 @@ function isRDRRManifest(manifest) {
   return manifest !== null && typeof manifest === 'object' && Array.isArray( (manifest).shards);
 }
 
+function normalizeBaseUrl(baseUrl) {
+  if (typeof baseUrl !== 'string' || baseUrl.trim().length === 0) {
+    return null;
+  }
+  return baseUrl.replace(/\/$/, '');
+}
+
+function createRemoteStorageContext(baseUrl, manifest) {
+  const root = normalizeBaseUrl(baseUrl);
+  if (!root || !isRDRRManifest(manifest)) {
+    return null;
+  }
+
+  return {
+    async loadShard(index) {
+      const shard = manifest.shards[index];
+      const filename = shard?.filename;
+      if (!filename) {
+        throw new Error(`Manifest shard ${index} is missing filename.`);
+      }
+      const response = await fetch(`${root}/${filename.replace(/^\/+/, '')}`);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch shard ${index} from ${root}: ${response.status}`);
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  };
+}
+
 
 function resolveQ4KConfig(
   manifest,
@@ -505,10 +534,12 @@ export async function initTokenizer(manifest, options = {}) {
 
 
 export async function loadWeights(manifest, modelConfig, options = {}) {
-  const { storageContext, onProgress, loadingConfig, baseUrl } = options;
+  const { onProgress, loadingConfig, baseUrl } = options;
+  const runtimeStorageContext = options.storageContext
+    ?? createRemoteStorageContext(baseUrl, manifest);
   const verifyHashes = (
-    typeof storageContext?.verifyHashes === 'boolean'
-      ? storageContext.verifyHashes
+    typeof runtimeStorageContext?.verifyHashes === 'boolean'
+      ? runtimeStorageContext.verifyHashes
       : options.verifyHashes
   ) ?? loadingConfig?.shardCache?.verifyHashes;
   if (verifyHashes == null) {
@@ -536,31 +567,31 @@ export async function loadWeights(manifest, modelConfig, options = {}) {
   }
 
   // Configure custom shard loader if provided (Native Bridge or direct-source bundle)
-  const hasLoadShard = typeof storageContext?.loadShard === 'function';
-  const hasLoadShardRange = typeof storageContext?.loadShardRange === 'function';
-  const hasStreamShardRange = typeof storageContext?.streamShardRange === 'function';
+  const hasLoadShard = typeof runtimeStorageContext?.loadShard === 'function';
+  const hasLoadShardRange = typeof runtimeStorageContext?.loadShardRange === 'function';
+  const hasStreamShardRange = typeof runtimeStorageContext?.streamShardRange === 'function';
   if (hasLoadShard || hasLoadShardRange) {
     log.debug('Pipeline', 'Using custom shard loader (Native Bridge or external)');
 
     const loadShard = async (index) => {
       if (hasLoadShard) {
-        const data = await storageContext.loadShard(index);
+        const data = await runtimeStorageContext.loadShard(index);
         return toUint8Array(data, 'storageContext.loadShard');
       }
-      const rangeData = await storageContext.loadShardRange(index, 0, null);
+      const rangeData = await runtimeStorageContext.loadShardRange(index, 0, null);
       return toUint8Array(rangeData, 'storageContext.loadShardRange');
     };
 
     const loadShardRange = hasLoadShardRange
       ? async (index, offset, length = null) => {
-        const data = await storageContext.loadShardRange(index, offset, length);
+        const data = await runtimeStorageContext.loadShardRange(index, offset, length);
         return toArrayBuffer(data, 'storageContext.loadShardRange');
       }
       : null;
 
     const streamShardRange = hasStreamShardRange
       ? async function* (index, offset = 0, length = null, streamOptions = {}) {
-        for await (const chunk of storageContext.streamShardRange(index, offset, length, streamOptions)) {
+        for await (const chunk of runtimeStorageContext.streamShardRange(index, offset, length, streamOptions)) {
           yield toUint8Array(chunk, 'storageContext.streamShardRange');
         }
       }

package/src/inference/pipelines/text.js

@@ -1,5 +1,5 @@
 
-import { getDevice } from '../../gpu/device.js';
+import { getDevice, initDevice } from '../../gpu/device.js';
 import { getBufferPool as getGlobalBufferPool } from '../../memory/buffer-pool.js';
 import { log } from '../../debug/index.js';
 import { configurePerfGuards } from '../../gpu/perf-guards.js';
@@ -85,6 +85,12 @@ export class InferencePipeline extends PipelineState {
     applyPipelineDebugConfig(sharedDebug?.pipeline);
     configurePerfGuards(sharedDebug?.perfGuards);
 
+    if (!this.gpuContext?.device && typeof globalThis.navigator !== 'undefined' && globalThis.navigator?.gpu) {
+      const device = await initDevice();
+      this.gpuContext = { device };
+      this.useGPU = true;
+    }
+
     this.emulation = await initEmulation(this.runtimeConfig);
 
     this.debug = sharedDebug?.pipeline?.enabled === true;

package/src/rules/execution-rules-contract-check.d.ts

@@ -0,0 +1,17 @@
+export interface InferenceExecutionRulesContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: Array<{ id: string; ok: boolean }>;
+  errors: string[];
+  stats: {
+    decodeRecorderRules: number;
+    batchDecodeRules: number;
+    decodeRecorderContexts: number;
+    batchDecodeContexts: number;
+  };
+}
+
+export declare function buildInferenceExecutionRulesContractArtifact(
+  ruleGroup: Record<string, unknown> | null | undefined
+): InferenceExecutionRulesContractArtifact;