@simulatte/doppler 0.1.4 → 0.1.6

package/src/rules/layer-pattern-contract-check.js

@@ -0,0 +1,231 @@
+import { selectByRules } from '../gpu/kernels/rule-matcher.js';
+import { computeGlobalLayers } from '../config/schema/inference.schema.js';
+
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function matchesExactObject(actual, expected) {
+  if (!isPlainObject(actual) || !isPlainObject(expected)) {
+    return false;
+  }
+  const actualKeys = Object.keys(actual).sort();
+  const expectedKeys = Object.keys(expected).sort();
+  if (actualKeys.length !== expectedKeys.length) {
+    return false;
+  }
+  for (let i = 0; i < actualKeys.length; i += 1) {
+    if (actualKeys[i] !== expectedKeys[i]) {
+      return false;
+    }
+  }
+  for (const key of expectedKeys) {
+    const expectedValue = expected[key];
+    const actualValue = actual[key];
+    if (isPlainObject(expectedValue)) {
+      if (!matchesExactObject(actualValue, expectedValue)) {
+        return false;
+      }
+      continue;
+    }
+    if (actualValue !== expectedValue) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function expectedPatternKind(context) {
+  if (context.patternType === 'alternating' && context.globalPattern === 'even') {
+    return 'alternating_even';
+  }
+  if (context.patternType === 'alternating' && context.globalPattern === 'odd') {
+    return 'alternating_odd';
+  }
+  if (context.patternType === 'every_n') {
+    return 'every_n';
+  }
+  return null;
+}
+
+function expectedLayerType(context) {
+  if (context.patternKind === 'alternating_even') {
+    return context.isEven ? 'full_attention' : 'sliding_attention';
+  }
+  if (context.patternKind === 'alternating_odd') {
+    return context.isEven ? 'sliding_attention' : 'full_attention';
+  }
+  if (context.patternKind === 'every_n') {
+    return context.isStride ? 'full_attention' : 'sliding_attention';
+  }
+  return null;
+}
+
+function enumeratePatternKindContexts() {
+  const patternTypes = ['alternating', 'every_n', 'custom', null];
+  const globalPatterns = ['even', 'odd', 'every_n', null];
+  const contexts = [];
+  for (const patternType of patternTypes) {
+    for (const globalPattern of globalPatterns) {
+      contexts.push({ patternType, globalPattern });
+    }
+  }
+  return contexts;
+}
+
+function enumerateLayerTypeContexts() {
+  const patternKinds = ['alternating_even', 'alternating_odd', 'every_n'];
+  const booleans = [true, false];
+  const contexts = [];
+  for (const patternKind of patternKinds) {
+    for (const isEven of booleans) {
+      for (const isStride of booleans) {
+        contexts.push({ patternKind, isEven, isStride });
+      }
+    }
+  }
+  return contexts;
+}
+
+function checkRuleShape(rules, expected, label) {
+  if (!Array.isArray(rules)) {
+    return {
+      ok: false,
+      errors: [`[LayerPatternContract] ${label} must be an array.`],
+    };
+  }
+  if (rules.length !== expected.length) {
+    return {
+      ok: false,
+      errors: [`[LayerPatternContract] ${label} must contain exactly ${expected.length} rules; got ${rules.length}.`],
+    };
+  }
+  const errors = [];
+  for (let i = 0; i < expected.length; i += 1) {
+    if (!matchesExactObject(rules[i]?.match, expected[i].match) || rules[i]?.value !== expected[i].value) {
+      errors.push(`[LayerPatternContract] ${label} rule[${i}] drifted from the expected decision table.`);
+      break;
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+function checkRuleSemantics(rules, contexts, expectedValue, label) {
+  const errors = [];
+  for (const context of contexts) {
+    const actual = selectByRules(rules, context);
+    const expected = expectedValue(context);
+    if (actual !== expected) {
+      errors.push(
+        `[LayerPatternContract] ${label} mismatched context ${JSON.stringify(context)}: ` +
+        `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}.`
+      );
+      break;
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+    sampledContexts: contexts.length,
+  };
+}
+
+function checkGlobalLayerSemantics() {
+  const checks = [
+    {
+      id: 'inference.layerPattern.computeGlobalLayers.even',
+      actual: computeGlobalLayers({ type: 'alternating', globalPattern: 'even' }, 6),
+      expected: [0, 2, 4],
+    },
+    {
+      id: 'inference.layerPattern.computeGlobalLayers.odd',
+      actual: computeGlobalLayers({ type: 'alternating', globalPattern: 'odd' }, 6),
+      expected: [1, 3, 5],
+    },
+    {
+      id: 'inference.layerPattern.computeGlobalLayers.every_n_offset',
+      actual: computeGlobalLayers({ type: 'every_n', period: 6, offset: 5 }, 12),
+      expected: [5, 11],
+    },
+    {
+      id: 'inference.layerPattern.computeGlobalLayers.every_n_negative_offset',
+      actual: computeGlobalLayers({ type: 'every_n', period: 6, offset: -1 }, 12),
+      expected: [5, 11],
+    },
+  ];
+  const errors = [];
+  const results = [];
+  for (const entry of checks) {
+    const ok = JSON.stringify(entry.actual) === JSON.stringify(entry.expected);
+    results.push({ id: entry.id, ok });
+    if (!ok) {
+      errors.push(
+        `[LayerPatternContract] ${entry.id} expected ${JSON.stringify(entry.expected)}, got ${JSON.stringify(entry.actual)}.`
+      );
+    }
+  }
+  return {
+    checks: results,
+    errors,
+  };
+}
+
+export function buildLayerPatternContractArtifact(ruleGroup) {
+  const errors = [];
+  const checks = [];
+  const patternKindRules = ruleGroup?.patternKind;
+  const layerTypeRules = ruleGroup?.layerType;
+
+  const patternKindShape = checkRuleShape(patternKindRules, [
+    { match: { patternType: 'alternating', globalPattern: 'even' }, value: 'alternating_even' },
+    { match: { patternType: 'alternating', globalPattern: 'odd' }, value: 'alternating_odd' },
+    { match: { patternType: 'every_n' }, value: 'every_n' },
+    { match: {}, value: null },
+  ], 'patternKind');
+  errors.push(...patternKindShape.errors);
+  checks.push({ id: 'inference.layerPattern.patternKind.shape', ok: patternKindShape.ok });
+
+  const patternKindSemantics = Array.isArray(patternKindRules)
+    ? checkRuleSemantics(patternKindRules, enumeratePatternKindContexts(), expectedPatternKind, 'patternKind')
+    : { ok: false, errors: ['[LayerPatternContract] patternKind is unavailable for semantic check.'], sampledContexts: 0 };
+  errors.push(...patternKindSemantics.errors);
+  checks.push({ id: 'inference.layerPattern.patternKind.semantics', ok: patternKindSemantics.ok });
+
+  const layerTypeShape = checkRuleShape(layerTypeRules, [
+    { match: { patternKind: 'alternating_even', isEven: true }, value: 'full_attention' },
+    { match: { patternKind: 'alternating_even' }, value: 'sliding_attention' },
+    { match: { patternKind: 'alternating_odd', isEven: false }, value: 'full_attention' },
+    { match: { patternKind: 'alternating_odd' }, value: 'sliding_attention' },
+    { match: { patternKind: 'every_n', isStride: true }, value: 'full_attention' },
+    { match: { patternKind: 'every_n' }, value: 'sliding_attention' },
+  ], 'layerType');
+  errors.push(...layerTypeShape.errors);
+  checks.push({ id: 'inference.layerPattern.layerType.shape', ok: layerTypeShape.ok });
+
+  const layerTypeSemantics = Array.isArray(layerTypeRules)
+    ? checkRuleSemantics(layerTypeRules, enumerateLayerTypeContexts(), expectedLayerType, 'layerType')
+    : { ok: false, errors: ['[LayerPatternContract] layerType is unavailable for semantic check.'], sampledContexts: 0 };
+  errors.push(...layerTypeSemantics.errors);
+  checks.push({ id: 'inference.layerPattern.layerType.semantics', ok: layerTypeSemantics.ok });
+
+  const globalLayerSemantics = checkGlobalLayerSemantics();
+  errors.push(...globalLayerSemantics.errors);
+  checks.push(...globalLayerSemantics.checks);
+
+  return {
+    schemaVersion: 1,
+    source: 'doppler',
+    ok: errors.length === 0,
+    checks,
+    errors,
+    stats: {
+      patternKindRules: Array.isArray(patternKindRules) ? patternKindRules.length : 0,
+      layerTypeRules: Array.isArray(layerTypeRules) ? layerTypeRules.length : 0,
+      patternKindContexts: patternKindSemantics.sampledContexts,
+      layerTypeContexts: layerTypeSemantics.sampledContexts,
+    },
+  };
+}

package/src/rules/rule-registry.d.ts

@@ -46,3 +46,31 @@ export declare function registerRuleGroup(
   group: RuleGroup,
   rules: Record<string, RuleSet>
 ): void;
+
+export declare function getInferenceExecutionRulesContractArtifact(): {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: Array<{ id: string; ok: boolean }>;
+  errors: string[];
+  stats: {
+    decodeRecorderRules: number;
+    batchDecodeRules: number;
+    decodeRecorderContexts: number;
+    batchDecodeContexts: number;
+  };
+};
+
+export declare function getInferenceLayerPatternContractArtifact(): {
+  schemaVersion: 1;
+  source: 'doppler';
+  ok: boolean;
+  checks: Array<{ id: string; ok: boolean }>;
+  errors: string[];
+  stats: {
+    patternKindRules: number;
+    layerTypeRules: number;
+    patternKindContexts: number;
+    layerTypeContexts: number;
+  };
+};

package/src/rules/rule-registry.js

@@ -1,8 +1,11 @@
 import { selectByRules } from '../gpu/kernels/rule-matcher.js';
+import { buildInferenceExecutionRulesContractArtifact } from './execution-rules-contract-check.js';
+import { buildLayerPatternContractArtifact } from './layer-pattern-contract-check.js';
 import { loadJson } from '../utils/load-json.js';
 
 const attentionRules = await loadJson('./kernels/attention.rules.json', import.meta.url, 'Failed to load rules');
 const conv2dRules = await loadJson('./kernels/conv2d.rules.json', import.meta.url, 'Failed to load rules');
+const depthwiseConv2dRules = await loadJson('./kernels/depthwise-conv2d.rules.json', import.meta.url, 'Failed to load rules');
 const dequantRules = await loadJson('./kernels/dequant.rules.json', import.meta.url, 'Failed to load rules');
 const energyRules = await loadJson('./kernels/energy.rules.json', import.meta.url, 'Failed to load rules');
 const fusedFfnRules = await loadJson('./kernels/fused-ffn.rules.json', import.meta.url, 'Failed to load rules');
@@ -10,6 +13,7 @@ const fusedMatmulResidualRules = await loadJson('./kernels/fused-matmul-residual
 const fusedMatmulRmsnormRules = await loadJson('./kernels/fused-matmul-rmsnorm.rules.json', import.meta.url, 'Failed to load rules');
 const gatherRules = await loadJson('./kernels/gather.rules.json', import.meta.url, 'Failed to load rules');
 const geluRules = await loadJson('./kernels/gelu.rules.json', import.meta.url, 'Failed to load rules');
+const groupedPointwiseConv2dRules = await loadJson('./kernels/grouped-pointwise-conv2d.rules.json', import.meta.url, 'Failed to load rules');
 const groupnormRules = await loadJson('./kernels/groupnorm.rules.json', import.meta.url, 'Failed to load rules');
 const kvQuantizeRules = await loadJson('./kernels/kv_quantize.rules.json', import.meta.url, 'Failed to load rules');
 const layernormRules = await loadJson('./kernels/layernorm.rules.json', import.meta.url, 'Failed to load rules');
@@ -18,9 +22,12 @@ const kernelMoeRules = await loadJson('./kernels/moe.rules.json', import.meta.ur
 const kernelMoeGptOssRules = await loadJson('./kernels/moe.rules.gptoss.json', import.meta.url, 'Failed to load rules');
 const modulateRules = await loadJson('./kernels/modulate.rules.json', import.meta.url, 'Failed to load rules');
 const pixelShuffleRules = await loadJson('./kernels/pixel_shuffle.rules.json', import.meta.url, 'Failed to load rules');
+const repeatChannelsRules = await loadJson('./kernels/repeat-channels.rules.json', import.meta.url, 'Failed to load rules');
+const reluRules = await loadJson('./kernels/relu.rules.json', import.meta.url, 'Failed to load rules');
 const residualRules = await loadJson('./kernels/residual.rules.json', import.meta.url, 'Failed to load rules');
 const rmsnormRules = await loadJson('./kernels/rmsnorm.rules.json', import.meta.url, 'Failed to load rules');
 const ropeRules = await loadJson('./kernels/rope.rules.json', import.meta.url, 'Failed to load rules');
+const sanaLinearAttentionRules = await loadJson('./kernels/sana-linear-attention.rules.json', import.meta.url, 'Failed to load rules');
 const sampleRules = await loadJson('./kernels/sample.rules.json', import.meta.url, 'Failed to load rules');
 const scaleRules = await loadJson('./kernels/scale.rules.json', import.meta.url, 'Failed to load rules');
 const siluRules = await loadJson('./kernels/silu.rules.json', import.meta.url, 'Failed to load rules');
@@ -46,6 +53,24 @@ const toolingCommandRuntimeRules = await loadJson(
   import.meta.url,
   'Failed to load rules'
 );
+const INFERENCE_EXECUTION_RULES_CONTRACT_ARTIFACT = buildInferenceExecutionRulesContractArtifact(
+  inferenceExecutionRules
+);
+if (!INFERENCE_EXECUTION_RULES_CONTRACT_ARTIFACT.ok) {
+  throw new Error(
+    `RuleRegistry: inference.execution rules contract failed: ` +
+    `${INFERENCE_EXECUTION_RULES_CONTRACT_ARTIFACT.errors.join(' | ')}`
+  );
+}
+const INFERENCE_LAYER_PATTERN_CONTRACT_ARTIFACT = buildLayerPatternContractArtifact(
+  layerPatternRules
+);
+if (!INFERENCE_LAYER_PATTERN_CONTRACT_ARTIFACT.ok) {
+  throw new Error(
+    `RuleRegistry: inference.layerPattern rules contract failed: ` +
+    `${INFERENCE_LAYER_PATTERN_CONTRACT_ARTIFACT.errors.join(' | ')}`
+  );
+}
 
 const RULE_SETS = {
   shared: {
@@ -54,6 +79,7 @@ const RULE_SETS = {
   kernels: {
     attention: attentionRules,
     conv2d: conv2dRules,
+    depthwiseConv2d: depthwiseConv2dRules,
     dequant: dequantRules,
     energy: energyRules,
     fusedFfn: fusedFfnRules,
@@ -61,6 +87,7 @@ const RULE_SETS = {
     fusedMatmulRmsnorm: fusedMatmulRmsnormRules,
     gather: gatherRules,
     gelu: geluRules,
+    groupedPointwiseConv2d: groupedPointwiseConv2dRules,
     groupnorm: groupnormRules,
     kv_quantize: kvQuantizeRules,
     layernorm: layernormRules,
@@ -69,9 +96,12 @@ const RULE_SETS = {
     moeGptoss: kernelMoeGptOssRules,
     modulate: modulateRules,
     pixel_shuffle: pixelShuffleRules,
+    repeatChannels: repeatChannelsRules,
+    relu: reluRules,
     residual: residualRules,
     rmsnorm: rmsnormRules,
     rope: ropeRules,
+    sanaLinearAttention: sanaLinearAttentionRules,
     sample: sampleRules,
     scale: scaleRules,
     silu: siluRules,
@@ -133,6 +163,14 @@ export function registerRuleGroup(domain, group, rules) {
   RULE_SETS[domain][group] = rules;
 }
 
+export function getInferenceExecutionRulesContractArtifact() {
+  return INFERENCE_EXECUTION_RULES_CONTRACT_ARTIFACT;
+}
+
+export function getInferenceLayerPatternContractArtifact() {
+  return INFERENCE_LAYER_PATTERN_CONTRACT_ARTIFACT;
+}
+
 function resolveRuleValue(value, context) {
   if (Array.isArray(value)) {
     return value.map((entry) => resolveRuleValue(entry, context));

package/src/rules/tooling/command-runtime.rules.json

@@ -27,6 +27,24 @@
         "intent": "verify"
       }
     },
+    {
+      "match": {
+        "command": "lora"
+      },
+      "value": {
+        "suite": null,
+        "intent": null
+      }
+    },
+    {
+      "match": {
+        "command": "distill"
+      },
+      "value": {
+        "suite": null,
+        "intent": null
+      }
+    },
     {
       "match": {},
       "value": {

package/src/tooling/command-api.d.ts

@@ -1,10 +1,12 @@
 import type { ConverterConfigSchema } from '../config/schema/converter.schema.js';
 
-export type ToolingCommand = 'convert' | 'debug' | 'bench' | 'verify';
+export type ToolingCommand = 'convert' | 'debug' | 'bench' | 'verify' | 'lora' | 'distill';
 export type ToolingSurface = 'browser' | 'node';
 export type ToolingSuite = 'kernels' | 'inference' | 'training' | 'bench' | 'debug' | 'diffusion' | 'energy';
 export type ToolingIntent = 'verify' | 'investigate' | 'calibrate' | null;
 export type ToolingTrainingStage = 'stage1_joint' | 'stage2_base' | 'stage_a' | 'stage_b';
+export type ToolingDistillAction = 'run' | 'stage-a' | 'stage-b' | 'eval' | 'watch' | 'compare' | 'quality-gate' | 'subsets';
+export type ToolingLoraAction = 'run' | 'eval' | 'watch' | 'export' | 'compare' | 'quality-gate' | 'activate';
 
 export interface ToolingConvertExecutionPayload {
   workers?: number | null;
@@ -25,6 +27,7 @@ export interface ToolingConvertPayload {
 
 export interface ToolingCommandRequestInput {
   command: ToolingCommand;
+  action?: ToolingDistillAction | ToolingLoraAction;
   suite?: ToolingSuite;
   modelId?: string;
   trainingTests?: string[];
@@ -65,6 +68,17 @@ export interface ToolingCommandRequestInput {
   inputDir?: string;
   outputDir?: string;
   convertPayload?: ToolingConvertPayload;
+  workloadPath?: string;
+  runRoot?: string;
+  checkpointPath?: string;
+  checkpointId?: string;
+  checkpointStep?: number;
+  stageId?: string;
+  stageArtifact?: string;
+  subsetManifest?: string;
+  evalDatasetId?: string;
+  pollIntervalMs?: number;
+  stopWhenIdle?: boolean;
   captureOutput?: boolean;
   keepPipeline?: boolean;
   report?: Record<string, unknown> | null;
@@ -76,6 +90,7 @@ export interface ToolingCommandRequest {
   command: ToolingCommand;
   suite: ToolingSuite | null;
   intent: ToolingIntent;
+  action: ToolingDistillAction | ToolingLoraAction | null;
   modelId: string | null;
   trainingTests: string[] | null;
   trainingStage: ToolingTrainingStage | null;
@@ -115,6 +130,17 @@ export interface ToolingCommandRequest {
   inputDir: string | null;
   outputDir: string | null;
   convertPayload: ToolingConvertPayload | null;
+  workloadPath: string | null;
+  runRoot: string | null;
+  checkpointPath: string | null;
+  checkpointId: string | null;
+  checkpointStep: number | null;
+  stageId: string | null;
+  stageArtifact: string | null;
+  subsetManifest: string | null;
+  evalDatasetId: string | null;
+  pollIntervalMs: number | null;
+  stopWhenIdle: boolean | null;
   captureOutput: boolean;
   keepPipeline: boolean;
   report: Record<string, unknown> | null;

package/src/tooling/command-api.js

@@ -1,12 +1,14 @@
 import { isPlainObject } from '../utils/plain-object.js';
 import { selectRuleValue } from '../rules/rule-registry.js';
 
-const TOOLING_COMMAND_SET = ['convert', 'debug', 'bench', 'verify'];
+const TOOLING_COMMAND_SET = ['convert', 'debug', 'bench', 'verify', 'lora', 'distill'];
 const TOOLING_SURFACE_SET = ['browser', 'node'];
 const TOOLING_SUITE_SET = ['kernels', 'inference', 'training', 'bench', 'debug', 'diffusion', 'energy'];
 const TOOLING_INTENT_SET = ['verify', 'investigate', 'calibrate'];
 const VERIFY_SUITES = ['kernels', 'inference', 'training', 'diffusion', 'energy'];
 const TRAINING_STAGE_SET = ['stage1_joint', 'stage2_base', 'stage_a', 'stage_b'];
+const DISTILL_ACTION_SET = ['run', 'stage-a', 'stage-b', 'eval', 'watch', 'compare', 'quality-gate', 'subsets'];
+const LORA_ACTION_SET = ['run', 'eval', 'watch', 'export', 'compare', 'quality-gate', 'activate'];
 const TRAINING_COMMAND_SCHEMA_VERSION = 1;
 
 export const TOOLING_COMMANDS = Object.freeze([...TOOLING_COMMAND_SET]);
@@ -82,6 +84,15 @@ function asOptionalForceResumeReason(value, label) {
   return reason;
 }
 
+function asOptionalAction(value, label, allowed) {
+  const action = asOptionalString(value, label);
+  if (!action) return null;
+  if (!allowed.includes(action)) {
+    throw new Error(`tooling command: ${label} must be one of ${allowed.join(', ')}.`);
+  }
+  return action;
+}
+
 function assertCommand(value) {
   const command = asOptionalString(value, 'command');
   if (!command) {
@@ -246,6 +257,7 @@ function normalizeConvert(raw) {
     command: 'convert',
     suite: null,
     intent: null,
+    action: null,
     modelId: null,
     trainingTests: null,
     trainingStage: null,
@@ -285,6 +297,113 @@ function normalizeConvert(raw) {
     inputDir,
     outputDir,
     convertPayload: payload,
+    workloadPath: null,
+    runRoot: null,
+    checkpointPath: null,
+    checkpointId: null,
+    checkpointStep: null,
+    stageId: null,
+    stageArtifact: null,
+    subsetManifest: null,
+    evalDatasetId: null,
+    pollIntervalMs: null,
+    stopWhenIdle: null,
+    captureOutput: false,
+    keepPipeline: false,
+    report: asOptionalObject(raw.report, 'report'),
+    timestamp: raw.timestamp ?? null,
+    searchParams: raw.searchParams ?? null,
+  };
+}
+
+function normalizeTrainingOperatorCommand(raw, command) {
+  const allowedActions = command === 'distill' ? DISTILL_ACTION_SET : LORA_ACTION_SET;
+  const action = asOptionalAction(raw.action, 'action', allowedActions);
+  if (!action) {
+    throw new Error(`tooling command: ${command} requires action.`);
+  }
+  const workloadPath = asOptionalString(raw.workloadPath, 'workloadPath');
+  const runRoot = asOptionalString(raw.runRoot, 'runRoot');
+  const checkpointPath = asOptionalString(raw.checkpointPath, 'checkpointPath');
+  const checkpointId = asOptionalString(raw.checkpointId, 'checkpointId');
+  const checkpointStep = asOptionalPositiveInteger(raw.checkpointStep, 'checkpointStep');
+  const stageId = asOptionalString(raw.stageId, 'stageId');
+  const stageArtifact = asOptionalString(raw.stageArtifact, 'stageArtifact');
+  const subsetManifest = asOptionalString(raw.subsetManifest, 'subsetManifest');
+  const evalDatasetId = asOptionalString(raw.evalDatasetId, 'evalDatasetId');
+  const pollIntervalMs = asOptionalPositiveInteger(raw.pollIntervalMs, 'pollIntervalMs');
+  const stopWhenIdle = asOptionalBoolean(raw.stopWhenIdle, 'stopWhenIdle');
+  if (!workloadPath && !runRoot) {
+    throw new Error(`tooling command: ${command} requires workloadPath or runRoot.`);
+  }
+  if ((action === 'eval' || action === 'export') && !checkpointPath && !runRoot) {
+    throw new Error(`tooling command: ${command} ${action} requires checkpointPath or runRoot.`);
+  }
+  if (action === 'watch' && !runRoot) {
+    throw new Error(`tooling command: ${command} watch requires runRoot.`);
+  }
+  if ((action === 'compare' || action === 'quality-gate') && !runRoot) {
+    throw new Error(`tooling command: ${command} ${action} requires runRoot.`);
+  }
+  if (command === 'distill' && action === 'stage-b' && !stageArtifact && !runRoot) {
+    throw new Error('tooling command: distill stage-b requires stageArtifact or runRoot.');
+  }
+
+  return {
+    command,
+    suite: null,
+    intent: null,
+    action,
+    modelId: null,
+    trainingTests: null,
+    trainingStage: null,
+    trainingConfig: null,
+    stage1Artifact: null,
+    stage1ArtifactHash: null,
+    ulArtifactDir: null,
+    stageAArtifact: null,
+    stageAArtifactHash: null,
+    distillArtifactDir: null,
+    teacherModelId: null,
+    studentModelId: null,
+    distillDatasetId: null,
+    distillDatasetPath: null,
+    distillLanguagePair: null,
+    distillSourceLangs: null,
+    distillTargetLangs: null,
+    distillPairAllowlist: null,
+    strictPairContract: null,
+    distillShardIndex: null,
+    distillShardCount: null,
+    resumeFrom: null,
+    forceResume: null,
+    forceResumeReason: null,
+    forceResumeSource: null,
+    checkpointOperator: null,
+    trainingSchemaVersion: null,
+    trainingBenchSteps: null,
+    checkpointEvery: null,
+    workloadType: 'training',
+    modelUrl: null,
+    cacheMode: asOptionalCacheMode(raw.cacheMode, 'cacheMode'),
+    loadMode: asOptionalLoadMode(raw.loadMode, 'loadMode'),
+    runtimePreset: asOptionalString(raw.runtimePreset, 'runtimePreset'),
+    runtimeConfigUrl: asOptionalString(raw.runtimeConfigUrl, 'runtimeConfigUrl'),
+    runtimeConfig: asOptionalObject(raw.runtimeConfig, 'runtimeConfig'),
+    inputDir: null,
+    outputDir: null,
+    convertPayload: null,
+    workloadPath,
+    runRoot,
+    checkpointPath,
+    checkpointId,
+    checkpointStep,
+    stageId,
+    stageArtifact,
+    subsetManifest,
+    evalDatasetId,
+    pollIntervalMs,
+    stopWhenIdle,
     captureOutput: false,
     keepPipeline: false,
     report: asOptionalObject(raw.report, 'report'),
@@ -428,6 +547,7 @@ function normalizeSuiteCommand(raw, command) {
     command,
     suite,
     intent: runtimeContract.intent,
+    action: null,
     modelId,
     trainingTests,
     trainingStage,
@@ -469,6 +589,17 @@ function normalizeSuiteCommand(raw, command) {
     inputDir: null,
     outputDir: null,
     convertPayload: null,
+    workloadPath: null,
+    runRoot: null,
+    checkpointPath: null,
+    checkpointId: null,
+    checkpointStep: null,
+    stageId: null,
+    stageArtifact: null,
+    subsetManifest: null,
+    evalDatasetId: null,
+    pollIntervalMs: null,
+    stopWhenIdle: null,
     captureOutput: asOptionalBoolean(raw.captureOutput, 'captureOutput') ?? false,
     keepPipeline: asOptionalBoolean(raw.keepPipeline, 'keepPipeline') ?? false,
     report: asOptionalObject(raw.report, 'report'),
@@ -485,6 +616,9 @@ export function normalizeToolingCommandRequest(input) {
   if (command === 'convert') {
     return normalizeConvert(input);
   }
+  if (command === 'lora' || command === 'distill') {
+    return normalizeTrainingOperatorCommand(input, command);
+  }
   return normalizeSuiteCommand(input, command);
 }
 
@@ -514,8 +648,13 @@ export function ensureCommandSupportedOnSurface(commandRequest, surface) {
     throw new Error(`tooling command: unsupported surface "${surface}".`);
   }
 
-  // All commands are contractually available on both surfaces.
-  // Surface-specific capability checks happen in the runners.
+  if (
+    normalizedSurface === 'browser'
+    && (request.command === 'lora' || request.command === 'distill')
+  ) {
+    throw new Error(`tooling command: ${request.command} is currently Node-only and must fail closed on browser.`);
+  }
+
   return {
     request,
     surface: normalizedSurface,

package/src/tooling/conversion-config-materializer.d.ts

@@ -0,0 +1,24 @@
+export declare function extractTensorEntriesFromManifest(
+  manifest: Record<string, unknown>
+): Array<{
+  name: string;
+  dtype: unknown;
+  shape: unknown;
+  role: unknown;
+  layout: unknown;
+}>;
+
+export declare function resolveMaterializedManifestFromConversionConfig(
+  conversionConfigInput: Record<string, unknown>,
+  manifest: Record<string, unknown>
+): {
+  modelId: string;
+  modelType: string;
+  architecture: Record<string, unknown> | null;
+  inference: Record<string, unknown> | null;
+};
+
+export declare function inferConversionConfigModelId(
+  configPath: string,
+  conversionConfigInput: Record<string, unknown>
+): string;