@simulatte/doppler 0.1.5 → 0.1.7

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

@@ -1,1007 +1,37 @@
 import { mergeRuntimeValues } from '../../../config/runtime-merge.js';
+import { buildExecutionV0FromKernelPath } from '../../../converter/execution-v0-manifest.js';
 import {
-  buildExecutionV0KernelProfileKey,
-  indexExecutionV0KernelProfiles,
-  normalizeExecutionV0Dtype,
-  resolveExecutionV0KernelProfile,
-  resolveExecutionV0KVIO,
-  resolveExecutionV0Precision,
-} from '../../../config/execution-v0-contract-check.js';
-import {
-  EXECUTION_V0_SCHEMA_ID,
+  DEFAULT_EXECUTION_V0_COMPUTE_DEFAULTS,
   DEFAULT_EXECUTION_V0_POLICIES,
   DEFAULT_EXECUTION_V0_SESSION_DEFAULTS,
-  isExecutionV0Digest,
-  isExecutionV0Semver,
 } from '../../../config/schema/execution-v0.schema.js';
-import { KERNEL_CONFIGS } from '../../../gpu/kernels/kernel-configs.js';
-import { buildKernelRefFromKernelEntry, isKernelRefBoundToKernel } from '../../../config/kernels/kernel-ref.js';
-
-const PATCH_SET_MUTABLE_FIELDS = new Set(['precision', 'kvIO', 'constants', 'entry']);
-const EXECUTION_V0_RUNTIME_KEYS = new Set(['session', 'executionPatch']);
-const PIPELINE_COMPATIBLE_OPS = new Set([
-  'save',
-  'load',
-  'conv',
-  'attention',
-  'rmsnorm',
-  'ffn',
-  'residual_add',
-  'cast',
-  'noop',
-]);
-
-const KERNEL_OUTPUT_CAPABILITIES = (() => {
-  const byKernelEntry = new Map();
-  for (const variants of Object.values(KERNEL_CONFIGS)) {
-    for (const config of Object.values(variants)) {
-      const kernel = config?.shaderFile;
-      const entry = config?.entryPoint ?? 'main';
-      if (typeof kernel !== 'string' || kernel.length === 0) continue;
-      const key = `${kernel}#${entry}`;
-      if (!byKernelEntry.has(key)) {
-        byKernelEntry.set(key, new Set());
-      }
-      const outputDtype = config?.outputDtype;
-      if (typeof outputDtype === 'string' && outputDtype.length > 0) {
-        byKernelEntry.get(key).add(String(outputDtype).toLowerCase());
-      }
-    }
-  }
-  return byKernelEntry;
-})();
-
-function getKernelOutputCapabilities(step) {
-  const kernel = String(step?.kernel ?? '').trim();
-  const entry = String(step?.entry ?? 'main').trim() || 'main';
-  if (!kernel) {
-    return null;
-  }
-  return KERNEL_OUTPUT_CAPABILITIES.get(`${kernel}#${entry}`) ?? null;
-}
-
-function cloneJson(value) {
-  if (typeof structuredClone === 'function') {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
-const normalizeDtype = normalizeExecutionV0Dtype;
-const resolvePrecision = resolveExecutionV0Precision;
-const resolveKVIO = resolveExecutionV0KVIO;
-
-function normalizePhase(value, label) {
-  const normalized = String(value ?? '').trim().toLowerCase();
-  if (normalized !== 'prefill' && normalized !== 'decode' && normalized !== 'both') {
-    throw new Error(`[ExecutionV0] ${label} must be prefill|decode|both; got "${value}"`);
-  }
-  return normalized;
-}
-
-function normalizeSection(value, label) {
-  const normalized = String(value ?? '').trim();
-  if (!['preLayer', 'layer', 'postLayer', 'sampling'].includes(normalized)) {
-    throw new Error(`[ExecutionV0] ${label} must be preLayer|layer|postLayer|sampling; got "${value}"`);
-  }
-  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) {
-    throw new Error(`[ExecutionV0] ${label}.id is required`);
-  }
-  if (!isExecutionV0Semver(kernelRef.version)) {
-    throw new Error(`[ExecutionV0] ${label}.version must be semver; got "${kernelRef.version}"`);
-  }
-  if (!isExecutionV0Digest(kernelRef.digest)) {
-    throw new Error(`[ExecutionV0] ${label}.digest must match sha256:<64-hex>`);
-  }
-}
-
-function isPhaseMatch(phase, targetPhase) {
-  return phase === 'both' || phase === targetPhase;
-}
-
-function stepHasLayer(step, layerIdx) {
-  if (step.layers === 'all') return true;
-  if (!Array.isArray(step.layers)) return false;
-  return step.layers.includes(layerIdx);
-}
-
-const buildKernelProfileKey = buildExecutionV0KernelProfileKey;
-
-function normalizeSlot(value, label) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`[ExecutionV0] ${label} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function assertKernelPrecisionCapability(step, resolvedPrecision, policies) {
-  if (step.op === 'cast') {
-    return;
-  }
-  if (policies.unsupportedPrecision !== 'error') {
-    return;
-  }
-  const kernel = String(step.kernel ?? '').trim();
-  const entry = String(step.entry ?? 'main').trim() || 'main';
-  const supportedOutputDtypes = getKernelOutputCapabilities(step);
-  if (!supportedOutputDtypes) {
-    throw new Error(
-      `[ExecutionV0] step "${step.id}" kernel "${kernel}#${entry}" ` +
-      'is not present in kernel registry; cannot validate precision capability.'
-    );
-  }
-  if (supportedOutputDtypes.size === 0) {
-    // Some kernels do not declare output dtype metadata yet; treat as unknown.
-    return;
-  }
-  const outputDtype = normalizeDtype(resolvedPrecision.outputDtype, `${step.id}.precision.outputDtype`);
-  if (!supportedOutputDtypes.has(outputDtype)) {
-    throw new Error(
-      `[ExecutionV0] step "${step.id}" outputDtype=${outputDtype} is unsupported by ` +
-      `kernel "${kernel}#${entry}" (supported: ${[...supportedOutputDtypes].join(', ') || 'none'}).`
-    );
-  }
-}
-
-function createSourceTrace() {
-  return {
-    session: {},
-    steps: {},
-  };
-}
-
-function setSourceTrace(trace, path, source) {
-  if (!trace || typeof path !== 'string' || path.length === 0) return;
-  trace[path] = { source };
-}
-
-function setStepSourceTrace(trace, stepId, path, source) {
-  if (!trace || !stepId || !path) return;
-  if (!trace.steps[stepId]) {
-    trace.steps[stepId] = {};
-  }
-  trace.steps[stepId][path] = { source };
-}
-
-function isPlainObject(value) {
-  return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function collectLeafPaths(value, prefix = [], out = []) {
-  if (Array.isArray(value)) {
-    if (prefix.length > 0) {
-      out.push(prefix);
-    }
-    return out;
-  }
-  if (!isPlainObject(value)) {
-    if (prefix.length > 0) {
-      out.push(prefix);
-    }
-    return out;
-  }
-  for (const [key, child] of Object.entries(value)) {
-    collectLeafPaths(child, [...prefix, key], out);
-  }
-  return out;
-}
-
-function hasDefinedPath(root, pathSegments) {
-  let current = root;
-  for (const segment of pathSegments) {
-    if (!isPlainObject(current) || !Object.prototype.hasOwnProperty.call(current, segment)) {
-      return false;
-    }
-    current = current[segment];
-  }
-  return current !== undefined;
-}
-
-const indexKernelProfiles = indexExecutionV0KernelProfiles;
-
-function resolveProfile(profileIndex, step) {
-  return resolveExecutionV0KernelProfile(profileIndex, step);
-}
-
-function validateStepShape(step, index) {
-  if (!step || typeof step !== 'object') {
-    throw new Error(`[ExecutionV0] execution.steps[${index}] must be an object`);
-  }
-  if (typeof step.id !== 'string' || step.id.trim().length === 0) {
-    throw new Error(`[ExecutionV0] execution.steps[${index}].id is required`);
-  }
-  if (typeof step.op !== 'string' || step.op.trim().length === 0) {
-    throw new Error(`[ExecutionV0] execution.steps[${index}].op is required`);
-  }
-  normalizePhase(step.phase, `execution.steps[${index}].phase`);
-  normalizeSection(step.section, `execution.steps[${index}].section`);
-  normalizeSlot(step.src, `execution.steps[${index}].src`);
-  normalizeSlot(step.dst, `execution.steps[${index}].dst`);
-  if (step.layers !== 'all' && !Array.isArray(step.layers)) {
-    throw new Error(`[ExecutionV0] execution.steps[${index}].layers must be "all" or number[]`);
-  }
-  if (step.layers !== 'all') {
-    for (const layer of step.layers) {
-      if (!Number.isInteger(layer) || layer < 0) {
-        throw new Error(`[ExecutionV0] execution.steps[${index}].layers must contain non-negative integers`);
-      }
-    }
-  }
-  if (step.op === 'cast') {
-    normalizeDtype(step.toDtype, `execution.steps[${index}].toDtype`);
-    if (step.fromDtype != null) {
-      normalizeDtype(step.fromDtype, `execution.steps[${index}].fromDtype`);
-    }
-  } else {
-    if (typeof step.kernel !== 'string' || step.kernel.trim().length === 0) {
-      throw new Error(
-        `[ExecutionV0] execution.steps[${index}] "${step.id}" requires kernel (non-cast op)`
-      );
-    }
-    if (!step.kernelRef || typeof step.kernelRef !== 'object' || Array.isArray(step.kernelRef)) {
-      throw new Error(
-        `[ExecutionV0] execution.steps[${index}] "${step.id}" requires kernelRef {id, version, digest} (non-cast op)`
-      );
-    }
-    assertKernelRef(step.kernelRef, `execution.steps[${index}].kernelRef`);
-    const entry = String(step.entry ?? 'main').trim() || 'main';
-    let expectedKernelRef;
-    try {
-      expectedKernelRef = buildKernelRefFromKernelEntry(step.kernel, entry);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(
-        `[ExecutionV0] execution.steps[${index}] "${step.id}" kernel "${step.kernel}#${entry}" ` +
-        `cannot be content-pinned: ${message}`
-      );
-    }
-    if (!isKernelRefBoundToKernel(step.kernelRef, step.kernel, entry)) {
-      throw new Error(
-        `[ExecutionV0] execution.steps[${index}] "${step.id}" kernelRef does not match kernel binding ` +
-        `("${step.kernel}#${entry}"). Expected ${expectedKernelRef.id}@${expectedKernelRef.version} ${expectedKernelRef.digest}.`
-      );
-    }
-  }
-}
-
-function assertExecutionRuntimeOverlay(runtimeInference) {
-  if (!runtimeInference || typeof runtimeInference !== 'object') {
-    return;
-  }
-  const unknownKeys = Object.keys(runtimeInference).filter((key) => !EXECUTION_V0_RUNTIME_KEYS.has(key));
-  if (unknownKeys.length > 0) {
-    throw new Error(
-      `[ExecutionV0] runtime.inference overlay supports only ${[...EXECUTION_V0_RUNTIME_KEYS].join(', ')}; ` +
-      `got unsupported keys: ${unknownKeys.join(', ')}.`
-    );
-  }
-}
-
-function validateUniqueStepIds(steps) {
-  const ids = new Set();
-  for (const step of steps) {
-    if (ids.has(step.id)) {
-      throw new Error(`[ExecutionV0] duplicate step id "${step.id}"`);
-    }
-    ids.add(step.id);
-  }
-}
-
-function assertExecutionV0Schema(manifestInference) {
-  if (!hasExecutionV0(manifestInference)) return;
-  const discriminator = manifestInference?.schema ?? null;
-  if (discriminator !== EXECUTION_V0_SCHEMA_ID) {
-    throw new Error(
-      `[ExecutionV0] manifest.inference.schema must be "${EXECUTION_V0_SCHEMA_ID}" ` +
-      `when execution is present; got "${discriminator}".`
-    );
-  }
-}
-
-function applyExecutionPatchAtomic(baseSteps, patch) {
-  if (!patch) {
-    return baseSteps;
-  }
-  const steps = cloneJson(baseSteps);
-  const byId = new Map(steps.map((step, index) => [step.id, index]));
-
-  for (const entry of patch.set ?? []) {
-    if (!entry || typeof entry !== 'object' || typeof entry.id !== 'string') {
-      throw new Error('[ExecutionV0] executionPatch.set entries require id');
-    }
-    if (!byId.has(entry.id)) {
-      throw new Error(`[ExecutionV0] executionPatch.set target "${entry.id}" does not exist`);
-    }
-    for (const key of Object.keys(entry)) {
-      if (key === 'id') continue;
-      if (!PATCH_SET_MUTABLE_FIELDS.has(key)) {
-        throw new Error(`[ExecutionV0] executionPatch.set "${entry.id}" cannot mutate "${key}"`);
-      }
-    }
-  }
-
-  for (const entry of patch.remove ?? []) {
-    if (!entry || typeof entry !== 'object' || typeof entry.id !== 'string') {
-      throw new Error('[ExecutionV0] executionPatch.remove entries require id');
-    }
-    if (!byId.has(entry.id)) {
-      throw new Error(`[ExecutionV0] executionPatch.remove target "${entry.id}" does not exist`);
-    }
-  }
-
-  for (const entry of patch.set ?? []) {
-    const index = byId.get(entry.id);
-    const target = steps[index];
-    if (entry.precision !== undefined) target.precision = cloneJson(entry.precision);
-    if (entry.kvIO !== undefined) target.kvIO = cloneJson(entry.kvIO);
-    if (entry.constants !== undefined) target.constants = cloneJson(entry.constants);
-    if (entry.entry !== undefined) target.entry = entry.entry;
-  }
-
-  const removeIds = new Set((patch.remove ?? []).map((entry) => entry.id));
-  const removedSteps = steps.filter((step) => !removeIds.has(step.id));
-
-  let current = removedSteps;
-  const insertedAfterAnchors = new Map();
-  for (const entry of patch.add ?? []) {
-    if (!entry?.step || typeof entry.step !== 'object') {
-      throw new Error('[ExecutionV0] executionPatch.add requires a step payload');
-    }
-    const hasBefore = typeof entry.insertBefore === 'string' && entry.insertBefore.length > 0;
-    const hasAfter = typeof entry.insertAfter === 'string' && entry.insertAfter.length > 0;
-    if (hasBefore === hasAfter) {
-      throw new Error('[ExecutionV0] executionPatch.add requires exactly one of insertBefore or insertAfter');
-    }
-    if (current.some((step) => step.id === entry.step.id)) {
-      throw new Error(`[ExecutionV0] executionPatch.add step id "${entry.step.id}" already exists`);
-    }
-    const anchorId = hasBefore ? entry.insertBefore : entry.insertAfter;
-    const anchorIndex = current.findIndex((step) => step.id === anchorId);
-    if (anchorIndex < 0) {
-      throw new Error(`[ExecutionV0] executionPatch.add anchor "${anchorId}" not found`);
-    }
-    let insertIndex = hasBefore ? anchorIndex : anchorIndex + 1;
-    if (!hasBefore) {
-      const insertedIds = insertedAfterAnchors.get(anchorId) ?? [];
-      while (insertIndex < current.length && insertedIds.includes(current[insertIndex].id)) {
-        insertIndex += 1;
-      }
-    }
-    current = [
-      ...current.slice(0, insertIndex),
-      cloneJson(entry.step),
-      ...current.slice(insertIndex),
-    ];
-    if (!hasBefore) {
-      const insertedIds = insertedAfterAnchors.get(anchorId) ?? [];
-      insertedIds.push(entry.step.id);
-      insertedAfterAnchors.set(anchorId, insertedIds);
-    }
-  }
-
-  validateUniqueStepIds(current);
-  return current;
-}
-
-function indexRuntimePatchMeta(patch) {
-  const meta = {
-    addedSteps: new Set(),
-    precisionFieldsByStep: new Map(),
-    kvIOFieldsByStep: new Set(),
-  };
-  if (!patch || typeof patch !== 'object') {
-    return meta;
-  }
-
-  for (const add of patch.add ?? []) {
-    const stepId = add?.step?.id;
-    if (typeof stepId === 'string' && stepId.length > 0) {
-      meta.addedSteps.add(stepId);
-    }
-  }
-
-  for (const set of patch.set ?? []) {
-    const stepId = set?.id;
-    if (typeof stepId !== 'string' || stepId.length === 0) continue;
-    if (set.precision && typeof set.precision === 'object') {
-      meta.precisionFieldsByStep.set(stepId, new Set(Object.keys(set.precision)));
-    }
-    if (set.kvIO && typeof set.kvIO === 'object') {
-      meta.kvIOFieldsByStep.add(stepId);
-    }
-  }
-  return meta;
-}
-
-function createInitialSlotDtypes(sessionDefaults) {
-  const activationDefault = normalizeDtype(
-    sessionDefaults?.compute?.defaults?.activationDtype ?? 'f16',
-    'sessionDefaults.compute.defaults.activationDtype'
-  );
-  return new Map([['state', activationDefault]]);
-}
-
-function ensureCompatibleKV(step, kvIO, sessionDefaults) {
-  if (step.op !== 'attention' || !kvIO) {
-    return;
-  }
-  const runtimeKvDtypeRaw = sessionDefaults?.kvcache?.kvDtype;
-  if (runtimeKvDtypeRaw == null) {
-    return;
-  }
-  const runtimeKvDtype = normalizeDtype(runtimeKvDtypeRaw, 'sessionDefaults.kvcache.kvDtype');
-  if (kvIO.readDtype !== runtimeKvDtype || kvIO.writeDtype !== runtimeKvDtype) {
-    throw new Error(
-      `[ExecutionV0] step "${step.id}" kvIO read/write (${kvIO.readDtype}/${kvIO.writeDtype}) ` +
-      `must match sessionDefaults.kvcache.kvDtype (${runtimeKvDtype}).`
-    );
-  }
-}
-
-function resolvePhaseSteps(phase, steps, sessionDefaults, profileIndex, policies, options = {}) {
-  const slotDtypes = options.initialSlotDtypes
-    ? new Map(options.initialSlotDtypes)
-    : createInitialSlotDtypes(sessionDefaults);
-  const resolved = [];
-  const sourceTrace = options.sourceTrace ?? null;
-  const sessionDefaultSources = options.sessionDefaultSources ?? {};
-  const runtimePatchMeta = options.runtimePatchMeta ?? {
-    addedSteps: new Set(),
-    precisionFieldsByStep: new Map(),
-    kvIOFieldsByStep: new Set(),
-  };
-
-  for (const step of steps) {
-    const stepPhase = normalizePhase(step.phase, `${step.id}.phase`);
-    if (!isPhaseMatch(stepPhase, phase)) continue;
-    const profile = resolveProfile(profileIndex, step);
-    if (
-      step.kernelRef
-      && !profile
-      && policies.unresolvedKernel === 'error'
-    ) {
-      throw new Error(
-        `[ExecutionV0] step "${step.id}" references kernel profile ` +
-        `${step.kernelRef.id}@${step.kernelRef.version} (${step.kernelRef.digest}) ` +
-        'but no matching sessionDefaults.compute.kernelProfiles entry was found.'
-      );
-    }
-    const { precision, sources: precisionSources } = resolvePrecision(step, profile, sessionDefaults);
-    const src = normalizeSlot(step.src, `${step.id}.src`);
-    const dst = normalizeSlot(step.dst, `${step.id}.dst`);
-    if (!slotDtypes.has(src)) {
-      throw new Error(
-        `[ExecutionV0] step "${step.id}" reads slot "${src}" before it is produced. ` +
-        'Add an explicit producer step or cast/load bridge.'
-      );
-    }
-    const derivedInput = slotDtypes.get(src);
-    const inputDtype = normalizeDtype(precision.inputDtype ?? derivedInput, `${step.id}.precision.inputDtype`);
-
-    if (
-      policies.dtypeTransition === 'require_cast_step'
-      && step.op !== 'cast'
-      && inputDtype !== derivedInput
-    ) {
-      throw new Error(
-        `[ExecutionV0] step "${step.id}" requires inputDtype=${inputDtype} ` +
-        `but slot "${src}" currently holds ${derivedInput}. Insert explicit cast step.`
-      );
-    }
-
-    let outputDtype = normalizeDtype(precision.outputDtype, `${step.id}.precision.outputDtype`);
-    let outputDtypeSource = precisionSources.outputDtype;
-    if (step.op !== 'cast' && outputDtypeSource === 'sessionDefault') {
-      const declaredOutputDtypes = getKernelOutputCapabilities(step);
-      if (declaredOutputDtypes && declaredOutputDtypes.size === 1) {
-        outputDtype = [...declaredOutputDtypes][0];
-        outputDtypeSource = 'derived';
-      }
-    }
-    if (step.op === 'cast') {
-      outputDtype = normalizeDtype(step.toDtype, `${step.id}.toDtype`);
-      outputDtypeSource = 'manifest';
-      const fromDtype = step.fromDtype
-        ? normalizeDtype(step.fromDtype, `${step.id}.fromDtype`)
-        : derivedInput;
-      if (fromDtype !== derivedInput) {
-        throw new Error(
-          `[ExecutionV0] cast step "${step.id}" fromDtype=${fromDtype} does not match slot "${src}" dtype=${derivedInput}`
-        );
-      }
-    }
-
-    const resolvedPrecision = {
-      inputDtype,
-      mathDtype: normalizeDtype(precision.mathDtype, `${step.id}.precision.mathDtype`),
-      accumDtype: normalizeDtype(precision.accumDtype, `${step.id}.precision.accumDtype`),
-      outputDtype,
-    };
-    assertKernelPrecisionCapability(step, resolvedPrecision, policies);
-    slotDtypes.set(dst, outputDtype);
-
-    const kvIOResolved = step.op === 'attention'
-      ? resolveKVIO(step, profile, sessionDefaults)
-      : null;
-    const kvIO = kvIOResolved?.value ?? null;
-    ensureCompatibleKV(step, kvIO, sessionDefaults);
-
-    if (sourceTrace) {
-      const precisionFieldsPatched = runtimePatchMeta.precisionFieldsByStep.get(step.id) ?? new Set();
-      const isAddedStep = runtimePatchMeta.addedSteps.has(step.id);
-      const inputPatched = isAddedStep
-        ? step.precision?.inputDtype != null
-        : precisionFieldsPatched.has('inputDtype');
-      const mathPatched = isAddedStep
-        ? step.precision?.mathDtype != null
-        : precisionFieldsPatched.has('mathDtype');
-      const accumPatched = isAddedStep
-        ? step.precision?.accumDtype != null
-        : precisionFieldsPatched.has('accumDtype');
-      const outputPatched = isAddedStep
-        ? step.precision?.outputDtype != null
-        : precisionFieldsPatched.has('outputDtype');
-      const mathSource = precisionSources.mathDtype === 'sessionDefault'
-        ? sessionDefaultSources.mathDtype ?? 'derived'
-        : precisionSources.mathDtype;
-      const accumSource = precisionSources.accumDtype === 'sessionDefault'
-        ? sessionDefaultSources.accumDtype ?? 'derived'
-        : precisionSources.accumDtype;
-      const outputSource = precisionSources.outputDtype === 'sessionDefault'
-        ? outputDtypeSource === 'sessionDefault'
-          ? (sessionDefaultSources.outputDtype ?? 'derived')
-          : outputDtypeSource
-        : outputDtypeSource;
-      setStepSourceTrace(sourceTrace, step.id, 'precision.inputDtype',
-        inputPatched
-          ? 'runtime.patch'
-          : precision.inputDtype != null
-            ? precisionSources.inputDtype
-            : 'derived');
-      setStepSourceTrace(sourceTrace, step.id, 'precision.mathDtype', mathPatched ? 'runtime.patch' : mathSource);
-      setStepSourceTrace(sourceTrace, step.id, 'precision.accumDtype', accumPatched ? 'runtime.patch' : accumSource);
-      setStepSourceTrace(sourceTrace, step.id, 'precision.outputDtype', outputPatched ? 'runtime.patch' : outputSource);
-      if (step.op === 'attention') {
-        const kvPatched = runtimePatchMeta.kvIOFieldsByStep.has(step.id)
-          || (isAddedStep && !!step.kvIO);
-        const kvSource = kvIOResolved?.source === 'sessionDefault'
-          ? sessionDefaultSources.kvDtype ?? 'derived'
-          : kvIOResolved?.source ?? 'derived';
-        const resolvedKvSource = kvPatched ? 'runtime.patch' : kvSource;
-        setStepSourceTrace(sourceTrace, step.id, 'kvIO.readDtype', resolvedKvSource);
-        setStepSourceTrace(sourceTrace, step.id, 'kvIO.writeDtype', resolvedKvSource);
-      }
-    }
-
-    resolved.push({
-      ...step,
-      src,
-      dst,
-      phase: stepPhase,
-      section: normalizeSection(step.section, `${step.id}.section`),
-      precision: resolvedPrecision,
-      kvIO,
-    });
-  }
-
-  return {
-    steps: resolved,
-    finalSlotDtypes: slotDtypes,
-  };
-}
-
-function stripPresetComputeDefaults(compute, manifestComputeDefaults) {
-  if (!compute?.defaults || !manifestComputeDefaults) {
-    return compute;
-  }
-  const dtypeKeys = ['activationDtype', 'mathDtype', 'accumDtype', 'outputDtype'];
-  const hasManifestDtype = dtypeKeys.some(
-    (key) => manifestComputeDefaults[key] !== undefined && manifestComputeDefaults[key] !== null
-  );
-  if (!hasManifestDtype) {
-    return compute;
-  }
-  const nextDefaults = { ...compute.defaults };
-  for (const key of dtypeKeys) {
-    if (manifestComputeDefaults[key] !== undefined && manifestComputeDefaults[key] !== null) {
-      delete nextDefaults[key];
-    }
-  }
-  if (Object.keys(nextDefaults).length === 0) {
-    const nextCompute = { ...compute };
-    delete nextCompute.defaults;
-    return Object.keys(nextCompute).length === 0 ? null : nextCompute;
-  }
-  return { ...compute, defaults: nextDefaults };
-}
-
-function normalizeRuntimeSessionForExecutionV0(runtimeSession, manifestInference) {
-  const manifestSessionDefaults = manifestInference?.sessionDefaults ?? null;
-  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 || typeof runtimeSession !== 'object') {
-    return runtimeSession;
-  }
-
-  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.
-  // default.json sets session.compute.defaults.activationDtype="f16" as a preset default.
-  // When the manifest declares its own compute dtypes (e.g. activationDtype="f32" for f32
-  // variants), the manifest must win. Only explicit user overrides (via --runtime-config-json
-  // or CLI flags) should take precedence, not baked-in preset values.
-  if (manifestComputeDefaults) {
-    const stripped = stripPresetComputeDefaults(compute, manifestComputeDefaults);
-    if (stripped !== compute) {
-      compute = stripped;
-      changed = true;
-    }
-  }
-
-  // Strip empty kernelProfiles when manifest provides them.
-  if (compute && Object.prototype.hasOwnProperty.call(compute, 'kernelProfiles')) {
-    const kernelProfiles = compute.kernelProfiles;
-    if (Array.isArray(kernelProfiles) && kernelProfiles.length === 0 && hasManifestProfiles) {
-      const nextCompute = { ...compute };
-      delete nextCompute.kernelProfiles;
-      compute = Object.keys(nextCompute).length === 0 ? null : nextCompute;
-      changed = true;
-    }
-  }
-
-  // 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) {
-    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 Object.keys(nextRuntimeSession).length === 0 ? {} : nextRuntimeSession;
-}
-
-function validatePhaseBoundaryCompatibility(options) {
-  const {
-    steps,
-    prefillFinalSlotDtypes,
-    decodeInitialSlotDtypes,
-    sessionDefaults,
-    profileIndex,
-    policies,
-  } = options;
-  const decodeSteps = steps.filter((step) => isPhaseMatch(normalizePhase(step.phase, `${step.id}.phase`), 'decode'));
-  if (decodeSteps.length === 0) {
-    return;
-  }
-  const writtenSlots = new Set();
-  for (const step of decodeSteps) {
-    const src = normalizeSlot(step.src, `${step.id}.src`);
-    const dst = normalizeSlot(step.dst, `${step.id}.dst`);
-    const readsCarriedSlot = !writtenSlots.has(src) && prefillFinalSlotDtypes.has(src);
-    if (readsCarriedSlot && step.op !== 'cast') {
-      const profile = resolveProfile(profileIndex, step);
-      const { precision } = resolvePrecision(step, profile, sessionDefaults);
-      const carriedDtype = prefillFinalSlotDtypes.get(src);
-      const decodeInput = normalizeDtype(
-        precision.inputDtype
-          ?? carriedDtype
-          ?? decodeInitialSlotDtypes.get(src),
-        `${step.id}.precision.inputDtype`
-      );
-      if (decodeInput !== carriedDtype) {
-        throw new Error(
-          `[ExecutionV0] decode step "${step.id}" reads carried slot "${src}" as ${decodeInput} ` +
-          `but prefill left ${carriedDtype}. Add explicit cast at phase boundary.`
-        );
-      }
-    }
-    writtenSlots.add(dst);
-  }
-}
-
-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;
-  return {
-    op: step.op,
-    kernel: step.kernel,
-    entry: step.entry ?? 'main',
-    ...(step.weights ? { weights: step.weights } : {}),
-    ...(step.constants ? { constants: step.constants } : {}),
-  };
-}
-
-function getSectionSteps(steps, section, phase = null) {
-  return steps
-    .filter((step) => step.section === section)
-    .filter((step) => (phase ? isPhaseMatch(step.phase, phase) : true))
-    .map(toKernelPathStep)
-    .filter((step) => step != null);
-}
-
-function buildLayerPhaseSteps(steps, phase, layerIdx) {
-  return steps
-    .filter((step) => step.section === 'layer' && isPhaseMatch(step.phase, phase))
-    .filter((step) => stepHasLayer(step, layerIdx))
-    .map(toKernelPathStep)
-    .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',
-    'sessionDefaults.compute.defaults.activationDtype'
-  );
-  const kvDtype = normalizeDtype(
-    sessionDefaults?.kvcache?.kvDtype ?? activationDtype,
-    'sessionDefaults.kvcache.kvDtype'
-  );
-  const decodeSteps = buildLayerPhaseSteps(steps, 'decode', 0);
-  const prefillSteps = buildLayerPhaseSteps(steps, 'prefill', 0);
-  if (decodeSteps.length === 0 && prefillSteps.length === 0) {
-    return null;
-  }
-
-  const path = {
-    id: `${modelId || 'model'}-execution-v0`,
-    name: 'Execution v0 inline kernel path',
-    description: 'Generated from manifest.inference.execution.steps',
-    activationDtype,
-    kvDtype,
-    decode: {
-      steps: decodeSteps.length > 0 ? decodeSteps : prefillSteps,
-    },
-    prefill: {
-      steps: prefillSteps.length > 0 ? prefillSteps : decodeSteps,
-    },
-  };
-
-  if (numLayers > 0) {
-    const overrides = [];
-    for (let layerIdx = 0; layerIdx < numLayers; layerIdx++) {
-      const decodeLayerSteps = buildLayerPhaseSteps(steps, 'decode', layerIdx);
-      const prefillLayerSteps = buildLayerPhaseSteps(steps, 'prefill', layerIdx);
-      const hasCustomDecode = JSON.stringify(decodeLayerSteps) !== JSON.stringify(path.decode.steps);
-      const hasCustomPrefill = JSON.stringify(prefillLayerSteps) !== JSON.stringify(path.prefill.steps);
-      if (!hasCustomDecode && !hasCustomPrefill) continue;
-      // Kernel path layerOverrides are single-step lists per layer.
-      const mergedLayerSteps = decodeLayerSteps.length > 0
-        ? decodeLayerSteps
-        : prefillLayerSteps;
-      if (mergedLayerSteps.length > 0) {
-        overrides.push({
-          layers: [layerIdx],
-          steps: mergedLayerSteps,
-        });
-      }
-    }
-    if (overrides.length > 0) {
-      path.layerOverrides = overrides;
-    }
-  }
-
-  const preLayer = getSectionSteps(steps, 'preLayer');
-  if (preLayer.length > 0) {
-    path.preLayer = preLayer;
-  }
-  const postLayer = getSectionSteps(steps, 'postLayer');
-  if (postLayer.length > 0) {
-    path.postLayer = postLayer;
-  }
-  const sampling = getSectionSteps(steps, 'sampling', 'decode');
-  if (sampling.length > 0) {
-    path.sampling = sampling;
-  }
-
-  assertInlineKernelPathSessionCompatibility(path, sessionDefaults);
-  return path;
-}
-
-function buildLayerPipelineFromExecution(steps) {
-  const layerSectionSteps = steps.filter((step) => step.section === 'layer');
-  if (layerSectionSteps.length === 0) {
-    return null;
-  }
-  if (layerSectionSteps.some((step) => !PIPELINE_COMPATIBLE_OPS.has(step.op))) {
-    return null;
-  }
-
-  const layerSteps = layerSectionSteps
-    .map((step) => ({
-      op: step.op,
-      phase: step.phase,
-      src: step.src ?? 'state',
-      dst: step.dst ?? 'state',
-      ...(step.residual !== undefined ? { residual: step.residual } : {}),
-      ...(step.a !== undefined ? { a: step.a } : {}),
-      ...(step.b !== undefined ? { b: step.b } : {}),
-      ...(step.variant !== undefined ? { variant: step.variant } : {}),
-      ...(step.skipInputNorm !== undefined ? { skipInputNorm: step.skipInputNorm } : {}),
-      ...(step.precision?.inputDtype ? { inputDtype: step.precision.inputDtype } : {}),
-      ...(step.precision?.outputDtype ? { outputDtype: step.precision.outputDtype } : {}),
-      ...(step.fromDtype ? { fromDtype: step.fromDtype } : {}),
-      ...(step.toDtype ? { toDtype: step.toDtype } : {}),
-      ...(step.probeStage ? { probeStage: step.probeStage } : {}),
-      ...(step.name ? { name: step.name } : {}),
-      ...(step.weight ? { weight: step.weight } : {}),
-    }));
-
-  return {
-    steps: layerSteps,
-    overrides: [],
-  };
-}
-
-function buildSessionRuntimePatch(sessionDefaults) {
-  const patch = {};
-  const computeDefaults = sessionDefaults?.compute?.defaults ?? null;
-  const computePatch = {};
-  const activationDtype = computeDefaults?.activationDtype;
-  if (activationDtype) {
-    computePatch.activationDtype = activationDtype;
-  }
-  if (computeDefaults && (computeDefaults.mathDtype || computeDefaults.accumDtype || computeDefaults.outputDtype)) {
-    computePatch.defaults = {
-      ...(computeDefaults.mathDtype ? { mathDtype: computeDefaults.mathDtype } : {}),
-      ...(computeDefaults.accumDtype ? { accumDtype: computeDefaults.accumDtype } : {}),
-      ...(computeDefaults.outputDtype ? { outputDtype: computeDefaults.outputDtype } : {}),
-    };
-  }
-  if (Object.keys(computePatch).length > 0) {
-    patch.compute = computePatch;
-  }
-  if (sessionDefaults?.kvcache) {
-    patch.kvcache = sessionDefaults.kvcache;
-  }
-  if (sessionDefaults?.decodeLoop) {
-    patch.batching = {
-      batchSize: sessionDefaults.decodeLoop.batchSize,
-      stopCheckMode: sessionDefaults.decodeLoop.stopCheckMode,
-      readbackInterval: sessionDefaults.decodeLoop.readbackInterval,
-      ringTokens: sessionDefaults.decodeLoop.ringTokens,
-      ringStop: sessionDefaults.decodeLoop.ringStop,
-      ringStaging: sessionDefaults.decodeLoop.ringStaging,
-    };
-  }
-  return patch;
-}
-
-function buildModelRuntimeOverrides(manifestInference) {
-  const model = manifestInference?.model;
-  if (!model || typeof model !== 'object') {
-    return null;
-  }
-  return cloneJson(model);
-}
+import {
+  applyExecutionPatchAtomic,
+  assertExecutionRuntimeOverlay,
+  assertExecutionV0Schema,
+  assertKVLayoutExecutionCompatibility,
+  collectLeafPaths,
+  createInitialSlotDtypes,
+  createSourceTrace,
+  hasDefinedPath,
+  indexKernelProfiles,
+  indexRuntimePatchMeta,
+  normalizeRuntimeSessionForExecutionV0,
+  resolvePhaseSteps,
+  setSourceTrace,
+  validateManifestSessionDefaultsContract,
+  validatePhaseBoundaryCompatibility,
+  validateStepShape,
+  validateUniqueStepIds,
+  cloneJson,
+} from './execution-v0-contract-helpers.js';
+import {
+  buildInlineKernelPath,
+  buildLayerPipelineFromExecution,
+  buildModelRuntimeOverrides,
+  buildSessionRuntimePatch,
+  resolveFinitenessFallbackKernelPathId,
+} from './execution-v0-runtime-builders.js';
 
 export function hasExecutionV0(manifestInference) {
   return !!manifestInference?.execution && Array.isArray(manifestInference.execution.steps);
@@ -1013,6 +43,7 @@ export function compileExecutionV0(options = {}) {
     return null;
   }
   assertExecutionV0Schema(manifestInference);
+  validateManifestSessionDefaultsContract(manifestInference);
 
   const modelId = options.modelId ?? 'model';
   const numLayers = Number.isInteger(options.numLayers) ? options.numLayers : 0;
@@ -1024,7 +55,8 @@ export function compileExecutionV0(options = {}) {
   };
   const normalizedRuntimeSession = normalizeRuntimeSessionForExecutionV0(
     runtimeInference.session ?? {},
-    manifestInference
+    manifestInference,
+    DEFAULT_EXECUTION_V0_COMPUTE_DEFAULTS
   );
   const sessionDefaults = mergeRuntimeValues(
     DEFAULT_EXECUTION_V0_SESSION_DEFAULTS,
@@ -1107,7 +139,19 @@ export function compileExecutionV0(options = {}) {
     ...resolvedDecodeSteps.filter((step) => step.phase === 'decode'),
   ];
 
-  const kernelPath = buildInlineKernelPath(patchedSteps, resolvedSession, modelId, numLayers);
+  const defaultKernelPathId = typeof manifestInference.defaultKernelPath === 'string'
+    && manifestInference.defaultKernelPath.trim().length > 0
+    ? manifestInference.defaultKernelPath.trim()
+    : null;
+  const finitenessFallbackKernelPathId = resolveFinitenessFallbackKernelPathId(defaultKernelPathId);
+
+  const kernelPath = buildInlineKernelPath(
+    patchedSteps,
+    resolvedSession,
+    modelId,
+    numLayers,
+    finitenessFallbackKernelPathId
+  );
   const layerPipeline = buildLayerPipelineFromExecution(resolvedSteps);
   const sessionPatch = buildSessionRuntimePatch(resolvedSession);
   const modelOverrides = buildModelRuntimeOverrides(manifestInference);
@@ -1144,13 +188,23 @@ export function applyExecutionV0RuntimeConfig(options = {}) {
   }
 
   const runtimeInference = runtimeConfig.inference ?? {};
+  const kernelPathExecution = runtimeInference.kernelPath !== undefined
+    ? buildExecutionV0FromKernelPath(runtimeInference.kernelPath)
+    : null;
+  const manifestInference = kernelPathExecution
+    ? {
+      ...manifest.inference,
+      ...kernelPathExecution,
+      defaultKernelPath: runtimeInference.kernelPath,
+    }
+    : manifest.inference;
   const runtimeExecutionOverlay = {
     ...(runtimeInference.session ? { session: runtimeInference.session } : {}),
     ...(runtimeInference.executionPatch ? { executionPatch: runtimeInference.executionPatch } : {}),
   };
 
   const executionV0State = compileExecutionV0({
-    manifestInference: manifest.inference,
+    manifestInference,
     runtimeInference: runtimeExecutionOverlay,
     modelId: options.modelId ?? manifest.modelId ?? 'model',
     numLayers: Number.isInteger(options.numLayers)
@@ -1161,13 +215,35 @@ export function applyExecutionV0RuntimeConfig(options = {}) {
     return { runtimeConfig, executionV0State: null };
   }
 
+  const compiledKernelPathSource = runtimeInference.kernelPath !== undefined
+    ? 'config'
+    : 'manifest';
   const runtimeInferencePatch = { ...executionV0State.runtimeInferencePatch };
+  if (runtimeInferencePatch.kernelPathSource) {
+    runtimeInferencePatch.kernelPathSource = compiledKernelPathSource;
+  }
+  if (runtimeInference.kernelPath !== undefined) {
+    delete runtimeInferencePatch.kernelPath;
+    delete runtimeInferencePatch.kernelPathSource;
+  }
   if (runtimeInferencePatch.modelOverrides) {
     runtimeInferencePatch.modelOverrides = mergeRuntimeValues(
       runtimeInferencePatch.modelOverrides,
       runtimeInference.modelOverrides ?? {}
     );
   }
+  if (runtimeInference.kernelPath !== undefined && runtimeInference.compute) {
+    runtimeInferencePatch.compute = mergeRuntimeValues(
+      runtimeInferencePatch.compute ?? {},
+      runtimeInference.compute
+    );
+  }
+  if (runtimeInference.kernelPath !== undefined && runtimeInference.kvcache) {
+    runtimeInferencePatch.kvcache = mergeRuntimeValues(
+      runtimeInferencePatch.kvcache ?? {},
+      runtimeInference.kvcache
+    );
+  }
 
   return {
     runtimeConfig: {