@atom-workflow-agent/workflow-planner 0.1.0

package/dist/workspace/semantic-plan-compiler.js

@@ -0,0 +1,643 @@
+import {} from "@atom-workflow-agent/contracts";
+import { requiredPropertiesForValue, schemaPathGuaranteed, schemasCompatible } from "@atom-workflow-agent/workflow-compiler";
+import { mapAggregateSchema } from "./map-aggregate-schema.js";
+function objectOf(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function schemaType(schema) {
+    const object = objectOf(schema);
+    if (!object)
+        return undefined;
+    if (typeof object.type === "string")
+        return object.type;
+    if (Array.isArray(object.enum) && object.enum.length > 0) {
+        const values = new Set(object.enum.map((value) => value === null ? "null" : typeof value));
+        return values.size === 1 ? [...values][0] : undefined;
+    }
+    return undefined;
+}
+function inferSchema(value) {
+    if (value === null)
+        return { type: "null" };
+    if (Array.isArray(value))
+        return { type: "array", items: value.length ? inferSchema(value[0]) : {} };
+    if (typeof value === "object")
+        return {
+            type: "object",
+            properties: Object.fromEntries(Object.entries(value).map(([name, nested]) => [name, inferSchema(nested)])),
+            required: Object.keys(value),
+            additionalProperties: false,
+        };
+    return { type: Number.isInteger(value) ? "integer" : typeof value };
+}
+function schemaAtPath(schema, path) {
+    if (path === "." || path === "")
+        return schema;
+    let current = schema;
+    for (const segment of path.split(".").filter(Boolean)) {
+        const object = objectOf(current);
+        current = segment === "[]" ? object?.items : objectOf(object?.properties)?.[segment];
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+function descriptionOf(schema, fallback) {
+    const description = objectOf(schema)?.description;
+    return typeof description === "string" && description.trim() ? description.trim() : fallback;
+}
+function schemaChildren(selectorBase, refBase, schema, order, prefix = "", parentGuaranteed = true) {
+    const root = selectorBase.source === "node" && prefix === "" ? [{
+            selector: { source: "node", nodeId: selectorBase.nodeId, path: "." },
+            name: selectorBase.nodeId,
+            schema,
+            description: descriptionOf(schema, `Atom 节点 ${selectorBase.nodeId} 的完整结构化输出。`),
+            ref: { $output: selectorBase.nodeId },
+            sourceRef: selectorBase.nodeId,
+            order,
+            guaranteed: parentGuaranteed,
+        }] : [];
+    const schemaObject = objectOf(schema);
+    const properties = objectOf(schemaObject?.properties);
+    if (!properties)
+        return root;
+    const required = new Set(Array.isArray(schemaObject?.required)
+        ? schemaObject.required.filter((name) => typeof name === "string")
+        : []);
+    return [...root, ...Object.entries(properties).flatMap(([name, nested]) => {
+            const path = prefix ? `${prefix}.${name}` : name;
+            const child = nested;
+            const sourceRef = selectorBase.source === "node" ? `${selectorBase.nodeId}.${path}` : undefined;
+            const guaranteed = parentGuaranteed && required.has(name);
+            const current = {
+                selector: { ...selectorBase, path },
+                name,
+                schema: child,
+                description: descriptionOf(child, path),
+                ref: selectorBase.source === "workflow" ? { $input: path } : { $output: sourceRef },
+                ...(sourceRef ? { sourceRef } : {}),
+                order,
+                guaranteed,
+            };
+            return [current, ...schemaChildren(selectorBase, refBase, child, order, path, guaranteed)];
+        })];
+}
+function terms(value) {
+    const normalized = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().replace(/[“”'"，。；：、（）()_.-]/g, " ");
+    const words = normalized.match(/[a-z0-9]+|[\u3400-\u9fff]/g) ?? [];
+    const joinedChinese = words.filter((word) => /^[\u3400-\u9fff]$/.test(word)).join("");
+    const bigrams = [...joinedChinese].slice(0, -1).map((char, index) => `${char}${[...joinedChinese][index + 1]}`);
+    return new Set([...words.filter((word) => word.length > 1 || /^[a-z0-9]+$/.test(word)), ...bigrams]);
+}
+function semanticScore(source, targetName, targetDescription) {
+    if (source.name === targetName)
+        return 1;
+    const left = terms(`${source.name} ${source.description}`);
+    const right = terms(`${targetName} ${targetDescription}`);
+    if (!left.size || !right.size)
+        return 0;
+    const overlap = [...left].filter((term) => right.has(term)).length;
+    return overlap / Math.min(left.size, right.size);
+}
+const MIN_SEMANTIC_SCORE = 0.34;
+const MIN_SEMANTIC_MARGIN = 0.12;
+/**
+ * Select a source without allowing registration order to decide business
+ * meaning. In a serial pipeline, one exact-name value on the latest control
+ * layer shadows older values; same-layer exact-name values (for example from
+ * parallel branches) remain ambiguous. Cross-name binding is allowed only when
+ * descriptions and schemas identify one source; equal descriptions or
+ * near-equal semantic scores remain an explicit Planner choice.
+ */
+function selectBindingSource(sources, targetName, targetSchema, targetDescription) {
+    const compatible = sources
+        .filter((source) => source.guaranteed)
+        .filter((source) => schemasCompatible(source.schema, targetSchema, source.schema, targetSchema))
+        .map((source) => ({
+        source,
+        score: semanticScore(source, targetName, targetDescription),
+        exactName: source.name === targetName,
+        exactDescription: source.description.trim() === targetDescription.trim(),
+    }));
+    const exactNames = compatible.filter(({ exactName }) => exactName);
+    if (exactNames.length > 0) {
+        const latestOrder = Math.max(...exactNames.map(({ source }) => source.order));
+        const latestExactNames = exactNames.filter(({ source }) => source.order === latestOrder);
+        const fieldExactNames = latestExactNames.filter(({ source }) => source.selector.source !== "value" && source.selector.path !== ".");
+        const mostSpecificExactNames = fieldExactNames.length > 0 ? fieldExactNames : latestExactNames;
+        if (mostSpecificExactNames.length === 1)
+            return { kind: "selected", candidate: mostSpecificExactNames[0] };
+        return { kind: "ambiguous", candidates: mostSpecificExactNames };
+    }
+    const exactDescriptions = compatible.filter(({ exactDescription }) => exactDescription);
+    if (exactDescriptions.length === 1)
+        return { kind: "selected", candidate: exactDescriptions[0] };
+    if (exactDescriptions.length > 1)
+        return { kind: "ambiguous", candidates: exactDescriptions };
+    const semantic = compatible
+        .filter(({ score }) => score >= MIN_SEMANTIC_SCORE)
+        .sort((left, right) => right.score - left.score);
+    const best = semantic[0];
+    if (!best)
+        return { kind: "none", candidates: [] };
+    const second = semantic[1];
+    if (second && best.score - second.score < MIN_SEMANTIC_MARGIN) {
+        return { kind: "ambiguous", candidates: semantic };
+    }
+    return { kind: "selected", candidate: best };
+}
+function candidateDetails(candidates) {
+    return candidates.slice(0, 5).map(({ source, score, exactName, exactDescription }) => ({
+        source: source.selector,
+        description: source.description,
+        schema: source.schema,
+        score,
+        exactName,
+        exactDescription,
+        guaranteed: source.guaranteed,
+    }));
+}
+function setPath(target, path, value) {
+    const segments = path.split(".").filter(Boolean);
+    let current = target;
+    for (let index = 0; index < segments.length - 1; index += 1) {
+        const name = segments[index];
+        const existing = current[name];
+        if (existing === null || typeof existing !== "object" || Array.isArray(existing))
+            current[name] = {};
+        current = current[name];
+    }
+    current[segments.at(-1)] = value;
+}
+function cloneState(state) {
+    return { sources: [...state.sources], aliases: new Map(state.aliases), ...(state.item ? { item: state.item } : {}), ...(state.mapGroup ? { mapGroup: state.mapGroup } : {}) };
+}
+function nextControlOrder(state) {
+    return Math.max(-1, ...state.sources.map(({ order }) => order)) + 1;
+}
+class Compiler {
+    workflowName;
+    workflowInputs;
+    selectedAtomKeys;
+    descriptors;
+    errors = [];
+    evidence = new Map();
+    constructor(registry, workflowName, workflowInputs, selectedAtomKeys) {
+        this.workflowName = workflowName;
+        this.workflowInputs = workflowInputs;
+        this.selectedAtomKeys = selectedAtomKeys;
+        this.descriptors = new Map(registry.list().map((entry) => [entry.plannerDescriptor.key, entry.plannerDescriptor]));
+    }
+    compile(blocks, outputs) {
+        let state = this.initialState();
+        const steps = [];
+        for (const [index, block] of blocks.entries()) {
+            const compiled = this.step(block.plan, state, `$.blocks[${index}].plan`);
+            if (compiled) {
+                steps.push(compiled.step);
+                state = compiled.state;
+            }
+        }
+        const resolvedOutputs = {};
+        for (const [name, source] of Object.entries(outputs)) {
+            const resolved = this.resolveSource(source, state, `$.outputs.${name}`);
+            if (resolved)
+                resolvedOutputs[name] = resolved.ref;
+        }
+        if (this.errors.length || steps.length === 0) {
+            if (steps.length === 0)
+                this.errors.push({ code: "PLANNING_DRAFT_EMPTY", stage: "draft-schema", path: "$.blocks", message: "Semantic plan has no control region", hint: "Add at least one add-region operation" });
+            return { success: false, errors: this.errors };
+        }
+        return {
+            success: true,
+            plannerDraft: {
+                schemaVersion: "1.0", kind: "workflow-draft", name: this.workflowName,
+                flow: steps.length === 1 ? steps[0] : { kind: "sequence", steps }, outputs: resolvedOutputs,
+            },
+            evidence: [...this.evidence.values()],
+        };
+    }
+    initialState() {
+        const rootSchema = {
+            type: "object",
+            properties: Object.fromEntries(Object.entries(this.workflowInputs).map(([name, value]) => [name, { ...objectOf(inferSchema(value)), description: `用户提供的 Workflow 输入字段 ${name}。` }])),
+            required: Object.keys(this.workflowInputs),
+        };
+        return { sources: schemaChildren({ source: "workflow" }, "$input", rootSchema, 0), aliases: new Map() };
+    }
+    step(plan, before, path) {
+        switch (plan.kind) {
+            case "atom": return this.atom(plan, before, path);
+            case "sequence": {
+                let state = cloneState(before);
+                const steps = [];
+                plan.steps.forEach((nested, index) => {
+                    const compiled = this.step(nested, state, `${path}.steps[${index}]`);
+                    if (compiled) {
+                        steps.push(compiled.step);
+                        state = compiled.state;
+                    }
+                });
+                return steps.length ? { step: steps.length === 1 ? steps[0] : { kind: "sequence", steps }, state } : undefined;
+            }
+            case "parallel": {
+                const branches = plan.branches.map((branch, index) => this.step(branch, cloneState(before), `${path}.branches[${index}]`)).filter((value) => Boolean(value));
+                const state = cloneState(before);
+                for (const branch of branches)
+                    for (const source of branch.state.sources)
+                        if (!state.sources.some((item) => JSON.stringify(item.selector) === JSON.stringify(source.selector)))
+                            state.sources.push(source);
+                for (const branch of branches)
+                    for (const [alias, atom] of branch.state.aliases)
+                        state.aliases.set(alias, atom);
+                return branches.length ? { step: { kind: "parallel", branches: branches.map(({ step }) => step) }, state } : undefined;
+            }
+            case "decision": return this.decision(plan, before, path);
+            case "map": return this.map(plan, before, path);
+            case "repeat": return this.repeat(plan, before, path);
+        }
+    }
+    atom(plan, before, path) {
+        const descriptor = this.descriptors.get(plan.atom);
+        if (!descriptor || !this.selectedAtomKeys.has(plan.atom)) {
+            this.errors.push({ code: "PLANNER_DRAFT_ATOM_NOT_SELECTED", stage: "atom-resolution", path: `${path}.atom`, message: `Atom is not in the selected Catalog Authority: ${plan.atom}`, received: plan.atom, hint: "Use an exact selected Atom key or report a missing capability" });
+            return undefined;
+        }
+        if (before.aliases.has(plan.id)) {
+            this.errors.push({ code: "PLANNER_DRAFT_ALIAS_DUPLICATE", stage: "draft-normalization", path: `${path}.id`, message: `Node id is already used: ${plan.id}`, hint: "Use one globally unique node id" });
+            return undefined;
+        }
+        const input = this.bindInput(plan.id, descriptor.inputSchema, plan.bindings ?? {}, before, `${path}.bindings`);
+        const step = { kind: "atom", as: plan.id, use: plan.atom, input, ...(plan.policy ? { policy: plan.policy } : {}) };
+        return { step, state: this.afterAtom(before, plan.id, plan.atom, descriptor.outputSchema) };
+    }
+    decision(plan, before, path) {
+        const atom = this.atom({ kind: "atom", id: plan.id, atom: plan.atom, ...(plan.bindings ? { bindings: plan.bindings } : {}), ...(plan.policy ? { policy: plan.policy } : {}) }, before, path);
+        if (!atom)
+            return undefined;
+        const descriptor = this.descriptors.get(plan.atom);
+        const branchSchema = schemaAtPath(descriptor.outputSchema, plan.select);
+        if (!branchSchema) {
+            this.errors.push({ code: "PLANNER_DRAFT_CONTROL_INVALID", stage: "control-graph", path: `${path}.select`, message: `Decision select does not exist in Atom output: ${plan.select}`, received: plan.select, hint: "Choose an exact relative output field path from the selected Atom descriptor" });
+        }
+        else if (schemaType(branchSchema) !== "string") {
+            this.errors.push({ code: "DECISION_SELECT_TYPE_MISMATCH", stage: "control-graph", path: `${path}.select`, message: "Decision select must resolve to a string output field", expected: "string", received: branchSchema, hint: "Choose a string output field whose values identify the business cases" });
+        }
+        const expected = Array.isArray(objectOf(branchSchema)?.enum) ? objectOf(branchSchema).enum : undefined;
+        const ids = Object.keys(plan.branches);
+        if (expected && (expected.some((id) => typeof id !== "string" || !ids.includes(id)) || ids.some((id) => !expected.includes(id)))) {
+            this.errors.push({ code: "DECISION_BRANCH_ENUM_MISMATCH", stage: "control-graph", path: `${path}.branches`, message: `Decision branches must exactly match the enum at output.${plan.select}`, expected: expected, received: ids, hint: "Declare one branch for every finite value of the selected output field" });
+        }
+        const branchesHaveNoEffect = Object.values(plan.branches).every((branch) => branch.mode === "continue" && !branch.flow && (!branch.result || Object.keys(branch.result).length === 0));
+        if (branchesHaveNoEffect) {
+            this.errors.push({
+                code: "PLANNING_DECISION_NO_EFFECT",
+                stage: "control-graph",
+                path: `${path}.branches`,
+                message: "Decision branch selection has no effect because every branch immediately continues without local flow or a typed result",
+                received: ids,
+                hint: "Give at least one branch distinct local work, terminal/revisit behavior, or typed results. If one branch must skip an Atom, keep that branch flow empty and export schema-compatible literal or existing values while another branch executes the Atom",
+            });
+        }
+        const branches = {};
+        const continuing = [];
+        for (const [branchId, branch] of Object.entries(plan.branches)) {
+            const branchPath = `${path}.branches.${branchId}`;
+            if (branch.mode === "terminal") {
+                branches[branchId] = { kind: "terminal", status: branch.status };
+                continue;
+            }
+            if (branch.mode === "continue" && !branch.flow) {
+                branches[branchId] = { kind: "continue" };
+                continuing.push({ branchId, state: cloneState(atom.state), hasFlow: false, ...(branch.result ? { result: branch.result } : {}) });
+                continue;
+            }
+            const compiled = this.step(branch.flow, cloneState(atom.state), `${branchPath}.flow`);
+            if (!compiled)
+                continue;
+            if (branch.mode === "revisit") {
+                const reentry = this.bindReentryInput(plan.id, descriptor.inputSchema, atom.state, compiled.state, `${branchPath}.reentry`);
+                branches[branchId] = {
+                    kind: "revisit",
+                    maxIterations: branch.maxIterations,
+                    body: compiled.step,
+                    ...(Object.keys(reentry).length ? { reentry } : {}),
+                };
+            }
+            else {
+                branches[branchId] = compiled.step;
+                continuing.push({ branchId, state: compiled.state, hasFlow: true, ...(branch.result ? { result: branch.result } : {}) });
+            }
+        }
+        const state = cloneState(atom.state);
+        let merge;
+        const requiresMerge = continuing.length > 1 && (continuing.some(({ hasFlow }) => hasFlow) || continuing.some(({ result }) => result !== undefined));
+        if (requiresMerge) {
+            const missing = continuing.filter(({ result }) => !result || Object.keys(result).length === 0).map(({ branchId }) => branchId);
+            if (missing.length > 0) {
+                this.errors.push({
+                    code: "PLANNING_BRANCH_RESULT_REQUIRED", stage: "data-link", path: `${path}.branches`,
+                    message: "Every continuing branch must export one non-empty typed result before mutually-exclusive paths can rejoin",
+                    expected: continuing.map(({ branchId }) => branchId), received: missing,
+                    hint: "Add result mappings to every mode='continue' branch. Map the same logical field names to values available on that branch; Runtime will create the typed merge node",
+                });
+            }
+            else {
+                const resolvedResults = continuing.map(({ branchId, state: branchState, result }) => {
+                    const values = {};
+                    const schemas = {};
+                    for (const [name, source] of Object.entries(result)) {
+                        const resolved = this.resolveSource(source, branchState, `${path}.branches.${branchId}.result.${name}`);
+                        if (!resolved)
+                            continue;
+                        values[name] = resolved.ref;
+                        schemas[name] = resolved.schema;
+                    }
+                    return { branchId, values, schemas };
+                });
+                const expectedKeys = Object.keys(resolvedResults[0].schemas).sort();
+                for (const current of resolvedResults.slice(1)) {
+                    const receivedKeys = Object.keys(current.schemas).sort();
+                    if (JSON.stringify(receivedKeys) !== JSON.stringify(expectedKeys)) {
+                        this.errors.push({
+                            code: "PLANNING_BRANCH_RESULT_MISMATCH", stage: "data-link", path: `${path}.branches.${current.branchId}.result`,
+                            message: "Continuing branches must export exactly the same logical result fields",
+                            expected: expectedKeys, received: receivedKeys,
+                            hint: "Use identical result keys on every continuing branch; source node ids and source field names may differ",
+                        });
+                        continue;
+                    }
+                    for (const name of expectedKeys) {
+                        const expectedSchema = resolvedResults[0].schemas[name];
+                        const receivedSchema = current.schemas[name];
+                        if (!schemasCompatible(expectedSchema, receivedSchema, expectedSchema, receivedSchema)
+                            || !schemasCompatible(receivedSchema, expectedSchema, receivedSchema, expectedSchema)) {
+                            this.errors.push({
+                                code: "PLANNING_BRANCH_RESULT_MISMATCH", stage: "data-link", path: `${path}.branches.${current.branchId}.result.${name}`,
+                                message: `Branch result field '${name}' has an incompatible Schema`,
+                                expected: expectedSchema, received: receivedSchema,
+                                hint: "Choose one schema-compatible value for this logical result on every continuing branch",
+                            });
+                        }
+                    }
+                }
+                if (expectedKeys.length > 0) {
+                    const mergeAlias = `${plan.id}-merge`;
+                    if (state.aliases.has(mergeAlias)) {
+                        this.errors.push({ code: "PLANNER_DRAFT_ALIAS_DUPLICATE", stage: "draft-normalization", path: `${path}.id`, message: `Generated branch merge id is already used: ${mergeAlias}`, hint: "Rename the Decision node so its '<id>-merge' control id is unique" });
+                    }
+                    else {
+                        const outputSchema = {
+                            type: "object",
+                            description: `Typed result selected from one continuing branch of Decision ${plan.id}.`,
+                            properties: Object.fromEntries(expectedKeys.map((name) => [name, resolvedResults[0].schemas[name]])),
+                            required: expectedKeys,
+                            additionalProperties: false,
+                        };
+                        merge = {
+                            as: mergeAlias,
+                            outputSchema,
+                            branches: Object.fromEntries(resolvedResults.map(({ branchId, values }) => [branchId, values])),
+                        };
+                        state.aliases.set(mergeAlias, "@runtime/branch-merge");
+                        state.sources.push(...schemaChildren({ source: "node", nodeId: mergeAlias }, "$output", outputSchema, nextControlOrder(state)));
+                    }
+                }
+            }
+        }
+        else if (continuing.length) {
+            const continuingStates = continuing.map(({ state: branchState }) => branchState);
+            const common = continuingStates.reduce((set, branch) => new Set([...set].filter((key) => branch.sources.some((source) => JSON.stringify(source.selector) === key))), new Set(continuingStates[0].sources.map((source) => JSON.stringify(source.selector))));
+            for (const source of continuingStates[0].sources)
+                if (common.has(JSON.stringify(source.selector)) && !state.sources.some((item) => JSON.stringify(item.selector) === JSON.stringify(source.selector)))
+                    state.sources.push(source);
+        }
+        return { step: { kind: "decision", as: plan.id, use: plan.atom, select: plan.select, input: atom.step.input, branches, defaultBranch: plan.defaultBranch, ...(merge ? { merge } : {}), ...(plan.policy ? { policy: plan.policy } : {}) }, state };
+    }
+    /**
+     * A revisit is a new activation of the same Decision, not a replay of its
+     * original static input. Carry only unambiguous values produced inside the
+     * branch; all unaffected fields continue to use the Decision's frozen base
+     * input. This gives local repair loops SSA-like "latest value" semantics
+     * without exposing references or edge overlays to the planning model.
+     */
+    bindReentryInput(alias, inputSchema, beforeBranch, afterBranch, path) {
+        const properties = objectOf(objectOf(inputSchema)?.properties) ?? {};
+        const branchAliases = new Set([...afterBranch.aliases.keys()].filter((candidate) => candidate !== alias && !beforeBranch.aliases.has(candidate)));
+        const freshSources = afterBranch.sources.filter((source) => source.selector.source === "node" && branchAliases.has(source.selector.nodeId));
+        const reentry = {};
+        for (const [name, targetRaw] of Object.entries(properties)) {
+            const targetSchema = targetRaw;
+            const targetDescription = descriptionOf(targetSchema, name);
+            const selection = selectBindingSource(freshSources, name, targetSchema, targetDescription);
+            if (selection.kind === "none")
+                continue;
+            if (selection.kind === "ambiguous") {
+                this.errors.push({
+                    code: "PLANNING_BINDING_AMBIGUOUS", stage: "data-link", path: `${path}.${name}`,
+                    message: `Multiple fresh branch sources could update ${alias}.${name} on Decision reentry`,
+                    expected: { field: name, description: targetDescription, schema: targetSchema },
+                    received: candidateDetails(selection.candidates),
+                    hint: `Make the repair branch produce one uniquely named or described value for ${name}`,
+                });
+                continue;
+            }
+            reentry[name] = selection.candidate.source.ref;
+            this.captureEvidence(alias, name, selection.candidate.source, targetSchema);
+        }
+        return reentry;
+    }
+    map(plan, before, path) {
+        const items = this.resolveSource(plan.items, before, `${path}.items`);
+        if (!items)
+            return undefined;
+        const itemSchema = objectOf(items.schema)?.items;
+        if (schemaType(items.schema) !== "array" || !itemSchema) {
+            this.errors.push({ code: "MAP_ITEMS_NOT_ARRAY", stage: "data-link", path: `${path}.items`, message: "Map items source must be an array", received: items.schema, hint: "Choose an array field from Workflow input or an upstream node" });
+            return undefined;
+        }
+        const item = { selector: { source: "item", path: "." }, name: "item", schema: itemSchema, description: descriptionOf(itemSchema, "当前 Map item"), ref: { $item: "." }, order: nextControlOrder(before), guaranteed: true };
+        const bodyBefore = { sources: [...before.sources], aliases: new Map(before.aliases), item, mapGroup: plan.id };
+        const body = this.step(plan.body, bodyBefore, `${path}.body`);
+        if (!body)
+            return undefined;
+        const createdAliases = [...body.state.aliases].filter(([alias]) => !before.aliases.has(alias));
+        const state = cloneState(before);
+        const aggregateOrder = nextControlOrder(body.state);
+        for (const [alias, atomKey] of createdAliases) {
+            state.aliases.set(alias, atomKey);
+            const descriptor = this.descriptors.get(atomKey);
+            state.sources.push(...schemaChildren({ source: "node", nodeId: alias }, "$output", descriptor.outputSchema, aggregateOrder).map((source) => ({
+                ...source,
+                schema: mapAggregateSchema(source.schema, plan.id),
+                description: descriptionOf(mapAggregateSchema(source.schema, plan.id), source.description),
+                guaranteed: true,
+            })));
+        }
+        return { step: { kind: "map", as: plan.id, items: items.ref, maxItems: plan.maxItems, ...(plan.maxConcurrency ? { maxConcurrency: plan.maxConcurrency } : {}), body: body.step }, state };
+    }
+    repeat(plan, before, path) {
+        const body = this.step(plan.body, cloneState(before), `${path}.body`);
+        if (!body)
+            return undefined;
+        const decisionAtom = this.atom({ kind: "atom", id: plan.decision.id, atom: plan.decision.atom, ...(plan.decision.bindings ? { bindings: plan.decision.bindings } : {}), ...(plan.decision.policy ? { policy: plan.decision.policy } : {}) }, body.state, `${path}.decision`);
+        if (!decisionAtom)
+            return undefined;
+        const decisionDescriptor = this.descriptors.get(plan.decision.atom);
+        const decisionSchema = schemaAtPath(decisionDescriptor.outputSchema, plan.decision.select);
+        if (!decisionSchema) {
+            this.errors.push({ code: "PLANNER_DRAFT_CONTROL_INVALID", stage: "control-graph", path: `${path}.decision.select`, message: `Repeat decision select does not exist in Atom output: ${plan.decision.select}`, received: plan.decision.select, hint: "Choose an exact relative output field path from the repeat decision Atom" });
+        }
+        else if (schemaType(decisionSchema) !== "string") {
+            this.errors.push({ code: "DECISION_SELECT_TYPE_MISMATCH", stage: "control-graph", path: `${path}.decision.select`, message: "Repeat decision select must resolve to a string output field", expected: "string", received: decisionSchema });
+        }
+        return {
+            step: {
+                kind: "repeat", maxIterations: plan.maxIterations, body: body.step,
+                decision: {
+                    as: plan.decision.id, use: plan.decision.atom, select: plan.decision.select, input: decisionAtom.step.input,
+                    continueBranch: plan.decision.continueBranch, exitBranch: plan.decision.exitBranch, defaultBranch: plan.decision.defaultBranch,
+                    ...(plan.decision.policy ? { policy: plan.decision.policy } : {}),
+                },
+            },
+            state: decisionAtom.state,
+        };
+    }
+    bindInput(alias, inputSchema, bindings, state, path) {
+        const object = objectOf(inputSchema);
+        const properties = objectOf(object?.properties) ?? {};
+        const input = {};
+        const explicitlyBoundTopLevels = new Set(Object.keys(bindings).map((targetPath) => targetPath.split(".")[0]));
+        for (const [targetPath, source] of Object.entries(bindings)) {
+            const targetSchema = schemaAtPath(inputSchema, targetPath);
+            if (!targetSchema) {
+                this.errors.push({ code: "INPUT_ADDITIONAL_PROPERTY_FORBIDDEN", stage: "data-link", path: `${path}.${targetPath}`, message: `Binding target does not exist in Atom input schema: ${targetPath}`, hint: "Use an exact input field path from the selected Atom descriptor" });
+                continue;
+            }
+            const resolved = this.resolveSource(source, state, `${path}.${targetPath}`, targetSchema);
+            if (resolved) {
+                setPath(input, targetPath, resolved.ref);
+                this.captureEvidence(alias, targetPath, resolved, targetSchema);
+            }
+        }
+        const required = new Set(requiredPropertiesForValue(inputSchema, inputSchema, input));
+        for (const [name, targetRaw] of Object.entries(properties)) {
+            if (input[name] !== undefined || explicitlyBoundTopLevels.has(name))
+                continue;
+            // Optional Atom inputs carry business intent (for example parentCard,
+            // templateName, thresholds or provider overrides). Inferring them from
+            // any compatible upstream value can silently change behavior. Only
+            // required inputs are eligible for Runtime auto-binding; optional inputs
+            // must be bound explicitly by the Planner or supplied by the user.
+            const targetSchema = targetRaw;
+            const targetDescription = descriptionOf(targetSchema, name);
+            if (!required.has(name)) {
+                // A same-name Workflow input is user-owned intent, rather than an
+                // inferred value from another Atom. It is therefore safe to forward
+                // into an optional Atom input. Keep this deliberately stricter than
+                // normal semantic auto-binding: optional fields are never matched by
+                // description and are never sourced from an upstream node.
+                const workflowMatches = state.sources.filter((source) => source.selector.source === "workflow"
+                    && source.name === name
+                    && source.guaranteed
+                    && schemasCompatible(source.schema, targetSchema, source.schema, targetSchema));
+                if (workflowMatches.length === 1)
+                    input[name] = workflowMatches[0].ref;
+                continue;
+            }
+            const selection = selectBindingSource([...state.sources, ...(state.item ? [state.item] : [])], name, targetSchema, targetDescription);
+            if (selection.kind === "selected") {
+                input[name] = selection.candidate.source.ref;
+                this.captureEvidence(alias, name, selection.candidate.source, targetSchema);
+            }
+            else if (selection.kind === "ambiguous" || required.has(name)) {
+                const code = selection.kind === "ambiguous" ? "PLANNING_BINDING_AMBIGUOUS" : "PLANNING_REQUIRED_INPUT_UNAVAILABLE";
+                this.errors.push({
+                    code, stage: "data-link", path: `${path}.${name}`,
+                    message: selection.kind === "ambiguous" ? `Multiple sources could satisfy ${alias}.${name}` : `No guaranteed source can satisfy ${alias}.${name}`,
+                    expected: { field: name, description: targetDescription, schema: targetSchema },
+                    received: candidateDetails(selection.candidates),
+                    hint: selection.kind === "ambiguous" ? `Add an explicit binding for ${name} using one listed semantic source` : "Add a preceding capability, provide the field as Workflow input, or report a deterministic missing-input gap",
+                });
+            }
+        }
+        return input;
+    }
+    captureEvidence(alias, targetPath, source, targetSchema) {
+        if (!source.sourceRef || source.name === targetPath.split(".").at(-1))
+            return;
+        const targetDescription = descriptionOf(targetSchema, targetPath);
+        const key = `${alias}:${targetPath}:${source.sourceRef}`;
+        this.evidence.set(key, {
+            schemaVersion: "1.0", consumerAlias: alias, targetPath, sourceRef: source.sourceRef,
+            sourceDescription: source.description, targetDescription, sourceSchema: source.schema, targetSchema,
+            reason: "Runtime auto-binding found one unique schema-compatible semantic source", confidence: "high",
+        });
+    }
+    resolveSource(source, state, path, targetSchema) {
+        if (source.source === "value") {
+            const schema = inferSchema(source.value);
+            if (targetSchema && !schemasCompatible(schema, targetSchema, schema, targetSchema))
+                this.errors.push({ code: "REFERENCE_TYPE_MISMATCH", stage: "data-link", path, message: "Literal value does not match the target input schema", expected: targetSchema, received: schema, hint: "Use a value with the required type" });
+            return { selector: source, name: "value", schema, description: "Planner supplied literal value", ref: source.value, order: nextControlOrder(state), guaranteed: true };
+        }
+        if (source.source === "item") {
+            if (!state.item) {
+                this.errors.push({ code: "MAP_REFERENCE_OUTSIDE_MAP", stage: "data-link", path, message: "Item source is only available inside a Map body", hint: "Use a Workflow or upstream node source outside Map" });
+                return undefined;
+            }
+            const schema = schemaAtPath(state.item.schema, source.path);
+            if (!schema)
+                return this.missingPath(source, path, state.sources);
+            const guaranteed = source.path === "." || schemaPathGuaranteed(state.item.schema, source.path.split(".").filter(Boolean), state.item.schema);
+            if (!guaranteed) {
+                this.errors.push({
+                    code: "PLANNING_BINDING_SOURCE_OPTIONAL", stage: "data-link", path,
+                    message: `Selected Map item source is optional and not guaranteed: ${source.path}`,
+                    received: source,
+                    hint: "Use a required item field or add control flow that materializes a guaranteed value",
+                });
+                return undefined;
+            }
+            return { ...state.item, selector: source, name: source.path === "." ? "item" : source.path.split(".").at(-1), schema, description: descriptionOf(schema, state.item.description), ref: { $item: source.path }, guaranteed };
+        }
+        const match = state.sources.filter((candidate) => candidate.selector.source === source.source
+            && (source.source !== "node" || (candidate.selector.source === "node" && candidate.selector.nodeId === source.nodeId))
+            && candidate.selector.path === source.path).at(-1);
+        if (!match)
+            return this.missingPath(source, path, state.sources);
+        if (!match.guaranteed) {
+            this.errors.push({
+                code: "PLANNING_BINDING_SOURCE_OPTIONAL", stage: "data-link", path,
+                message: `Selected source is optional and not guaranteed: ${JSON.stringify(source)}`,
+                received: source,
+                hint: "Omit the optional binding, provide the value as Workflow input, or add control flow that materializes a required result",
+            });
+            return undefined;
+        }
+        if (targetSchema && !schemasCompatible(match.schema, targetSchema, match.schema, targetSchema)) {
+            this.errors.push({ code: "REFERENCE_TYPE_MISMATCH", stage: "data-link", path, message: "Selected source schema is incompatible with the target input", expected: targetSchema, received: match.schema, hint: "Choose one of the schema-compatible sources reported by Runtime auto-binding" });
+        }
+        return match;
+    }
+    missingPath(source, path, available) {
+        this.errors.push({
+            code: "PLANNING_REQUIRED_INPUT_UNAVAILABLE", stage: "data-link", path,
+            message: `Semantic source is not guaranteed or does not exist: ${JSON.stringify(source)}`,
+            received: available.slice(-20).map(({ selector }) => selector),
+            hint: "Use an exact available semantic source, add its producer earlier, or report a missing-input gap",
+        });
+        return undefined;
+    }
+    afterAtom(before, alias, atomKey, outputSchema) {
+        const state = cloneState(before);
+        state.aliases.set(alias, atomKey);
+        state.sources.push(...schemaChildren({ source: "node", nodeId: alias }, "$output", outputSchema, nextControlOrder(before)));
+        return state;
+    }
+}
+export function compileSemanticPlan(input) {
+    return new Compiler(input.registry, input.workflowName, input.workflowInputs, new Set(input.selectedAtomKeys)).compile(input.blocks, input.outputs);
+}
+//# sourceMappingURL=semantic-plan-compiler.js.map