@simulatte/doppler 0.1.3 → 0.1.5

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

@@ -0,0 +1,317 @@
+import { DEFAULT_BATCHING_DEFAULTS, DEFAULT_GENERATION_CONFIG } from './schema/inference-defaults.schema.js';
+import { buildExecutionV0ContractArtifact } from './execution-v0-contract-check.js';
+import { buildExecutionV0GraphContractArtifact } from './execution-v0-graph-contract-check.js';
+import { EXECUTION_V0_SCHEMA_ID } from './schema/execution-v0.schema.js';
+import { DEFAULT_KVCACHE_CONFIG } from './schema/kvcache.schema.js';
+
+const KV_LAYOUTS = new Set(['contiguous', 'paged', 'tiered', 'bdpa']);
+const PHASES = new Set(['prefill', 'decode', 'both']);
+const COLD_QUANT_MODES = new Set(['none', 'int8', 'int4']);
+const ATTENTION_OPS = new Set(['attention']);
+const EMBED_OPS = new Set(['embed', 'gather']);
+const SAMPLE_OPS = new Set(['sample']);
+const BDPA_MAX_HEAD_DIM = 256;
+const BDPA_MAX_KV_LEN = 2048;
+const TIERED_MAX_QUANT_HEAD_DIM = 256;
+
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertManifestObject(manifest) {
+  if (!isPlainObject(manifest)) {
+    throw new Error('execution contract: manifest must be an object.');
+  }
+  return manifest;
+}
+
+function assertPositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`execution contract: ${label} must be a non-negative integer.`);
+  }
+  return value;
+}
+
+function assertPositiveIntegerOrDefault(value, fallback, label) {
+  if (value == null) {
+    return assertPositiveInteger(fallback, `${label} fallback`);
+  }
+  return assertPositiveInteger(value, label);
+}
+
+function normalizeKVLayout(value) {
+  const normalized = String(value ?? DEFAULT_KVCACHE_CONFIG.layout).trim().toLowerCase();
+  if (!KV_LAYOUTS.has(normalized)) {
+    throw new Error(
+      `execution contract: unsupported KV layout "${value}". ` +
+      `Expected one of ${[...KV_LAYOUTS].join(', ')}.`
+    );
+  }
+  return normalized;
+}
+
+function normalizePhase(value, label) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!PHASES.has(normalized)) {
+    throw new Error(
+      `execution contract: ${label} must be one of ${[...PHASES].join(', ')}.`
+    );
+  }
+  return normalized;
+}
+
+function normalizeColdQuantMode(kvcache) {
+  const tieringMode = String(
+    kvcache?.tiering?.mode
+      ?? DEFAULT_KVCACHE_CONFIG.tiering.mode
+  ).trim().toLowerCase();
+  if (tieringMode === 'off' || tieringMode === 'fp16') {
+    return 'none';
+  }
+  if (!COLD_QUANT_MODES.has(tieringMode)) {
+    throw new Error(
+      `execution contract: unsupported tiered cold quant mode "${tieringMode}".`
+    );
+  }
+  return tieringMode;
+}
+
+function classifyOp(op) {
+  const normalized = String(op ?? '').trim().toLowerCase();
+  if (!normalized) {
+    throw new Error('execution contract: execution step op is required.');
+  }
+  if (ATTENTION_OPS.has(normalized)) return 'attention';
+  if (EMBED_OPS.has(normalized)) return 'embed';
+  if (SAMPLE_OPS.has(normalized)) return 'sample';
+  if (normalized.includes('norm')) return 'norm';
+  if (normalized.includes('residual')) return 'residual';
+  if (normalized.endsWith('_proj') || normalized.startsWith('rope_') || normalized === 'activation') {
+    return 'projection';
+  }
+  return 'other';
+}
+
+export function sanitizeLeanModuleName(value) {
+  const raw = String(value ?? 'GeneratedExecutionContractCheck').trim();
+  const alnum = raw.replace(/[^A-Za-z0-9_]/g, '_');
+  if (!alnum) {
+    return 'GeneratedExecutionContractCheck';
+  }
+  if (/^[A-Za-z_]/.test(alnum)) {
+    return alnum;
+  }
+  return `Generated_${alnum}`;
+}
+
+export function extractExecutionContractFacts(manifest) {
+  const normalizedManifest = assertManifestObject(manifest);
+  const modelId = String(normalizedManifest.modelId ?? 'model').trim() || 'model';
+  const architecture = isPlainObject(normalizedManifest.architecture)
+    ? normalizedManifest.architecture
+    : {};
+  const inference = isPlainObject(normalizedManifest.inference)
+    ? normalizedManifest.inference
+    : {};
+  const sessionDefaults = isPlainObject(inference.sessionDefaults)
+    ? inference.sessionDefaults
+    : {};
+  const execution = isPlainObject(inference.execution)
+    ? inference.execution
+    : {};
+  const kvcache = isPlainObject(sessionDefaults.kvcache)
+    ? sessionDefaults.kvcache
+    : {};
+  const decodeLoop = isPlainObject(sessionDefaults.decodeLoop)
+    ? sessionDefaults.decodeLoop
+    : {};
+
+  const steps = Array.isArray(execution.steps)
+    ? execution.steps.map((step, index) => {
+      if (!isPlainObject(step)) {
+        throw new Error(`execution contract: execution.steps[${index}] must be an object.`);
+      }
+      const id = String(step.id ?? '').trim();
+      if (!id) {
+        throw new Error(`execution contract: execution.steps[${index}].id is required.`);
+      }
+      return {
+        id,
+        phase: normalizePhase(step.phase, `execution.steps[${index}].phase`),
+        opClass: classifyOp(step.op),
+      };
+    })
+    : [];
+
+  return {
+    modelId,
+    session: {
+      layout: normalizeKVLayout(kvcache.layout),
+      disableCommandBatching: decodeLoop.disableCommandBatching
+        ?? DEFAULT_GENERATION_CONFIG.disableCommandBatching,
+      decodeBatchSize: assertPositiveIntegerOrDefault(
+        decodeLoop.batchSize,
+        DEFAULT_BATCHING_DEFAULTS.batchSize,
+        'sessionDefaults.decodeLoop.batchSize'
+      ),
+      headDim: assertPositiveInteger(architecture.headDim, 'architecture.headDim'),
+      kvLen: assertPositiveIntegerOrDefault(
+        architecture.maxSeqLen ?? kvcache.maxSeqLen,
+        DEFAULT_KVCACHE_CONFIG.maxSeqLen,
+        'architecture.maxSeqLen'
+      ),
+      coldQuantMode: normalizeColdQuantMode(kvcache),
+    },
+    steps,
+  };
+}
+
+export function validateExecutionContractFacts(facts) {
+  const errors = [];
+  const checks = [];
+  const modelId = String(facts?.modelId ?? 'model');
+  const session = facts?.session ?? {};
+  const steps = Array.isArray(facts?.steps) ? facts.steps : [];
+
+  const incompatibleStep = session.layout === 'bdpa'
+    ? steps.find((step) => step.opClass === 'attention' && (step.phase === 'prefill' || step.phase === 'both'))
+    : null;
+  if (incompatibleStep) {
+    errors.push(
+      `[ExecutionContract] sessionDefaults.kvcache.layout="bdpa" is decode-only, ` +
+      `but step "${incompatibleStep.id}" declares ${incompatibleStep.phase} attention.`
+    );
+  }
+  checks.push({
+    id: `${modelId}.steps`,
+    ok: incompatibleStep == null,
+  });
+
+  const sessionErrorCount = errors.length;
+  if (session.layout === 'bdpa') {
+    if (session.disableCommandBatching !== true) {
+      errors.push(
+        '[ExecutionContract] sessionDefaults.kvcache.layout="bdpa" requires ' +
+        'sessionDefaults.decodeLoop.disableCommandBatching=true.'
+      );
+    }
+    if (session.decodeBatchSize > 1) {
+      errors.push(
+        `[ExecutionContract] sessionDefaults.kvcache.layout="bdpa" requires ` +
+        `sessionDefaults.decodeLoop.batchSize <= 1; got ${session.decodeBatchSize}.`
+      );
+    }
+    if (session.headDim > BDPA_MAX_HEAD_DIM) {
+      errors.push(
+        `[ExecutionContract] sessionDefaults.kvcache.layout="bdpa" requires architecture.headDim <= ${BDPA_MAX_HEAD_DIM}; ` +
+        `got ${session.headDim}.`
+      );
+    }
+    if (session.kvLen > BDPA_MAX_KV_LEN) {
+      errors.push(
+        `[ExecutionContract] sessionDefaults.kvcache.layout="bdpa" requires architecture.maxSeqLen <= ${BDPA_MAX_KV_LEN}; ` +
+        `got ${session.kvLen}.`
+      );
+    }
+  }
+
+  if (
+    session.layout === 'tiered'
+    && session.coldQuantMode !== 'none'
+    && session.headDim > TIERED_MAX_QUANT_HEAD_DIM
+  ) {
+    errors.push(
+      `[ExecutionContract] sessionDefaults.kvcache.layout="tiered" with cold quantization requires ` +
+      `architecture.headDim <= ${TIERED_MAX_QUANT_HEAD_DIM}; got ${session.headDim}.`
+    );
+  }
+
+  checks.push({
+    id: `${modelId}.session`,
+    ok: errors.length === sessionErrorCount,
+  });
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    checks,
+  };
+}
+
+export function validateManifestExecutionContract(manifest) {
+  const facts = extractExecutionContractFacts(manifest);
+  const evaluation = validateExecutionContractFacts(facts);
+  return {
+    ...evaluation,
+    facts,
+  };
+}
+
+export function buildExecutionContractArtifact(manifest) {
+  if (!manifest || typeof manifest !== 'object') {
+    return null;
+  }
+  if (manifest.modelType === 'diffusion' || manifest.modelType === 'energy') {
+    return null;
+  }
+  if (!manifest.architecture || !manifest.inference || typeof manifest.inference !== 'object') {
+    return null;
+  }
+  try {
+    const evaluation = validateManifestExecutionContract(manifest);
+    const attentionPhaseCounts = { prefill: 0, decode: 0, both: 0 };
+    for (const step of evaluation.facts.steps) {
+      if (step.opClass !== 'attention') continue;
+      if (Object.prototype.hasOwnProperty.call(attentionPhaseCounts, step.phase)) {
+        attentionPhaseCounts[step.phase] += 1;
+      }
+    }
+    const executionV0 =
+      manifest?.inference?.schema === EXECUTION_V0_SCHEMA_ID
+        ? {
+            kernelProfiles: buildExecutionV0ContractArtifact(manifest.inference, {
+              modelId: evaluation.facts.modelId,
+            }),
+            graph: buildExecutionV0GraphContractArtifact({
+              modelId: evaluation.facts.modelId,
+              numLayers: manifest?.architecture?.numLayers,
+              manifestInference: manifest.inference,
+            }),
+          }
+        : null;
+    const nestedChecks = [];
+    const nestedErrors = [];
+    if (executionV0?.kernelProfiles) {
+      nestedChecks.push(...executionV0.kernelProfiles.checks);
+      nestedErrors.push(...executionV0.kernelProfiles.errors);
+    }
+    if (executionV0?.graph) {
+      nestedChecks.push(...executionV0.graph.checks);
+      nestedErrors.push(...executionV0.graph.errors);
+    }
+    return {
+      schemaVersion: 1,
+      source: 'doppler',
+      ok: evaluation.ok && nestedErrors.length === 0,
+      checks: [...evaluation.checks, ...nestedChecks],
+      errors: [...evaluation.errors, ...nestedErrors],
+      session: evaluation.facts.session,
+      steps: {
+        total: evaluation.facts.steps.length,
+        attention: attentionPhaseCounts.prefill + attentionPhaseCounts.decode + attentionPhaseCounts.both,
+        attentionPhases: attentionPhaseCounts,
+      },
+      ...(executionV0 ? { executionV0 } : {}),
+    };
+  } catch (error) {
+    return {
+      schemaVersion: 1,
+      source: 'doppler',
+      ok: false,
+      checks: [],
+      errors: [error instanceof Error ? error.message : String(error)],
+      session: null,
+      steps: null,
+    };
+  }
+}

package/src/config/execution-v0-contract-check.d.ts

@@ -0,0 +1,94 @@
+import type {
+  ExecutionV0ComputeDefaultsSchema,
+  ExecutionV0KernelProfileSchema,
+  ExecutionV0KernelRefSchema,
+  ExecutionV0KVIO,
+  ExecutionV0PrecisionSchema,
+  ExecutionV0SessionDefaultsSchema,
+  ExecutionV0StepSchema,
+} from './schema/execution-v0.schema.js';
+
+export interface ExecutionV0ContractCheckResult {
+  id: string;
+  ok: boolean;
+}
+
+export interface ExecutionV0ContractPerStep {
+  precision: {
+    inputDtype: string | null;
+    mathDtype: string | null;
+    accumDtype: string | null;
+    outputDtype: string | null;
+  };
+  precisionSources: {
+    inputDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    mathDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    accumDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    outputDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+  };
+  resolvedPrecision?: {
+    inputDtype: 'f16' | 'f32' | null;
+    mathDtype: 'f16' | 'f32';
+    accumDtype: 'f16' | 'f32';
+    outputDtype: 'f16' | 'f32';
+  };
+  kvIO?: ExecutionV0KVIO;
+  kvIOSource?: 'manifest' | 'kernelProfile' | 'sessionDefault';
+}
+
+export interface ExecutionV0ContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: ExecutionV0ContractCheckResult[];
+  errors: string[];
+  stats: {
+    kernelProfiles: number;
+    pinnedSteps: number;
+  };
+  perStep: Record<string, ExecutionV0ContractPerStep>;
+}
+
+export declare function normalizeExecutionV0Dtype(value: unknown, label: string): 'f16' | 'f32';
+export declare function buildExecutionV0KernelProfileKey(
+  kernelRef: ExecutionV0KernelRefSchema | null | undefined
+): string | null;
+export declare function indexExecutionV0KernelProfiles(
+  sessionDefaults?: Partial<ExecutionV0SessionDefaultsSchema> | null
+): Map<string, ExecutionV0KernelProfileSchema>;
+export declare function resolveExecutionV0KernelProfile(
+  profileIndex: Map<string, ExecutionV0KernelProfileSchema>,
+  step: Partial<ExecutionV0StepSchema>
+): ExecutionV0KernelProfileSchema | null;
+export declare function resolveExecutionV0Precision(
+  step: Partial<ExecutionV0StepSchema>,
+  profile: ExecutionV0KernelProfileSchema | null,
+  sessionDefaults?: Partial<ExecutionV0SessionDefaultsSchema> | null
+): {
+  precision: {
+    inputDtype: 'f16' | 'f32' | null;
+    mathDtype: 'f16' | 'f32';
+    accumDtype: 'f16' | 'f32';
+    outputDtype: 'f16' | 'f32';
+  };
+  sources: {
+    inputDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    mathDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    accumDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+    outputDtype: 'manifest' | 'kernelProfile' | 'sessionDefault' | 'derived';
+  };
+};
+export declare function resolveExecutionV0KVIO(
+  step: Partial<ExecutionV0StepSchema>,
+  profile: ExecutionV0KernelProfileSchema | null,
+  sessionDefaults?: Partial<ExecutionV0SessionDefaultsSchema> | null
+): {
+  value: ExecutionV0KVIO;
+  source: 'manifest' | 'kernelProfile' | 'sessionDefault';
+};
+export declare function buildExecutionV0ContractArtifact(
+  manifestInference: Record<string, unknown> | null | undefined,
+  options?: {
+    modelId?: string;
+  }
+): ExecutionV0ContractArtifact | null;

package/src/config/execution-v0-contract-check.js

@@ -0,0 +1,251 @@
+import {
+  DEFAULT_EXECUTION_V0_COMPUTE_DEFAULTS,
+  isExecutionV0Digest,
+  isExecutionV0Semver,
+} from './schema/execution-v0.schema.js';
+
+function normalizeDtype(value, label) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (normalized !== 'f16' && normalized !== 'f32') {
+    throw new Error(`[ExecutionV0Contract] ${label} must be "f16" or "f32"; got "${value}"`);
+  }
+  return normalized;
+}
+
+function buildKernelProfileKey(kernelRef) {
+  if (!kernelRef) return null;
+  return `${kernelRef.id}|${kernelRef.version}|${kernelRef.digest}`;
+}
+
+function assertExecutionV0KernelRef(kernelRef, label) {
+  if (!kernelRef || typeof kernelRef !== 'object' || Array.isArray(kernelRef)) {
+    throw new Error(`[ExecutionV0Contract] ${label} is required.`);
+  }
+  if (typeof kernelRef.id !== 'string' || kernelRef.id.trim().length === 0) {
+    throw new Error(`[ExecutionV0Contract] ${label}.id is required.`);
+  }
+  if (!isExecutionV0Semver(kernelRef.version)) {
+    throw new Error(`[ExecutionV0Contract] ${label}.version must be semver.`);
+  }
+  if (!isExecutionV0Digest(kernelRef.digest)) {
+    throw new Error(`[ExecutionV0Contract] ${label}.digest must match sha256:<64-hex>.`);
+  }
+}
+
+function createPrecisionSources(step, profile) {
+  return {
+    inputDtype: step.precision?.inputDtype != null
+      ? 'manifest'
+      : profile?.precision?.inputDtype != null
+        ? 'kernelProfile'
+        : 'derived',
+    mathDtype: step.precision?.mathDtype != null
+      ? 'manifest'
+      : profile?.precision?.mathDtype != null
+        ? 'kernelProfile'
+        : 'sessionDefault',
+    accumDtype: step.precision?.accumDtype != null
+      ? 'manifest'
+      : profile?.precision?.accumDtype != null
+        ? 'kernelProfile'
+        : 'sessionDefault',
+    outputDtype: step.precision?.outputDtype != null
+      ? 'manifest'
+      : profile?.precision?.outputDtype != null
+        ? 'kernelProfile'
+        : 'sessionDefault',
+  };
+}
+
+export function normalizeExecutionV0Dtype(value, label) {
+  return normalizeDtype(value, label);
+}
+
+export function buildExecutionV0KernelProfileKey(kernelRef) {
+  return buildKernelProfileKey(kernelRef);
+}
+
+export function indexExecutionV0KernelProfiles(sessionDefaults = {}) {
+  const byKey = new Map();
+  const profiles = sessionDefaults?.compute?.kernelProfiles ?? [];
+  for (const profile of profiles) {
+    assertExecutionV0KernelRef(profile?.kernelRef, 'sessionDefaults.compute.kernelProfiles[].kernelRef');
+    const key = buildKernelProfileKey(profile?.kernelRef);
+    if (byKey.has(key)) {
+      throw new Error(
+        `[ExecutionV0Contract] duplicate kernel profile for ${profile.kernelRef.id}@${profile.kernelRef.version} ` +
+        `(${profile.kernelRef.digest}). Expected exactly one pinned profile per kernelRef.`
+      );
+    }
+    byKey.set(key, profile);
+  }
+  return byKey;
+}
+
+export function resolveExecutionV0KernelProfile(profileIndex, step) {
+  const key = buildKernelProfileKey(step?.kernelRef);
+  if (!key) return null;
+  return profileIndex.get(key) ?? null;
+}
+
+export function resolveExecutionV0Precision(step, profile, sessionDefaults = {}) {
+  const defaults = {
+    ...DEFAULT_EXECUTION_V0_COMPUTE_DEFAULTS,
+    ...(sessionDefaults?.compute?.defaults ?? {}),
+  };
+  const precision = {
+    inputDtype: step.precision?.inputDtype
+      ?? profile?.precision?.inputDtype
+      ?? null,
+    mathDtype: step.precision?.mathDtype
+      ?? profile?.precision?.mathDtype
+      ?? defaults.mathDtype,
+    accumDtype: step.precision?.accumDtype
+      ?? profile?.precision?.accumDtype
+      ?? defaults.accumDtype,
+    outputDtype: step.precision?.outputDtype
+      ?? profile?.precision?.outputDtype
+      ?? defaults.outputDtype,
+  };
+  return {
+    precision,
+    sources: createPrecisionSources(step, profile),
+  };
+}
+
+export function resolveExecutionV0KVIO(step, profile, sessionDefaults = {}) {
+  if (step.kvIO) {
+    return {
+      value: {
+        readDtype: normalizeDtype(step.kvIO.readDtype, `${step.id}.kvIO.readDtype`),
+        writeDtype: normalizeDtype(step.kvIO.writeDtype, `${step.id}.kvIO.writeDtype`),
+      },
+      source: 'manifest',
+    };
+  }
+  if (profile?.kvIO) {
+    return {
+      value: {
+        readDtype: normalizeDtype(profile.kvIO.readDtype, `${step.id}.profile.kvIO.readDtype`),
+        writeDtype: normalizeDtype(profile.kvIO.writeDtype, `${step.id}.profile.kvIO.writeDtype`),
+      },
+      source: 'kernelProfile',
+    };
+  }
+  const defaults = {
+    ...DEFAULT_EXECUTION_V0_COMPUTE_DEFAULTS,
+    ...(sessionDefaults?.compute?.defaults ?? {}),
+  };
+  const kvDtype = normalizeDtype(
+    sessionDefaults?.kvcache?.kvDtype ?? defaults.activationDtype,
+    `${step.id}.sessionDefaults.kvcache.kvDtype`
+  );
+  return {
+    value: { readDtype: kvDtype, writeDtype: kvDtype },
+    source: 'sessionDefault',
+  };
+}
+
+export function buildExecutionV0ContractArtifact(manifestInference, options = {}) {
+  if (!manifestInference?.execution || !Array.isArray(manifestInference.execution.steps)) {
+    return null;
+  }
+
+  const modelId = String(options.modelId ?? 'model');
+  const checks = [];
+  const errors = [];
+  const perStep = {};
+  const sessionDefaults = manifestInference.sessionDefaults ?? {};
+  let profileIndex;
+
+  try {
+    profileIndex = indexExecutionV0KernelProfiles(sessionDefaults);
+  } catch (error) {
+    errors.push(error instanceof Error ? error.message : String(error));
+    checks.push({ id: `${modelId}.kernelProfilePinning`, ok: false });
+    checks.push({ id: `${modelId}.precisionPrecedence`, ok: false });
+    checks.push({ id: `${modelId}.kvIOPrecedence`, ok: false });
+    return {
+      schemaVersion: 1,
+      source: 'doppler',
+      ok: false,
+      checks,
+      errors,
+      stats: {
+        kernelProfiles: sessionDefaults?.compute?.kernelProfiles?.length ?? 0,
+        pinnedSteps: 0,
+      },
+      perStep,
+    };
+  }
+
+  let pinningOk = true;
+  let precisionOk = true;
+  let kvOk = true;
+  let pinnedSteps = 0;
+
+  for (const step of manifestInference.execution.steps) {
+    if (!step || typeof step !== 'object') continue;
+    if (step.op === 'cast') continue;
+    if (!step.kernelRef) {
+      pinningOk = false;
+      precisionOk = false;
+      errors.push(`[ExecutionV0Contract] step "${step.id ?? 'unknown'}" requires kernelRef.`);
+      continue;
+    }
+    const profile = resolveExecutionV0KernelProfile(profileIndex, step);
+    if (!profile) {
+      pinningOk = false;
+      precisionOk = false;
+      errors.push(
+        `[ExecutionV0Contract] step "${step.id ?? 'unknown'}" kernelRef ` +
+        `${step.kernelRef.id}@${step.kernelRef.version} (${step.kernelRef.digest}) is unresolved.`
+      );
+      continue;
+    }
+    pinnedSteps += 1;
+    const { precision, sources } = resolveExecutionV0Precision(step, profile, sessionDefaults);
+    perStep[step.id] = {
+      precision,
+      precisionSources: sources,
+    };
+    try {
+      perStep[step.id].resolvedPrecision = {
+        inputDtype: precision.inputDtype == null ? null : normalizeDtype(precision.inputDtype, `${step.id}.precision.inputDtype`),
+        mathDtype: normalizeDtype(precision.mathDtype, `${step.id}.precision.mathDtype`),
+        accumDtype: normalizeDtype(precision.accumDtype, `${step.id}.precision.accumDtype`),
+        outputDtype: normalizeDtype(precision.outputDtype, `${step.id}.precision.outputDtype`),
+      };
+    } catch (error) {
+      precisionOk = false;
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+    if (step.op === 'attention') {
+      try {
+        const kvIO = resolveExecutionV0KVIO(step, profile, sessionDefaults);
+        perStep[step.id].kvIO = kvIO.value;
+        perStep[step.id].kvIOSource = kvIO.source;
+      } catch (error) {
+        kvOk = false;
+        errors.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  checks.push({ id: `${modelId}.kernelProfilePinning`, ok: pinningOk });
+  checks.push({ id: `${modelId}.precisionPrecedence`, ok: precisionOk });
+  checks.push({ id: `${modelId}.kvIOPrecedence`, ok: kvOk });
+
+  return {
+    schemaVersion: 1,
+    source: 'doppler',
+    ok: errors.length === 0,
+    checks,
+    errors,
+    stats: {
+      kernelProfiles: sessionDefaults?.compute?.kernelProfiles?.length ?? 0,
+      pinnedSteps,
+    },
+    perStep,
+  };
+}

package/src/config/execution-v0-graph-contract-check.d.ts

@@ -0,0 +1,20 @@
+export interface ExecutionV0GraphContractCheckResult {
+  id: string;
+  ok: boolean;
+}
+
+export interface ExecutionV0GraphContractArtifact {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: ExecutionV0GraphContractCheckResult[];
+  errors: string[];
+  stats: {
+    prefillSteps: number;
+    decodeSteps: number;
+  };
+}
+
+export declare function buildExecutionV0GraphContractArtifact(
+  options?: Record<string, unknown>
+): ExecutionV0GraphContractArtifact | null;