@atom-workflow-agent/workflow-compiler 0.1.0

package/dist/compiler/compile-workflow.js

@@ -0,0 +1,865 @@
+import { AtomManifestSchema, classifyReferenceLikeString, RuntimePolicySchema, WorkflowReferenceSchema, WorkflowSpecSchema, atomKey, } from "@atom-workflow-agent/contracts";
+import { WorkflowCompilationError, sortValidationErrors } from "../errors/workflow-compilation-error.js";
+import { canonicalize, contentHash, freezeDeep } from "../normalization/canonical-json.js";
+import { validateControlGraph } from "../validation/control-graph.js";
+import { validateGraph } from "../validation/graph.js";
+import { childSchemaForProperty, inferSchema, itemSchema, requiredProperties, requiredPropertiesForValue, resolveSchemaPath, schemaPathGuaranteed, schemaAcceptsLiteral, schemasCompatible, schemaTypes, } from "../validation/json-schema.js";
+import { isReferenceCandidate, parseWorkflowReference, valueAtPath, } from "../validation/references.js";
+function zodPath(path, prefix = "$.") {
+    let result = prefix.endsWith(".") ? prefix.slice(0, -1) : prefix;
+    for (const segment of path) {
+        if (typeof segment === "number")
+            result += `[${segment}]`;
+        else if (typeof segment === "string" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(segment))
+            result += `.${segment}`;
+        else
+            result += `[${JSON.stringify(String(segment))}]`;
+    }
+    return result;
+}
+function schemaErrors(raw) {
+    let candidate = raw;
+    if (typeof raw === "string") {
+        try {
+            candidate = JSON.parse(raw);
+        }
+        catch (error) {
+            return { errors: [{ code: "WORKFLOW_JSON_INVALID", path: "$", message: error instanceof Error ? error.message : "Workflow JSON could not be parsed" }] };
+        }
+    }
+    const result = WorkflowSpecSchema.safeParse(candidate);
+    if (result.success)
+        return { spec: result.data, errors: [] };
+    return {
+        errors: result.error.issues.map((issue) => ({
+            code: "WORKFLOW_SCHEMA_INVALID",
+            path: zodPath(issue.path),
+            message: issue.message,
+        })),
+    };
+}
+function parsePolicy(input) {
+    const result = RuntimePolicySchema.safeParse(input ?? {});
+    if (result.success)
+        return result.data;
+    return result.error.issues.map((issue) => ({
+        code: "RUNTIME_POLICY_INVALID",
+        path: zodPath(issue.path, "$.runtimePolicy."),
+        message: issue.message,
+    }));
+}
+function buildCatalog(entries, errors) {
+    const catalog = new Map();
+    entries.forEach((entry, index) => {
+        const parsed = AtomManifestSchema.safeParse(entry.manifest);
+        if (!parsed.success) {
+            errors.push({ code: "ATOM_CATALOG_INVALID", path: `$.atomCatalog[${index}].manifest`, message: "Atom catalog contains an invalid Manifest" });
+            return;
+        }
+        const key = atomKey(parsed.data);
+        if (catalog.has(key)) {
+            errors.push({ code: "ATOM_CATALOG_DUPLICATE", path: `$.atomCatalog[${index}]`, message: `Atom catalog contains a duplicate exact version: ${key}`, atomId: parsed.data.id });
+            return;
+        }
+        catalog.set(key, { manifest: parsed.data, enabled: entry.enabled });
+    });
+    return catalog;
+}
+function splitAtomReference(reference) {
+    const separator = reference.lastIndexOf("@");
+    return { id: reference.slice(0, separator), version: reference.slice(separator + 1) };
+}
+function mergePolicy(manifest, node, policy) {
+    const retryOverride = node.policy?.retry;
+    const retry = {
+        maxAttempts: retryOverride?.maxAttempts ?? manifest.defaults.retry.maxAttempts,
+        strategy: retryOverride?.strategy ?? manifest.defaults.retry.strategy,
+        baseDelayMs: retryOverride?.baseDelayMs ?? manifest.defaults.retry.baseDelayMs,
+        maxDelayMs: retryOverride?.maxDelayMs ?? manifest.defaults.retry.maxDelayMs,
+        jitter: retryOverride?.jitter ?? manifest.defaults.retry.jitter,
+    };
+    const cacheOverride = node.policy?.cache;
+    const rawCache = {
+        enabled: cacheOverride?.enabled ?? manifest.defaults.cache.enabled,
+        ...(cacheOverride?.ttlMs !== undefined
+            ? { ttlMs: cacheOverride.ttlMs }
+            : manifest.defaults.cache.ttlMs !== undefined ? { ttlMs: manifest.defaults.cache.ttlMs } : {}),
+    };
+    const attemptTimeoutMs = node.policy?.attemptTimeoutMs ?? manifest.defaults.timeoutMs ?? null;
+    const lifecycleTickTimeoutMs = node.policy?.lifecycleTickTimeoutMs
+        ?? node.policy?.attemptTimeoutMs
+        ?? manifest.defaults.timeoutMs
+        ?? null;
+    return {
+        attemptTimeoutMs,
+        lifecycleTickTimeoutMs,
+        maxLifecycleTicks: node.policy?.maxLifecycleTicks ?? policy.maxLifecycleTicks,
+        retry,
+        cache: rawCache.enabled ? rawCache : { enabled: false },
+    };
+}
+function validateNodePolicies(spec, catalog, policy, errors) {
+    const resolved = new Map();
+    if (spec.nodes.length > policy.maxNodes) {
+        errors.push({ code: "NODE_LIMIT_EXCEEDED", path: "$.nodes", message: `Workflow has ${spec.nodes.length} nodes but Runtime Policy allows ${policy.maxNodes}`, expected: policy.maxNodes, received: spec.nodes.length });
+    }
+    spec.nodes.forEach((node, index) => {
+        const path = `$.nodes[${index}]`;
+        if (node.dependsOn.length > policy.maxDependenciesPerNode) {
+            errors.push({ code: "DEPENDENCY_LIMIT_EXCEEDED", path: `${path}.dependsOn`, message: "Node dependency count exceeds Runtime Policy", expected: policy.maxDependenciesPerNode, received: node.dependsOn.length });
+        }
+        if (node.kind === "merge")
+            return;
+        const entry = catalog.get(node.atom);
+        const atomReference = splitAtomReference(node.atom);
+        if (!entry) {
+            errors.push({ code: "ATOM_NOT_FOUND", path: `${path}.atom`, message: `No registered Atom matches exact reference: ${node.atom}`, atomId: atomReference.id, received: node.atom });
+            return;
+        }
+        if (!entry.enabled) {
+            errors.push({ code: "ATOM_UNAVAILABLE", path: `${path}.atom`, message: `Atom is registered but not enabled: ${node.atom}`, atomId: atomReference.id, received: node.atom });
+            return;
+        }
+        const manifest = entry.manifest;
+        if (manifest.status === "deprecated" && !policy.allowDeprecatedAtoms) {
+            errors.push({ code: "DEPRECATED_ATOM_FORBIDDEN", path: `${path}.atom`, message: `Deprecated Atom is forbidden by Runtime Policy: ${node.atom}`, atomId: manifest.id });
+        }
+        const effectivePolicy = mergePolicy(manifest, node, policy);
+        if (policy.maxAttemptDurationMs !== null
+            && (effectivePolicy.attemptTimeoutMs === null || effectivePolicy.attemptTimeoutMs > policy.maxAttemptDurationMs)) {
+            errors.push({ code: "ATTEMPT_TIMEOUT_LIMIT_EXCEEDED", path: `${path}.policy.attemptTimeoutMs`, message: "Attempt timeout exceeds Runtime Policy", expected: policy.maxAttemptDurationMs, received: effectivePolicy.attemptTimeoutMs });
+        }
+        const tickExceedsRuntime = policy.maxLifecycleTickTimeoutMs !== null
+            && (effectivePolicy.lifecycleTickTimeoutMs === null || effectivePolicy.lifecycleTickTimeoutMs > policy.maxLifecycleTickTimeoutMs);
+        const tickExceedsAttempt = effectivePolicy.attemptTimeoutMs !== null
+            && (effectivePolicy.lifecycleTickTimeoutMs === null || effectivePolicy.lifecycleTickTimeoutMs > effectivePolicy.attemptTimeoutMs);
+        if (tickExceedsRuntime || tickExceedsAttempt) {
+            const limits = [policy.maxLifecycleTickTimeoutMs, effectivePolicy.attemptTimeoutMs]
+                .filter((value) => value !== null);
+            errors.push({ code: "LIFECYCLE_TICK_TIMEOUT_LIMIT_EXCEEDED", path: `${path}.policy.lifecycleTickTimeoutMs`, message: "Lifecycle tick timeout exceeds its Runtime or Attempt budget", expected: limits.length > 0 ? Math.min(...limits) : null, received: effectivePolicy.lifecycleTickTimeoutMs });
+        }
+        if (effectivePolicy.maxLifecycleTicks > policy.maxLifecycleTicks) {
+            errors.push({ code: "LIFECYCLE_TICK_LIMIT_EXCEEDED", path: `${path}.policy.maxLifecycleTicks`, message: "Lifecycle tick count exceeds Runtime Policy", expected: policy.maxLifecycleTicks, received: effectivePolicy.maxLifecycleTicks });
+        }
+        if (effectivePolicy.retry.maxAttempts > policy.maxRetryAttempts) {
+            errors.push({ code: "RETRY_LIMIT_EXCEEDED", path: `${path}.policy.retry.maxAttempts`, message: "Effective retry attempts exceed Runtime Policy", expected: policy.maxRetryAttempts, received: effectivePolicy.retry.maxAttempts });
+        }
+        if (effectivePolicy.retry.baseDelayMs > policy.maxRetryDelayMs || effectivePolicy.retry.maxDelayMs > policy.maxRetryDelayMs) {
+            errors.push({ code: "RETRY_DELAY_LIMIT_EXCEEDED", path: `${path}.policy.retry`, message: "Effective retry delay exceeds Runtime Policy", expected: policy.maxRetryDelayMs, received: effectivePolicy.retry.maxDelayMs });
+        }
+        if (effectivePolicy.retry.maxDelayMs < effectivePolicy.retry.baseDelayMs) {
+            errors.push({ code: "RETRY_POLICY_INVALID", path: `${path}.policy.retry.maxDelayMs`, message: "Effective maxDelayMs must be greater than or equal to baseDelayMs", expected: effectivePolicy.retry.baseDelayMs, received: effectivePolicy.retry.maxDelayMs });
+        }
+        if (!manifest.idempotent && effectivePolicy.retry.maxAttempts > 1) {
+            errors.push({ code: "NON_IDEMPOTENT_RETRY_FORBIDDEN", path: `${path}.policy.retry.maxAttempts`, message: "A non-idempotent Atom cannot be automatically retried", atomId: manifest.id, expected: 1, received: effectivePolicy.retry.maxAttempts });
+        }
+        if (effectivePolicy.cache.enabled && effectivePolicy.cache.ttlMs !== undefined && effectivePolicy.cache.ttlMs > policy.maxCacheTtlMs) {
+            errors.push({ code: "CACHE_TTL_LIMIT_EXCEEDED", path: `${path}.policy.cache.ttlMs`, message: "Effective cache TTL exceeds Runtime Policy", expected: policy.maxCacheTtlMs, received: effectivePolicy.cache.ttlMs });
+        }
+        if (node.policy?.cache?.enabled === true && !manifest.defaults.cache.enabled && !policy.allowCacheEnableOverride) {
+            errors.push({ code: "CACHE_ENABLE_OVERRIDE_FORBIDDEN", path: `${path}.policy.cache.enabled`, message: "Runtime Policy does not allow enabling cache for this Atom", atomId: manifest.id });
+        }
+        const mapMaxItems = node.map?.maxItems;
+        if (mapMaxItems !== undefined && mapMaxItems > policy.maxMapItems) {
+            errors.push({ code: "MAP_LIMIT_EXCEEDED", path: `${path}.map.maxItems`, message: "Map maxItems exceeds Runtime Policy", expected: policy.maxMapItems, received: mapMaxItems });
+        }
+        if (node.map && node.map.maxConcurrency > policy.maxNodeActivations) {
+            errors.push({ code: "MAP_LIMIT_EXCEEDED", path: `${path}.map.maxConcurrency`, message: "Map maxConcurrency exceeds the Runtime node activation policy", expected: policy.maxNodeActivations, received: node.map.maxConcurrency });
+        }
+        if (!resolved.has(node.id))
+            resolved.set(node.id, { manifest, effectivePolicy });
+    });
+    return resolved;
+}
+function nodeOutputSchema(spec, resolvedByNode, nodeId) {
+    const node = spec.nodes.find((candidate) => candidate.id === nodeId);
+    if (!node)
+        return undefined;
+    return node.kind === "merge" ? node.outputSchema : resolvedByNode.get(nodeId)?.manifest.outputSchema;
+}
+function referenceErrorCode(context, fallback) {
+    if (context.scope === "branch-merge-input") {
+        return fallback.startsWith("REFERENCE") ? "BRANCH_MERGE_SOURCE_INVALID" : "BRANCH_MERGE_INPUT_MISSING";
+    }
+    return context.scope === "edge-input" ? "EDGE_INPUT_SCHEMA_MISMATCH" : fallback;
+}
+function resolveReference(reference, path, context) {
+    const parsed = parseWorkflowReference(reference);
+    if (parsed.kind === "workflow-input") {
+        const result = valueAtPath(context.spec.inputs, parsed.path);
+        if (!result.found) {
+            context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Workflow input reference does not exist: ${reference.$ref}`, received: reference.$ref });
+            return undefined;
+        }
+        return { kind: "literal", value: result.value };
+    }
+    if (parsed.kind === "map-index" || parsed.kind === "map-item") {
+        if (context.node.kind === "merge" || !context.node.map || !context.mapItem) {
+            context.errors.push({ code: "MAP_REFERENCE_OUTSIDE_MAP", path, message: `${reference.$ref} can only be used by a Map processor node`, received: reference.$ref });
+            return undefined;
+        }
+        if (parsed.kind === "map-index")
+            return { kind: "schema", schema: { type: "integer", minimum: 0 }, root: { type: "integer" }, guaranteed: true };
+        if (context.mapItem.kind === "literal") {
+            const result = valueAtPath(context.mapItem.value, parsed.path);
+            if (!result.found) {
+                context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Map item reference cannot be resolved: ${reference.$ref}` });
+                return undefined;
+            }
+            return { kind: "literal", value: result.value };
+        }
+        const nested = resolveSchemaPath(context.mapItem.schema, parsed.path, context.mapItem.root);
+        if (nested === undefined) {
+            context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Map item Schema path does not exist: ${reference.$ref}` });
+            return undefined;
+        }
+        const guaranteed = context.mapItem.guaranteed && schemaPathGuaranteed(context.mapItem.schema, parsed.path, context.mapItem.root);
+        if (!guaranteed)
+            context.errors.push({
+                code: "REFERENCE_SOURCE_OPTIONAL", path,
+                message: `Reference source path is optional and may be absent at runtime: ${reference.$ref}`,
+                received: reference.$ref,
+                hint: "Omit this binding, provide a guaranteed Workflow input, or use explicit control flow that produces a required branch result",
+            });
+        return { kind: "schema", schema: nested, root: context.mapItem.root, guaranteed };
+    }
+    if (parsed.kind === "edge-source-output") {
+        if ((context.scope !== "edge-input" && context.scope !== "branch-merge-input" && context.scope !== "decision-select") || !context.edgeSourceNodeId) {
+            context.errors.push({ code: "EDGE_REFERENCE_OUTSIDE_EDGE", path, message: "node.output is only valid inside an Edge with or DecisionNode select", received: reference.$ref });
+            return undefined;
+        }
+        const sourceSchema = nodeOutputSchema(context.spec, context.resolvedByNode, context.edgeSourceNodeId);
+        const nested = sourceSchema && resolveSchemaPath(sourceSchema, parsed.path, sourceSchema);
+        if (nested === undefined) {
+            context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Edge source output Schema path does not exist: ${reference.$ref}` });
+            return undefined;
+        }
+        const guaranteed = schemaPathGuaranteed(sourceSchema, parsed.path, sourceSchema);
+        if (!guaranteed)
+            context.errors.push({
+                code: "REFERENCE_SOURCE_OPTIONAL", path,
+                message: `Reference source path is optional and may be absent at runtime: ${reference.$ref}`,
+                received: reference.$ref,
+                hint: "Omit this binding or route a required value through the selected control edge",
+            });
+        return { kind: "schema", schema: nested, root: sourceSchema, guaranteed };
+    }
+    if (parsed.kind === "activation-output") {
+        if (context.scope !== "workflow-output") {
+            context.errors.push({ code: "WORKFLOW_OUTPUT_REFERENCE_INVALID", path, message: "Activation selectors are only valid in Workflow outputs", received: reference.$ref });
+            return undefined;
+        }
+        const sourceSchema = nodeOutputSchema(context.spec, context.resolvedByNode, parsed.nodeId);
+        const nested = sourceSchema && resolveSchemaPath(sourceSchema, parsed.path, sourceSchema);
+        if (nested === undefined) {
+            context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Activation output Schema path does not exist: ${reference.$ref}`, received: reference.$ref });
+            return undefined;
+        }
+        const sourceNode = context.spec.nodes.find((node) => node.id === parsed.nodeId);
+        if (sourceNode?.kind !== "merge" && sourceNode?.map) {
+            const schema = { type: "array", items: nested };
+            return { kind: "schema", schema, root: schema, guaranteed: true };
+        }
+        const guaranteed = schemaPathGuaranteed(sourceSchema, parsed.path, sourceSchema);
+        if (!guaranteed)
+            context.errors.push({
+                code: "REFERENCE_SOURCE_OPTIONAL", path,
+                message: `Workflow output references an optional source path: ${reference.$ref}`,
+                received: reference.$ref,
+                hint: "Publish a guaranteed output or merge branch-local values into a required result field",
+            });
+        return { kind: "schema", schema: nested, root: sourceSchema, guaranteed };
+    }
+    const outputSchema = nodeOutputSchema(context.spec, context.resolvedByNode, parsed.nodeId);
+    if (!outputSchema) {
+        context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Dependency output does not exist: ${reference.$ref}`, received: reference.$ref });
+        return undefined;
+    }
+    // Edge overlays are evaluated while routing the source activation. Their
+    // dependency references therefore belong to the edge source's lineage, not
+    // to the target node that will receive the resolved overlay.
+    const targetCanRead = parsed.nodeId === context.node.id || context.graph.ancestors.get(context.node.id)?.has(parsed.nodeId);
+    const edgeSourceCanRead = (context.scope === "edge-input" || context.scope === "branch-merge-input") && context.edgeSourceNodeId !== undefined
+        && (parsed.nodeId === context.edgeSourceNodeId || context.graph.ancestors.get(context.edgeSourceNodeId)?.has(parsed.nodeId));
+    if (!targetCanRead && !edgeSourceCanRead) {
+        context.errors.push({ code: "REFERENCE_NOT_DEPENDENCY", path, message: `Output must come from an explicit dependency activation: ${reference.$ref}`, received: parsed.nodeId });
+    }
+    const nested = resolveSchemaPath(outputSchema, parsed.path, outputSchema);
+    if (nested === undefined) {
+        context.errors.push({ code: "REFERENCE_NOT_FOUND", path, message: `Dependency output Schema path does not exist: ${reference.$ref}`, received: reference.$ref });
+        return undefined;
+    }
+    const sourceNode = context.spec.nodes.find((node) => node.id === parsed.nodeId);
+    const sourceGroup = sourceNode?.kind !== "merge" ? sourceNode?.map?.group ?? (sourceNode?.map ? sourceNode.id : undefined) : undefined;
+    const targetGroup = context.node.kind !== "merge" ? context.node.map?.group ?? (context.node.map ? context.node.id : undefined) : undefined;
+    if (sourceGroup && sourceGroup !== targetGroup) {
+        const schema = { type: "array", items: nested };
+        return { kind: "schema", schema, root: schema, guaranteed: true };
+    }
+    const guaranteed = schemaPathGuaranteed(outputSchema, parsed.path, outputSchema);
+    if (!guaranteed)
+        context.errors.push({
+            code: "REFERENCE_SOURCE_OPTIONAL", path,
+            message: `Reference source path is optional and may be absent at runtime: ${reference.$ref}`,
+            received: reference.$ref,
+            hint: "Omit this binding, provide a guaranteed Workflow input, or use explicit control flow that produces a required branch result",
+        });
+    return { kind: "schema", schema: nested, root: outputSchema, guaranteed };
+}
+function sourceCompatible(source, target, targetRoot) {
+    return source.kind === "literal"
+        ? schemaAcceptsLiteral(target, source.value, targetRoot)
+        : schemasCompatible(source.schema, target, source.root, targetRoot);
+}
+function validateBoundValue(value, target, targetRoot, path, context, checkRequired = true) {
+    if (typeof value === "string") {
+        const referenceKind = classifyReferenceLikeString(value);
+        if (referenceKind) {
+            context.errors.push({
+                code: referenceErrorCode(context, "REFERENCE_INVALID"),
+                path,
+                message: `Reference-like string cannot be used as a literal Workflow value: ${value}`,
+                received: value,
+                hint: referenceKind === "planner-draft"
+                    ? "PlannerDraft shorthand is not valid in WorkflowSpec; use a structured {\"$ref\":\"...\"} Workflow reference"
+                    : `Wrap the reference as {\"$ref\":${JSON.stringify(value)}}`,
+            });
+            return;
+        }
+    }
+    if (isReferenceCandidate(value)) {
+        const parsed = WorkflowReferenceSchema.safeParse(value);
+        if (!parsed.success) {
+            context.errors.push({ code: "REFERENCE_INVALID", path, message: "A binding must contain only a valid $ref", received: value });
+            return;
+        }
+        const source = resolveReference(parsed.data, path, context);
+        if (source && !sourceCompatible(source, target, targetRoot)) {
+            context.errors.push({ code: referenceErrorCode(context, "REFERENCE_TYPE_MISMATCH"), path, message: `Reference is incompatible with the target input Schema: ${parsed.data.$ref}`, received: parsed.data.$ref });
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)
+        && Object.keys(value).some((key) => key.startsWith("$"))) {
+        context.errors.push({
+            code: referenceErrorCode(context, "REFERENCE_INVALID"),
+            path,
+            message: "Unsupported reference directive object inside WorkflowSpec",
+            received: value,
+            hint: "Use one structured {\"$ref\":\"...\"} Workflow reference; pass reserved-key business data through a Workflow input instead of an inline literal",
+        });
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (!schemaTypes(target, targetRoot).has("array")) {
+            context.errors.push({ code: referenceErrorCode(context, "INPUT_SCHEMA_MISMATCH"), path, message: "Expected an array-compatible input", received: value });
+            return;
+        }
+        const nestedTarget = itemSchema(target, targetRoot) ?? true;
+        value.forEach((item, index) => validateBoundValue(item, nestedTarget, targetRoot, `${path}[${index}]`, context));
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        if (!schemaTypes(target, targetRoot).has("object")) {
+            context.errors.push({ code: referenceErrorCode(context, "INPUT_SCHEMA_MISMATCH"), path, message: "Expected an object-compatible input", received: value });
+            return;
+        }
+        if (checkRequired) {
+            for (const required of requiredPropertiesForValue(target, targetRoot, value)) {
+                if (!(required in value)) {
+                    context.errors.push({ code: referenceErrorCode(context, "INPUT_REQUIRED_PROPERTY_MISSING"), path: `${path}.${required}`, message: `Required input property is missing: ${required}`, expected: required });
+                }
+            }
+        }
+        for (const [key, nested] of Object.entries(value)) {
+            const nestedTarget = childSchemaForProperty(target, key, targetRoot);
+            if (nestedTarget === undefined) {
+                context.errors.push({ code: referenceErrorCode(context, "INPUT_ADDITIONAL_PROPERTY_FORBIDDEN"), path: `${path}.${key}`, message: `Atom input Schema does not allow property: ${key}`, received: key });
+            }
+            else {
+                validateBoundValue(nested, nestedTarget, targetRoot, `${path}.${key}`, context, true);
+            }
+        }
+        return;
+    }
+    if (!schemaAcceptsLiteral(target, value, targetRoot)) {
+        context.errors.push({ code: referenceErrorCode(context, "INPUT_SCHEMA_MISMATCH"), path, message: "Literal value is incompatible with Atom input Schema", received: value });
+    }
+}
+function sourceMustBeArray(source, path, errors) {
+    if (source.kind === "literal") {
+        if (!Array.isArray(source.value)) {
+            errors.push({ code: "MAP_ITEMS_NOT_ARRAY", path, message: "Map items must resolve to an array", received: source.value });
+            return undefined;
+        }
+        const inferred = inferSchema(source.value);
+        return { kind: "schema", schema: inferred, root: inferred, guaranteed: true };
+    }
+    if (!schemaTypes(source.schema, source.root).has("array")) {
+        errors.push({ code: "MAP_ITEMS_NOT_ARRAY", path, message: "Map items Schema must be an array" });
+        return undefined;
+    }
+    return { kind: "schema", schema: itemSchema(source.schema, source.root) ?? true, root: source.root, guaranteed: source.guaranteed };
+}
+function mergeEdgeInput(base, overlay) {
+    if (base !== null && typeof base === "object" && !Array.isArray(base))
+        return { ...base, ...overlay };
+    return Object.keys(overlay).length === 0 ? base : { ...overlay };
+}
+function validateReferencesAndInputs(spec, graph, control, resolvedByNode, errors) {
+    const nodeById = new Map(spec.nodes.map((node) => [node.id, node]));
+    const indexById = new Map(spec.nodes.map((node, index) => [node.id, index]));
+    const entry = new Set(spec.entry);
+    const mapItems = new Map();
+    for (const node of spec.nodes) {
+        const nodeIndex = indexById.get(node.id);
+        if (node.kind === "merge") {
+            if (entry.has(node.id)) {
+                const required = requiredProperties(node.outputSchema, node.outputSchema);
+                if (required.length > 0)
+                    errors.push({
+                        code: "BRANCH_MERGE_INPUT_MISSING", path: `$.nodes[${nodeIndex}]`,
+                        message: `Merge node ${node.id} cannot be an entry because its typed result requires incoming branch values`,
+                        expected: [...required],
+                    });
+            }
+            continue;
+        }
+        const resolved = resolvedByNode.get(node.id);
+        if (!resolved)
+            continue;
+        const baseContext = { node, nodeIndex, graph, resolvedByNode, spec, errors, scope: "node-input" };
+        let mapItem;
+        if (node.map) {
+            const source = resolveReference(node.map.items, `$.nodes[${nodeIndex}].map.items`, baseContext);
+            if (source)
+                mapItem = sourceMustBeArray(source, `$.nodes[${nodeIndex}].map.items`, errors);
+        }
+        if (mapItem)
+            mapItems.set(node.id, mapItem);
+        const context = mapItem ? { ...baseContext, mapItem } : baseContext;
+        validateBoundValue(node.input, resolved.manifest.inputSchema, resolved.manifest.inputSchema, `$.nodes[${nodeIndex}].input`, context, false);
+        if (entry.has(node.id)) {
+            validateBoundValue(node.input, resolved.manifest.inputSchema, resolved.manifest.inputSchema, `$.nodes[${nodeIndex}].input`, context, true);
+        }
+        if (node.kind === "decision") {
+            const selectContext = { ...context, scope: "decision-select", edgeSourceNodeId: node.id };
+            const source = resolveReference(node.select, `$.nodes[${nodeIndex}].select`, selectContext);
+            const stringSchema = { type: "string" };
+            if (source && !sourceCompatible(source, stringSchema, stringSchema)) {
+                errors.push({ code: "DECISION_SELECT_TYPE_MISMATCH", path: `$.nodes[${nodeIndex}].select`, message: "DecisionNode select must resolve to a string", received: node.select.$ref });
+            }
+            if (source?.kind === "schema" && source.schema !== true && source.schema !== false) {
+                const schemaObject = source.schema;
+                const enumValues = Array.isArray(schemaObject.enum) && schemaObject.enum.every((value) => typeof value === "string")
+                    ? [...schemaObject.enum]
+                    : undefined;
+                if (enumValues) {
+                    const declared = Object.keys(node.branches);
+                    const missing = enumValues.filter((value) => !declared.includes(value));
+                    const extra = declared.filter((value) => !enumValues.includes(value));
+                    if (missing.length > 0 || extra.length > 0) {
+                        errors.push({
+                            code: "DECISION_BRANCH_ENUM_MISMATCH",
+                            path: `$.nodes[${nodeIndex}].branches`,
+                            message: `Decision branches must exactly cover the enum selected by ${node.select.$ref}`,
+                            atomId: resolved.manifest.id,
+                            expected: [...enumValues].sort(),
+                            received: [...declared].sort(),
+                            hint: "Declare one frozen branch for every finite value of the selected Atom output field",
+                        });
+                    }
+                }
+            }
+        }
+    }
+    for (const edge of control.edges) {
+        for (const targetId of edge.targets) {
+            const target = nodeById.get(targetId);
+            if (!target)
+                continue;
+            const targetIndex = indexById.get(targetId);
+            if (target.kind === "merge") {
+                const context = {
+                    node: target, nodeIndex: targetIndex, graph, resolvedByNode, spec, errors,
+                    scope: "branch-merge-input", edgeSourceNodeId: edge.sourceNodeId,
+                };
+                validateBoundValue(edge.with, target.outputSchema, target.outputSchema, `$.nodes[${targetIndex}].incoming.${edge.id}.with`, context, true);
+                continue;
+            }
+            const resolved = resolvedByNode.get(targetId);
+            if (!resolved)
+                continue;
+            const merged = mergeEdgeInput(target.input, edge.with);
+            const context = {
+                node: target,
+                nodeIndex: targetIndex,
+                graph,
+                resolvedByNode,
+                spec,
+                errors,
+                scope: "edge-input",
+                edgeSourceNodeId: edge.sourceNodeId,
+                ...(mapItems.has(targetId) ? { mapItem: mapItems.get(targetId) } : {}),
+            };
+            const sourceIndex = indexById.get(edge.sourceNodeId);
+            const edgePath = edge.kind === "next" ? `$.nodes[${sourceIndex}].next` : edge.kind === "decision-default" ? `$.nodes[${sourceIndex}].default` : `$.nodes[${sourceIndex}].branches.${edge.branchId}`;
+            validateBoundValue(merged, resolved.manifest.inputSchema, resolved.manifest.inputSchema, `${edgePath}.with`, context, true);
+        }
+    }
+    const outputContextNode = spec.nodes[0];
+    const outputContext = {
+        node: outputContextNode,
+        nodeIndex: 0,
+        graph,
+        resolvedByNode,
+        spec,
+        errors,
+        scope: "workflow-output",
+    };
+    for (const [name, reference] of Object.entries(spec.outputs)) {
+        resolveReference(reference, `$.outputs.${name}`, outputContext);
+    }
+}
+function validateMapGroups(spec, control, errors) {
+    const groups = new Map();
+    spec.nodes.forEach((node, index) => {
+        if (node.kind === "merge" || !node.map)
+            return;
+        const group = node.map.group ?? node.id;
+        groups.set(group, [...(groups.get(group) ?? []), { node, index }]);
+    });
+    for (const [group, declarations] of groups) {
+        const first = declarations[0].node.map;
+        const expected = JSON.stringify(canonicalize({
+            items: first.items,
+            maxItems: first.maxItems,
+            maxConcurrency: first.maxConcurrency,
+        }));
+        for (const { node, index } of declarations.slice(1)) {
+            const current = node.map;
+            const received = JSON.stringify(canonicalize({
+                items: current.items,
+                maxItems: current.maxItems,
+                maxConcurrency: current.maxConcurrency,
+            }));
+            if (received !== expected)
+                errors.push({
+                    code: "MAP_GROUP_CONFIG_MISMATCH",
+                    path: `$.nodes[${index}].map`,
+                    message: `All processor nodes in Map group ${group} must declare identical items, maxItems and maxConcurrency`,
+                    expected: JSON.parse(expected),
+                    received: JSON.parse(received),
+                });
+        }
+        const body = new Set(declarations.map(({ node }) => node.id));
+        const exits = control.edges.filter((edge) => body.has(edge.sourceNodeId)
+            && (edge.terminal !== undefined || edge.targets.some((target) => !body.has(target))));
+        const descriptors = new Set(exits.map((edge) => JSON.stringify(canonicalize({
+            targets: edge.targets.filter((target) => !body.has(target)).sort(),
+            terminal: edge.terminal ?? null,
+            with: edge.with,
+            maxTraversals: edge.maxTraversals ?? null,
+            backEdge: edge.backEdge,
+        }))));
+        if (descriptors.size > 1)
+            errors.push({
+                code: "MAP_COMPLETION_CONFLICT",
+                path: `$.nodes[${declarations[0].index}].map`,
+                message: `Map processor ${group} has conflicting completion routes; route the aggregated Map output through one following DecisionNode`,
+                received: [...descriptors].map((descriptor) => JSON.parse(descriptor)),
+            });
+    }
+}
+function normalizeIR(spec, graph, control, resolvedByNode, policy) {
+    const mapIdByGroup = new Map();
+    for (const node of spec.nodes)
+        if (node.kind !== "merge" && node.map) {
+            const group = node.map.group ?? node.id;
+            mapIdByGroup.set(group, `__control-map-${group}`);
+        }
+    let nodes = [...spec.nodes].sort((a, b) => a.id.localeCompare(b.id)).map((node) => {
+        if (node.kind === "merge")
+            return canonicalize({
+                id: node.id,
+                kind: "merge",
+                dependsOn: [...node.dependsOn].sort(),
+                outputSchema: node.outputSchema,
+            });
+        const resolved = resolvedByNode.get(node.id);
+        const { id, version } = splitAtomReference(node.atom);
+        const mapGroup = node.map?.group ?? (node.map ? node.id : undefined);
+        return canonicalize({
+            id: node.id,
+            atom: { key: node.atom, id, version, manifest: resolved.manifest },
+            kind: "atom",
+            dependsOn: [...node.dependsOn].sort(),
+            input: node.input,
+            ...(mapGroup ? { mapScope: mapIdByGroup.get(mapGroup) } : {}),
+            ...(node.kind === "decision" ? { decisionBranches: Object.keys(node.branches).sort() } : {}),
+            effectivePolicy: resolved.effectivePolicy,
+        });
+    });
+    // DecisionNode is authoring sugar: execute its Atom, then route through a
+    // pure SwitchNode. Atom output can never inject a new target.
+    let edges = [];
+    for (const edge of control.edges) {
+        const source = spec.nodes.find((node) => node.id === edge.sourceNodeId);
+        if (source.kind !== "decision") {
+            edges.push(canonicalize({ ...edge, kind: "next", targets: [...edge.targets].sort() }));
+            continue;
+        }
+        const switchId = `__control-switch-${source.id}`;
+        edges.push(canonicalize({
+            ...edge,
+            id: edge.kind === "decision-default" ? `${switchId}:default` : `${switchId}:case:${edge.branchId}`,
+            sourceNodeId: switchId,
+            kind: edge.kind === "decision-default" ? "switch-default" : "switch-case",
+            targets: [...edge.targets].sort(),
+        }));
+    }
+    for (const source of spec.nodes.filter((node) => node.kind === "decision")) {
+        const switchId = `__control-switch-${source.id}`;
+        const selectRef = source.select.$ref === "node.output"
+            ? `dependencies.${source.id}.output`
+            : `dependencies.${source.id}.output.${source.select.$ref.split(".").slice(2).join(".")}`;
+        nodes.push(canonicalize({
+            id: switchId,
+            kind: "switch",
+            dependsOn: [source.id],
+            select: { $ref: selectRef },
+            caseIds: Object.keys(source.branches).sort(),
+        }));
+        edges.push(canonicalize({
+            id: `${source.id}:to-switch`, sourceNodeId: source.id, kind: "next",
+            targets: [switchId], with: {}, backEdge: false,
+        }));
+    }
+    // Make an actual parallel fan-in an explicit JoinNode. `dependsOn` also
+    // contains data dependencies, so it is not sufficient evidence that every
+    // incoming control path must arrive. A bounded revisit can put an entire
+    // parallel region on graph-theoretic back edges, though, so `backEdge` alone
+    // cannot distinguish an OR re-entry from the branches of one AND fan-out.
+    //
+    // Correlate those regions from the frozen fan-out edge: every branch must
+    // reach exactly one distinct direct arrival at the target without first
+    // passing through the target. This keeps unrelated revisit edges as OR
+    // paths while giving loop-local parallel work the same durable JoinNode and
+    // fork-lineage semantics as a forward-only parallel block.
+    for (const target of nodes.filter((node) => node.kind === "atom" && node.dependsOn.length > 1)) {
+        const forwardIncoming = edges.filter((edge) => !edge.backEdge && edge.targets.includes(target.id));
+        const forwardSources = [...new Set(forwardIncoming.map((edge) => edge.sourceNodeId))].sort();
+        const logicalSource = (sourceNodeId) => sourceNodeId.startsWith("__control-switch-")
+            ? sourceNodeId.slice("__control-switch-".length)
+            : sourceNodeId;
+        const sourceIsDependency = (sourceNodeId) => target.dependsOn.includes(logicalSource(sourceNodeId));
+        const reachesWithoutLeavingTarget = (start, sought) => {
+            const pending = [start];
+            const seen = new Set();
+            while (pending.length > 0) {
+                const current = pending.pop();
+                if (current === sought)
+                    return true;
+                if (current === target.id || seen.has(current))
+                    continue;
+                seen.add(current);
+                for (const edge of edges)
+                    if (edge.sourceNodeId === current)
+                        pending.push(...edge.targets);
+            }
+            return false;
+        };
+        const directIncoming = edges.filter((edge) => edge.targets.includes(target.id));
+        const groups = new Map();
+        for (const fork of edges.filter((edge) => edge.targets.length > 1 && !edge.targets.includes(target.id))) {
+            const arrivals = [];
+            let complete = true;
+            for (const branchEntry of fork.targets) {
+                const candidates = directIncoming.filter((incoming) => sourceIsDependency(incoming.sourceNodeId)
+                    && reachesWithoutLeavingTarget(branchEntry, incoming.sourceNodeId));
+                if (candidates.length !== 1) {
+                    complete = false;
+                    break;
+                }
+                arrivals.push(candidates[0]);
+            }
+            const unique = [...new Map(arrivals.map((edge) => [edge.id, edge])).values()]
+                .sort((left, right) => left.id.localeCompare(right.id));
+            if (complete && unique.length === fork.targets.length && unique.length > 1) {
+                groups.set(unique.map((edge) => edge.id).join("|"), unique);
+            }
+        }
+        if (forwardSources.length > 1 && forwardSources.every(sourceIsDependency)) {
+            const group = [...forwardIncoming].sort((left, right) => left.id.localeCompare(right.id));
+            groups.set(group.map((edge) => edge.id).join("|"), group);
+        }
+        const claimedEdgeIds = new Set();
+        const joinGroups = [...groups.values()]
+            .sort((left, right) => right.length - left.length || left[0].id.localeCompare(right[0].id))
+            .filter((group) => {
+            if (group.some((edge) => claimedEdgeIds.has(edge.id)))
+                return false;
+            group.forEach((edge) => claimedEdgeIds.add(edge.id));
+            return true;
+        })
+            .sort((left, right) => left[0].id.localeCompare(right[0].id));
+        joinGroups.forEach((group, groupIndex) => {
+            const joinId = joinGroups.length === 1
+                ? `__control-join-${target.id}`
+                : `__control-join-${target.id}-${groupIndex + 1}`;
+            const joinedEdgeIds = new Set(group.map((edge) => edge.id));
+            edges = edges.map((edge) => joinedEdgeIds.has(edge.id)
+                ? canonicalize({ ...edge, targets: edge.targets.map((id) => id === target.id ? joinId : id).sort() })
+                : edge);
+            const sources = [...new Set(group.map((edge) => edge.sourceNodeId))].sort();
+            nodes.push(canonicalize({
+                id: joinId,
+                kind: "join",
+                dependsOn: sources,
+                dependencies: sources,
+                incomingEdgeIds: [],
+                ...(target.mapScope ? { mapScope: target.mapScope } : {}),
+            }));
+            edges.push(canonicalize({
+                id: `${joinId}:next`, sourceNodeId: joinId, kind: "join-next",
+                targets: [target.id], with: {}, backEdge: false,
+            }));
+        });
+    }
+    let entry = [...spec.entry];
+    for (const [group, mapId] of [...mapIdByGroup.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        const declarations = spec.nodes.filter((node) => node.kind !== "merge" && (node.map?.group ?? (node.map ? node.id : undefined)) === group);
+        const config = declarations[0].map;
+        const bodyNodeIds = new Set(nodes.filter((node) => node.mapScope === mapId).map((node) => node.id));
+        const bodyEntries = new Set();
+        for (const nodeId of bodyNodeIds) {
+            if (entry.includes(nodeId) || edges.some((edge) => !bodyNodeIds.has(edge.sourceNodeId) && edge.targets.includes(nodeId)))
+                bodyEntries.add(nodeId);
+        }
+        if (bodyEntries.size === 0) {
+            for (const nodeId of bodyNodeIds) {
+                if (!edges.some((edge) => bodyNodeIds.has(edge.sourceNodeId) && edge.targets.includes(nodeId)))
+                    bodyEntries.add(nodeId);
+            }
+        }
+        const exits = edges.filter((edge) => bodyNodeIds.has(edge.sourceNodeId)
+            && (edge.terminal !== undefined || edge.targets.some((target) => !bodyNodeIds.has(target))));
+        const completionDescriptors = new Map();
+        for (const exit of exits) {
+            const descriptor = canonicalize({
+                targets: exit.targets.filter((target) => !bodyNodeIds.has(target)).sort(),
+                ...(exit.terminal ? { terminal: exit.terminal } : {}),
+                with: exit.with,
+                ...(exit.maxTraversals !== undefined ? { maxTraversals: exit.maxTraversals } : {}),
+                backEdge: exit.backEdge,
+            });
+            completionDescriptors.set(JSON.stringify(descriptor), exit);
+        }
+        edges = edges.map((edge) => {
+            if (bodyNodeIds.has(edge.sourceNodeId)
+                && (edge.terminal !== undefined || edge.targets.some((target) => !bodyNodeIds.has(target)))) {
+                return canonicalize({
+                    id: `${edge.id}:map-return`, sourceNodeId: edge.sourceNodeId, kind: "map-return",
+                    targets: [], with: {}, backEdge: false,
+                });
+            }
+            if (!bodyNodeIds.has(edge.sourceNodeId) && edge.targets.some((target) => bodyNodeIds.has(target))) {
+                return canonicalize({ ...edge, targets: [...new Set(edge.targets.map((target) => bodyNodeIds.has(target) ? mapId : target))].sort() });
+            }
+            return edge;
+        });
+        entry = [...new Set(entry.map((nodeId) => bodyNodeIds.has(nodeId) ? mapId : nodeId))];
+        const maxItems = config.maxItems;
+        const maxConcurrency = Math.min(config.maxConcurrency, maxItems, policy.maxNodeActivations);
+        nodes.push(canonicalize({
+            id: mapId,
+            kind: "map",
+            dependsOn: [],
+            items: config.items,
+            maxItems,
+            maxConcurrency,
+            bodyEntries: [...bodyEntries].sort(),
+            bodyNodeIds: [...bodyNodeIds].sort(),
+            bodyExitNodeIds: [...new Set(exits.map((edge) => edge.sourceNodeId))].sort(),
+        }));
+        edges.push(canonicalize({
+            id: `${mapId}:enter`, sourceNodeId: mapId, kind: "map-enter",
+            targets: [...bodyEntries].sort(), with: {}, backEdge: false,
+        }));
+        let completionIndex = 0;
+        for (const original of completionDescriptors.values()) {
+            edges.push(canonicalize({
+                id: `${mapId}:complete:${completionIndex++}`,
+                sourceNodeId: mapId,
+                kind: "map-complete",
+                targets: original.targets.filter((target) => !bodyNodeIds.has(target)).sort(),
+                ...(original.terminal ? { terminal: original.terminal } : {}),
+                with: original.with,
+                ...(original.maxTraversals !== undefined ? { maxTraversals: original.maxTraversals } : {}),
+                backEdge: original.backEdge,
+            }));
+        }
+    }
+    edges = [...edges].sort((left, right) => left.id.localeCompare(right.id));
+    nodes = nodes.map((node) => node.kind === "join" ? canonicalize({
+        ...node,
+        incomingEdgeIds: edges.filter((edge) => edge.targets.includes(node.id)).map((edge) => edge.id).sort(),
+    }) : node);
+    nodes = [...nodes].sort((left, right) => left.id.localeCompare(right.id));
+    const payload = canonicalize({
+        schemaVersion: "1.3",
+        name: spec.name,
+        inputs: spec.inputs,
+        nodes,
+        outputs: spec.outputs,
+        control: {
+            entry: [...entry].sort(),
+            terminals: [...new Set(edges.flatMap((edge) => edge.terminal ? [edge.terminal] : []))].sort(),
+            edges,
+        },
+        readiness: {
+            dependencyStages: graph.stages.map((stage) => [...stage].sort()),
+            forks: edges.filter((edge) => edge.targets.length > 1).map((edge) => ({ edgeId: edge.id, targets: edge.targets })),
+            joins: nodes.filter((node) => node.kind === "join")
+                .map((node) => ({ nodeId: node.id, dependencies: node.dependencies })),
+        },
+        activationIdentity: { strategy: "workflow-revision-node-activation-index-v1" },
+        effectiveRuntimePolicy: {
+            maxEdgeTraversals: policy.maxEdgeTraversals,
+            maxWorkflowTransitions: policy.maxWorkflowTransitions,
+            maxNodeActivations: policy.maxNodeActivations,
+            maxMapItems: policy.maxMapItems,
+        },
+    });
+    return freezeDeep({ ...payload, hash: contentHash(payload) });
+}
+export function compileWorkflow(raw, options) {
+    const parsed = schemaErrors(raw);
+    if (!parsed.spec)
+        throw new WorkflowCompilationError(sortValidationErrors(parsed.errors));
+    const policyResult = parsePolicy(options.runtimePolicy);
+    if (Array.isArray(policyResult))
+        throw new WorkflowCompilationError(sortValidationErrors(policyResult));
+    const errors = [];
+    const catalog = buildCatalog(options.atomCatalog, errors);
+    const resolvedByNode = validateNodePolicies(parsed.spec, catalog, policyResult, errors);
+    const graph = validateGraph(parsed.spec.nodes, errors);
+    const control = validateControlGraph(parsed.spec, policyResult, errors);
+    validateMapGroups(parsed.spec, control, errors);
+    if (graph)
+        validateReferencesAndInputs(parsed.spec, graph, control, resolvedByNode, errors);
+    if (errors.length > 0)
+        throw new WorkflowCompilationError(sortValidationErrors(errors));
+    return normalizeIR(parsed.spec, graph, control, resolvedByNode, policyResult);
+}
+export function validateWorkflow(raw, options) {
+    try {
+        return { success: true, ir: compileWorkflow(raw, options) };
+    }
+    catch (error) {
+        if (error instanceof WorkflowCompilationError)
+            return { success: false, errors: error.errors };
+        throw error;
+    }
+}
+//# sourceMappingURL=compile-workflow.js.map