@k2b/cloud 0.6.0-rc.0

package/src/workflows/editor.ts

@@ -0,0 +1,113 @@
+import { type Highlighter, highlight } from "@k2b/stdlib";
+import type { Completion, SuggestContext, Suggestion } from "@k2b/ui";
+import type { WorkflowCompletionItem, WorkflowFieldSchema } from "./index";
+import type { DefinedWorkflowModule } from "./module";
+
+export type WorkflowAutocompleteRequest = {
+  source: string;
+  caret: number;
+};
+
+export type WorkflowAutocompleteResponse<TDiagnostics = unknown> = {
+  items: WorkflowCompletionItem[];
+  diagnostics?: TDiagnostics;
+};
+
+type WorkflowAutocompleteFetcher<TResponse extends WorkflowAutocompleteResponse> = (
+  request: WorkflowAutocompleteRequest,
+  signal: AbortSignal,
+) => Promise<TResponse>;
+
+const WORKFLOW_TRIGGER_CHARS = [" ", "\n", "\t", ":", "-", ".", "[", "{", ",", "'"];
+export const workflowCompletionItemToSuggestion = (item: WorkflowCompletionItem): Suggestion => ({
+  text: item.insertText,
+  label: item.label,
+  hint: item.detail ?? item.kind,
+  appendSpace: false,
+  textEdit: item.textEdit,
+});
+
+export const buildWorkflowAutocompleteCompletions = <TResponse extends WorkflowAutocompleteResponse>(config: {
+  fetchAutocomplete: WorkflowAutocompleteFetcher<TResponse>;
+  onResponse?: (response: TResponse) => void;
+}): Completion[] => {
+  const suggest = (_query: string, ctx: SuggestContext, signal: AbortSignal): Suggestion[] | Promise<Suggestion[]> => {
+    if (signal.aborted) return [];
+    return config.fetchAutocomplete({ source: ctx.fullText, caret: ctx.caret }, signal).then((response) => {
+      if (signal.aborted) return [];
+      config.onResponse?.(response);
+      return response.items.map(workflowCompletionItemToSuggestion);
+    });
+  };
+  return [
+    { dropdown: true, suggest },
+    ...WORKFLOW_TRIGGER_CHARS.map(
+      (trigger): Completion => ({
+        trigger,
+        dropdown: true,
+        allowAfterWord: true,
+        suggest,
+      }),
+    ),
+  ];
+};
+
+const collectSchemaKeys = (schema: WorkflowFieldSchema, keys: Set<string>): void => {
+  if (schema.kind === "object") {
+    for (const [key, value] of Object.entries(schema.properties)) {
+      keys.add(key);
+      collectSchemaKeys(value, keys);
+    }
+  } else if (schema.kind === "array") collectSchemaKeys(schema.items, keys);
+  else if (schema.kind === "record") collectSchemaKeys(schema.values, keys);
+  else if (schema.kind === "union") {
+    for (const variant of schema.variants) collectSchemaKeys(variant, keys);
+  }
+};
+
+const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const createWorkflowYamlHighlighter = (workflows?: DefinedWorkflowModule): Highlighter => {
+  const manifest = workflows?.manifest;
+  const keywords = new Set([
+    "inputs",
+    "triggers",
+    "steps",
+    "type",
+    "required",
+    "with",
+    "if",
+    "then",
+    "else",
+    "switch",
+    "cases",
+    "default",
+    "forEach",
+    "as",
+    "do",
+    "true",
+    "false",
+    "null",
+  ]);
+  if (manifest) {
+    for (const descriptor of [...manifest.inputs, ...manifest.triggers, ...manifest.actions]) {
+      keywords.add(descriptor.kind);
+      collectSchemaKeys(descriptor.config, keywords);
+    }
+  }
+  const keywordPattern = new RegExp(`\\b(?:${[...keywords].sort().map(escapeRegex).join("|")})\\b`);
+  return highlight.compile(
+    [
+      { kind: "placeholder", match: /\$\{\{\s*[^{}]+?\s*\}\}/ },
+      { kind: "placeholder", match: /\b(?:inputs|trigger|steps)\.[A-Za-z_][A-Za-z0-9_.-]*\b/ },
+      { kind: "string", match: /"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'/ },
+      { kind: "keyword", match: /\b[A-Za-z][A-Za-z0-9]*(?=\s*:)/ },
+      { kind: "keyword", match: keywordPattern },
+      { kind: "function", match: /\bnow\(\)/ },
+      { kind: "number", match: /\b-?\d+(?:\.\d+)?\b/ },
+      { kind: "operator", match: /[:{}\[\],-]/ },
+      { kind: "comment", match: /#[^\n]*/ },
+    ],
+    { classPrefix: "doc-token-" },
+  );
+};

package/src/workflows/index.ts

@@ -0,0 +1,71 @@
+export { AI_WORKFLOW_ACTIONS } from "./ai-actions";
+export {
+  buildWorkflowManifestCompletions,
+  type WorkflowCompletionContext,
+  type WorkflowCompletionItem,
+  type WorkflowCompletionKind,
+  workflowCompletionContext,
+  workflowCompletionItem,
+} from "./authoring";
+export {
+  createWorkflowBuiltinActionPorts,
+  renderWorkflowTextTemplate,
+  type WorkflowBuiltinActionAuthorize,
+  type WorkflowBuiltinActionPorts,
+  type WorkflowBuiltinTextRenderer,
+} from "./builtins";
+export type {
+  WorkflowActionDescriptor,
+  WorkflowActionEffect,
+  WorkflowActionPolicy,
+  WorkflowActor,
+  WorkflowBoundPlan,
+  WorkflowCondition,
+  WorkflowControlTraversal,
+  WorkflowDependency,
+  WorkflowDescriptorDocs,
+  WorkflowDiagnostic,
+  WorkflowExecutionError,
+  WorkflowFieldSchema,
+  WorkflowInputDescriptor,
+  WorkflowInvocation,
+  WorkflowInvocationMode,
+  WorkflowInvocationReceipt,
+  WorkflowIr,
+  WorkflowIrInput,
+  WorkflowIrStep,
+  WorkflowIrTrigger,
+  WorkflowJsonPrimitive,
+  WorkflowJsonValue,
+  WorkflowLanguageManifest,
+  WorkflowLauncher,
+  WorkflowPlanningIssue,
+  WorkflowPlanningOutcome,
+  WorkflowRevision,
+  WorkflowRunState,
+  WorkflowSourceLocation,
+  WorkflowStepOutcome,
+  WorkflowStepState,
+  WorkflowTriggerDescriptor,
+} from "./contracts";
+export { workflowPathKey } from "./contracts";
+export type {
+  ErasedWorkflowAction,
+  FromFieldSchema,
+  WorkflowActionContext,
+  WorkflowActionDefinition,
+  WorkflowActionMap,
+  WorkflowActionResult,
+  WorkflowEffectClass,
+  WorkflowPlannedEffect,
+  WorkflowReconcileResult,
+} from "./definition";
+export {
+  isReplayable,
+  LANGUAGE_EFFECT,
+  workflowAction,
+} from "./definition";
+export {
+  type DefinedWorkflowModule,
+  defineWorkflowModule,
+} from "./module";

package/src/workflows/language/binder.ts

@@ -0,0 +1,45 @@
+import type { WorkflowBoundPlan, WorkflowIr, WorkflowJsonValue } from "../contracts";
+import type { DefinedWorkflowModule } from "../module";
+import { hashWorkflowJson, normalizeWorkflowJson } from "./canonical";
+
+export type WorkflowCatalogBinding = {
+  catalog: WorkflowJsonValue;
+  bindings: Record<string, WorkflowJsonValue>;
+};
+
+export type WorkflowCatalogBinder = (ir: Readonly<WorkflowIr>) => WorkflowCatalogBinding | Promise<WorkflowCatalogBinding>;
+
+export const bindWorkflow = async (
+  ir: WorkflowIr,
+  workflows: DefinedWorkflowModule,
+  bindCatalog: WorkflowCatalogBinder,
+): Promise<WorkflowBoundPlan> => {
+  const manifest = workflows.manifest;
+  if (ir.languageId !== manifest.id || ir.languageVersion !== manifest.version) {
+    throw new TypeError(
+      `Workflow IR language ${ir.languageId}@${ir.languageVersion} does not match manifest ${manifest.id}@${manifest.version}`,
+    );
+  }
+
+  const manifestHash = await hashWorkflowJson(manifest);
+  if (ir.manifestHash !== manifestHash) {
+    throw new TypeError(`Workflow IR manifest hash ${ir.manifestHash} does not match manifest hash ${manifestHash}`);
+  }
+
+  const binding = await bindCatalog(ir);
+  const catalogHash = await hashWorkflowJson(binding.catalog);
+  return {
+    schemaVersion: 2,
+    languageId: ir.languageId,
+    languageVersion: ir.languageVersion,
+    sourceHash: ir.sourceHash,
+    manifestHash,
+    catalogHash,
+    ...(manifest.limits?.maxLoopItems !== undefined ? { maxLoopItems: manifest.limits.maxLoopItems } : {}),
+    actionPolicies: Object.fromEntries(manifest.actions.map((action) => [action.kind, { effect: action.effect, dryRun: action.dryRun }])),
+    inputs: ir.inputs,
+    triggers: ir.triggers,
+    steps: ir.steps,
+    bindings: normalizeWorkflowJson(binding.bindings),
+  };
+};

package/src/workflows/language/canonical.ts

@@ -0,0 +1,29 @@
+import { crypto } from "@k2b/stdlib";
+import type { WorkflowJsonValue } from "../contracts";
+
+const compareJsonKeys = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const normalizeUnknown = (value: unknown, path: string): WorkflowJsonValue => {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) return value.map((item, index) => normalizeUnknown(item, `${path}[${index}]`));
+  if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) throw new TypeError(`${path} must be a plain JSON object`);
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => compareJsonKeys(left, right))
+      .map(([key, item]) => [key, normalizeUnknown(item, `${path}.${key}`)] as const);
+    return Object.fromEntries(entries) as Record<string, WorkflowJsonValue>;
+  }
+  throw new TypeError(`${path} must contain only JSON values`);
+};
+
+export const normalizeWorkflowJson = <T extends WorkflowJsonValue>(value: T): T => normalizeUnknown(value, "value") as T;
+
+export const canonicalWorkflowJson = (value: unknown): string => JSON.stringify(normalizeUnknown(value, "value"));
+
+export const hashWorkflowJson = (value: unknown): Promise<string> => crypto.common.hash(canonicalWorkflowJson(value));
+
+export const hashWorkflowSource = (source: string): Promise<string> => crypto.common.hash(source);

package/src/workflows/language/compiler.ts

@@ -0,0 +1,396 @@
+import type {
+  WorkflowActionDescriptor,
+  WorkflowCondition,
+  WorkflowDiagnostic,
+  WorkflowInputDescriptor,
+  WorkflowIr,
+  WorkflowIrInput,
+  WorkflowIrStep,
+  WorkflowIrTrigger,
+  WorkflowJsonValue,
+  WorkflowLanguageManifest,
+  WorkflowSourceLocation,
+  WorkflowTriggerDescriptor,
+} from "../contracts";
+import type { DefinedWorkflowModule } from "../module";
+import { hashWorkflowJson, hashWorkflowSource, normalizeWorkflowJson } from "./canonical";
+import { validateWorkflowField, workflowDiagnostic, workflowRecord } from "./schema";
+import { parseWorkflowYaml } from "./strict-yaml";
+
+export type CompileWorkflowResult = { ok: true; ir: WorkflowIr } | { ok: false; diagnostics: WorkflowDiagnostic[] };
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_ACTIONS = new Set(["if", "switch", "forEach"]);
+const hasOwn = (value: object, key: string): boolean => Object.prototype.hasOwnProperty.call(value, key);
+
+type CompileContext = {
+  manifest: WorkflowLanguageManifest;
+  locations: Record<string, WorkflowSourceLocation>;
+  diagnostics: WorkflowDiagnostic[];
+  actions: Map<string, WorkflowActionDescriptor>;
+  stepCount: number;
+  stepLimitReported: boolean;
+  conditionCount: number;
+  conditionLimitReported: boolean;
+};
+
+const addDiagnostic = (context: CompileContext, code: string, message: string, path: Array<string | number>): void => {
+  context.diagnostics.push(workflowDiagnostic(code, message, path, context.locations));
+};
+
+const validateExactKeys = (
+  value: Record<string, WorkflowJsonValue>,
+  allowed: readonly string[],
+  path: Array<string | number>,
+  context: CompileContext,
+): void => {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) addDiagnostic(context, "schema.unknown", `Unknown property "${key}"`, [...path, key]);
+  }
+};
+
+const descriptorMap = <T extends { kind: string }>(
+  descriptors: T[],
+  section: string,
+  diagnostics: WorkflowDiagnostic[],
+): Map<string, T> => {
+  const result = new Map<string, T>();
+  for (const descriptor of descriptors) {
+    if (result.has(descriptor.kind)) {
+      diagnostics.push({
+        code: "manifest.duplicate",
+        message: `Duplicate ${section} descriptor "${descriptor.kind}"`,
+        severity: "error",
+        path: [],
+      });
+    } else {
+      result.set(descriptor.kind, descriptor);
+    }
+  }
+  return result;
+};
+
+const validateManifest = (manifest: WorkflowLanguageManifest, diagnostics: WorkflowDiagnostic[]): void => {
+  if (manifest.id.trim().length === 0)
+    diagnostics.push({ code: "manifest.id", message: "Manifest id must not be empty", severity: "error", path: [] });
+  if (!Number.isInteger(manifest.version) || manifest.version < 1)
+    diagnostics.push({ code: "manifest.version", message: "Manifest version must be a positive integer", severity: "error", path: [] });
+  for (const [name, value] of Object.entries(manifest.limits ?? {})) {
+    if (!Number.isInteger(value) || value! < 1) {
+      diagnostics.push({
+        code: "manifest.limit",
+        message: `Manifest limit "${name}" must be a positive integer`,
+        severity: "error",
+        path: [],
+      });
+    }
+  }
+  for (const action of manifest.actions) {
+    if (RESERVED_ACTIONS.has(action.kind)) {
+      diagnostics.push({
+        code: "manifest.reserved",
+        message: `Action descriptor "${action.kind}" uses a reserved control-flow name`,
+        severity: "error",
+        path: [],
+      });
+    }
+  }
+};
+
+const compileInputs = (
+  value: WorkflowJsonValue | undefined,
+  descriptors: Map<string, WorkflowInputDescriptor>,
+  context: CompileContext,
+): WorkflowIrInput[] => {
+  if (value === undefined) return [];
+  if (!workflowRecord(value)) {
+    addDiagnostic(context, "schema.type", "Expected inputs to be an object", ["inputs"]);
+    return [];
+  }
+  const names = Object.keys(value).sort();
+  const maxInputs = context.manifest.limits?.maxInputs;
+  if (maxInputs !== undefined && names.length > maxInputs)
+    addDiagnostic(context, "limit.inputs", `Workflow defines more than ${maxInputs} inputs`, ["inputs"]);
+
+  const inputs: WorkflowIrInput[] = [];
+  for (const name of names) {
+    const path = ["inputs", name] as Array<string | number>;
+    if (!IDENTIFIER.test(name)) addDiagnostic(context, "input.name", `Input name "${name}" must be an identifier`, path);
+    const definition = value[name];
+    if (!workflowRecord(definition)) {
+      addDiagnostic(context, "schema.type", "Expected input definition to be an object", path);
+      continue;
+    }
+    const type = definition.type;
+    if (typeof type !== "string") {
+      addDiagnostic(context, "schema.required", "Input requires a string type", [...path, "type"]);
+      continue;
+    }
+    const descriptor = descriptors.get(type);
+    if (!descriptor) {
+      addDiagnostic(context, "input.unknown", `Unknown input type "${type}"`, [...path, "type"]);
+      continue;
+    }
+    const config = Object.fromEntries(Object.entries(definition).filter(([key]) => key !== "type")) as Record<string, WorkflowJsonValue>;
+    validateWorkflowField(config, descriptor.config, path, context.locations, context.diagnostics);
+    inputs.push({ name, type, config: normalizeWorkflowJson(config) });
+  }
+  return inputs;
+};
+
+const compileTriggers = (
+  value: WorkflowJsonValue | undefined,
+  descriptors: Map<string, WorkflowTriggerDescriptor>,
+  inputNames: Set<string>,
+  context: CompileContext,
+): WorkflowIrTrigger[] => {
+  if (value === undefined) return [];
+  if (!workflowRecord(value)) {
+    addDiagnostic(context, "schema.type", "Expected triggers to be an object", ["triggers"]);
+    return [];
+  }
+  const kinds = Object.keys(value).sort();
+  if (kinds.length === 0) {
+    addDiagnostic(context, "trigger.empty", "Omit triggers for a direct-only workflow; an empty triggers object is invalid", ["triggers"]);
+    return [];
+  }
+
+  const triggers: WorkflowIrTrigger[] = [];
+  for (const kind of kinds) {
+    const path = ["triggers", kind] as Array<string | number>;
+    const descriptor = descriptors.get(kind);
+    if (!descriptor) {
+      addDiagnostic(context, "trigger.unknown", `Unknown trigger "${kind}"`, path);
+      continue;
+    }
+    const definition = value[kind];
+    if (!workflowRecord(definition)) {
+      addDiagnostic(context, "schema.type", "Expected trigger definition to be an object", path);
+      continue;
+    }
+    const withValue = definition.with;
+    const withBindings = withValue === undefined ? {} : withValue;
+    if (!workflowRecord(withBindings)) {
+      addDiagnostic(context, "schema.type", "Expected trigger with bindings to be an object", [...path, "with"]);
+      continue;
+    }
+    for (const inputName of Object.keys(withBindings)) {
+      if (!inputNames.has(inputName))
+        addDiagnostic(context, "trigger.input", `Trigger binds unknown input "${inputName}"`, [...path, "with", inputName]);
+    }
+    const config = Object.fromEntries(Object.entries(definition).filter(([key]) => key !== "with")) as Record<string, WorkflowJsonValue>;
+    validateWorkflowField(config, descriptor.config, path, context.locations, context.diagnostics);
+    triggers.push({ kind, config: normalizeWorkflowJson(config), with: normalizeWorkflowJson(withBindings) });
+  }
+  return triggers;
+};
+
+const compileCondition = (
+  value: WorkflowJsonValue | undefined,
+  path: Array<string | number>,
+  depth: number,
+  context: CompileContext,
+): WorkflowCondition | undefined => {
+  context.conditionCount += 1;
+  const maxConditions = context.manifest.limits?.maxConditions;
+  if (maxConditions !== undefined && context.conditionCount > maxConditions) {
+    if (!context.conditionLimitReported) {
+      addDiagnostic(context, "limit.conditions", `Workflow defines more than ${maxConditions} conditions`, path);
+      context.conditionLimitReported = true;
+    }
+    return undefined;
+  }
+  const maxDepth = context.manifest.limits?.maxConditionDepth;
+  if (maxDepth !== undefined && depth > maxDepth) {
+    addDiagnostic(context, "limit.conditionDepth", `Workflow condition depth exceeds ${maxDepth}`, path);
+    return undefined;
+  }
+  if (!workflowRecord(value)) {
+    addDiagnostic(context, "condition.type", "Condition must be an object", path);
+    return undefined;
+  }
+  const operators = Object.keys(value);
+  if (
+    operators.length !== 1 ||
+    !["equals", "notEquals", "includes", "textEquals", "contains", "startsWith", "endsWith", "exists", "all", "any", "not"].includes(
+      operators[0]!,
+    )
+  ) {
+    addDiagnostic(context, "condition.operator", "Condition must contain exactly one supported operator", path);
+    return undefined;
+  }
+  const operator = operators[0]!;
+  const operand = value[operator];
+  if (operator === "all" || operator === "any") {
+    if (!Array.isArray(operand) || operand.length === 0) {
+      addDiagnostic(context, "condition.conditions", `${operator} requires at least one condition`, [...path, operator]);
+      return undefined;
+    }
+    const conditions = operand
+      .map((condition, index) => compileCondition(condition, [...path, operator, index], depth + 1, context))
+      .filter((condition): condition is WorkflowCondition => condition !== undefined);
+    if (conditions.length !== operand.length) return undefined;
+    return operator === "all" ? { operator: "all", conditions } : { operator: "any", conditions };
+  }
+  if (operator === "not") {
+    const condition = compileCondition(operand, [...path, operator], depth + 1, context);
+    return condition ? { operator, condition } : undefined;
+  }
+  if (operator === "exists") {
+    if (typeof operand !== "string" || operand.length === 0) {
+      addDiagnostic(context, "condition.exists", "exists requires a non-empty reference", [...path, operator]);
+      return undefined;
+    }
+    return { operator: "exists", reference: operand };
+  }
+  if (!Array.isArray(operand) || operand.length !== 2) {
+    addDiagnostic(context, "condition.operands", `${operator} requires exactly two operands`, [...path, operator]);
+    return undefined;
+  }
+  return {
+    operator: operator as "equals" | "notEquals" | "includes" | "textEquals" | "contains" | "startsWith" | "endsWith",
+    operands: [normalizeWorkflowJson(operand[0]!), normalizeWorkflowJson(operand[1]!)],
+  };
+};
+
+const compileSteps = (
+  value: WorkflowJsonValue | undefined,
+  path: Array<string | number>,
+  depth: number,
+  context: CompileContext,
+): WorkflowIrStep[] => {
+  if (!Array.isArray(value) || value.length === 0) {
+    addDiagnostic(context, "steps.type", "Expected at least one workflow step", path);
+    return [];
+  }
+
+  const result: WorkflowIrStep[] = [];
+  value.forEach((step, index) => {
+    const stepPath = [...path, index];
+    context.stepCount += 1;
+    const maxSteps = context.manifest.limits?.maxSteps;
+    if (maxSteps !== undefined && context.stepCount > maxSteps && !context.stepLimitReported) {
+      addDiagnostic(context, "limit.steps", `Workflow defines more than ${maxSteps} steps`, stepPath);
+      context.stepLimitReported = true;
+    }
+    const maxDepth = context.manifest.limits?.maxDepth;
+    if (maxDepth !== undefined && depth > maxDepth)
+      addDiagnostic(context, "limit.depth", `Workflow control-flow depth exceeds ${maxDepth}`, stepPath);
+
+    if (!workflowRecord(step)) {
+      addDiagnostic(context, "step.type", "Workflow step must be an object", stepPath);
+      return;
+    }
+    if (hasOwn(step, "if")) {
+      validateExactKeys(step, ["if", "then", "else"], stepPath, context);
+      const condition = compileCondition(step.if, [...stepPath, "if"], 1, context);
+      const thenSteps = compileSteps(step.then, [...stepPath, "then"], depth + 1, context);
+      const elseSteps = step.else === undefined ? [] : compileSteps(step.else, [...stepPath, "else"], depth + 1, context);
+      if (condition) result.push({ kind: "if", condition, then: thenSteps, else: elseSteps, sourcePath: stepPath });
+      return;
+    }
+    if (hasOwn(step, "switch")) {
+      validateExactKeys(step, ["switch", "cases", "default"], stepPath, context);
+      if (!Array.isArray(step.cases) || step.cases.length === 0) {
+        addDiagnostic(context, "switch.cases", "switch requires at least one case", [...stepPath, "cases"]);
+        return;
+      }
+      const cases: Array<{ when: WorkflowJsonValue; steps: WorkflowIrStep[] }> = [];
+      step.cases.forEach((caseValue, caseIndex) => {
+        const casePath = [...stepPath, "cases", caseIndex];
+        if (!workflowRecord(caseValue)) {
+          addDiagnostic(context, "switch.case", "Switch case must be an object", casePath);
+          return;
+        }
+        validateExactKeys(caseValue, ["when", "do"], casePath, context);
+        if (!hasOwn(caseValue, "when")) {
+          addDiagnostic(context, "schema.required", "Switch case requires when", [...casePath, "when"]);
+          return;
+        }
+        cases.push({
+          when: normalizeWorkflowJson(caseValue.when!),
+          steps: compileSteps(caseValue.do, [...casePath, "do"], depth + 1, context),
+        });
+      });
+      const defaultSteps = step.default === undefined ? [] : compileSteps(step.default, [...stepPath, "default"], depth + 1, context);
+      result.push({ kind: "switch", value: normalizeWorkflowJson(step.switch!), cases, default: defaultSteps, sourcePath: stepPath });
+      return;
+    }
+    if (hasOwn(step, "forEach")) {
+      validateExactKeys(step, ["forEach", "as", "do"], stepPath, context);
+      if (typeof step.forEach !== "string" || step.forEach.length === 0)
+        addDiagnostic(context, "forEach.reference", "forEach requires a non-empty reference", [...stepPath, "forEach"]);
+      if (typeof step.as !== "string" || !IDENTIFIER.test(step.as))
+        addDiagnostic(context, "forEach.alias", "forEach alias must be an identifier", [...stepPath, "as"]);
+      const steps = compileSteps(step.do, [...stepPath, "do"], depth + 1, context);
+      if (typeof step.forEach === "string" && step.forEach.length > 0 && typeof step.as === "string" && IDENTIFIER.test(step.as))
+        result.push({ kind: "forEach", reference: step.forEach, alias: step.as, steps, sourcePath: stepPath });
+      return;
+    }
+
+    const keys = Object.keys(step);
+    if (keys.length !== 1) {
+      addDiagnostic(context, "step.shape", "Action step must contain exactly one action", stepPath);
+      return;
+    }
+    const action = keys[0]!;
+    const descriptor = context.actions.get(action);
+    if (!descriptor) {
+      addDiagnostic(context, "action.unknown", `Unknown action "${action}"`, [...stepPath, action]);
+      return;
+    }
+    const config = step[action];
+    if (!workflowRecord(config)) {
+      addDiagnostic(context, "schema.type", "Action configuration must be an object", [...stepPath, action]);
+      return;
+    }
+    validateWorkflowField(config, descriptor.config, [...stepPath, action], context.locations, context.diagnostics);
+    result.push({ kind: "action", action, config: normalizeWorkflowJson(config), sourcePath: stepPath });
+  });
+  return result;
+};
+
+export const compileWorkflow = async (source: string, workflows: DefinedWorkflowModule): Promise<CompileWorkflowResult> => {
+  const manifest = workflows.manifest;
+  const parsed = parseWorkflowYaml(source);
+  if (!parsed.ok) return { ok: false, diagnostics: parsed.diagnostics };
+
+  const diagnostics: WorkflowDiagnostic[] = [];
+  validateManifest(manifest, diagnostics);
+  const inputs = descriptorMap(manifest.inputs, "input", diagnostics);
+  const triggers = descriptorMap(manifest.triggers, "trigger", diagnostics);
+  const actions = descriptorMap(manifest.actions, "action", diagnostics);
+  const context: CompileContext = {
+    manifest,
+    locations: parsed.parsed.sourceLocations,
+    diagnostics,
+    actions,
+    stepCount: 0,
+    stepLimitReported: false,
+    conditionCount: 0,
+    conditionLimitReported: false,
+  };
+  const root = parsed.parsed.value as Record<string, WorkflowJsonValue>;
+  validateExactKeys(root, ["inputs", "triggers", "steps"], [], context);
+  const compiledInputs = compileInputs(root.inputs, inputs, context);
+  const compiledTriggers = compileTriggers(root.triggers, triggers, new Set(compiledInputs.map((input) => input.name)), context);
+  const compiledSteps = compileSteps(root.steps, ["steps"], 1, context);
+  if (diagnostics.length > 0) return { ok: false, diagnostics };
+
+  const [sourceHash, manifestHash] = await Promise.all([hashWorkflowSource(source), hashWorkflowJson(manifest)]);
+
+  return {
+    ok: true,
+    ir: {
+      schemaVersion: 1,
+      languageId: manifest.id,
+      languageVersion: manifest.version,
+      sourceHash,
+      manifestHash,
+      inputs: compiledInputs,
+      triggers: compiledTriggers,
+      steps: compiledSteps,
+      sourceLocations: parsed.parsed.sourceLocations,
+    },
+  };
+};