@simulatte/doppler 0.1.4 → 0.1.5

package/src/config/merge-contract-check.js

@@ -0,0 +1,321 @@
+import { resolveConfig, resolvePreset } from './loader.js';
+import {
+  chooseNullish,
+  chooseDefinedWithSource,
+  mergeExecutionPatchLists,
+  mergeKernelPathPolicy,
+  mergeLayeredShallowObjects,
+  mergeShallowObject,
+  replaceSubtree,
+} from './merge-helpers.js';
+import { mergeConfig } from './merge.js';
+import { createDopplerConfig } from './schema/index.js';
+
+function buildWitnessManifestForArchitecture() {
+  return {
+    modelId: 'merge-semantics-witness',
+    modelType: 'transformer',
+    architecture: {
+      numLayers: 2,
+      hiddenSize: 256,
+      intermediateSize: 512,
+      numAttentionHeads: 4,
+      numKeyValueHeads: 4,
+      headDim: 64,
+      vocabSize: 1024,
+      maxSeqLen: 2048,
+      ropeTheta: null,
+      rmsNormEps: 1e-6,
+    },
+    config: {},
+  };
+}
+
+function buildWitnessMergeManifest() {
+  return {
+    modelId: 'merge-overlay-witness',
+    inference: {
+      attention: {
+        queryPreAttnScalar: 1,
+        attentionBias: false,
+        attnLogitSoftcapping: null,
+        slidingWindow: 4096,
+        queryKeyNorm: false,
+        attentionOutputGate: false,
+        causal: true,
+      },
+      normalization: {
+        rmsNormEps: 1e-6,
+        rmsNormWeightOffset: 0,
+        postAttentionNorm: true,
+        preFeedforwardNorm: true,
+        postFeedforwardNorm: false,
+      },
+      ffn: {
+        activation: 'gelu',
+        gatedActivation: false,
+        swigluLimit: null,
+      },
+      rope: {
+        ropeTheta: 1000000,
+        ropeLocalTheta: null,
+        ropeScalingType: null,
+        ropeScalingFactor: null,
+        ropeLocalScalingType: null,
+        ropeLocalScalingFactor: null,
+        yarnBetaFast: null,
+        yarnBetaSlow: null,
+        yarnOriginalMaxPos: null,
+        ropeLocalYarnBetaFast: null,
+        ropeLocalYarnBetaSlow: null,
+        ropeLocalYarnOriginalMaxPos: null,
+      },
+      output: {
+        finalLogitSoftcapping: 30,
+        tieWordEmbeddings: true,
+        scaleEmbeddings: false,
+        embeddingTranspose: false,
+        embeddingVocabSize: 1024,
+      },
+      layerPattern: null,
+      chatTemplate: {
+        type: 'gemma',
+        enabled: true,
+      },
+      defaultKernelPath: 'gemma3-f16-fused-f16a-online',
+    },
+    architecture: {
+      headDim: 64,
+      maxSeqLen: 2048,
+    },
+  };
+}
+
+function recordCheck(results, id, ok, detail, mode = 'actual') {
+  results.push({ id, ok, detail, mode });
+}
+
+export function buildMergeContractArtifact() {
+  const checks = [];
+  const preset = resolvePreset('gemma3');
+  const resolved = resolveConfig(buildWitnessManifestForArchitecture(), 'gemma3');
+  recordCheck(
+    checks,
+    'loader.architecture.nullish_null_falls_through',
+    resolved.architecture.ropeTheta === preset.architecture.ropeTheta,
+    `resolved ropeTheta=${resolved.architecture.ropeTheta}, preset ropeTheta=${preset.architecture.ropeTheta}`
+  );
+
+  const mergedUndefined = mergeConfig(buildWitnessMergeManifest(), {});
+  recordCheck(
+    checks,
+    'runtime.mergeConfig.defined_overlay_missing_falls_through',
+    mergedUndefined.inference.defaultKernelPath === 'gemma3-f16-fused-f16a-online'
+      && mergedUndefined._sources.get('inference.defaultKernelPath') === 'manifest',
+    `value=${mergedUndefined.inference.defaultKernelPath}, source=${mergedUndefined._sources.get('inference.defaultKernelPath')}`
+  );
+
+  const mergedNull = mergeConfig(buildWitnessMergeManifest(), {
+    defaultKernelPath: null,
+    chatTemplate: {
+      enabled: null,
+    },
+  });
+  recordCheck(
+    checks,
+    'runtime.mergeConfig.defined_overlay_preserves_null',
+    mergedNull.inference.defaultKernelPath === null
+      && mergedNull._sources.get('inference.defaultKernelPath') === 'runtime',
+    `value=${mergedNull.inference.defaultKernelPath}, source=${mergedNull._sources.get('inference.defaultKernelPath')}`
+  );
+  recordCheck(
+    checks,
+    'runtime.inference.chatTemplate.spread_preserves_null',
+    mergedNull.inference.chatTemplate.enabled === null
+      && mergedNull._sources.get('inference.chatTemplate.enabled') === 'runtime',
+    `value=${String(mergedNull.inference.chatTemplate.enabled)}`
+  );
+
+  const runtimeConfig = createDopplerConfig({
+    runtime: {
+      inference: {
+        chatTemplate: {
+          enabled: null,
+        },
+      },
+    },
+  });
+  recordCheck(
+    checks,
+    'runtime.schema.chatTemplate.spread_preserves_null',
+    runtimeConfig.runtime.inference.chatTemplate.enabled === null,
+    `value=${String(runtimeConfig.runtime.inference.chatTemplate.enabled)}`
+  );
+
+  const overlaySources = new Map();
+  const chosenRuntimeValue = chooseDefinedWithSource(
+    'inference.defaultKernelPath',
+    null,
+    'manifest-path',
+    overlaySources
+  );
+  recordCheck(
+    checks,
+    'runtime.mergeHelpers.chooseDefinedWithSource.runtime_marks_source',
+    chosenRuntimeValue === null && overlaySources.get('inference.defaultKernelPath') === 'runtime',
+    `value=${String(chosenRuntimeValue)}, source=${overlaySources.get('inference.defaultKernelPath')}`,
+    'actual'
+  );
+
+  const manifestSources = new Map();
+  const chosenManifestValue = chooseDefinedWithSource(
+    'inference.defaultKernelPath',
+    undefined,
+    'manifest-path',
+    manifestSources
+  );
+  recordCheck(
+    checks,
+    'runtime.mergeHelpers.chooseDefinedWithSource.manifest_marks_source',
+    chosenManifestValue === 'manifest-path' && manifestSources.get('inference.defaultKernelPath') === 'manifest',
+    `value=${String(chosenManifestValue)}, source=${manifestSources.get('inference.defaultKernelPath')}`,
+    'actual'
+  );
+
+  const executionPatchBase = {
+    set: [{ op: 'seed' }],
+    remove: ['old_step'],
+    add: [{ id: 'new_step' }],
+  };
+  const executionPatchOverride = {
+    set: null,
+    remove: [],
+    add: undefined,
+  };
+  const mergedExecutionPatch = {
+    ...mergeExecutionPatchLists(executionPatchBase, executionPatchOverride),
+  };
+  recordCheck(
+    checks,
+    'runtime.inference.executionPatch.nullish_null_falls_through',
+    mergedExecutionPatch.set === executionPatchBase.set
+      && mergedExecutionPatch.add === executionPatchBase.add
+      && Array.isArray(mergedExecutionPatch.remove)
+      && mergedExecutionPatch.remove.length === 0,
+    `setLength=${mergedExecutionPatch.set.length}, removeLength=${mergedExecutionPatch.remove.length}, addLength=${mergedExecutionPatch.add.length}`,
+    'actual'
+  );
+
+  const sessionBase = {
+    kvcache: {
+      layout: 'paged',
+      maxSeqLen: 8192,
+      kvDtype: 'f16',
+    },
+    decodeLoop: {
+      batchSize: 16,
+      disableCommandBatching: false,
+    },
+  };
+  const sessionOverride = {
+    kvcache: {
+      layout: 'tiered',
+    },
+    decodeLoop: {
+      batchSize: 1,
+    },
+  };
+  const mergedSession = {
+    kvcache: replaceSubtree(sessionOverride.kvcache, sessionBase.kvcache),
+    decodeLoop: replaceSubtree(sessionOverride.decodeLoop, sessionBase.decodeLoop),
+  };
+  recordCheck(
+    checks,
+    'runtime.inference.session.subtree_override_replaces_base',
+    mergedSession.kvcache.layout === 'tiered'
+      && mergedSession.kvcache.maxSeqLen === undefined
+      && mergedSession.decodeLoop.batchSize === 1
+      && mergedSession.decodeLoop.disableCommandBatching === undefined,
+    `kvcacheKeys=${Object.keys(mergedSession.kvcache).join(',')}; decodeLoopKeys=${Object.keys(mergedSession.decodeLoop).join(',')}`,
+    'actual'
+  );
+
+  const mergedChatTemplate = mergeShallowObject(
+    { type: 'base', enabled: true },
+    { enabled: null }
+  );
+  recordCheck(
+    checks,
+    'runtime.mergeShallowObject.spread_preserves_null',
+    mergedChatTemplate.enabled === null && mergedChatTemplate.type === 'base',
+    `type=${mergedChatTemplate.type}, enabled=${String(mergedChatTemplate.enabled)}`,
+    'actual'
+  );
+
+  const layeredAttention = mergeLayeredShallowObjects(
+    { slidingWindow: 4096, attentionBias: false },
+    { slidingWindow: 2048 },
+    { slidingWindow: null }
+  );
+  recordCheck(
+    checks,
+    'loader.mergeLayeredShallowObjects.spread_preserves_null',
+    layeredAttention.slidingWindow === null && layeredAttention.attentionBias === false,
+    `slidingWindow=${String(layeredAttention.slidingWindow)}, attentionBias=${String(layeredAttention.attentionBias)}`,
+    'actual'
+  );
+
+  const mergedKernelPathPolicy = mergeKernelPathPolicy(
+    {
+      mode: 'locked',
+      sourceScope: ['model', 'manifest'],
+      allowSources: ['model', 'manifest'],
+      onIncompatible: 'error',
+    },
+    {
+      allowSources: ['runtime', 'execution-v0'],
+      onIncompatible: 'remap',
+    }
+  );
+  recordCheck(
+    checks,
+    'runtime.kernelPathPolicy.source_scope_mirrors_allow_sources',
+    Array.isArray(mergedKernelPathPolicy.sourceScope)
+      && Array.isArray(mergedKernelPathPolicy.allowSources)
+      && mergedKernelPathPolicy.sourceScope.length === 2
+      && mergedKernelPathPolicy.sourceScope[0] === 'runtime'
+      && mergedKernelPathPolicy.allowSources[1] === 'execution-v0'
+      && mergedKernelPathPolicy.onIncompatible === 'remap',
+    `sourceScope=${JSON.stringify(mergedKernelPathPolicy.sourceScope)}, allowSources=${JSON.stringify(mergedKernelPathPolicy.allowSources)}`,
+    'actual'
+  );
+
+  const runtimeConfigWithKernelPathPolicy = createDopplerConfig({
+    runtime: {
+      inference: {
+        kernelPathPolicy: {
+          allowSources: ['runtime', 'execution-v0'],
+        },
+      },
+    },
+  });
+  recordCheck(
+    checks,
+    'runtime.schema.kernelPathPolicy.helper_is_used',
+    Array.isArray(runtimeConfigWithKernelPathPolicy.runtime.inference.kernelPathPolicy.sourceScope)
+      && runtimeConfigWithKernelPathPolicy.runtime.inference.kernelPathPolicy.sourceScope[0] === 'runtime'
+      && runtimeConfigWithKernelPathPolicy.runtime.inference.kernelPathPolicy.allowSources[1] === 'execution-v0',
+    `policy=${JSON.stringify(runtimeConfigWithKernelPathPolicy.runtime.inference.kernelPathPolicy)}`,
+    'actual'
+  );
+
+  const errors = checks.filter((entry) => !entry.ok).map((entry) => `[MergeContract] ${entry.id}: ${entry.detail}`);
+
+  return {
+    schemaVersion: 1,
+    source: 'doppler',
+    ok: errors.length === 0,
+    checks,
+    errors,
+  };
+}

package/src/config/merge-helpers.d.ts

@@ -0,0 +1,58 @@
+export declare function chooseNullish<T>(
+  overrideValue: T | null | undefined,
+  fallbackValue: T
+): T;
+
+export declare function chooseDefined<T>(
+  overrideValue: T | undefined,
+  fallbackValue: T
+): T;
+
+export declare function chooseDefinedWithSource<T>(
+  path: string,
+  overrideValue: T | undefined,
+  fallbackValue: T,
+  sources: Map<string, string> | null | undefined
+): T;
+
+export declare function mergeShallowObject<T extends object>(
+  base: T,
+  override: Partial<T> | null | undefined
+): T;
+
+export declare function mergeLayeredShallowObjects<T extends object>(
+  ...layers: Array<Partial<T> | null | undefined>
+): T;
+
+export declare function replaceSubtree<T>(
+  overrideValue: T | null | undefined,
+  fallbackValue: T
+): T;
+
+export declare function mergeKernelPathPolicy<T extends {
+  mode?: unknown;
+  sourceScope?: unknown;
+  allowSources?: unknown;
+  onIncompatible?: unknown;
+}>(
+  basePolicy: T | null | undefined,
+  overridePolicy: T | null | undefined
+): {
+  mode: unknown;
+  sourceScope: unknown;
+  allowSources: unknown;
+  onIncompatible: unknown;
+};
+
+export declare function mergeExecutionPatchLists<T extends {
+  set?: unknown;
+  remove?: unknown;
+  add?: unknown;
+}>(
+  basePatch: T | null | undefined,
+  overridePatch: T | null | undefined
+): {
+  set: unknown;
+  remove: unknown;
+  add: unknown;
+};

package/src/config/merge-helpers.js

@@ -0,0 +1,54 @@
+export function chooseNullish(overrideValue, fallbackValue) {
+  return overrideValue ?? fallbackValue;
+}
+
+export function chooseDefined(overrideValue, fallbackValue) {
+  return overrideValue !== undefined ? overrideValue : fallbackValue;
+}
+
+export function chooseDefinedWithSource(path, overrideValue, fallbackValue, sources) {
+  const value = chooseDefined(overrideValue, fallbackValue);
+  if (sources && typeof sources.set === 'function') {
+    sources.set(path, overrideValue !== undefined ? 'runtime' : 'manifest');
+  }
+  return value;
+}
+
+export function mergeShallowObject(base, override) {
+  if (!override || typeof override !== 'object' || Array.isArray(override)) {
+    return base;
+  }
+  return { ...base, ...override };
+}
+
+export function mergeLayeredShallowObjects(...layers) {
+  return layers.reduce((merged, layer) => mergeShallowObject(merged, layer), {});
+}
+
+export function replaceSubtree(overrideValue, fallbackValue) {
+  return chooseNullish(overrideValue, fallbackValue);
+}
+
+export function mergeKernelPathPolicy(basePolicy, overridePolicy) {
+  const base = basePolicy ?? {};
+  const override = overridePolicy ?? {};
+  const baseSourceScope = base.sourceScope ?? base.allowSources;
+  const overrideSourceScope = override.sourceScope ?? override.allowSources;
+  const sourceScope = overrideSourceScope ?? baseSourceScope;
+  return {
+    mode: override.mode ?? base.mode,
+    sourceScope,
+    allowSources: sourceScope,
+    onIncompatible: override.onIncompatible ?? base.onIncompatible,
+  };
+}
+
+export function mergeExecutionPatchLists(basePatch, overridePatch) {
+  const base = basePatch ?? {};
+  const override = overridePatch ?? {};
+  return {
+    set: chooseNullish(override.set, chooseNullish(base.set, [])),
+    remove: chooseNullish(override.remove, chooseNullish(base.remove, [])),
+    add: chooseNullish(override.add, chooseNullish(base.add, [])),
+  };
+}

package/src/config/merge.js

@@ -1,3 +1,5 @@
+import { chooseDefined, chooseDefinedWithSource } from './merge-helpers.js';
+
 // =============================================================================
 // Merge Implementation
 // =============================================================================
@@ -8,12 +10,7 @@ function overlay(
   runtimeValue,
   sources
 ) {
-  if (runtimeValue !== undefined) {
-    sources.set(path, 'runtime');
-    return runtimeValue;
-  }
-  sources.set(path, 'manifest');
-  return manifestValue;
+  return chooseDefinedWithSource(path, runtimeValue, manifestValue, sources);
 }
 
 function mergeAttention(

package/src/config/presets/models/janus-text.json

@@ -14,6 +14,8 @@
   },
 
   "tokenizer": {
+    "bosToken": "<｜begin▁of▁sentence｜>",
+    "eosTokens": ["<｜end▁of▁sentence｜>"],
     "addBosToken": true,
     "addEosToken": false
   },

package/src/config/quantization-contract-check.d.ts

@@ -0,0 +1,12 @@
+export interface QuantizationContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: Array<{ id: string; ok: boolean }>;
+  errors: string[];
+  stats: {
+    sampledSizes: number;
+  };
+}
+
+export declare function buildQuantizationContractArtifact(): QuantizationContractArtifact;

package/src/config/quantization-contract-check.js

@@ -0,0 +1,91 @@
+import {
+  K_SCALE_SIZE,
+  Q4K_BLOCK_BYTES,
+  Q6K_BLOCK_BYTES,
+  Q8_0_BLOCK_BYTES,
+  Q8_0_BLOCK_SIZE,
+  QK4_K_BLOCK_SIZE,
+  QK_K,
+  padToQ4KBlock,
+  q4kBlockCount,
+} from './schema/quantization.schema.js';
+import {
+  TILE_SIZES,
+  QUANTIZATION,
+} from '../gpu/kernels/constants.js';
+import * as loaderQuantization from '../loader/quantization-constants.js';
+
+const EXPECTED_CONSTANTS = Object.freeze({
+  QK_K: 256,
+  Q4K_BLOCK_BYTES: 144,
+  Q6K_BLOCK_BYTES: 210,
+  Q8_0_BLOCK_BYTES: 34,
+  Q8_0_BLOCK_SIZE: 32,
+  K_SCALE_SIZE: 12,
+});
+
+export function buildQuantizationContractArtifact() {
+  const errors = [];
+  const checks = [];
+
+  const literalConstantsOk =
+    QK_K === EXPECTED_CONSTANTS.QK_K
+    && Q4K_BLOCK_BYTES === EXPECTED_CONSTANTS.Q4K_BLOCK_BYTES
+    && Q6K_BLOCK_BYTES === EXPECTED_CONSTANTS.Q6K_BLOCK_BYTES
+    && Q8_0_BLOCK_BYTES === EXPECTED_CONSTANTS.Q8_0_BLOCK_BYTES
+    && Q8_0_BLOCK_SIZE === EXPECTED_CONSTANTS.Q8_0_BLOCK_SIZE
+    && K_SCALE_SIZE === EXPECTED_CONSTANTS.K_SCALE_SIZE
+    && QK4_K_BLOCK_SIZE === Q4K_BLOCK_BYTES;
+  if (!literalConstantsOk) {
+    errors.push('[QuantizationContract] schema constants drifted from the expected Q4K/Q6K/Q8 values.');
+  }
+  checks.push({ id: 'quantization.constants.schema', ok: literalConstantsOk });
+
+  const crossModuleOk =
+    loaderQuantization.QK_K === QK_K
+    && loaderQuantization.Q4K_BLOCK_BYTES === Q4K_BLOCK_BYTES
+    && loaderQuantization.Q6K_BLOCK_BYTES === Q6K_BLOCK_BYTES
+    && loaderQuantization.Q8_0_BLOCK_BYTES === Q8_0_BLOCK_BYTES
+    && loaderQuantization.Q8_0_BLOCK_SIZE === Q8_0_BLOCK_SIZE
+    && TILE_SIZES.Q4K_SUPER_BLOCK_SIZE === QK_K
+    && QUANTIZATION.Q4K_BLOCK_BYTES === Q4K_BLOCK_BYTES;
+  if (!crossModuleOk) {
+    errors.push('[QuantizationContract] loader/GPU quantization constants drifted from schema constants.');
+  }
+  checks.push({ id: 'quantization.constants.crossModule', ok: crossModuleOk });
+
+  let padPropertiesOk = true;
+  let q4kCoverageOk = true;
+  let previous = -1;
+  for (let size = 0; size <= QK_K * 2 + 7; size += 1) {
+    const padded = padToQ4KBlock(size);
+    if (padded < size || padded % QK_K !== 0 || padToQ4KBlock(padded) !== padded || padded < previous) {
+      padPropertiesOk = false;
+      break;
+    }
+    previous = padded;
+    if (q4kBlockCount(size) * QK_K < size) {
+      q4kCoverageOk = false;
+      break;
+    }
+  }
+  if (!padPropertiesOk) {
+    errors.push('[QuantizationContract] padToQ4KBlock must be monotone, aligned, and idempotent.');
+  }
+  checks.push({ id: 'quantization.padToQ4KBlock.properties', ok: padPropertiesOk });
+  if (!q4kCoverageOk) {
+    errors.push('[QuantizationContract] q4kBlockCount must cover the requested element count.');
+  }
+  checks.push({ id: 'quantization.q4kBlockCount.coverage', ok: q4kCoverageOk });
+
+  return {
+    schemaVersion: 1,
+    source: 'doppler',
+    ok: errors.length === 0,
+    checks,
+    errors,
+    stats: {
+      sampledSizes: QK_K * 2 + 8,
+    },
+  };
+}

package/src/config/required-inference-fields-contract-check.d.ts

@@ -0,0 +1,24 @@
+export interface RequiredInferenceFieldsContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: Array<{ id: string; ok: boolean }>;
+  errors: string[];
+  stats: {
+    fieldCases: number;
+    nullableCases: number;
+    nonNullableCases: number;
+  };
+}
+
+export declare function buildRequiredInferenceFieldsContractArtifact(): RequiredInferenceFieldsContractArtifact;
+
+export interface ManifestRequiredInferenceFieldsArtifact extends RequiredInferenceFieldsContractArtifact {
+  scope: 'manifest';
+  label: string;
+}
+
+export declare function buildManifestRequiredInferenceFieldsArtifact(
+  inference: Record<string, unknown> | null | undefined,
+  label?: string
+): ManifestRequiredInferenceFieldsArtifact;