@simulatte/doppler 0.1.5 → 0.1.7

package/src/inference/pipelines/text/chat-format.js

@@ -224,6 +224,29 @@ function formatChatML(messages) {
   return parts.join('');
 }
 
+function formatQwen(messages) {
+  // Qwen 3.5 chat format is ChatML-like, but the generation prelude includes
+  // an explicit empty thinking block before assistant output.
+  const parts = [];
+  for (const [index, message] of messages.entries()) {
+    const role = normalizeChatRole(message?.role);
+    assertSupportedChatRole(role, 'Qwen', index);
+    if (role === 'system' && index !== 0) {
+      throw new Error('Qwen template requires any system message to appear first.');
+    }
+    const content = normalizeChatMessageContent(message?.content);
+    if (role === 'system') {
+      parts.push(`<|im_start|>system\n${content}<|im_end|>\n`);
+    } else if (role === 'user') {
+      parts.push(`<|im_start|>user\n${content}<|im_end|>\n`);
+    } else if (role === 'assistant') {
+      parts.push(`<|im_start|>assistant\n${content}<|im_end|>\n`);
+    }
+  }
+  parts.push('<|im_start|>assistant\n<think>\n\n</think>\n\n');
+  return parts.join('');
+}
+
 function formatTranslateGemmaUserPrompt(content) {
   if (!Array.isArray(content) || content.length !== 1) {
     throw new Error(
@@ -345,7 +368,7 @@ const CHAT_FORMATTERS = {
   'llama3': formatHeaderBased,
   'gpt-oss': formatChannelBased,
   'chatml': formatChatML,
-  'qwen': formatChatML,
+  'qwen': formatQwen,
   'translategemma': formatTranslateGemma,
 };
 
@@ -363,4 +386,5 @@ export function formatChatMessages(messages, templateType) {
 export const formatGemmaChat = formatTurnBased;
 export const formatLlama3Chat = formatHeaderBased;
 export const formatGptOssChat = formatChannelBased;
+export const formatQwenChat = formatQwen;
 export const formatTranslateGemmaChat = formatTranslateGemma;

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

@@ -148,6 +148,10 @@ export interface ParsedModelConfig {
   slidingWindow: number | null;
   ropeTheta: number;
   ropeLocalTheta: number | null;
+  ropeRotaryDim: number;
+  ropeInterleaved: boolean;
+  mropeSection: number[] | null;
+  partialRotaryFactor: number | null;
   ropeScale: number;
   ropeLocalScale: number;
   ropeScalingType: string | null;

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

@@ -21,6 +21,28 @@ function assertSupportedRuntimeModelType(manifest) {
   );
 }
 
+function resolveRotaryDim(headDim, partialRotaryFactor, modelId) {
+  if (partialRotaryFactor == null) {
+    return headDim;
+  }
+  if (typeof partialRotaryFactor !== 'number' || Number.isNaN(partialRotaryFactor)) {
+    throw new Error(`Manifest "${modelId}" has invalid rope.partialRotaryFactor.`);
+  }
+  if (partialRotaryFactor <= 0 || partialRotaryFactor > 1) {
+    throw new Error(
+      `Manifest "${modelId}" requires 0 < rope.partialRotaryFactor <= 1; got ${partialRotaryFactor}.`
+    );
+  }
+  const rotaryDim = Math.trunc(headDim * partialRotaryFactor);
+  if (rotaryDim <= 0 || (rotaryDim % 2) !== 0) {
+    throw new Error(
+      `Manifest "${modelId}" resolves rope rotary dim ${rotaryDim} from headDim=${headDim} ` +
+      `and partialRotaryFactor=${partialRotaryFactor}, but rotary dim must be a positive even integer.`
+    );
+  }
+  return rotaryDim;
+}
+
 export function getStopTokenIds(manifest) {
   const eosTokenId = manifest?.eos_token_id;
   if (Array.isArray(eosTokenId)) return eosTokenId;
@@ -112,11 +134,10 @@ function resolveIntermediateSizeForRuntime(manifest, inf, arch, modelId) {
   if (inferred == null || inferred === fromArch) {
     return fromArch;
   }
-  log.warn(
-    'Config',
-    `Manifest "${modelId}" has intermediateSize=${fromArch}, inferred ${inferred} from FFN tensor shapes; using inferred value.`
+  throw new Error(
+    `Manifest "${modelId}" has intermediateSize=${fromArch}, but FFN tensors imply ${inferred}. ` +
+    'Re-convert the model so manifest architecture matches the weights.'
   );
-  return inferred;
 }
 
 // =============================================================================
@@ -130,7 +151,14 @@ export function hasManifestInference(manifest) {
 
 
 export function validateRequiredInferenceFields(inf, modelId) {
-  
+  inf = inf ?? {};
+  inf.attention = inf.attention ?? {};
+  inf.normalization = inf.normalization ?? {};
+  inf.ffn = inf.ffn ?? {};
+  inf.rope = inf.rope ?? {};
+  inf.output = inf.output ?? {};
+  inf.layerPattern = inf.layerPattern ?? {};
+  inf.chatTemplate = inf.chatTemplate ?? {};
   const errors = [];
 
   // Attention fields - non-nullable required
@@ -201,6 +229,20 @@ export function validateRequiredInferenceFields(inf, modelId) {
   if (inf.rope.ropeLocalTheta === undefined) {
     errors.push('rope.ropeLocalTheta must be explicitly set (null for no local theta, or number)');
   }
+  if (inf.rope.mropeInterleaved == null) {
+    errors.push('rope.mropeInterleaved is required');
+  }
+  if (inf.rope.mropeSection === undefined) {
+    errors.push('rope.mropeSection must be explicitly set (null when unused, or an array of positive integers)');
+  }
+  if (inf.rope.partialRotaryFactor === undefined) {
+    errors.push('rope.partialRotaryFactor must be explicitly set (null when unused, or a number in (0, 1])');
+  } else {
+    const factor = inf.rope.partialRotaryFactor;
+    if (factor !== null && (typeof factor !== 'number' || Number.isNaN(factor) || factor <= 0 || factor > 1)) {
+      errors.push('rope.partialRotaryFactor must be a number in (0, 1] or null');
+    }
+  }
 
   // Output fields - non-nullable required
   if (inf.output.tieWordEmbeddings == null) {
@@ -458,6 +500,26 @@ export function toParsedConfigFromMerged(merged, manifest) {
   const ropeScalingType = inf.rope.ropeScalingType;
   const ropeLocalScale = inf.rope.ropeLocalScalingFactor ?? ropeScale;
   const ropeLocalScalingType = inf.rope.ropeLocalScalingType ?? ropeScalingType;
+  const partialRotaryFactor = inf.rope.partialRotaryFactor;
+  const ropeInterleaved = inf.rope.mropeInterleaved === true;
+  const mropeSection = Array.isArray(inf.rope.mropeSection)
+    ? inf.rope.mropeSection.map((entry) => Math.trunc(Number(entry)))
+    : null;
+  const ropeRotaryDim = resolveRotaryDim(arch.headDim, partialRotaryFactor, merged.modelId);
+  if (mropeSection && mropeSection.some((entry) => !Number.isFinite(entry) || entry <= 0)) {
+    throw new Error(
+      `Manifest "${merged.modelId}" has invalid rope.mropeSection; expected positive integers.`
+    );
+  }
+  if (ropeInterleaved && mropeSection) {
+    const doubledMropeDim = mropeSection.reduce((sum, entry) => sum + entry, 0) * 2;
+    if (doubledMropeDim !== ropeRotaryDim) {
+      throw new Error(
+        `Manifest "${merged.modelId}" declares rope.mropeSection=${JSON.stringify(mropeSection)}, ` +
+        `which expands to rotary dim ${doubledMropeDim}, but the resolved rotary dim is ${ropeRotaryDim}.`
+      );
+    }
+  }
 
   // Build ropeScaling object from manifest values if scaling is enabled
   // Include YARN params when present
@@ -532,6 +594,10 @@ export function toParsedConfigFromMerged(merged, manifest) {
     slidingWindow: inf.attention.slidingWindow,
     ropeTheta: inf.rope.ropeTheta,
     ropeLocalTheta: inf.rope.ropeLocalTheta,
+    ropeRotaryDim,
+    ropeInterleaved,
+    mropeSection,
+    partialRotaryFactor,
     ropeScale,
     ropeLocalScale,
     ropeScalingType,

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

@@ -319,14 +319,8 @@ export async function embed(tokenIds, embedBuffer, config) {
     const firstTokenId = tokenIdArray[0];
     const bytesPerElement = useF16 ? 2 : 4;
     const sampleSize = Math.min(32 * bytesPerElement, hiddenSize * bytesPerElement);
-    const staging = device.createBuffer({ size: sampleSize, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
-    const enc = device.createCommandEncoder();
-    enc.copyBufferToBuffer(gatherOutput.buffer, 0, staging, 0, sampleSize);
-    device.queue.submit([enc.finish()]);
-    await staging.mapAsync(GPUMapMode.READ);
-    const data = decodeReadback(staging.getMappedRange().slice(0), gatherOptions.outputDtype);
-    staging.unmap();
-    staging.destroy();
+    const readback = await readBuffer(gatherOutput.buffer, sampleSize);
+    const data = decodeReadback(readback, gatherOptions.outputDtype);
 
     // Compute statistics
     let sum = 0, sumSq = 0;

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

@@ -1,4 +1,3 @@
-import { log } from '../../../debug/index.js';
 import { resolveKernelPath } from '../../../config/kernel-path-loader.js';
 import { selectRuleValue } from '../../../rules/rule-registry.js';
 import {
@@ -9,19 +8,36 @@ import {
 export const PRIMARY_EXECUTION_PLAN_ID = 'primary';
 export const FINITENESS_FALLBACK_EXECUTION_PLAN_ID = 'finiteness_fallback';
 
-function normalizePositiveInt(value, fallback, label) {
-  if (!Number.isFinite(value)) return fallback;
-  const normalized = Math.floor(value);
-  if (normalized >= 1) return normalized;
-  log.warn('Pipeline', `[ExecutionPlan] ${label}=${value} is invalid; using ${fallback}.`);
-  return fallback;
+function assertOptionalBoolean(value, label) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== 'boolean') {
+    throw new Error(`[ExecutionPlan] ${label} must be boolean when provided; got ${JSON.stringify(value)}.`);
+  }
+  return value;
+}
+
+function assertOptionalPositiveInt(value, label) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`[ExecutionPlan] ${label} must be a positive integer when provided; got ${JSON.stringify(value)}.`);
+  }
+  return value;
 }
 
-function normalizeStopCheckMode(value, fallback) {
-  if (value === 'batch' || value === 'per-token') {
-    return value;
+function assertOptionalStopCheckMode(value) {
+  if (value === undefined) {
+    return undefined;
   }
-  return fallback;
+  if (value !== 'batch' && value !== 'per-token') {
+    throw new Error(
+      `[ExecutionPlan] stopCheckMode must be "batch" or "per-token" when provided; got ${JSON.stringify(value)}.`
+    );
+  }
+  return value;
 }
 
 function resolveFallbackActivationDtype(primaryActivationDtype) {
@@ -42,56 +58,48 @@ function resolveFallbackActivationDtype(primaryActivationDtype) {
 function resolveFallbackKernelPath(primaryKernelPath) {
   const primaryKernelPathId = primaryKernelPath?.id ?? null;
   if (!primaryKernelPathId) {
-    return {
-      kernelPath: null,
-      kernelPathId: null,
-      kernelPathSource: 'none',
-    };
+    throw new Error(
+      '[ExecutionPlan] F16 finiteness fallback requires a primary kernel path with a stable id. ' +
+      'Add a registered kernelPath id and a finiteness fallback rule.'
+    );
   }
 
-  const primaryKernelPathIsObject = typeof primaryKernelPath === 'object' && primaryKernelPath !== null;
+  const explicitFallbackKernelPathId = typeof primaryKernelPath?.finitenessFallbackKernelPathId === 'string'
+    && primaryKernelPath.finitenessFallbackKernelPathId.length > 0
+    ? primaryKernelPath.finitenessFallbackKernelPathId
+    : null;
 
-  const fallbackKernelPathId = selectRuleValue(
+  const fallbackKernelPathId = explicitFallbackKernelPathId ?? selectRuleValue(
     'inference',
     'kernelPath',
     'finitenessFallback',
     { kernelPathId: primaryKernelPathId }
   );
 
-  const resolvedKernelPathId = typeof fallbackKernelPathId === 'string' && fallbackKernelPathId.length > 0
-    ? fallbackKernelPathId
-    : primaryKernelPathId;
-  const kernelPathSource = resolvedKernelPathId === primaryKernelPathId ? 'self' : 'rule';
+  if (typeof fallbackKernelPathId !== 'string' || fallbackKernelPathId.length === 0) {
+    throw new Error(
+      `[ExecutionPlan] Missing finiteness fallback kernel path mapping for "${primaryKernelPathId}". ` +
+      'Add an explicit rule in src/rules/inference/kernel-path.rules.json.'
+    );
+  }
 
-  if (kernelPathSource === 'self') {
-    log.warn(
-      'Pipeline',
-      `[ExecutionPlan] No finiteness fallback kernel path mapping for "${primaryKernelPathId}"; using primary kernel path.`
+  if (fallbackKernelPathId === primaryKernelPathId) {
+    throw new Error(
+      `[ExecutionPlan] Invalid finiteness fallback mapping for "${primaryKernelPathId}": ` +
+      `fallback kernel path resolves to itself. Add an explicit widening path.`
     );
   }
 
   try {
-    const kernelPath = resolveKernelPath(resolvedKernelPathId);
+    const kernelPath = resolveKernelPath(fallbackKernelPathId);
     return {
       kernelPath,
-      kernelPathId: resolvedKernelPathId,
-      kernelPathSource,
+      kernelPathId: fallbackKernelPathId,
+      kernelPathSource: 'rule',
     };
   } catch (error) {
-    if (primaryKernelPathIsObject) {
-      log.warn(
-        'Pipeline',
-        `[ExecutionPlan] Failed to resolve finiteness fallback kernel path "${resolvedKernelPathId}" ` +
-        `for "${primaryKernelPathId}", using inline kernel path as fallback. ${error?.message || error}`
-      );
-      return {
-        kernelPath: primaryKernelPath,
-        kernelPathId: primaryKernelPathId,
-        kernelPathSource,
-      };
-    }
     throw new Error(
-      `[ExecutionPlan] Failed to resolve finiteness fallback kernel path "${resolvedKernelPathId}" ` +
+      `[ExecutionPlan] Failed to resolve finiteness fallback kernel path "${fallbackKernelPathId}" ` +
       `(from "${primaryKernelPathId}"): ${error?.message || error}`
     );
   }
@@ -252,11 +260,17 @@ export function activateFallbackExecutionPlan(container) {
 
 function resolveExecutionOverrides(options = {}) {
   return {
-    disableCommandBatching: options.disableCommandBatching,
-    disableMultiTokenDecode: options.disableMultiTokenDecode,
-    batchSize: options.batchSize,
-    stopCheckMode: options.stopCheckMode,
-    maxTokens: options.maxTokens,
+    disableCommandBatching: assertOptionalBoolean(
+      options.disableCommandBatching,
+      'disableCommandBatching'
+    ),
+    disableMultiTokenDecode: assertOptionalBoolean(
+      options.disableMultiTokenDecode,
+      'disableMultiTokenDecode'
+    ),
+    batchSize: assertOptionalPositiveInt(options.batchSize, 'batchSize'),
+    stopCheckMode: assertOptionalStopCheckMode(options.stopCheckMode),
+    maxTokens: assertOptionalPositiveInt(options.maxTokens, 'maxTokens'),
   };
 }
 
@@ -276,9 +290,9 @@ export function resolveExecutionSessionPlan(container, options = {}) {
     deferredRoundingWindowTokens: activePlan.deferredRoundingWindowTokens,
     disableCommandBatching: overrides.disableCommandBatching ?? activePlan.defaultDisableCommandBatching,
     disableMultiTokenDecode: overrides.disableMultiTokenDecode ?? activePlan.defaultDisableMultiTokenDecode,
-    batchSize: normalizePositiveInt(overrides.batchSize, activePlan.defaultBatchSize, 'batchSize'),
-    stopCheckMode: normalizeStopCheckMode(overrides.stopCheckMode, activePlan.defaultStopCheckMode),
-    maxTokens: normalizePositiveInt(overrides.maxTokens, activePlan.defaultMaxTokens, 'maxTokens'),
+    batchSize: overrides.batchSize ?? activePlan.defaultBatchSize,
+    stopCheckMode: overrides.stopCheckMode ?? activePlan.defaultStopCheckMode,
+    maxTokens: overrides.maxTokens ?? activePlan.defaultMaxTokens,
     readbackInterval: activePlan.readbackInterval,
     ringTokens: activePlan.ringTokens,
     ringStop: activePlan.ringStop,

package/src/inference/pipelines/text/execution-v0-contract-helpers.d.ts

@@ -0,0 +1,59 @@
+export declare function cloneJson<T>(value: T): T;
+export declare function validateManifestSessionDefaultsContract(manifestInference: Record<string, unknown> | null): void;
+export declare function isPhaseMatch(phase: string, targetPhase: string): boolean;
+export declare function stepHasLayer(step: Record<string, unknown>, layerIdx: number): boolean;
+export declare function normalizePhase(value: unknown, label: string): string;
+export declare function normalizeSection(value: unknown, label: string): string;
+export declare function normalizeSlot(value: unknown, label: string): string;
+export declare function createSourceTrace(): { session: Record<string, unknown>; steps: Record<string, unknown> };
+export declare function setSourceTrace(trace: Record<string, unknown>, path: string, source: string): void;
+export declare function collectLeafPaths(value: unknown, prefix?: string[], out?: string[][]): string[][];
+export declare function hasDefinedPath(root: unknown, pathSegments: string[]): boolean;
+export declare function validateStepShape(step: Record<string, unknown>, index: number): void;
+export declare function assertExecutionRuntimeOverlay(runtimeInference: Record<string, unknown> | null | undefined): void;
+export declare function validateUniqueStepIds(steps: Array<Record<string, unknown>>): void;
+export declare function hasExecutionV0(manifestInference: Record<string, unknown> | null | undefined): boolean;
+export declare function assertExecutionV0Schema(manifestInference: Record<string, unknown> | null | undefined): void;
+export declare function applyExecutionPatchAtomic(
+  baseSteps: Array<Record<string, unknown>>,
+  patch: Record<string, unknown> | null | undefined
+): Array<Record<string, unknown>>;
+export declare function indexRuntimePatchMeta(
+  patch: Record<string, unknown> | null | undefined
+): {
+  addedSteps: Set<string>;
+  precisionFieldsByStep: Map<string, Set<string>>;
+  kvIOFieldsByStep: Set<string>;
+};
+export declare function requireSessionActivationDtype(
+  sessionDefaults: Record<string, unknown> | null | undefined,
+  label?: string
+): string;
+export declare function createInitialSlotDtypes(sessionDefaults: Record<string, unknown>): Map<string, string>;
+export declare function resolvePhaseSteps(
+  phase: string,
+  steps: Array<Record<string, unknown>>,
+  sessionDefaults: Record<string, unknown>,
+  profileIndex: Map<string, unknown>,
+  policies: Record<string, unknown>,
+  options?: Record<string, unknown>
+): {
+  steps: Array<Record<string, unknown>>;
+  finalSlotDtypes: Map<string, string>;
+};
+export declare function normalizeRuntimeSessionForExecutionV0(
+  runtimeSession: Record<string, unknown> | null | undefined,
+  manifestInference: Record<string, unknown> | null | undefined,
+  defaultComputeDefaults: Record<string, unknown>
+): Record<string, unknown> | null | undefined;
+export declare function validatePhaseBoundaryCompatibility(options: Record<string, unknown>): void;
+export declare function assertKVLayoutExecutionCompatibility(
+  steps: Array<Record<string, unknown>>,
+  sessionDefaults: Record<string, unknown>
+): void;
+export declare const buildKernelProfileKey: (
+  kernelRef: Record<string, unknown> | null | undefined,
+  step?: Record<string, unknown> | null | undefined
+) => string;
+export declare const indexKernelProfiles: (sessionDefaults: Record<string, unknown>) => Map<string, unknown>;
+export declare const normalizeDtype: (value: unknown, label: string) => string;