@simulatte/doppler 0.1.3 → 0.1.5

package/src/config/loader.js

@@ -5,6 +5,7 @@ import {
 } from './schema/index.js';
 import { createDopplerError, ERROR_CODES } from '../errors/index.js';
 import { loadJson } from '../utils/load-json.js';
+import { chooseNullish, mergeLayeredShallowObjects } from './merge-helpers.js';
 
 // Static imports keep presets bundled for browser use.
 const transformerPreset = await loadJson('./presets/models/transformer.json', import.meta.url, 'Failed to load preset');
@@ -14,6 +15,7 @@ const gemma3Preset = await loadJson('./presets/models/gemma3.json', import.meta.
 const translateGemmaPreset = await loadJson('./presets/models/translategemma.json', import.meta.url, 'Failed to load preset');
 const embeddingGemmaPreset = await loadJson('./presets/models/embeddinggemma.json', import.meta.url, 'Failed to load preset');
 const functiongemmaPreset = await loadJson('./presets/models/functiongemma.json', import.meta.url, 'Failed to load preset');
+const janusTextPreset = await loadJson('./presets/models/janus-text.json', import.meta.url, 'Failed to load preset');
 const llama3Preset = await loadJson('./presets/models/llama3.json', import.meta.url, 'Failed to load preset');
 const mixtralPreset = await loadJson('./presets/models/mixtral.json', import.meta.url, 'Failed to load preset');
 const deepseekPreset = await loadJson('./presets/models/deepseek.json', import.meta.url, 'Failed to load preset');
@@ -36,6 +38,7 @@ export const PRESET_REGISTRY = {
   translategemma: translateGemmaPreset,
   embeddinggemma: embeddingGemmaPreset,
   functiongemma: functiongemmaPreset,
+  janus_text: janusTextPreset,
   llama3: llama3Preset,
   mixtral: mixtralPreset,
   deepseek: deepseekPreset,
@@ -85,6 +88,7 @@ export const PRESET_DETECTION_ORDER = [
   // Most specific first (model variants)
   'functiongemma',
   'embeddinggemma',
+  'janus_text',
   'modernbert',
   'diffusion',
   // Model families (check more specific patterns first)
@@ -107,8 +111,9 @@ export function detectPreset(
   config,
   architecture
 ) {
+  const nestedTextConfig = getNestedTextConfig(config);
   const archLower = (architecture || '').toLowerCase();
-  const modelType = (config.model_type || '').toLowerCase();
+  const modelType = String(nestedTextConfig?.model_type ?? config.model_type ?? '').toLowerCase();
   // Weak hint case: architecture fallback is often model_type copy (e.g. qwen2).
   const hintsAreWeak = !archLower || !modelType || archLower === modelType;
 
@@ -186,18 +191,21 @@ export function resolveConfig(
   // Note: Uses nullish coalesce (??) so null values fall through to next level.
   // This means explicit null in manifest = "use preset/default".
   const presetArch = preset.architecture || {};
-  const numLayers = manifestArch.numLayers ?? presetArch.numLayers;
-  const hiddenSize = manifestArch.hiddenSize ?? presetArch.hiddenSize;
-  const intermediateSize = manifestArch.intermediateSize ?? presetArch.intermediateSize;
-  const numAttentionHeads = manifestArch.numAttentionHeads ?? presetArch.numAttentionHeads;
-  const numKeyValueHeads = manifestArch.numKeyValueHeads ?? presetArch.numKeyValueHeads ?? numAttentionHeads;
-  const headDim = manifestArch.headDim ?? presetArch.headDim ?? (
-    hiddenSize && numAttentionHeads ? hiddenSize / numAttentionHeads : undefined
+  const numLayers = chooseNullish(manifestArch.numLayers, presetArch.numLayers);
+  const hiddenSize = chooseNullish(manifestArch.hiddenSize, presetArch.hiddenSize);
+  const intermediateSize = chooseNullish(manifestArch.intermediateSize, presetArch.intermediateSize);
+  const numAttentionHeads = chooseNullish(manifestArch.numAttentionHeads, presetArch.numAttentionHeads);
+  const numKeyValueHeads = chooseNullish(
+    manifestArch.numKeyValueHeads,
+    chooseNullish(presetArch.numKeyValueHeads, numAttentionHeads)
   );
-  const vocabSize = manifestArch.vocabSize ?? presetArch.vocabSize;
-  const maxSeqLen = manifestArch.maxSeqLen ?? presetArch.maxSeqLen;
-  const ropeTheta = manifestArch.ropeTheta ?? presetArch.ropeTheta;
-  const rmsNormEps = manifestArch.rmsNormEps ?? presetArch.rmsNormEps;
+  const headDim = chooseNullish(manifestArch.headDim, chooseNullish(presetArch.headDim, (
+    hiddenSize && numAttentionHeads ? hiddenSize / numAttentionHeads : undefined
+  )));
+  const vocabSize = chooseNullish(manifestArch.vocabSize, presetArch.vocabSize);
+  const maxSeqLen = chooseNullish(manifestArch.maxSeqLen, presetArch.maxSeqLen);
+  const ropeTheta = chooseNullish(manifestArch.ropeTheta, presetArch.ropeTheta);
+  const rmsNormEps = chooseNullish(manifestArch.rmsNormEps, presetArch.rmsNormEps);
 
   const architecture = {
     numLayers,
@@ -222,44 +230,44 @@ export function resolveConfig(
   const manifestInference = extractInferenceFromConfig(manifest.config || {});
 
   const inference = {
-    attention: {
-      ...baseInference.attention,
-      ...presetInference.attention,
-      ...manifestInference.attention,
-    },
-    normalization: {
-      ...baseInference.normalization,
-      ...presetInference.normalization,
-    },
-    ffn: {
-      ...baseInference.ffn,
-      ...presetInference.ffn,
-    },
-    moe: presetInference.moe ?? baseInference.moe ?? null,
-    output: {
-      ...baseInference.output,
-      ...presetInference.output,
-      ...manifestInference.output,
-    },
-    layerPattern: presetInference.layerPattern ?? baseInference.layerPattern,
-    rope: {
-      ...baseInference.rope,
-      ...presetInference.rope,
-      ...manifestInference.rope,
-    },
-    pipeline: manifestInference.pipeline ?? presetInference.pipeline ?? baseInference.pipeline,
-    chatTemplate: {
-      ...baseInference.chatTemplate,
-      ...presetInference.chatTemplate,
-    },
-    kernelPath: presetInference.kernelPath ?? baseInference.kernelPath,
+    attention: mergeLayeredShallowObjects(
+      baseInference.attention,
+      presetInference.attention,
+      manifestInference.attention
+    ),
+    normalization: mergeLayeredShallowObjects(
+      baseInference.normalization,
+      presetInference.normalization
+    ),
+    ffn: mergeLayeredShallowObjects(
+      baseInference.ffn,
+      presetInference.ffn
+    ),
+    moe: chooseNullish(presetInference.moe, chooseNullish(baseInference.moe, null)),
+    output: mergeLayeredShallowObjects(
+      baseInference.output,
+      presetInference.output,
+      manifestInference.output
+    ),
+    layerPattern: chooseNullish(presetInference.layerPattern, baseInference.layerPattern),
+    rope: mergeLayeredShallowObjects(
+      baseInference.rope,
+      presetInference.rope,
+      manifestInference.rope
+    ),
+    pipeline: chooseNullish(manifestInference.pipeline, chooseNullish(presetInference.pipeline, baseInference.pipeline)),
+    chatTemplate: mergeLayeredShallowObjects(
+      baseInference.chatTemplate,
+      presetInference.chatTemplate
+    ),
+    kernelPath: chooseNullish(presetInference.kernelPath, baseInference.kernelPath),
   };
 
   // Merge tokenizer config
-  const tokenizer = {
-    ...preset.tokenizer,
-    ...extractTokenizerFromManifest(manifest),
-  };
+  const tokenizer = mergeLayeredShallowObjects(
+    preset.tokenizer,
+    extractTokenizerFromManifest(manifest)
+  );
 
   // Sampling defaults
   const sampling = preset.sampling ?? {
@@ -317,41 +325,56 @@ function assertArchitecture(manifest, architecture) {
 // =============================================================================
 
 function extractArchitectureFromConfig(config) {
+  const nestedTextConfig = getNestedTextConfig(config);
   return {
-    numLayers: config.num_hidden_layers ?? config.n_layer ?? config.blockCount,
-    hiddenSize: config.hidden_size ?? config.n_embd ?? config.embeddingLength,
-    intermediateSize: config.intermediate_size ?? config.n_inner ?? config.feedForwardLength,
-    numAttentionHeads: config.num_attention_heads ?? config.n_head ?? config.attentionHeadCount,
-    numKeyValueHeads: config.num_key_value_heads ?? config.attentionHeadCountKV,
-    headDim: config.head_dim,
-    vocabSize: config.vocab_size ?? config.vocabSize,
-    maxSeqLen: config.max_position_embeddings ?? config.n_positions ?? config.contextLength,
-    ropeTheta: config.rope_theta ?? config.ropeFreqBase,
-    rmsNormEps: config.rms_norm_eps ?? config.attentionLayerNormRMSEpsilon,
+    numLayers: config.num_hidden_layers ?? nestedTextConfig?.num_hidden_layers ?? config.n_layer ?? config.blockCount,
+    hiddenSize: config.hidden_size ?? nestedTextConfig?.hidden_size ?? config.n_embd ?? config.embeddingLength,
+    intermediateSize: config.intermediate_size ?? nestedTextConfig?.intermediate_size ?? config.n_inner ?? config.feedForwardLength,
+    numAttentionHeads: config.num_attention_heads ?? nestedTextConfig?.num_attention_heads ?? config.n_head ?? config.attentionHeadCount,
+    numKeyValueHeads: config.num_key_value_heads ?? nestedTextConfig?.num_key_value_heads ?? config.attentionHeadCountKV,
+    headDim: config.head_dim ?? nestedTextConfig?.head_dim,
+    vocabSize: config.vocab_size ?? nestedTextConfig?.vocab_size ?? config.vocabSize,
+    maxSeqLen: config.max_position_embeddings ?? nestedTextConfig?.max_position_embeddings ?? config.n_positions ?? config.contextLength,
+    ropeTheta: config.rope_theta ?? nestedTextConfig?.rope_theta ?? config.ropeFreqBase,
+    rmsNormEps: config.rms_norm_eps ?? nestedTextConfig?.rms_norm_eps ?? config.attentionLayerNormRMSEpsilon,
   };
 }
 
 function extractInferenceFromConfig(config) {
+  const nestedTextConfig = getNestedTextConfig(config);
   return {
     attention: {
-      slidingWindow: config.sliding_window,
-      attnLogitSoftcapping: config.attn_logit_softcapping,
-      attentionOutputGate: config.attn_output_gate,
+      slidingWindow: config.sliding_window ?? nestedTextConfig?.sliding_window,
+      attnLogitSoftcapping: config.attn_logit_softcapping ?? nestedTextConfig?.attn_logit_softcapping,
+      attentionOutputGate: config.attn_output_gate ?? nestedTextConfig?.attn_output_gate,
     },
     output: {
-      finalLogitSoftcapping: config.final_logit_softcapping,
-      tieWordEmbeddings: config.tie_word_embeddings,
-      scaleEmbeddings: config.scale_embeddings,
+      finalLogitSoftcapping: config.final_logit_softcapping ?? nestedTextConfig?.final_logit_softcapping,
+      tieWordEmbeddings: config.tie_word_embeddings ?? nestedTextConfig?.tie_word_embeddings,
+      scaleEmbeddings: config.scale_embeddings ?? nestedTextConfig?.scale_embeddings,
     },
-    pipeline: config.pipeline,
+    pipeline: config.pipeline ?? nestedTextConfig?.pipeline,
     rope: {
-      ropeTheta: config.rope_theta ?? config.ropeFreqBase,
-      ropeScalingType: config.rope_scaling_type,
-      ropeScalingFactor: config.rope_scaling_factor,
+      ropeTheta: config.rope_theta ?? nestedTextConfig?.rope_theta ?? config.ropeFreqBase,
+      ropeScalingType: config.rope_scaling_type ?? nestedTextConfig?.rope_scaling_type,
+      ropeScalingFactor: config.rope_scaling_factor ?? nestedTextConfig?.rope_scaling_factor,
     },
   };
 }
 
+function getNestedTextConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return null;
+  }
+  if (config.text_config && typeof config.text_config === 'object' && !Array.isArray(config.text_config)) {
+    return config.text_config;
+  }
+  if (config.language_config && typeof config.language_config === 'object' && !Array.isArray(config.language_config)) {
+    return config.language_config;
+  }
+  return null;
+}
+
 function extractTokenizerFromManifest(manifest) {
   if (!manifest.tokenizer) return {};
 

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

@@ -0,0 +1,16 @@
+export interface MergeContractCheckResult {
+  id: string;
+  ok: boolean;
+  detail: string;
+  mode: 'actual' | 'modeled';
+}
+
+export interface MergeContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: MergeContractCheckResult[];
+  errors: string[];
+}
+
+export declare function buildMergeContractArtifact(): MergeContractArtifact;

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, [])),
+  };
+}