@simulatte/doppler 0.1.4 → 0.1.6

package/src/config/schema/doppler.schema.js

@@ -3,6 +3,13 @@ import { DEFAULT_INFERENCE_DEFAULTS_CONFIG } from './inference-defaults.schema.j
 import { DEFAULT_SHARED_RUNTIME_CONFIG } from './shared-runtime.schema.js';
 import { DEFAULT_EMULATION_CONFIG, createEmulationConfig } from './emulation.schema.js';
 import { mergeEcosystemConfig } from './ecosystem.schema.js';
+import {
+  chooseNullish,
+  mergeExecutionPatchLists,
+  mergeKernelPathPolicy,
+  mergeShallowObject,
+  replaceSubtree,
+} from '../merge-helpers.js';
 
 // =============================================================================
 // Runtime Config (all non-model-specific settings)
@@ -172,8 +179,6 @@ function mergeInferenceConfig(
   const overrideExecutionPatch = overrides.executionPatch ?? {};
   const baseKernelPathPolicy = base.kernelPathPolicy ?? {};
   const overrideKernelPathPolicy = overrides.kernelPathPolicy ?? {};
-  const baseKernelPathSourceScope = baseKernelPathPolicy.sourceScope ?? baseKernelPathPolicy.allowSources;
-  const overrideKernelPathSourceScope = overrideKernelPathPolicy.sourceScope ?? overrideKernelPathPolicy.allowSources;
   const hasRuntimeKernelProfiles = Object.prototype.hasOwnProperty.call(
     overrideSessionCompute,
     'kernelProfiles'
@@ -236,15 +241,8 @@ function mergeInferenceConfig(
     pipeline: overrides.pipeline ?? base.pipeline,
     kernelPath: overrides.kernelPath ?? base.kernelPath,
     kernelPathSource: overrides.kernelPathSource ?? base.kernelPathSource,
-    kernelPathPolicy: {
-      mode: overrideKernelPathPolicy.mode ?? baseKernelPathPolicy.mode,
-      sourceScope: overrideKernelPathSourceScope ?? baseKernelPathSourceScope,
-      allowSources: overrideKernelPathSourceScope ?? baseKernelPathSourceScope,
-      onIncompatible: overrideKernelPathPolicy.onIncompatible ?? baseKernelPathPolicy.onIncompatible,
-    },
-    chatTemplate: overrides.chatTemplate
-      ? { ...base.chatTemplate, ...overrides.chatTemplate }
-      : base.chatTemplate,
+    kernelPathPolicy: mergeKernelPathPolicy(baseKernelPathPolicy, overrideKernelPathPolicy),
+    chatTemplate: mergeShallowObject(base.chatTemplate, overrides.chatTemplate),
     session: {
       ...baseSession,
       ...overrideSession,
@@ -259,14 +257,10 @@ function mergeInferenceConfig(
           ? { kernelProfiles: overrideSessionCompute.kernelProfiles }
           : { kernelProfiles: baseSessionCompute.kernelProfiles }),
       },
-      kvcache: overrideSession.kvcache ?? baseSession.kvcache,
-      decodeLoop: overrideSession.decodeLoop ?? baseSession.decodeLoop,
-    },
-    executionPatch: {
-      set: overrideExecutionPatch.set ?? baseExecutionPatch.set ?? [],
-      remove: overrideExecutionPatch.remove ?? baseExecutionPatch.remove ?? [],
-      add: overrideExecutionPatch.add ?? baseExecutionPatch.add ?? [],
+      kvcache: replaceSubtree(overrideSession.kvcache, baseSession.kvcache),
+      decodeLoop: replaceSubtree(overrideSession.decodeLoop, baseSession.decodeLoop),
     },
+    executionPatch: mergeExecutionPatchLists(baseExecutionPatch, overrideExecutionPatch),
     // Model-specific inference overrides (merged with manifest.inference at load time)
     modelOverrides: overrides.modelOverrides ?? base.modelOverrides,
   };

package/src/config/schema/index.d.ts

@@ -225,6 +225,28 @@ export {
   type ConversionIOSchema,
 } from './conversion.schema.js';
 
+// =============================================================================
+// Browser Suite Metrics Schema
+// =============================================================================
+export {
+  type BrowserSuiteMetricsSchema,
+  BROWSER_SUITE_METRICS_SCHEMA_VERSION,
+  DEFAULT_BROWSER_SUITE_METRICS,
+  validateBrowserSuiteMetrics,
+} from './browser-suite-metrics.schema.js';
+
+// =============================================================================
+// Conversion Report Schema
+// =============================================================================
+export {
+  type ConversionReportResultSchema,
+  type ConversionReportManifestSchema,
+  type ConversionReportSchema,
+  CONVERSION_REPORT_SCHEMA_VERSION,
+  DEFAULT_CONVERSION_REPORT,
+  validateConversionReport,
+} from './conversion-report.schema.js';
+
 // =============================================================================
 // Converter Schema
 // =============================================================================

package/src/config/schema/index.js

@@ -55,6 +55,24 @@ export {
   ConversionStage,
 } from './conversion.schema.js';
 
+// =============================================================================
+// Browser Suite Metrics Schema
+// =============================================================================
+export {
+  BROWSER_SUITE_METRICS_SCHEMA_VERSION,
+  DEFAULT_BROWSER_SUITE_METRICS,
+  validateBrowserSuiteMetrics,
+} from './browser-suite-metrics.schema.js';
+
+// =============================================================================
+// Conversion Report Schema
+// =============================================================================
+export {
+  CONVERSION_REPORT_SCHEMA_VERSION,
+  DEFAULT_CONVERSION_REPORT,
+  validateConversionReport,
+} from './conversion-report.schema.js';
+
 // =============================================================================
 // Converter Schema
 // =============================================================================

package/src/config/schema/inference-defaults.schema.js

@@ -165,6 +165,9 @@ export const DEFAULT_PRESET_INFERENCE_CONFIG = {
   rope: {
     ropeTheta: 10000,
     ropeLocalTheta: null,
+    mropeInterleaved: false,
+    mropeSection: null,
+    partialRotaryFactor: null,
     ropeScalingType: null,
     ropeScalingFactor: 1.0,
     ropeLocalScalingType: null,

package/src/config/schema/inference.schema.d.ts

@@ -18,6 +18,15 @@ export interface RoPEConfigSchema {
   /** Local RoPE theta for sliding window layers (Gemma 3 uses 10000) */
   ropeLocalTheta?: number;
 
+  /** Apply adjacent-pair rotary layout instead of rotate-half layout. */
+  mropeInterleaved?: boolean;
+
+  /** mRoPE section sizes before the Qwen doubling step. */
+  mropeSection?: number[] | null;
+
+  /** Fraction of the head dimension that participates in rotary embedding. */
+  partialRotaryFactor?: number | null;
+
   /** RoPE scaling type */
   ropeScalingType?: 'linear' | 'dynamic' | 'yarn' | null;
 

package/src/config/schema/kernel-path.schema.d.ts

@@ -105,6 +105,12 @@ export interface KernelPathSchema {
   /** KV cache dtype for this path; defaults to activationDtype when omitted. */
   kvDtype?: string;
 
+  /**
+   * Explicit widening target used by the finiteness fallback execution plan.
+   * Required for inline/generated kernel paths that do not have a stable registry id.
+   */
+  finitenessFallbackKernelPathId?: string;
+
   /**
    * Prefill phase kernel sequence (M > 1).
    * If not specified, uses decode with batched variants.

package/src/config/schema/manifest.schema.d.ts

@@ -217,6 +217,12 @@ export interface ManifestRoPESchema {
   ropeTheta: number;
   /** Local theta for sliding window layers (null = same as ropeTheta) */
   ropeLocalTheta: number | null;
+  /** Use adjacent-pair rotary layout instead of rotate-half layout. */
+  mropeInterleaved: boolean;
+  /** mRoPE section sizes before the Qwen doubling step. */
+  mropeSection: number[] | null;
+  /** Fraction of the head dimension that participates in rotary embedding. */
+  partialRotaryFactor: number | null;
   /** RoPE scaling type (null = no scaling, 'linear', 'dynamic', 'yarn') */
   ropeScalingType: string | null;
   /** RoPE scaling factor (1.0 if no scaling) */

package/src/config/schema/manifest.schema.js

@@ -62,6 +62,9 @@ export const DEFAULT_MANIFEST_INFERENCE = {
   rope: {
     ropeTheta: 10000,
     ropeLocalTheta: null,  // Same as ropeTheta (null = use ropeTheta)
+    mropeInterleaved: false,
+    mropeSection: null,
+    partialRotaryFactor: null,
     ropeScalingType: null,  // No scaling (null = disabled)
     ropeScalingFactor: 1.0,
     ropeLocalScalingType: null,  // Local scaling policy (null = no scaling)

package/src/converter/core.d.ts

@@ -27,6 +27,12 @@ import type {
   MoEConfigSchema,
   ConversionInfoSchema,
 } from '../config/schema/index.js';
+import type { ExecutionContractArtifact } from '../config/execution-contract-check.js';
+import type { ExecutionV0GraphContractArtifact } from '../config/execution-v0-graph-contract-check.js';
+import type {
+  ManifestRequiredInferenceFieldsArtifact,
+  RequiredInferenceFieldsContractArtifact,
+} from '../config/required-inference-fields-contract-check.js';
 
 export { generateShardFilename } from '../formats/rdrr/index.js';
 
@@ -144,6 +150,10 @@ export interface ConvertResult {
   shardCount: number;
   tensorCount: number;
   totalSize: number;
+  executionContractArtifact: ExecutionContractArtifact | null;
+  executionV0GraphContractArtifact: ExecutionV0GraphContractArtifact | null;
+  layerPatternContractArtifact: Record<string, unknown> | null;
+  requiredInferenceFieldsArtifact: ManifestRequiredInferenceFieldsArtifact | RequiredInferenceFieldsContractArtifact | null;
 }
 
 /** @deprecated Use ConversionIOSchema from config/schema */

package/src/converter/core.js

@@ -9,15 +9,20 @@ import {
   formatBytes,
 } from '../config/schema/index.js';
 
-import { classifyTensorRole, generateShardFilename } from '../formats/rdrr/index.js';
+import { classifyTensor, classifyTensorRole, generateShardFilename } from '../formats/rdrr/index.js';
 import { log } from '../debug/index.js';
-import { selectRuleValue } from '../rules/rule-registry.js';
+import {
+  getInferenceLayerPatternContractArtifact,
+  selectRuleValue,
+} from '../rules/rule-registry.js';
 import {
   createConverterConfig,
   detectPreset,
   listPresets,
   resolvePreset,
 } from '../config/index.js';
+import { buildExecutionContractArtifact } from '../config/execution-contract-check.js';
+import { buildManifestRequiredInferenceFieldsArtifact } from '../config/required-inference-fields-contract-check.js';
 import { buildManifestInference, inferEmbeddingOutputConfig } from './manifest-inference.js';
 import { resolveEosTokenId } from './tokenizer-utils.js';
 import {
@@ -1128,6 +1133,7 @@ export async function convertModel(model, io, options = {}) {
   }
   const totalTensors = tensors.length;
   const targetQuant = String(options.quantization ?? model.quantization ?? '').trim().toLowerCase();
+  const tensorGroupModelType = String(options.modelType ?? model.modelType ?? 'transformer');
   const q4kLayout = normalizeQ4KLayout(options.quantizationInfo?.layout);
   const quantizeEmbeddings = resolveQuantizeEmbeddings(
     options.quantizationInfo ?? null,
@@ -1251,6 +1257,7 @@ export async function convertModel(model, io, options = {}) {
 
     // Record tensor location
     const role = classifyTensorRole(tensor.name);
+    const group = classifyTensor(tensor.name, tensorGroupModelType);
 
     if (tensorSpans.length === 1) {
       tensorLocations[tensor.name] = {
@@ -1260,6 +1267,7 @@ export async function convertModel(model, io, options = {}) {
         shape: tensor.shape,
         dtype: outDtype,
         role,
+        group,
         ...(outLayout ? { layout: outLayout } : {}),
       };
     } else {
@@ -1269,6 +1277,7 @@ export async function convertModel(model, io, options = {}) {
         shape: tensor.shape,
         dtype: outDtype,
         role,
+        group,
         ...(outLayout ? { layout: outLayout } : {}),
       };
     }
@@ -1327,11 +1336,27 @@ export async function convertModel(model, io, options = {}) {
     totalSize: formatBytes(totalSize),
   });
 
+  const executionContractArtifact = buildExecutionContractArtifact(manifest);
+  const layerPatternContractArtifact = getInferenceLayerPatternContractArtifact();
+  const requiredInferenceFieldsArtifact = manifest?.modelType === 'transformer'
+    && manifest?.inference
+    && typeof manifest.inference === 'object'
+    && manifest.inference.attention
+    && typeof manifest.inference.attention === 'object'
+    ? buildManifestRequiredInferenceFieldsArtifact(
+      manifest?.inference ?? null,
+      `${manifest?.modelId ?? modelId}.inference`
+    )
+    : null;
   return {
     manifest,
     shardCount: shards.length,
     tensorCount: tensors.length,
     totalSize,
+    executionContractArtifact,
+    executionV0GraphContractArtifact: executionContractArtifact?.executionV0?.graph ?? null,
+    layerPatternContractArtifact,
+    requiredInferenceFieldsArtifact,
   };
 }
 

package/src/converter/parsers/diffusion.js

@@ -4,6 +4,13 @@ const SD3_LAYOUT = {
   id: 'sd3',
   requiredComponents: ['transformer', 'text_encoder', 'text_encoder_2', 'text_encoder_3', 'vae', 'scheduler'],
   weightedComponents: ['transformer', 'text_encoder', 'text_encoder_2', 'text_encoder_3', 'vae'],
+  matches(modelIndex, components) {
+    return (
+      components.has('text_encoder_2') &&
+      components.has('text_encoder_3') &&
+      getComponentClassName(modelIndex?.transformer) === 'SD3Transformer2DModel'
+    );
+  },
   tokenizerSpecs: [
     {
       modelIndexKey: 'tokenizer',
@@ -66,6 +73,10 @@ const FLUX_LAYOUT = {
   id: 'flux',
   requiredComponents: ['transformer', 'text_encoder', 'vae', 'scheduler'],
   weightedComponents: ['transformer', 'text_encoder', 'vae'],
+  matches(modelIndex) {
+    const transformerClass = getComponentClassName(modelIndex?.transformer);
+    return typeof transformerClass === 'string' && /^Flux/i.test(transformerClass);
+  },
   tokenizerSpecs: [
     {
       modelIndexKey: 'tokenizer',
@@ -91,7 +102,39 @@ const FLUX_LAYOUT = {
   ],
 };
 
-const LAYOUTS = [SD3_LAYOUT, FLUX_LAYOUT];
+const SANA_LAYOUT = {
+  id: 'sana',
+  requiredComponents: ['transformer', 'text_encoder', 'tokenizer', 'vae', 'scheduler'],
+  weightedComponents: ['transformer', 'text_encoder', 'vae'],
+  matches(modelIndex) {
+    return (
+      getComponentClassName(modelIndex?.transformer) === 'SanaTransformer2DModel' &&
+      getComponentClassName(modelIndex?.text_encoder) === 'Gemma2Model'
+    );
+  },
+  tokenizerSpecs: [
+    {
+      modelIndexKey: 'tokenizer',
+      componentId: 'text_encoder',
+      type: 'bundled',
+      assets: [
+        { suffix: 'tokenizer/tokenizer.json', targetName: 'tokenizer_tokenizer.json', kind: 'text', required: true },
+        { suffix: 'tokenizer/tokenizer_config.json', targetName: 'tokenizer_config.json', kind: 'text', required: false },
+        { suffix: 'tokenizer/special_tokens_map.json', targetName: 'tokenizer_special_tokens_map.json', kind: 'text', required: false },
+        { suffix: 'tokenizer/tokenizer.model', targetName: 'tokenizer_tokenizer.model', kind: 'binary', required: false },
+      ],
+      config: {
+        type: 'bundled',
+        tokenizerFile: 'tokenizer_tokenizer.json',
+        configFile: 'tokenizer_config.json',
+        specialTokensFile: 'tokenizer_special_tokens_map.json',
+        sentencePieceFile: 'tokenizer_tokenizer.model',
+      },
+    },
+  ],
+};
+
+const LAYOUTS = [SD3_LAYOUT, FLUX_LAYOUT, SANA_LAYOUT];
 
 function toAbortError(message = 'Cancelled') {
   if (typeof DOMException === 'function') {
@@ -112,12 +155,26 @@ function listModelComponents(modelIndex) {
   return Object.keys(modelIndex || {}).filter((key) => !key.startsWith('_'));
 }
 
+function getComponentClassName(componentEntry) {
+  if (Array.isArray(componentEntry) && componentEntry.length >= 2 && typeof componentEntry[1] === 'string') {
+    return componentEntry[1];
+  }
+  if (componentEntry && typeof componentEntry === 'object' && typeof componentEntry._class_name === 'string') {
+    return componentEntry._class_name;
+  }
+  return null;
+}
+
 export function detectDiffusionLayout(modelIndex) {
   const components = new Set(listModelComponents(modelIndex));
   for (const layout of LAYOUTS) {
-    if (layout.requiredComponents.every((component) => components.has(component))) {
-      return layout;
+    if (!layout.requiredComponents.every((component) => components.has(component))) {
+      continue;
     }
+    if (typeof layout.matches === 'function' && !layout.matches(modelIndex, components)) {
+      continue;
+    }
+    return layout;
   }
   const listed = [...components].sort().join(', ') || '(none)';
   const expected = LAYOUTS
@@ -199,6 +256,9 @@ export async function parseDiffusionModel(adapter) {
   const tensors = [];
 
   for (const componentId of layout.requiredComponents) {
+    if (componentId === 'tokenizer') {
+      continue;
+    }
     const configSuffix = defaultConfigPath(componentId);
     const config = await readJson(configSuffix, `${componentId} config`);
     if (componentId === 'transformer' && config && !config.weight_format) {

package/src/converter/rope-config.js

@@ -6,10 +6,26 @@ function asObject(value) {
 }
 
 function asFiniteNumber(value) {
+  if (value == null || value === '') {
+    return null;
+  }
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+function asBoolean(value) {
+  return typeof value === 'boolean' ? value : null;
+}
+
+function asNumberArray(value) {
+  if (!Array.isArray(value)) return null;
+  const normalized = value.map((entry) => asFiniteNumber(entry));
+  if (normalized.some((entry) => entry == null || entry <= 0)) {
+    return null;
+  }
+  return normalized.map((entry) => Math.trunc(entry));
+}
+
 function normalizeRoPEType(value) {
   if (typeof value !== 'string') return null;
   const normalized = value.trim().toLowerCase();
@@ -125,6 +141,13 @@ function failOnConflictingScaling(sourceLabel, canonicalScaling, candidateScalin
 export function buildRoPEConfig(presetInference, config) {
   const ropeScaling = asObject(config.rope_scaling);
   const ropeParameters = asObject(config.rope_parameters);
+  const flatRoPEParameters = (
+    ropeParameters
+      && !asObject(ropeParameters.full_attention)
+      && !asObject(ropeParameters.sliding_attention)
+  )
+    ? ropeParameters
+    : null;
   const fullAttentionRoPE = asObject(ropeParameters?.full_attention);
   const slidingAttentionRoPE = asObject(ropeParameters?.sliding_attention);
   const presetRoPE = presetInference.rope ?? {};
@@ -164,6 +187,11 @@ export function buildRoPEConfig(presetInference, config) {
       strictMissingTypeAndFactor: false,
       sourceLabel: 'HF config rope_parameters.full_attention',
     });
+  } else if (flatRoPEParameters) {
+    globalScaling = resolveScalingConfig(flatRoPEParameters, {
+      strictMissingTypeAndFactor: false,
+      sourceLabel: 'HF config rope_parameters',
+    });
   }
 
   const hasPresetLocalScaling = presetRoPE.ropeLocalScalingType !== undefined
@@ -192,6 +220,7 @@ export function buildRoPEConfig(presetInference, config) {
   // HF config is source of truth for ropeTheta when provided:
   // prefer rope_parameters.full_attention.rope_theta, then rope_theta.
   const ropeTheta = asFiniteNumber(fullAttentionRoPE?.rope_theta)
+    ?? asFiniteNumber(flatRoPEParameters?.rope_theta)
     ?? asFiniteNumber(config.rope_theta)
     ?? presetInference.rope?.ropeTheta
     ?? 10000;
@@ -201,9 +230,22 @@ export function buildRoPEConfig(presetInference, config) {
     ?? presetInference.rope?.ropeLocalTheta
     ?? null;
 
+  const mropeInterleaved = asBoolean(flatRoPEParameters?.mrope_interleaved)
+    ?? presetInference.rope?.mropeInterleaved
+    ?? false;
+  const mropeSection = asNumberArray(flatRoPEParameters?.mrope_section)
+    ?? presetInference.rope?.mropeSection
+    ?? null;
+  const partialRotaryFactor = asFiniteNumber(flatRoPEParameters?.partial_rotary_factor)
+    ?? asFiniteNumber(presetInference.rope?.partialRotaryFactor)
+    ?? null;
+
   return {
     ropeTheta,
     ropeLocalTheta,
+    mropeInterleaved,
+    mropeSection,
+    partialRotaryFactor,
     ropeScalingType: globalScaling.ropeScalingType,
     ropeScalingFactor: globalScaling.ropeScalingFactor,
     yarnBetaFast: globalScaling.yarnBetaFast,

package/src/gpu/device.js

@@ -28,6 +28,62 @@ function advanceDeviceEpoch() {
   deviceEpoch += 1;
 }
 
+function isValidGPUBuffer(value) {
+  if (!value) {
+    return false;
+  }
+  if (typeof GPUBuffer === 'undefined') {
+    return true;
+  }
+  return value instanceof GPUBuffer;
+}
+
+function describeBindGroupBufferValue(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof GPUBuffer !== 'undefined' && value instanceof GPUBuffer) return 'GPUBuffer';
+  if (typeof value === 'object') {
+    return value.constructor?.name || 'object';
+  }
+  return typeof value;
+}
+
+function validateBindGroupDescriptor(descriptor) {
+  const label = descriptor?.label || 'unlabeled_bind_group';
+  const entries = Array.isArray(descriptor?.entries) ? descriptor.entries : [];
+  for (const entry of entries) {
+    const resource = entry?.resource;
+    if (!resource || typeof resource !== 'object' || !('buffer' in resource)) {
+      continue;
+    }
+    if (isValidGPUBuffer(resource.buffer)) {
+      continue;
+    }
+    throw new Error(
+      `[${label}] binding ${entry.binding} requires a GPUBuffer; ` +
+      `got ${describeBindGroupBufferValue(resource.buffer)}.`
+    );
+  }
+}
+
+function wrapDeviceCreateBindGroup(device) {
+  if (!device || device.__dopplerBindGroupValidationWrapped) {
+    return device;
+  }
+  const originalCreateBindGroup = device.createBindGroup.bind(device);
+  device.createBindGroup = (descriptor) => {
+    validateBindGroupDescriptor(descriptor);
+    return originalCreateBindGroup(descriptor);
+  };
+  Object.defineProperty(device, '__dopplerBindGroupValidationWrapped', {
+    value: true,
+    configurable: true,
+    enumerable: false,
+    writable: false,
+  });
+  return device;
+}
+
 
 export const FEATURES =  ({
   SHADER_F16: 'shader-f16',
@@ -201,6 +257,7 @@ export async function initDevice() {
   if (!gpuDevice) {
     throw createDopplerError(ERROR_CODES.GPU_DEVICE_FAILED, 'Failed to create WebGPU device');
   }
+  wrapDeviceCreateBindGroup(gpuDevice);
   advanceDeviceEpoch();
 
   // Set up device lost handler
@@ -253,6 +310,7 @@ export function setDevice(device, options = {}) {
   }
 
   gpuDevice = device;
+  wrapDeviceCreateBindGroup(gpuDevice);
   advanceDeviceEpoch();
   wrapQueueForTracking(gpuDevice.queue);