@relayflows/sdk 2.0.0

package/src/compile.ts

@@ -0,0 +1,573 @@
+// The YAML -> spec compiler. Authoring surface in, the kernel's spec dialect
+// out (RFC settled decision #5: the composable unit is the spec, not any
+// language). Compilation is two mappings:
+//
+//   compileYaml / compileSpec  — parse + validate (fail-closed) + authoring
+//                                defaults, staying in the authoring shape.
+//   toKernelSpec               — authoring shape -> the ONE boundary dialect
+//                                the kernel parses, journals, and hashes
+//                                (snake_case, flat v0 verification, defaults
+//                                materialized).
+//
+// `compileYamlToCanonicalJson` / `specHash` operate on the kernel dialect, so
+// sha256(canonical JSON) equals the kernel's `spec_hash`. That claim is
+// proven, not asserted: `tests/spec-parity.test.ts` and the kernel's
+// `tests/spec_parity.rs` pin both sides to the same `testdata/` fixture.
+
+import { parse as parseYaml } from 'yaml';
+import type {
+  AgentStepSpec,
+  DeterministicStepSpec,
+  FlowSpec,
+  KernelAgentStep,
+  KernelRunSpec,
+  KernelStepCommon,
+  KernelStepSpec,
+  KernelTriggerSpec,
+  KernelVerificationSpec,
+  LlmStepSpec,
+  NamedAgentSpec,
+  OutputVerificationSpec,
+  StepSpec,
+  StepType,
+  TriggerSpec,
+  VerificationSpec,
+} from './spec.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import { canonicalize, specHash } from './canonical.js';
+import { validateOutputDeclaration } from './output-schema.js';
+import { validateSpec, type ValidationResult } from './validate.js';
+import { snapshotJsonValue } from './json-value.js';
+
+export class CompileError extends Error {
+  readonly errors: string[];
+  constructor(errors: string[]) {
+    super('spec compile failed:\n  - ' + errors.join('\n  - '));
+    this.name = 'CompileError';
+    this.errors = errors;
+  }
+}
+
+/**
+ * Compile a YAML string into a validated authoring `FlowSpec`.
+ * Throws `CompileError` on a YAML parse error or any validation failure.
+ */
+export function compileYaml(yaml: string): FlowSpec {
+  const parsed = parseYaml(yaml);
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new CompileError(['YAML: expected a mapping at the top level']);
+  }
+  return compileSpec(parsed);
+}
+
+/** Kernel-dialect canonical JSON of `compileYaml` (sorted keys, no whitespace). */
+export function compileYamlToCanonicalJson(yaml: string): string {
+  return canonicalize(toKernelSpec(compileYaml(yaml)));
+}
+
+/**
+ * Validate a parsed spec object and apply authoring defaults, returning a
+ * normalized `FlowSpec`. Throws `CompileError` on validation failure.
+ */
+export function compileSpec(spec: unknown): FlowSpec {
+  let snapshot: unknown;
+  try {
+    snapshot = snapshotJsonValue(spec, 'spec');
+  } catch (error) {
+    throw new CompileError([
+      error instanceof Error ? error.message : 'spec: expected JSON-compatible data',
+    ]);
+  }
+  const validation: ValidationResult = validateSpec(snapshot);
+  if (!validation.ok) throw new CompileError(validation.errors);
+
+  const input = snapshot as FlowSpec;
+  // Preserve named declarations and selectors through authoring normalization.
+  // They are resolved exactly once at the kernel boundary, after public
+  // preflight has validated every declaration with truthful provenance.
+  const steps = input.steps.map(compileStep);
+  const flow: FlowSpec = {
+    version: input.version,
+    ...(input.name !== undefined ? { name: input.name } : {}),
+    ...(input.description !== undefined ? { description: input.description } : {}),
+    ...(input.cli !== undefined ? { cli: input.cli } : {}),
+    ...(input.agents !== undefined ? { agents: input.agents } : {}),
+    // The kernel omits an empty trigger list when serializing RunSpec. Normalize
+    // it here so the authoring shape and boundary shape retain one hashable form.
+    ...(input.triggers?.length ? { triggers: input.triggers } : {}),
+    steps,
+    ...(input.budget !== undefined ? { budget: input.budget } : {}),
+  };
+  return flow;
+}
+
+function compileStep(step: StepSpec): StepSpec {
+  const maxIterations = step.maxIterations ?? 1;
+  const verification = typedOutputVerification(step);
+  const base = {
+    id: step.id,
+    type: step.type,
+    ...(step.dependsOn !== undefined ? { dependsOn: step.dependsOn } : {}),
+    maxIterations,
+  };
+
+  switch (step.type as StepType) {
+    case 'deterministic': {
+      const s = step as DeterministicStepSpec;
+      // A deterministic step with no verification gets the implicit exit_code
+      // gate. Read the SHARED `verification`, never `s.verification`: for this
+      // verb the two are equal today (typedOutputVerification returns
+      // `step.verification` unchanged, because `output` is not authorable on a
+      // deterministic step), but reading the shared binding is what keeps every
+      // branch of this switch on the lowered gate rather than the raw authored
+      // one. See ops/reviews/20260903-pr139-repair-0903.md §10, trap 2.
+      return {
+        ...base,
+        type: 'deterministic',
+        command: s.command,
+        verification: verification ?? { type: 'exit_code' as const },
+        // #138: `timeoutMs` is deterministic-only — worker-backed verbs own
+        // their dispatch timeout. It must be spread HERE and nowhere in `base`.
+        ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
+      };
+    }
+    case 'llm': {
+      const s = step as LlmStepSpec;
+      return {
+        ...base,
+        type: 'llm',
+        prompt: s.prompt,
+        // From the shared `verification` — which may have been lowered from an
+        // `output` declaration — never from `s.verification`, which would drop
+        // that lowering.
+        ...(verification !== undefined ? { verification: outputGate(verification, s.id) } : {}),
+        ...(s.model !== undefined ? { model: s.model } : {}),
+        ...(s.cli !== undefined ? { cli: s.cli } : {}),
+      };
+    }
+    case 'agent': {
+      const s = step as AgentStepSpec;
+      const recoveryMode = s.recoveryMode ?? 'reset';
+      return {
+        ...base,
+        type: 'agent',
+        instruction: s.instruction,
+        ...(verification !== undefined ? { verification: outputGate(verification, s.id) } : {}),
+        ...(s.agent !== undefined ? { agent: s.agent } : {}),
+        ...(s.cli !== undefined ? { cli: s.cli } : {}),
+        ...(s.model !== undefined ? { model: s.model } : {}),
+        recoveryMode,
+        ...(s.surfaces !== undefined ? { surfaces: s.surfaces } : {}),
+        ...(s.permissions !== undefined ? { permissions: s.permissions } : {}),
+      };
+    }
+    default:
+      // validateSpec already gated this; unreachable.
+      throw new CompileError([`step "${step.id}": unknown type "${String((step as { type: unknown }).type)}"`]);
+  }
+}
+
+/**
+ * Narrow a gate to the ones an `llm`/`agent` step may carry. `validateSpec`
+ * already refuses `exit_code` off a deterministic step, so this is the
+ * fail-closed backstop for a runtime value cast past the authoring types.
+ */
+function outputGate(gate: VerificationSpec, stepId: string): OutputVerificationSpec {
+  if (gate.type === 'exit_code') {
+    throw new CompileError([
+      `step "${stepId}": exit_code is supported only on deterministic steps`,
+    ]);
+  }
+  return gate;
+}
+
+function typedOutputVerification(step: StepSpec): StepSpec['verification'] {
+  if (step.type !== 'deterministic' && step.output !== undefined) {
+    const errors = validateOutputDeclaration(step, `step "${step.id}"`);
+    if (errors.length > 0) throw new CompileError(errors);
+    return { type: 'json_schema', schema: step.output };
+  }
+  return step.verification;
+}
+
+/**
+ * Resolve declarative named-agent sugar at kernel lowering. Explicit step
+ * fields win independently, so an author may override
+ * only the CLI or only the model. The selector and declaration map never
+ * cross the journal boundary.
+ */
+function resolveNamedAgent(
+  step: StepSpec,
+  agents: Record<string, NamedAgentSpec> | undefined,
+): StepSpec {
+  if (step.type !== 'agent' || step.agent === undefined) return step;
+  const declaration = agents !== undefined && Object.hasOwn(agents, step.agent)
+    ? agents[step.agent]
+    : undefined;
+  if (declaration === undefined) {
+    throw new CompileError([
+      `step "${step.id}": unknown named agent "${step.agent}"`,
+    ]);
+  }
+  return {
+    ...step,
+    ...(step.cli === undefined ? { cli: declaration.cli } : {}),
+    ...(step.model === undefined ? { model: declaration.model } : {}),
+  };
+}
+
+// Kernel defaults, materialized at compile time so the emitted spec is
+// byte-identical to the kernel's own serialization of it (spec.rs defaults).
+const KERNEL_RETRY_DEFAULTS = {
+  initial_backoff_ms: 100,
+  max_backoff_ms: 60_000,
+  multiplier: 2,
+  jitter_percent: 20,
+} as const;
+
+/**
+ * Map an authoring `FlowSpec` to the kernel spec dialect — the single shape at
+ * the SDK↔kernel boundary (`kernel/relayflowd-core/src/spec.rs`). Authoring
+ * sugar that the dialect cannot carry is a `CompileError`, never a silent drop.
+ */
+export function toKernelSpec(flow: FlowSpec): KernelRunSpec {
+  // This public boundary is callable without compileSpec. Compile again so
+  // runtime casts are validated and all returned schema data is snapshotted.
+  const compiled = compileSpec(flow);
+
+  return {
+    version: compiled.version,
+    ...(compiled.name !== undefined ? { name: compiled.name } : {}),
+    ...(compiled.description !== undefined ? { description: compiled.description } : {}),
+    ...(compiled.cli !== undefined ? { cli: compiled.cli } : {}),
+    // Both halves are load-bearing, and this hunk is trap 2's shape a second
+    // time. `compiled.*` is #139's snapshot guard: this boundary is callable
+    // without compileSpec, so it recompiles and reads the validated, snapshotted
+    // spec rather than the caller's raw object. `.map(toKernelTrigger)` is
+    // #151's LOWERING of authoring trigger keys into the kernel dialect --
+    // authoring sugar that becomes a different object at the boundary, exactly
+    // like `output:`. Taking either side of this conflict wholesale silently
+    // reverts the other, and `validateSpec` and `flows check` would both still
+    // look correct. See ops/reviews/20260903-pr139-repair-0903.md section 10.
+    ...(compiled.triggers?.length ? { triggers: compiled.triggers.map(toKernelTrigger) } : {}),
+    steps: compiled.steps.map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
+    ...(compiled.budget !== undefined
+      ? {
+          budget: {
+            ...(compiled.budget.maxTokensIn !== undefined ? { max_tokens_in: compiled.budget.maxTokensIn } : {}),
+            ...(compiled.budget.maxTokensOut !== undefined ? { max_tokens_out: compiled.budget.maxTokensOut } : {}),
+            ...(compiled.budget.maxDollars !== undefined ? { max_dollars: compiled.budget.maxDollars } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * Map the kernel boundary dialect back to the normalized authoring shape.
+ * This is the inverse of `toKernelSpec` over specs this compiler emits.
+ * Kernel-only values with no authoring representation are refused.
+ */
+export function kernelToAuthoring(value: unknown): unknown {
+  let snapshot: unknown;
+  try {
+    snapshot = snapshotJsonValue(value, 'spec');
+  } catch (error) {
+    throw new CompileError([
+      error instanceof Error ? error.message : 'spec: expected JSON-compatible data',
+    ]);
+  }
+  const root = requireKernelObject(
+    snapshot,
+    ['version', 'name', 'description', 'cli', 'triggers', 'steps', 'budget'],
+    'spec',
+  );
+  const steps = requireKernelArray(root['steps'], 'spec.steps')
+    .map((step, index) => kernelStepToAuthoring(step, `spec.steps[${index}]`));
+  const triggers = root['triggers'];
+  return {
+    ...copyDefined(root, ['version', 'name', 'description', 'cli']),
+    ...(triggers !== undefined
+      ? {
+          triggers: requireKernelArray(triggers, 'spec.triggers')
+            .map((trigger, index) => kernelTriggerToAuthoring(trigger, `spec.triggers[${index}]`)),
+        }
+      : {}),
+    steps,
+    ...(root['budget'] !== undefined
+      ? { budget: kernelBudgetToAuthoring(root['budget'], 'spec.budget') }
+      : {}),
+  };
+}
+
+/**
+ * Lower one authoring trigger into the kernel dialect.
+ *
+ * This mapping was missing entirely: `toKernelSpec` used to spread
+ * `flow.triggers` through untouched, so every event subscription reached the
+ * kernel in camelCase and `relayflowd` — whose `TriggerSpec` is
+ * `#[serde(deny_unknown_fields)]` over snake_case — refused the spec outright:
+ *
+ *   malformed run spec: unknown field `dedupeKeyTemplate`, expected one of
+ *   `id`, `executor`, `event_type`, `pattern`, `dedupe_key_template`,
+ *   `stale_after_ms`
+ *
+ * The committed `testdata/*.spec.canonical.json` fixtures are snake_case and
+ * the kernel accepts them, which is why nothing noticed: no test compiled a
+ * triggered flow through this function and compared it to a fixture. Every
+ * triggered flow in `testdata/` was therefore unauthorable through the
+ * supported SDK path. `tests/spec-parity.test.ts` now pins the mapping.
+ */
+function toKernelTrigger(trigger: TriggerSpec): KernelTriggerSpec {
+  return {
+    id: trigger.id,
+    executor: trigger.executor,
+    ...(trigger.eventType !== undefined ? { event_type: trigger.eventType } : {}),
+    ...(trigger.pattern !== undefined ? { pattern: trigger.pattern } : {}),
+    ...(trigger.dedupeKeyTemplate !== undefined
+      ? { dedupe_key_template: trigger.dedupeKeyTemplate }
+      : {}),
+    ...(trigger.staleAfterMs !== undefined ? { stale_after_ms: trigger.staleAfterMs } : {}),
+  };
+}
+
+/** Inverse of `toKernelTrigger`. Kernel-only keys are refused, never dropped. */
+function kernelTriggerToAuthoring(value: unknown, at: string): unknown {
+  const trigger = requireKernelObject(
+    value,
+    ['id', 'executor', 'event_type', 'pattern', 'dedupe_key_template', 'stale_after_ms'],
+    at,
+  );
+  return {
+    id: trigger['id'],
+    executor: trigger['executor'],
+    ...(trigger['event_type'] !== undefined ? { eventType: trigger['event_type'] } : {}),
+    ...(trigger['pattern'] !== undefined ? { pattern: trigger['pattern'] } : {}),
+    ...(trigger['dedupe_key_template'] !== undefined
+      ? { dedupeKeyTemplate: trigger['dedupe_key_template'] }
+      : {}),
+    ...(trigger['stale_after_ms'] !== undefined ? { staleAfterMs: trigger['stale_after_ms'] } : {}),
+  };
+}
+
+function kernelStepToAuthoring(value: unknown, at: string): unknown {
+  const unionKeys = [
+    'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification',
+    'command', 'timeout_ms', 'prompt', 'model', 'cli', 'instruction',
+    'recovery_mode', 'surfaces', 'permissions',
+  ] as const;
+  const step = requireKernelObject(value, unionKeys, at);
+  const type = step['type'];
+  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification'] as const;
+  const typeKeys = type === 'deterministic'
+    ? ['command', 'timeout_ms'] as const
+    : type === 'llm'
+      ? ['prompt', 'model', 'cli'] as const
+      : type === 'agent'
+        ? ['instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions'] as const
+        : [];
+  assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
+  if (step['retry'] !== undefined) validateKernelRetry(step['retry'], `${at}.retry`);
+  const dependsOn = step['depends_on'];
+  const common = {
+    id: step['id'],
+    type,
+    ...(dependsOn !== undefined && (!Array.isArray(dependsOn) || dependsOn.length > 0)
+      ? { dependsOn }
+      : {}),
+    ...(step['max_iterations'] !== undefined ? { maxIterations: step['max_iterations'] } : {}),
+    ...kernelVerificationToAuthoring(type, step['verification'], `${at}.verification`),
+  };
+  if (type === 'deterministic') {
+    return {
+      ...common,
+      command: step['command'],
+      ...(step['timeout_ms'] !== undefined ? { timeoutMs: step['timeout_ms'] } : {}),
+    };
+  }
+  if (type === 'llm') {
+    return { ...common, prompt: step['prompt'], ...copyDefined(step, ['model', 'cli']) };
+  }
+  if (type === 'agent') {
+    return {
+      ...common,
+      instruction: step['instruction'],
+      ...(step['recovery_mode'] !== undefined ? { recoveryMode: step['recovery_mode'] } : {}),
+      ...copyDefined(step, ['cli', 'model', 'surfaces']),
+      ...(step['permissions'] !== undefined
+        ? { permissions: kernelPermissionsToAuthoring(step['permissions'], `${at}.permissions`) }
+        : {}),
+    };
+  }
+  return common;
+}
+
+function validateKernelRetry(value: unknown, at: string): void {
+  const retry = requireKernelObject(value, [
+    'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent',
+  ], at);
+  for (const [field, expected] of Object.entries(KERNEL_RETRY_DEFAULTS)) {
+    if (retry[field] !== expected) {
+      throw new CompileError([
+        `${at}.${field} must equal the authoring default ${expected}`,
+      ]);
+    }
+  }
+}
+
+function kernelVerificationToAuthoring(
+  type: unknown,
+  value: unknown,
+  at: string,
+): Record<string, unknown> {
+  if (value === undefined) return {};
+  const verification = requireKernelObject(value, ['output_contains', 'json_schema'], at);
+  if (verification['output_contains'] !== undefined && verification['json_schema'] !== undefined) {
+    throw new CompileError([`${at} may not contain two gates in spec v0.1.0`]);
+  }
+  if (verification['output_contains'] !== undefined) {
+    return { verification: { type: 'output_contains', value: verification['output_contains'] } };
+  }
+  if (verification['json_schema'] !== undefined) {
+    return { verification: { type: 'json_schema', schema: verification['json_schema'] } };
+  }
+  return type === 'deterministic' ? { verification: { type: 'exit_code' } } : {};
+}
+
+function kernelBudgetToAuthoring(value: unknown, at: string): unknown {
+  const budget = requireKernelObject(value, ['max_tokens_in', 'max_tokens_out', 'max_dollars'], at);
+  return {
+    ...(budget['max_tokens_in'] !== undefined ? { maxTokensIn: budget['max_tokens_in'] } : {}),
+    ...(budget['max_tokens_out'] !== undefined ? { maxTokensOut: budget['max_tokens_out'] } : {}),
+    ...(budget['max_dollars'] !== undefined ? { maxDollars: budget['max_dollars'] } : {}),
+  };
+}
+
+function kernelPermissionsToAuthoring(value: unknown, at: string): unknown {
+  const permissions = requireKernelObject(value, ['file_globs', 'network_allowlist', 'access_preset'], at);
+  return {
+    ...(permissions['file_globs'] !== undefined ? { fileGlobs: permissions['file_globs'] } : {}),
+    ...(permissions['network_allowlist'] !== undefined ? { networkAllowlist: permissions['network_allowlist'] } : {}),
+    ...(permissions['access_preset'] !== undefined ? { accessPreset: permissions['access_preset'] } : {}),
+  };
+}
+
+function requireKernelObject(
+  value: unknown,
+  allowed: readonly string[],
+  at: string,
+): Record<string, unknown> {
+  if (!isObject(value)) {
+    throw new CompileError([`${at}: expected an object`]);
+  }
+  assertKernelKeys(value, allowed, at);
+  return value;
+}
+
+function assertKernelKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  at: string,
+): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new CompileError([
+      `${at}: unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.map((key) => `"${key}"`).join(', ')} (expected one of ${allowed.join(' | ')})`,
+    ]);
+  }
+}
+
+function requireKernelArray(value: unknown, at: string): unknown[] {
+  if (!Array.isArray(value)) throw new CompileError([`${at}: expected an array`]);
+  return value;
+}
+
+function copyDefined(value: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+  return Object.fromEntries(keys.filter((key) => value[key] !== undefined).map((key) => [key, value[key]]));
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function toKernelStep(step: StepSpec): KernelStepSpec {
+  const common: KernelStepCommon = {
+    id: step.id,
+    depends_on: step.dependsOn ?? [],
+    max_iterations: step.maxIterations ?? 1,
+    retry: { ...KERNEL_RETRY_DEFAULTS },
+    verification: toKernelVerification(step),
+  };
+  switch (step.type) {
+    case 'deterministic':
+      return {
+        ...common,
+        type: 'deterministic',
+        command: step.command,
+        ...(step.timeoutMs !== undefined ? { timeout_ms: step.timeoutMs } : {}),
+      };
+    case 'llm': {
+      return {
+        ...common,
+        type: 'llm',
+        prompt: step.prompt,
+        ...(step.model !== undefined ? { model: step.model } : {}),
+        ...(step.cli !== undefined ? { cli: step.cli } : {}),
+      };
+    }
+    case 'agent': {
+      const out: KernelAgentStep = {
+        ...common,
+        type: 'agent',
+        instruction: step.instruction,
+        ...(step.cli !== undefined ? { cli: step.cli } : {}),
+        ...(step.model !== undefined ? { model: step.model } : {}),
+        recovery_mode: step.recoveryMode ?? 'reset',
+      };
+      const surfaces = {
+        ...(step.surfaces?.workspace?.length ? { workspace: step.surfaces.workspace.map((w) => ({ surface: w.surface })) } : {}),
+        ...(step.surfaces?.streams?.length ? { streams: step.surfaces.streams.map((s) => ({ stream: s.stream })) } : {}),
+        ...(step.surfaces?.external?.length ? { external: step.surfaces.external } : {}),
+      };
+      if (Object.keys(surfaces).length > 0) out.surfaces = surfaces;
+      if (step.permissions !== undefined) {
+        out.permissions = {
+          ...(step.permissions.fileGlobs !== undefined ? { file_globs: step.permissions.fileGlobs } : {}),
+          ...(step.permissions.networkAllowlist !== undefined ? { network_allowlist: step.permissions.networkAllowlist } : {}),
+          ...(step.permissions.accessPreset !== undefined ? { access_preset: step.permissions.accessPreset } : {}),
+        };
+      }
+      return out;
+    }
+  }
+}
+
+function toKernelVerification(step: StepSpec): KernelVerificationSpec {
+  const output = step.type === 'deterministic' ? undefined : step.output;
+  if (output !== undefined) {
+    const errors = validateOutputDeclaration(step, `step "${step.id}"`);
+    if (errors.length > 0) throw new CompileError(errors);
+    return { json_schema: output };
+  }
+  const gate = step.verification;
+  // Validation permits explicit exit_code only on deterministic steps, where
+  // {} selects the kernel's implicit exit_code == 0 gate (DESIGN.md §4).
+  if (gate === undefined || gate.type === 'exit_code') return {};
+  if (gate.type === 'output_contains') return { output_contains: gate.value };
+  if (gate.type === 'json_schema') return { json_schema: gate.schema };
+  throw new CompileError([
+    `step "${step.id}".verification.type: expected exit_code | output_contains | json_schema`,
+  ]);
+}
+
+/**
+ * Compile + hash in one call. `hash` is sha256 of the kernel-dialect canonical
+ * JSON — the spec identity the kernel stamps as `spec_hash` in `run.spawned`.
+ */
+export function compileAndHash(yaml: string): { spec: FlowSpec; kernelSpec: KernelRunSpec; hash: string } {
+  const spec = compileYaml(yaml);
+  const kernelSpec = toKernelSpec(spec);
+  return { spec, kernelSpec, hash: specHash(kernelSpec) };
+}
+
+export { SPEC_SCHEMA_VERSION, canonicalize, specHash };