@reasonlayer/sdk 0.0.1

package/dist/compile.js

@@ -0,0 +1,834 @@
+/**
+ * compileWorkflow (spec §4.4): lower a WorkflowDefinition to WorkflowIR.
+ * Every selector is validated against the step graph; wrong wiring is a
+ * compile error, not a runtime surprise. Returns { ok, ir, codeRefs,
+ * agentRefs } or { ok: false, errors } — it never throws for authoring
+ * mistakes.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, normalize, relative, resolve } from "node:path";
+import { toJsonSchema } from "@valibot/to-json-schema";
+import { resolveCatalogActionDescriptor } from "@reasonlayer/integrations";
+import { STEP_ID_PATTERN, canonicalEnvironmentDeclarationJson, parseExactNpmPackage, parseExactPipPackage, mapChildId, } from "@reasonlayer/protocol";
+import { WiringError, inputProxy, lower, mapItemProxy, referencedStepIds, stepsProxy, usesMapItem, } from "./selectors.js";
+import { checkSelectorSatisfiesSchema, resolveSelectorArrayItemSchema, } from "./selector-schema.js";
+import { validateSchedule } from "./schedule-validation.js";
+import { variableDefinitionForCompile } from "./types.js";
+/** IR step ids must be safe as JS export names in the emitted bundles. */
+export function exportNameFor(stepId) {
+    return `step__${stepId.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+function secretNames(secrets) {
+    if (!secrets || secrets.length === 0)
+        return undefined;
+    return secrets.map((s) => s.__rlSecret);
+}
+function collectVariableNames(selector) {
+    switch (selector.kind) {
+        case "variable":
+            return [selector.name];
+        case "object":
+            return Object.values(selector.fields).flatMap(collectVariableNames);
+        case "array":
+            return selector.items.flatMap(collectVariableNames);
+        default:
+            return [];
+    }
+}
+function stepSelectors(step) {
+    if (step.kind === "map")
+        return [step.over, step.key, step.step.input];
+    return [step.input];
+}
+function variableSchemasFor(selectors) {
+    const schemas = Object.create(null);
+    for (const name of new Set(selectors.flatMap(collectVariableNames))) {
+        const definition = variableDefinitionForCompile(name);
+        if (definition)
+            schemas[name] = definition.schemaJson;
+    }
+    return schemas;
+}
+function isSecretRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.__rlSecret === "string" &&
+        value.__rlSecret.length > 0);
+}
+function envHashFor(declaration) {
+    return createHash("sha256")
+        .update(canonicalEnvironmentDeclarationJson({ envHash: "", ...declaration }))
+        .digest("hex");
+}
+function normalizeSecretRefs(stepId, serverName, label, values, errors) {
+    if (!values || Object.keys(values).length === 0)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
+        if (!isSecretRef(value)) {
+            errors.push({
+                stepId,
+                message: `environment mcp.${serverName}.${label}.${key} must use secret("name"); inline secret values are not allowed`,
+            });
+            continue;
+        }
+        out[key] = { kind: "secret", name: value.__rlSecret };
+    }
+    return out;
+}
+function normalizeMcpServer(stepId, name, config, errors) {
+    const hasCommand = "command" in config && typeof config.command === "string";
+    const hasUrl = "url" in config && typeof config.url === "string";
+    if (hasCommand === hasUrl) {
+        errors.push({
+            stepId,
+            message: `environment mcp.${name} must declare exactly one of command or url`,
+        });
+        return undefined;
+    }
+    if (hasCommand) {
+        if (!config.command.trim()) {
+            errors.push({ stepId, message: `environment mcp.${name}.command cannot be empty` });
+            return undefined;
+        }
+        if (config.transport !== "http") {
+            errors.push({
+                stepId,
+                message: `environment mcp.${name}.command servers must declare transport: "http"; stdio MCP commands need an HTTP bridge`,
+            });
+            return undefined;
+        }
+        const env = normalizeSecretRefs(stepId, name, "env", config.env, errors);
+        return {
+            kind: "command",
+            command: config.command,
+            transport: "http",
+            ...(env !== undefined ? { env } : {}),
+        };
+    }
+    try {
+        new URL(config.url);
+    }
+    catch {
+        errors.push({ stepId, message: `environment mcp.${name}.url must be an absolute URL` });
+        return undefined;
+    }
+    const headers = normalizeSecretRefs(stepId, name, "headers", config.headers, errors);
+    return {
+        kind: "url",
+        url: config.url,
+        ...(headers !== undefined ? { headers } : {}),
+    };
+}
+function sortedNonEmptyStrings(stepId, label, values, errors) {
+    if (!values || values.length === 0)
+        return undefined;
+    const out = [];
+    for (const value of values) {
+        if (typeof value !== "string" || !value.trim()) {
+            errors.push({ stepId, message: `environment ${label} entries must be non-empty strings` });
+            continue;
+        }
+        out.push(value);
+    }
+    return out.sort((a, b) => a.localeCompare(b));
+}
+function isInsideDirectory(child, parent) {
+    const rel = relative(parent, child);
+    return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+function lowerEnvironmentFiles(stepId, files, options, errors) {
+    if (!files || Object.keys(files).length === 0)
+        return undefined;
+    const baseDir = options.environmentFileBaseDir
+        ? resolve(options.environmentFileBaseDir)
+        : undefined;
+    const out = [];
+    for (const [src, dest] of Object.entries(files).sort(([a], [b]) => a.localeCompare(b))) {
+        if (!src.trim() || !dest.trim() || !dest.startsWith("/")) {
+            errors.push({
+                stepId,
+                message: `environment file mapping "${src}" must have a non-empty relative source and absolute destination`,
+            });
+            continue;
+        }
+        if (isAbsolute(src) || normalize(src).split(/[\\/]/).includes("..")) {
+            errors.push({
+                stepId,
+                message: `environment file source "${src}" must be relative to the workflow entry directory`,
+            });
+            continue;
+        }
+        if (!options.inlineEnvironmentFiles)
+            continue;
+        if (!baseDir) {
+            errors.push({
+                stepId,
+                message: "environment files require an environmentFileBaseDir when inlineEnvironmentFiles is enabled",
+            });
+            continue;
+        }
+        const sourcePath = resolve(baseDir, src);
+        if (!isInsideDirectory(sourcePath, baseDir)) {
+            errors.push({
+                stepId,
+                message: `environment file source "${src}" escapes the workflow entry directory`,
+            });
+            continue;
+        }
+        let bytes;
+        try {
+            const stat = statSync(sourcePath);
+            if (!stat.isFile()) {
+                errors.push({ stepId, message: `environment file source "${src}" must be a regular file` });
+                continue;
+            }
+            bytes = readFileSync(sourcePath);
+        }
+        catch (err) {
+            errors.push({
+                stepId,
+                message: `environment file source "${src}" cannot be read: ${err.message}`,
+            });
+            continue;
+        }
+        out.push({
+            path: dest,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            contentBase64: bytes.toString("base64"),
+        });
+    }
+    return out.length > 0 ? out.sort((a, b) => a.path.localeCompare(b.path)) : undefined;
+}
+function lowerEnvironment(stepId, environment, host, stepKind, errors, options) {
+    if (!environment)
+        return undefined;
+    if (environment.__rlEnvironment !== true) {
+        errors.push({ stepId, message: "environment must be created with defineEnvironment(...)" });
+        return undefined;
+    }
+    if (host.kind === "device") {
+        const disallowed = [];
+        if (environment.config.npm?.length)
+            disallowed.push("npm");
+        if (environment.config.pip?.length)
+            disallowed.push("pip");
+        if (environment.config.apt?.length)
+            disallowed.push("apt");
+        if (Object.keys(environment.config.files ?? {}).length > 0)
+            disallowed.push("files");
+        if (environment.config.setup?.length)
+            disallowed.push("setup");
+        if (stepKind === "code" && Object.keys(environment.config.mcp ?? {}).length > 0)
+            disallowed.push("mcp");
+        if (disallowed.length > 0) {
+            const allowed = stepKind === "agent" ? "binaries or MCP servers" : "binaries";
+            errors.push({
+                stepId,
+                message: `device-hosted environments are verification-only and may only declare ${allowed}; remove ${disallowed.join(", ")}`,
+            });
+            return undefined;
+        }
+    }
+    const npm = sortedNonEmptyStrings(stepId, "npm", environment.config.npm, errors);
+    for (const spec of npm ?? []) {
+        if (!parseExactNpmPackage(spec)) {
+            errors.push({
+                stepId,
+                message: `environment npm package "${spec}" must include an exact semver version, e.g. name@1.2.3`,
+            });
+        }
+    }
+    const pip = sortedNonEmptyStrings(stepId, "pip", environment.config.pip, errors);
+    for (const spec of pip ?? []) {
+        if (!parseExactPipPackage(spec)) {
+            errors.push({
+                stepId,
+                message: `environment pip package "${spec}" must use an exact == version, e.g. name==1.2.3`,
+            });
+        }
+    }
+    const apt = sortedNonEmptyStrings(stepId, "apt", environment.config.apt, errors);
+    const binaries = sortedNonEmptyStrings(stepId, "binaries", environment.config.binaries, errors);
+    const setup = environment.config.setup?.filter((cmd) => {
+        if (typeof cmd === "string" && cmd.trim())
+            return true;
+        errors.push({ stepId, message: "environment setup entries must be non-empty strings" });
+        return false;
+    });
+    const files = lowerEnvironmentFiles(stepId, environment.config.files, options, errors);
+    const mcp = environment.config.mcp && Object.keys(environment.config.mcp).length > 0
+        ? Object.fromEntries(Object.entries(environment.config.mcp)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .flatMap(([name, server]) => {
+            if (!STEP_ID_PATTERN.test(name)) {
+                errors.push({
+                    stepId,
+                    message: `environment MCP server name "${name}" must match ${STEP_ID_PATTERN}`,
+                });
+                return [];
+            }
+            const lowered = normalizeMcpServer(stepId, name, server, errors);
+            return lowered ? [[name, lowered]] : [];
+        }))
+        : undefined;
+    const declaration = {
+        ...(npm !== undefined ? { npm } : {}),
+        ...(pip !== undefined ? { pip } : {}),
+        ...(apt !== undefined ? { apt } : {}),
+        ...(binaries !== undefined ? { binaries } : {}),
+        ...(files !== undefined ? { files } : {}),
+        ...(setup !== undefined && setup.length > 0 ? { setup } : {}),
+        ...(mcp !== undefined ? { mcp } : {}),
+    };
+    return { envHash: envHashFor(declaration), ...declaration };
+}
+function schemaToJson(schema, where, errors, stepId) {
+    try {
+        return toJsonSchema(schema);
+    }
+    catch (err) {
+        errors.push({
+            ...(stepId !== undefined ? { stepId } : {}),
+            message: `${where}: schema cannot convert to JSON Schema — ${err.message}`,
+        });
+        return {};
+    }
+}
+function maybeLowerEnvironment(stepId, environment, host, stepKind, errors, options) {
+    if (options.omitEnvironments)
+        return undefined;
+    return lowerEnvironment(stepId, environment, host, stepKind, errors, options);
+}
+function lowerCatalogTools(stepId, tools, errors) {
+    if (tools === undefined)
+        return [];
+    if (!Array.isArray(tools)) {
+        errors.push({ stepId, message: "agent tools must be an array of catalog action descriptors" });
+        return [];
+    }
+    const actionIds = [];
+    const seen = new Set();
+    for (const [index, value] of tools.entries()) {
+        const action = resolveCatalogActionDescriptor(value);
+        if (!action) {
+            errors.push({
+                stepId,
+                message: `agent tool at index ${index} must use a descriptor exported by @reasonlayer/sdk`,
+            });
+            continue;
+        }
+        if (seen.has(action.id))
+            continue;
+        seen.add(action.id);
+        actionIds.push(action.id);
+    }
+    return actionIds;
+}
+function lowerExecutableStep(args) {
+    const irStepId = args.irStepId ?? args.stepId;
+    if (!args.config.host) {
+        args.errors.push({
+            stepId: args.stepId,
+            message: args.missingHostMessage ?? `${args.kind} steps require a host`,
+        });
+        return undefined;
+    }
+    if (args.config.host.kind === "device" && !args.config.host.handle) {
+        args.errors.push({
+            stepId: args.stepId,
+            message: `${args.kind} device hosts require a handle`,
+        });
+    }
+    if (args.config.browserProfile !== undefined) {
+        if (!args.config.browserProfile.trim()) {
+            args.errors.push({ stepId: args.stepId, message: "browserProfile must be a non-empty string" });
+        }
+        if (args.config.host.kind !== "device") {
+            args.errors.push({ stepId: args.stepId, message: "browserProfile requires a device host" });
+        }
+    }
+    args.checkAtLeastOne(args.stepId, args.config.retries?.maxAttempts, args.retriesLabel ?? "retries.maxAttempts");
+    const secrets = secretNames(args.config.secrets);
+    const environment = maybeLowerEnvironment(args.stepId, args.config.environment, args.config.host, args.kind, args.errors, args.options);
+    const catalogTools = args.kind === "agent" ? lowerCatalogTools(args.stepId, args.config.tools, args.errors) : undefined;
+    const base = {
+        id: irStepId,
+        input: args.input,
+        outputSchemaJson: args.outputSchemaJson,
+        moduleRef: args.kind === "code" ? "steps.js" : "agents.js",
+        exportName: exportNameFor(irStepId),
+        host: args.config.host,
+        ...(args.config.browserProfile !== undefined
+            ? { browserProfile: args.config.browserProfile }
+            : {}),
+        ...(args.config.timeoutMs !== undefined ? { timeoutMs: args.config.timeoutMs } : {}),
+        ...(args.config.retries !== undefined ? { retries: args.config.retries } : {}),
+        ...(secrets !== undefined ? { secrets } : {}),
+        ...(environment !== undefined ? { environment } : {}),
+    };
+    return args.kind === "code"
+        ? { ...base, kind: "code" }
+        : { ...base, kind: "agent", framework: "flue", catalogTools: catalogTools };
+}
+export function compileWorkflow(definition, options = {}) {
+    const errors = [];
+    const { config, steps } = definition;
+    const devices = [];
+    const declaredDeviceHandles = new Set();
+    for (const ref of config.devices ?? []) {
+        const handle = ref.__rlDeviceHandle;
+        if (typeof handle !== "string" || !STEP_ID_PATTERN.test(handle)) {
+            errors.push({ message: `device handle "${String(handle)}" must match ${STEP_ID_PATTERN}` });
+            continue;
+        }
+        if (declaredDeviceHandles.has(handle)) {
+            errors.push({ message: `duplicate device handle "${handle}"` });
+            continue;
+        }
+        declaredDeviceHandles.add(handle);
+        devices.push({ kind: "device", handle });
+    }
+    const secrets = [];
+    const declaredSecretNames = new Set();
+    for (const ref of config.secrets ?? []) {
+        const name = ref.__rlSecret;
+        if (typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)) {
+            errors.push({ message: `secret name "${String(name)}" must match /^[A-Z_][A-Z0-9_]*$/` });
+            continue;
+        }
+        if (declaredSecretNames.has(name)) {
+            errors.push({ message: `duplicate secret handle "${name}"` });
+            continue;
+        }
+        declaredSecretNames.add(name);
+        secrets.push({ kind: "secret", name });
+    }
+    const triggers = [];
+    const triggerNames = new Set();
+    for (const trigger of config.triggers ?? []) {
+        if (!STEP_ID_PATTERN.test(trigger.name)) {
+            errors.push({ message: `trigger name "${trigger.name}" must match ${STEP_ID_PATTERN}` });
+            continue;
+        }
+        if (triggerNames.has(trigger.name)) {
+            errors.push({ message: `duplicate trigger name "${trigger.name}"` });
+            continue;
+        }
+        triggerNames.add(trigger.name);
+        const timezone = trigger.timezone ?? "UTC";
+        try {
+            validateSchedule(trigger.cron, timezone);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push({
+                message: `trigger "${trigger.name}" has invalid schedule in timezone "${timezone}": ${message}`,
+            });
+            continue;
+        }
+        triggers.push({
+            kind: "schedule",
+            name: trigger.name,
+            cron: trigger.cron,
+            timezone,
+        });
+    }
+    if (!config.id || !STEP_ID_PATTERN.test(config.id)) {
+        errors.push({ message: `workflow id "${config.id}" must match ${STEP_ID_PATTERN}` });
+    }
+    const inputSchemaErrorCount = errors.length;
+    const inputSchemaJson = schemaToJson(config.input, "workflow input", errors);
+    const inputSchemaValid = errors.length === inputSchemaErrorCount;
+    const outputSchemaJson = schemaToJson(config.output, "workflow output", errors);
+    const irSteps = {};
+    const codeRefs = {};
+    const agentRefs = {};
+    const knownIds = [];
+    const stepSchemas = Object.create(null);
+    const invalidStepSchemas = new Set();
+    const runWiring = (stepId, wiring) => {
+        if (!wiring)
+            return { kind: "input", path: [] };
+        try {
+            return lower(wiring(stepsProxy(knownIds), inputProxy()));
+        }
+        catch (err) {
+            if (err instanceof WiringError) {
+                errors.push({ stepId, message: err.message });
+                return { kind: "literal", value: null };
+            }
+            throw err;
+        }
+    };
+    const checkSelector = (stepId, selector, mapScope) => {
+        for (const ref of referencedStepIds(selector)) {
+            if (!knownIds.includes(ref)) {
+                errors.push({ stepId, message: `selector references undeclared step "${ref}"` });
+            }
+        }
+        for (const name of new Set(collectVariableNames(selector))) {
+            if (!variableDefinitionForCompile(name)) {
+                errors.push({
+                    stepId,
+                    message: `variable "${name}" is referenced but not defined via defineVariable()`,
+                });
+            }
+        }
+        if (!mapScope && usesMapItem(selector)) {
+            errors.push({ stepId, message: "mapItem is only valid inside a map step's child" });
+        }
+    };
+    const selectorSourcesAreUsable = (selector, mapItemSchema) => {
+        switch (selector.kind) {
+            case "input":
+                return inputSchemaValid;
+            case "step":
+                return (Object.prototype.hasOwnProperty.call(stepSchemas, selector.stepId) &&
+                    !invalidStepSchemas.has(selector.stepId));
+            case "variable":
+                return variableDefinitionForCompile(selector.name) !== undefined;
+            case "mapItem":
+                return mapItemSchema !== undefined;
+            case "object":
+                return Object.values(selector.fields).every((field) => selectorSourcesAreUsable(field, mapItemSchema));
+            case "array":
+                return selector.items.every((item) => selectorSourcesAreUsable(item, mapItemSchema));
+            case "literal":
+                return true;
+        }
+    };
+    const checkReviewCompatibility = (stepId, input, outputSchema, mapItemSchema) => {
+        if (!selectorSourcesAreUsable(input, mapItemSchema))
+            return;
+        const context = {
+            inputSchema: inputSchemaJson,
+            stepSchemas,
+            variableSchemas: variableSchemasFor([input]),
+            ...(mapItemSchema !== undefined ? { mapItemSchema } : {}),
+        };
+        const mismatches = checkSelectorSatisfiesSchema(input, outputSchema, context);
+        if (mismatches.length === 0)
+            return;
+        const conclusiveMismatches = mismatches.filter((mismatch) => !mismatch.startsWith("compatibility cannot be proven"));
+        const detail = (conclusiveMismatches.length > 0 ? conclusiveMismatches : mismatches)
+            .slice(0, 5)
+            .join("; ");
+        const guidance = "Review steps approve or edit their input; select an output-shaped value (e.g. { send: steps.draft.emails }).";
+        if (conclusiveMismatches.length === 0) {
+            errors.push({
+                stepId,
+                message: `review input compatibility cannot be proven — ${detail.replace(/^compatibility cannot be proven\s*/, "")}. ${guidance}`,
+            });
+            return;
+        }
+        errors.push({
+            stepId,
+            message: `review input does not satisfy the review output schema — ${detail}. ${guidance}`,
+        });
+    };
+    const checkAtLeastOne = (stepId, value, label) => {
+        if (value !== undefined && value < 1) {
+            errors.push({ stepId, message: `${label} must be ≥ 1` });
+        }
+    };
+    const lowerChild = (mapId, child, mapItemSchema) => {
+        const childId = mapChildId(mapId);
+        const cfg = child.config;
+        const inputErrorCount = errors.length;
+        let input;
+        try {
+            input = lower(cfg.input);
+        }
+        catch (err) {
+            if (err instanceof WiringError) {
+                errors.push({ stepId: mapId, message: `map child input: ${err.message}` });
+                return undefined;
+            }
+            throw err;
+        }
+        checkSelector(mapId, input, true);
+        const inputValid = errors.length === inputErrorCount;
+        const outputSchemaErrorCount = errors.length;
+        const outputJson = schemaToJson(cfg.output, "map child output", errors, mapId);
+        const outputSchemaValid = errors.length === outputSchemaErrorCount;
+        if (child.__rlChildStep === "review") {
+            const review = cfg;
+            if (inputValid && outputSchemaValid) {
+                checkReviewCompatibility(mapId, input, outputJson, mapItemSchema);
+            }
+            checkAtLeastOne(mapId, review.deadlineMs, "map child: deadlineMs");
+            return {
+                step: {
+                    kind: "review",
+                    id: childId,
+                    input,
+                    outputSchemaJson: outputJson,
+                    view: review.view ?? { kind: "json" },
+                    ...(review.deadlineMs !== undefined ? { deadlineMs: review.deadlineMs } : {}),
+                },
+                outputSchemaJson: outputJson,
+                outputSchemaValid,
+            };
+        }
+        const common = cfg;
+        const childKind = child.__rlChildStep === "code" ? "code" : "agent";
+        const lowered = lowerExecutableStep({
+            stepId: mapId,
+            irStepId: childId,
+            kind: childKind,
+            input,
+            outputSchemaJson: outputJson,
+            config: common,
+            errors,
+            options,
+            checkAtLeastOne,
+            missingHostMessage: "map child: executable steps require a host",
+            retriesLabel: "map child: retries.maxAttempts",
+        });
+        if (!lowered)
+            return { outputSchemaJson: outputJson, outputSchemaValid };
+        if (child.__rlChildStep === "code") {
+            codeRefs[childId] = cfg.run;
+            return { step: lowered, outputSchemaJson: outputJson, outputSchemaValid };
+        }
+        agentRefs[childId] = cfg.agent;
+        return { step: lowered, outputSchemaJson: outputJson, outputSchemaValid };
+    };
+    for (const def of steps) {
+        if (!STEP_ID_PATTERN.test(def.id)) {
+            errors.push({
+                stepId: def.id,
+                message: `step id "${def.id}" must match ${STEP_ID_PATTERN} (":" is reserved for map children)`,
+            });
+        }
+        if (knownIds.includes(def.id)) {
+            errors.push({ stepId: def.id, message: "duplicate step id" });
+            continue;
+        }
+        switch (def.kind) {
+            case "code": {
+                const cfg = def.config;
+                const input = runWiring(def.id, cfg.input);
+                checkSelector(def.id, input, false);
+                const schemaErrorCount = errors.length;
+                const stepOutputSchema = schemaToJson(cfg.output, "step output", errors, def.id);
+                stepSchemas[def.id] = stepOutputSchema;
+                if (errors.length !== schemaErrorCount)
+                    invalidStepSchemas.add(def.id);
+                const lowered = lowerExecutableStep({
+                    stepId: def.id,
+                    kind: "code",
+                    input,
+                    outputSchemaJson: stepOutputSchema,
+                    config: cfg,
+                    errors,
+                    options,
+                    checkAtLeastOne,
+                });
+                if (lowered) {
+                    codeRefs[def.id] = cfg.run;
+                    irSteps[def.id] = lowered;
+                }
+                break;
+            }
+            case "agent": {
+                const cfg = def.config;
+                const input = runWiring(def.id, cfg.input);
+                checkSelector(def.id, input, false);
+                const schemaErrorCount = errors.length;
+                const stepOutputSchema = schemaToJson(cfg.output, "step output", errors, def.id);
+                stepSchemas[def.id] = stepOutputSchema;
+                if (errors.length !== schemaErrorCount)
+                    invalidStepSchemas.add(def.id);
+                const lowered = lowerExecutableStep({
+                    stepId: def.id,
+                    kind: "agent",
+                    input,
+                    outputSchemaJson: stepOutputSchema,
+                    config: cfg,
+                    errors,
+                    options,
+                    checkAtLeastOne,
+                });
+                if (lowered) {
+                    agentRefs[def.id] = cfg.agent;
+                    irSteps[def.id] = lowered;
+                }
+                break;
+            }
+            case "action": {
+                const cfg = def.config;
+                const action = resolveCatalogActionDescriptor(cfg.action);
+                if (!action) {
+                    errors.push({
+                        stepId: def.id,
+                        message: "action must use a descriptor exported by @reasonlayer/sdk",
+                    });
+                    break;
+                }
+                if (typeof cfg.input !== "function") {
+                    errors.push({ stepId: def.id, message: "action input wiring is required" });
+                    break;
+                }
+                const input = runWiring(def.id, cfg.input);
+                checkSelector(def.id, input, false);
+                checkAtLeastOne(def.id, cfg.timeoutMs, "timeoutMs");
+                checkAtLeastOne(def.id, cfg.retries?.maxAttempts, "retries.maxAttempts");
+                const actionStep = {
+                    kind: "action",
+                    id: def.id,
+                    actionId: action.id,
+                    actionVersion: action.version,
+                    input,
+                    inputSchemaJson: action.inputSchemaJson,
+                    outputSchemaJson: action.outputSchemaJson,
+                    ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
+                    ...(cfg.retries !== undefined ? { retries: cfg.retries } : {}),
+                };
+                stepSchemas[def.id] = action.outputSchemaJson;
+                irSteps[def.id] = actionStep;
+                break;
+            }
+            case "review": {
+                const cfg = def.config;
+                const inputErrorCount = errors.length;
+                const input = runWiring(def.id, cfg.input);
+                checkSelector(def.id, input, false);
+                const inputValid = errors.length === inputErrorCount;
+                const schemaErrorCount = errors.length;
+                const stepOutputSchema = schemaToJson(cfg.output, "step output", errors, def.id);
+                const outputSchemaValid = errors.length === schemaErrorCount;
+                stepSchemas[def.id] = stepOutputSchema;
+                if (!outputSchemaValid)
+                    invalidStepSchemas.add(def.id);
+                if (inputValid && outputSchemaValid) {
+                    checkReviewCompatibility(def.id, input, stepOutputSchema);
+                }
+                checkAtLeastOne(def.id, cfg.deadlineMs, "deadlineMs");
+                irSteps[def.id] = {
+                    kind: "review",
+                    id: def.id,
+                    input,
+                    outputSchemaJson: stepOutputSchema,
+                    view: cfg.view ?? { kind: "json" },
+                    ...(cfg.deadlineMs !== undefined ? { deadlineMs: cfg.deadlineMs } : {}),
+                };
+                break;
+            }
+            case "map": {
+                const cfg = def.config;
+                const overErrorCount = errors.length;
+                const over = runWiring(def.id, cfg.over);
+                checkSelector(def.id, over, false);
+                const overValid = errors.length === overErrorCount;
+                const mapItemResolution = overValid && selectorSourcesAreUsable(over)
+                    ? resolveSelectorArrayItemSchema(over, {
+                        inputSchema: inputSchemaJson,
+                        stepSchemas,
+                        variableSchemas: variableSchemasFor([over]),
+                    })
+                    : { issues: [] };
+                if (mapItemResolution.issues.length > 0) {
+                    errors.push({
+                        stepId: def.id,
+                        message: `map over: ${mapItemResolution.issues.slice(0, 5).join("; ")}`,
+                    });
+                }
+                let key = { kind: "mapItem", path: [] };
+                try {
+                    key = lower(cfg.key(mapItemProxy()));
+                }
+                catch (err) {
+                    if (err instanceof WiringError) {
+                        errors.push({ stepId: def.id, message: `map key: ${err.message}` });
+                    }
+                    else
+                        throw err;
+                }
+                if (key.kind !== "mapItem" && key.kind !== "variable") {
+                    errors.push({
+                        stepId: def.id,
+                        message: "map key must select a field off the item or use a variable that resolves to a string",
+                    });
+                }
+                checkSelector(def.id, key, true);
+                checkAtLeastOne(def.id, cfg.concurrency, "concurrency");
+                checkAtLeastOne(def.id, cfg.retries?.maxAttempts, "retries.maxAttempts");
+                const loweredChild = lowerChild(def.id, cfg.step(mapItemProxy()), mapItemResolution.schema);
+                if (!loweredChild)
+                    break;
+                stepSchemas[def.id] = { type: "array", items: loweredChild.outputSchemaJson };
+                if (!loweredChild.outputSchemaValid)
+                    invalidStepSchemas.add(def.id);
+                const child = loweredChild.step;
+                if (!child)
+                    break;
+                irSteps[def.id] = {
+                    kind: "map",
+                    id: def.id,
+                    over,
+                    key,
+                    step: child,
+                    ...(cfg.concurrency !== undefined ? { concurrency: cfg.concurrency } : {}),
+                    ...(cfg.retries !== undefined ? { retries: cfg.retries } : {}),
+                };
+                break;
+            }
+        }
+        knownIds.push(def.id);
+    }
+    let output = { kind: "input", path: [] };
+    try {
+        output = lower(definition.outputWiring(stepsProxy(knownIds), inputProxy()));
+    }
+    catch (err) {
+        if (err instanceof WiringError) {
+            errors.push({ message: `workflow output: ${err.message}` });
+        }
+        else
+            throw err;
+    }
+    checkSelector("(output)", output, false);
+    const referencedVariables = new Set(collectVariableNames(output));
+    for (const step of Object.values(irSteps)) {
+        for (const selector of stepSelectors(step)) {
+            for (const name of collectVariableNames(selector))
+                referencedVariables.add(name);
+        }
+    }
+    const variables = [...referencedVariables]
+        .sort((a, b) => a.localeCompare(b))
+        .flatMap((name) => {
+        const definition = variableDefinitionForCompile(name);
+        return definition ? [{ name, ...definition }] : [];
+    });
+    for (const step of Object.values(irSteps)) {
+        const executable = step.kind === "map" ? step.step : step;
+        if ((executable.kind === "code" || executable.kind === "agent") &&
+            executable.host.kind === "device" &&
+            !declaredDeviceHandles.has(executable.host.handle)) {
+            errors.push({
+                stepId: step.id,
+                message: `device handle "${executable.host.handle}" must be declared in workflow devices`,
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const ir = {
+        schemaVersion: 1,
+        id: config.id,
+        ...(config.description !== undefined ? { description: config.description } : {}),
+        ...(devices.length > 0 ? { devices } : {}),
+        ...(secrets.length > 0 ? { secrets } : {}),
+        ...(variables.length > 0 ? { variables } : {}),
+        ...(triggers.length > 0 ? { triggers } : {}),
+        inputSchemaJson,
+        outputSchemaJson,
+        steps: irSteps,
+        output,
+    };
+    return { ok: true, ir, codeRefs, agentRefs };
+}