@atom-workflow-agent/workflow-planner 0.1.0

package/dist/planning/planning-controller.js

@@ -0,0 +1,773 @@
+import { join } from "node:path";
+import { PlannerCapabilityPlanSchema, PlanningStepJsonSchema, PlanningCheckpointSchema, PlanningWorkspaceActionSchema, WorkflowValidationErrorSchema, } from "@atom-workflow-agent/contracts";
+import { resolveCapabilityCoverage } from "../capabilities/capability-coverage-resolver.js";
+import { buildPlannerCatalog, buildPlannerCatalogIndex, selectPlannerCatalog } from "../catalog/planner-catalog.js";
+import { PlanningModelExecutionError, } from "../model/planning-model-port.js";
+import { PlanningWorkspaceService } from "../workspace/planning-workspace-service.js";
+const DEFAULT_MAX_ERRORS = 20;
+const DEFAULT_MAX_CAPABILITY_REPAIRS = 2;
+const DEFAULT_MAX_PLANNING_TURNS = 64;
+export class WorkflowPlanningFailedError extends Error {
+    attempts;
+    validationErrors;
+    rawOutputs;
+    audit;
+    code;
+    retryable;
+    constructor(message, attempts, validationErrors, rawOutputs, audit, options = {}) {
+        super(message, options);
+        this.attempts = attempts;
+        this.validationErrors = validationErrors;
+        this.rawOutputs = rawOutputs;
+        this.audit = audit;
+        this.name = "WorkflowPlanningFailedError";
+        this.code = options.code ?? "WORKFLOW_PLANNING_FAILED";
+        this.retryable = options.retryable ?? false;
+    }
+}
+const asJson = (value) => JSON.parse(JSON.stringify(value));
+const fullCatalog = (registry) => buildPlannerCatalog(registry.list({ includeDisabled: true }));
+function pathOf(parts) {
+    return parts.reduce((path, part) => typeof part === "number" ? `${path}[${part}]` : `${path}.${String(part)}`, "$");
+}
+function schemaIssues(issues, stage) {
+    return issues.flatMap((raw) => {
+        const issue = raw;
+        const make = (path, message = issue.message) => ({
+            code: stage === "capability-schema" ? "PLANNER_CAPABILITY_SCHEMA_INVALID" : "PLANNING_WORKSPACE_ACTION_INVALID",
+            stage,
+            path: pathOf(path),
+            message: message ?? "Planner document does not match the phase contract",
+            hint: "Return exactly one complete JSON document matching the current phase contract",
+        });
+        return issue.code === "unrecognized_keys" && issue.keys?.length
+            ? issue.keys.map((key) => make([...(issue.path ?? []), key], `Unrecognized field: ${key}`))
+            : [make(issue.path ?? [])];
+    });
+}
+const feedback = (errors, limit) => [...errors]
+    .sort((left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code)).slice(0, limit);
+function coverageErrors(coverage) {
+    return coverage.gaps.map((gap) => ({
+        code: gap.code,
+        stage: "capability-resolution",
+        path: `$.requirements.${gap.requirement.id}`,
+        message: gap.message,
+        received: gap.fieldIssues ?? gap.nearMatches,
+        hint: gap.code === "PLANNING_CAPABILITY_SCHEMA_MISMATCH"
+            ? "Reference exact top-level field names from atomCatalogIndex and declare every required input of each selected Atom; Runtime owns their full Schemas"
+            : gap.code === "PLANNING_CAPABILITY_ATOM_UNKNOWN"
+                ? "Use an exact registered Atom key from atomCatalogIndex"
+                : "If this is only a control-flow terminal, retry, loop, branch, literal binding, Signal, Host wait, or rollback path, remove the capability requirement; otherwise keep resolution.kind='missing' to report a genuine missing Atom",
+    }));
+}
+function outputFailure(error) {
+    return ["PLANNER_OUTPUT_INVALID_JSON", "PLANNER_OUTPUT_EMPTY"].includes(error.code) ? {
+        code: "WORKFLOW_JSON_INVALID", stage: "json-extract", path: "$", message: error.message,
+        hint: "Return exactly one JSON document without Markdown or explanation",
+    } : undefined;
+}
+function capabilityPayload(input, index, referenceDirectory) {
+    return asJson({
+        goal: input.goal,
+        workflowInputs: input.workflowInputs,
+        context: input.context,
+        atomCatalogIndex: index,
+        ...(referenceDirectory ? { references: {
+                plannerInput: join(referenceDirectory, "planner-input.json"),
+                usage: "Read this file with local file tools only if the inline goal or inputs are insufficient; never modify it.",
+            } } : {}),
+        contract: {
+            schemaVersion: "1.1", kind: "capability-plan",
+            requirements: [
+                {
+                    id: "covered-capability", description: "required business capability supplied by registered Atoms", required: true,
+                    resolution: {
+                        kind: "covered",
+                        uses: [{
+                                atom: "exact registered Atom key",
+                                inputs: [{ role: "business meaning", field: "exact required input field" }],
+                                outputs: [{ role: "business meaning", field: "exact relevant output field" }],
+                            }],
+                    },
+                },
+                {
+                    id: "missing-capability", description: "required business capability absent from the catalog", required: true,
+                    resolution: {
+                        kind: "missing",
+                        desiredInputs: [{ name: "input", description: "business meaning", required: true, acceptedTypes: ["object"] }],
+                        desiredOutputs: [{ name: "output", description: "business meaning", required: true, acceptedTypes: ["string"] }],
+                    },
+                },
+            ],
+        },
+        rules: [
+            "List executable Atom capabilities only. Sequence, parallel, Decision containers and branch routing, Map or Repeat scaffolding, retry exhaustion, terminal states, rollback paths, literal bindings, Signal waiting, and Host waiting are control concerns rather than separate capabilities",
+            "Every Atom that a control node will execute is still a capability and must be covered. In particular, when a branch depends on runtime data, select an exact decision-capable Atom from the Catalog and map the runtime facts input plus selected-branch output; never pre-evaluate or omit that selector",
+            "Split a composite behavior into the exact registered Atoms that implement it; never invent a handler Atom merely to terminate a Decision or bounded loop branch",
+            "Use only exact keys from atomCatalogIndex; never turn a natural-language capability into an Atom key",
+            "Give every requirement a unique, stable kebab-case id that describes its business capability; never reuse example ids such as covered-capability or missing-capability",
+            "Never output JSON Schema. For a covered capability, reference exact Atom keys and exact top-level field names; Runtime reads and validates the authoritative Schemas from the Catalog",
+            "For every selected Atom use, list every inputFields entry whose required flag is true. List only outputs that carry a business result needed by the goal or later planning",
+            "Use role to state why the exact Atom field participates in this capability. Do not rename the field or copy its description as a substitute for the field name",
+            "Use Workflow map only when each item needs independent branching, retry, pause, rollback, progress, or multiple Atom calls; otherwise call a registered batch Atom once",
+            "Use resolution.kind='missing' only when no registered Atom can provide a required executable business capability. acceptedTypes are coarse business shapes, not JSON Schema",
+            "Do not return nodes, bindings, control structures, or Workflow JSON in this preflight",
+        ],
+    });
+}
+function summarizeStep(step) {
+    switch (step.kind) {
+        case "atom": return { kind: step.kind, id: step.id, atom: step.atom };
+        case "sequence": return { kind: step.kind, steps: step.steps.map(summarizeStep) };
+        case "parallel": return { kind: step.kind, branches: step.branches.map(summarizeStep) };
+        case "decision": return asJson({
+            kind: step.kind,
+            id: step.id,
+            atom: step.atom,
+            select: step.select,
+            branches: Object.fromEntries(Object.entries(step.branches).map(([branchId, branch]) => [
+                branchId,
+                branch.mode === "revisit"
+                    ? { mode: "revisit", maxIterations: branch.maxIterations, flow: summarizeStep(branch.flow) }
+                    : branch.mode === "continue" && branch.flow
+                        ? { mode: "continue", flow: summarizeStep(branch.flow) }
+                        : branch.mode === "continue"
+                            ? { mode: "continue" }
+                            : branch,
+            ])),
+            defaultBranch: step.defaultBranch,
+        });
+        case "map": return { kind: step.kind, id: step.id, maxItems: step.maxItems, maxConcurrency: step.maxConcurrency ?? null, body: summarizeStep(step.body) };
+        case "repeat": return {
+            kind: step.kind, maxIterations: step.maxIterations, body: summarizeStep(step.body),
+            decision: { id: step.decision.id, atom: step.decision.atom, select: step.decision.select, continueBranch: step.decision.continueBranch, exitBranch: step.decision.exitBranch },
+        };
+    }
+}
+function schemaShape(schema) {
+    if (schema === null || Array.isArray(schema) || typeof schema !== "object")
+        return {};
+    const value = schema;
+    const items = value.items !== null && !Array.isArray(value.items) && typeof value.items === "object"
+        ? value.items
+        : undefined;
+    return asJson({
+        ...(typeof value.type === "string" ? { type: value.type } : {}),
+        ...(Array.isArray(value.enum) ? { enum: value.enum } : {}),
+        ...(typeof value.format === "string" ? { format: value.format } : {}),
+        ...(items && typeof items.type === "string" ? { itemType: items.type } : {}),
+    });
+}
+function compactFrontier(frontier) {
+    return asJson({
+        revision: frontier.revision,
+        draftHash: frontier.draftHash,
+        guaranteedAliases: frontier.guaranteedAliases,
+        availableValues: frontier.availableValues.map((value) => ({
+            ref: value.ref,
+            ...(value.producerAlias ? { producerAlias: value.producerAlias } : {}),
+            path: value.path,
+            shape: schemaShape(value.schema),
+            description: value.description,
+        })),
+    });
+}
+function regionDigest(step) {
+    const atomKeys = new Set();
+    const nodeIds = new Set();
+    const controls = new Set();
+    const branches = new Set();
+    const visit = (current) => {
+        switch (current.kind) {
+            case "atom":
+                atomKeys.add(current.atom);
+                nodeIds.add(current.id);
+                break;
+            case "sequence":
+                controls.add("sequence");
+                current.steps.forEach(visit);
+                break;
+            case "parallel":
+                controls.add("parallel");
+                current.branches.forEach(visit);
+                break;
+            case "decision":
+                controls.add("decision");
+                atomKeys.add(current.atom);
+                nodeIds.add(current.id);
+                Object.entries(current.branches).forEach(([branchId, branch]) => {
+                    branches.add(`${current.id}.${branchId}:${branch.mode}`);
+                    if (branch.mode !== "terminal" && branch.flow)
+                        visit(branch.flow);
+                });
+                break;
+            case "map":
+                controls.add("map");
+                nodeIds.add(current.id);
+                visit(current.body);
+                break;
+            case "repeat":
+                controls.add("repeat");
+                visit(current.body);
+                atomKeys.add(current.decision.atom);
+                nodeIds.add(current.decision.id);
+                branches.add(`${current.decision.id}.${current.decision.continueBranch}:continue`);
+                branches.add(`${current.decision.id}.${current.decision.exitBranch}:exit`);
+                break;
+        }
+    };
+    visit(step);
+    return { atomKeys: [...atomKeys].sort(), nodeIds: [...nodeIds].sort(), controls: [...controls].sort(), branches: [...branches].sort() };
+}
+function promptReferences(directory, revision) {
+    if (!directory)
+        return undefined;
+    return asJson({
+        plannerInput: join(directory, "planner-input.json"),
+        catalogAndAudit: join(directory, "planning", "audit.json"),
+        workspaceState: join(directory, "planning", "workspace", "state.json"),
+        workspaceTransactions: join(directory, "planning", "workspace", "transactions.jsonl"),
+        ...(revision > 0 ? { currentRevision: join(directory, "planning", "workspace", "revisions", `${String(revision).padStart(4, "0")}.json`) } : {}),
+        usage: "These are read-only authoritative details. Inspect them with local file tools only when the compact payload is insufficient; never modify them.",
+    });
+}
+function focusedRules(intent, errors) {
+    const codes = new Set(errors.map(({ code }) => code));
+    if (codes.has("PLANNING_WORKFLOW_OUTPUT_REQUIRED"))
+        return [
+            "Only declare stable Workflow outputs from guaranteed final Atom fields; do not add or repeat business regions",
+            "If every continuing Decision branch already materializes the same terminal output contract, expose that typed merge as Workflow outputs; never call the same terminal Atom again merely to repackage its outputs",
+            "Use the exact current revision and draftHash, then set finalize=true in the same workspace-plan action",
+        ];
+    if (intent === "repair")
+        return [
+            "Correct only the rejected transaction described by previousValidationErrors against the exact current revision and draftHash",
+            "Reuse exact candidate field names and sources from the errors; do not guess or redesign already committed regions",
+            "Preserve branch-local terminal outputs through the typed merge; do not add a duplicate downstream call to the same terminal Atom merely to obtain Workflow outputs",
+            "Return one corrected workspace action and no explanation",
+        ];
+    if (intent === "finalize")
+        return [
+            "Audit remaining required Atom keys, outputs, and path obligations, then finalize the exact current revision",
+            "Use already materialized final branch results as Workflow outputs instead of re-executing their terminal Atom after the merge",
+            "Do not add business regions unless the compact progress proves a required capability is still unrealized",
+        ];
+    return [
+        "Add only the next small independently valid business region using exact selected Atom keys",
+        "Omit bindings unless Runtime previously reported an ambiguity",
+        "Do not repeat committed regions; Runtime owns graph edges, joins, internal references, and compilation",
+    ];
+}
+function collectDraftAtomKeys(step, target = new Set()) {
+    switch (step.kind) {
+        case "atom":
+            target.add(step.use);
+            break;
+        case "sequence":
+            step.steps.forEach((nested) => collectDraftAtomKeys(nested, target));
+            break;
+        case "parallel":
+            step.branches.forEach((nested) => collectDraftAtomKeys(nested, target));
+            break;
+        case "decision":
+            target.add(step.use);
+            Object.values(step.branches).forEach((branch) => {
+                if (branch.kind === "continue" || branch.kind === "terminal")
+                    return;
+                collectDraftAtomKeys(branch.kind === "revisit" ? branch.body : branch, target);
+            });
+            break;
+        case "map":
+            collectDraftAtomKeys(step.body, target);
+            break;
+        case "repeat":
+            collectDraftAtomKeys(step.body, target);
+            target.add(step.decision.use);
+            break;
+    }
+    return target;
+}
+function compactTransactionResult(result) {
+    return asJson(result.status === "committed" ? {
+        status: "committed", operationId: result.operationId, revision: result.revision.revision,
+        draftHash: result.revision.draftHash, workflowNodeCount: result.revision.validation.workflowNodeCount,
+    } : {
+        status: "rejected", operationId: result.operationId, code: result.code, message: result.message,
+        errors: result.errors,
+    });
+}
+function workspacePayload(args) {
+    const snapshot = args.workspace.snapshot();
+    const latest = snapshot.revisions.at(-1);
+    const realizedAtomKeys = latest ? collectDraftAtomKeys(latest.plannerDraft.flow) : new Set();
+    const remainingRequiredAtomKeys = snapshot.workspace.requiredAtomKeys.filter((key) => !realizedAtomKeys.has(key));
+    const incremental = snapshot.workspace.requiredAtomKeys.length > 12;
+    const intent = args.includeFullCatalog
+        ? "bootstrap"
+        : args.validationErrors.length > 0
+            ? "repair"
+            : remainingRequiredAtomKeys.length === 0
+                ? "finalize"
+                : "extend";
+    const authority = {
+        workspaceId: snapshot.workspace.workspaceId,
+        requestId: snapshot.workspace.requestId,
+        workflowName: snapshot.workspace.workflowName,
+        revision: snapshot.workspace.currentRevision,
+        draftHash: snapshot.workspace.currentDraftHash,
+        catalogHash: snapshot.workspace.catalogHash,
+    };
+    const references = promptReferences(args.referenceDirectory, snapshot.workspace.currentRevision);
+    const outputRepair = args.validationErrors.some(({ code }) => code === "PLANNING_WORKFLOW_OUTPUT_REQUIRED");
+    const outputsExist = Object.keys(latest?.outputs ?? {}).length > 0;
+    const actionContract = {
+        recommendedAction: outputRepair
+            ? "workspace-plan:set-workflow-output"
+            : intent === "finalize" && outputsExist
+                ? "workspace-finalize"
+                : "workspace-plan:add-or-repair-region",
+        plan: {
+            schemaVersion: "1.0", kind: "workspace-plan", finalize: outputRepair || intent === "finalize",
+            transaction: {
+                schemaVersion: "1.0", operationId: "stable-unique-id",
+                baseRevision: snapshot.workspace.currentRevision, baseDraftHash: snapshot.workspace.currentDraftHash,
+                operations: outputRepair || (intent === "finalize" && !outputsExist)
+                    ? [{ op: "set-workflow-output", name: "result-name", value: { source: "node", nodeId: "guaranteed-final-node", path: "output-field" } }]
+                    : [{ op: "add-region", block: { blockId: "business-region", plan: "must match the planning step contract from the bootstrap turn" } }],
+            },
+        },
+        supportedPlanOperations: ["add-region", "replace-region", "remove-region", "set-workflow-output", "remove-workflow-output"],
+        finalize: { schemaVersion: "1.0", kind: "workspace-finalize", revision: snapshot.workspace.currentRevision, draftHash: snapshot.workspace.currentDraftHash },
+        reportGap: {
+            schemaVersion: "1.0", kind: "workspace-report-gap",
+            report: {
+                schemaVersion: "1.0", kind: "missing-input", code: "PLANNING_REQUIRED_INPUT_UNAVAILABLE",
+                message: "what is unavailable", paths: ["exact path"], resolution: "what the user or an Atom must provide",
+            },
+        },
+    };
+    const progress = {
+        planningTurn: args.turn,
+        maxPlanningTurns: args.maximum,
+        remainingTurnsIncludingCurrent: args.maximum - args.turn + 1,
+        realizedAtomKeys: [...realizedAtomKeys].sort(),
+        remainingRequiredAtomKeys,
+        currentOutputs: latest?.outputs ?? {},
+        regionIndex: latest?.blocks.map(({ blockId, plan }) => ({ blockId, ...regionDigest(plan) })) ?? [],
+    };
+    if (!args.includeFullCatalog)
+        return asJson({
+            turnIntent: intent,
+            goal: args.plannerInput.goal,
+            workspaceAuthority: authority,
+            progress,
+            frontierSummary: compactFrontier(args.workspace.frontier()),
+            ...(args.previousResult?.status === "committed" ? { lastCommit: compactTransactionResult(args.previousResult) } : {}),
+            contract: actionContract,
+            activeRules: focusedRules(intent, args.validationErrors),
+            ...(references ? { references } : {}),
+        });
+    return asJson({
+        turnIntent: intent,
+        goal: args.plannerInput.goal,
+        context: args.plannerInput.context,
+        workspaceAuthority: {
+            ...authority,
+            selectedAtomKeys: snapshot.workspace.selectedAtomKeys,
+            requiredAtomKeys: snapshot.workspace.requiredAtomKeys,
+            runtimePolicy: snapshot.workspace.runtimePolicy,
+        },
+        planningCatalog: args.includeFullCatalog
+            ? args.catalog
+            : { schemaVersion: args.catalog.schemaVersion, hash: args.catalog.hash, atomKeys: args.catalog.atoms.map(({ key }) => key) },
+        frontier: args.workspace.frontier(),
+        committedRegions: latest?.blocks.map(({ blockId, plan }) => ({ blockId, control: summarizeStep(plan) })) ?? [],
+        currentOutputs: latest?.outputs ?? {},
+        ...(args.previousResult?.status === "committed" ? { lastCommit: compactTransactionResult(args.previousResult) } : {}),
+        planningBudget: { planningTurn: args.turn, maxPlanningTurns: args.maximum, remainingTurnsIncludingCurrent: args.maximum - args.turn + 1 },
+        planningStrategy: incremental ? {
+            mode: "incremental-regions",
+            reason: `This long plan requires ${snapshot.workspace.requiredAtomKeys.length} exact Atoms; keep every JSON response small and independently valid.`,
+            recommendedNewAtomCallsThisTurn: { min: 4, max: 10 },
+            finalizeThisTurn: remainingRequiredAtomKeys.length === 0,
+            remainingRequiredAtomKeys,
+        } : {
+            mode: "single-turn-if-valid",
+            finalizeThisTurn: true,
+            remainingRequiredAtomKeys,
+        },
+        contract: {
+            ...actionContract,
+            ...(args.includeFullCatalog ? { planningStepSchema: PlanningStepJsonSchema } : {}),
+        },
+        rules: [
+            incremental
+                ? "This is a long plan: submit one small independently valid business region with roughly 4-10 new Atom calls and finalize=false. Never emit or repeat the entire Workflow in one response; later turns append later regions"
+                : "This is a small plan: prefer one workspace-plan containing all semantic regions with finalize=true",
+            "Plan business nodes and structured control only. Runtime owns dependsOn, joins, edges, internal references, traversal budgets, WorkflowSpec and WorkflowIR",
+            "Do not write $input/$output/$item references or BindingEvidence. Omit bindings and let Runtime auto-bind exact or uniquely compatible fields",
+            "Use bindings only after Runtime reports an ambiguity. A binding selects {source:'workflow',path}, {source:'node',nodeId,path}, {source:'item',path}, or a literal {source:'value',value}",
+            "Parallel includes all branches in one region. Runtime creates fan-in dependencies for the following shared node",
+            "Use Decision branches with mode='continue' for common downstream flow, mode='revisit' with a finite maxIterations for local adjustment and return to the same gate, and mode='terminal' only for an explicit success/failure path",
+            "When two or more Decision branches continue and at least one branch contains local flow, every continuing branch must declare a non-empty result object. Use the same logical result keys on every branch, but map each key to the value produced on that branch. Runtime creates one typed merge and downstream nodes consume only the selected branch result",
+            "A branch result uses semantic sources, for example result:{finalDecision:{source:'node',nodeId:'manual-review',path:'reviewDecision'},auditSummary:{source:'node',nodeId:'manual-review',path:'auditSummary'}}. Direct branches may source the Decision Atom itself; branch-local paths must source their fresh final node",
+            "If the goal explicitly says one Decision branch skips an expensive Atom, keep that branch flow empty and export schema-compatible literal or already-available values in its result. Never execute the skipped Atom merely to make branch shapes match; Runtime can merge literal and branch-local results",
+            "Before finalizing, recursively audit committedRegions. A collect/adjust/revise/user-change branch must revisit the relevant gate or confirmation. It must not terminate after merely invoking its mutation Atom",
+            "A revisit branch must contain one complete repair cycle before returning: mutate the current value, rerun every affected calculation/check required by the goal, aggregate those fresh results through the relevant gate, and only then revisit the confirmation or decision. Runtime carries unambiguous branch outputs into the next Decision activation; never rely on its original pre-branch value",
+            "Do not duplicate a long common downstream pipeline inside every branch. Keep only branch-specific work in branches, export typed branch results, and let Runtime merge them before the following shared block",
+            "Conversely, when each continuing branch already invokes the same terminal Atom and therefore materializes the final output contract, include those final fields in the typed branch results and expose the merge directly as Workflow outputs. Never invoke that terminal Atom again after the merge merely to repackage identical outputs",
+            "Do not turn every natural-language mention of iteration into Workflow control: use map/repeat only when iterations require external branching, retry, pause, rollback, progress, multiple Atom calls, or an external stop condition",
+            "When one selected Atom accepts and returns the complete collection and only the final result is observable, call it once as a batch Atom; when an Atom accepts one item from an upstream collection and per-item control is required, use map. maxItems is a safety bound and maxConcurrency only limits simultaneous items; neither truncates the collection",
+            "For Map, select items with a semantic source. map.id names the control group; body Atom outputs become ordered arrays outside the Map",
+            "Runtime auto-binding is strict: exact names win; different names require one uniquely schema-compatible description match. Ambiguity or absence is returned with candidates and must not be guessed",
+            "Every requiredAtomKey must appear in a reachable control region before finalize. Conditional capabilities remain frozen in Decision/repeat branches even when the current example input may bypass them",
+            "Before finalize, declare at least one stable Workflow output that represents the user-visible result. A dynamically planned Workflow without outputs is invalid; side-effect-only completion is reserved for explicitly imported mature Workflows",
+            "A Decision or repeat decision must set select to an exact relative string field path in that Atom's output, such as 'action' or 'result.status'. Atom fields have no implicit control meaning",
+            "When the selected output field declares a finite string enum, branch ids must cover it exactly. For an open string field, keep a safe explicit defaultBranch",
+            "Set finalize=true when the plan should be validated and frozen in this same turn. Use workspace-finalize only for an already committed Revision",
+            "In incremental-regions mode, set finalize=true only when planningStrategy.remainingRequiredAtomKeys is empty and all outputs plus path obligations are complete",
+            "Report a deterministic missing input/capability instead of retrying or inventing data",
+        ],
+        ...(references ? { references } : {}),
+    });
+}
+function resultErrors(result) {
+    return result.errors.length ? [...result.errors] : [{
+            code: result.code, stage: "draft-normalization", path: "$", message: result.message,
+            hint: "Inspect the current Revision/frontier and submit a corrected transaction using the exact base Revision and hash",
+        }];
+}
+function validationErrorsFromCause(error) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (!Array.isArray(cause))
+        return [];
+    return cause.flatMap((item) => {
+        const parsed = WorkflowValidationErrorSchema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    });
+}
+function requiredAtomKeys(coverage) {
+    return [...new Set(coverage.plan.requirements
+            .filter(({ required }) => required)
+            .flatMap(({ resolution }) => resolution.kind === "covered" ? resolution.uses.map(({ atom }) => atom) : []))];
+}
+function tokenSum(attempts) {
+    const values = attempts.flatMap((attempt) => attempt.usage ? [attempt.usage] : []);
+    return values.length ? {
+        totalTokens: values.reduce((sum, value) => sum + value.totalTokens, 0),
+        inputTokens: values.reduce((sum, value) => sum + value.inputTokens, 0),
+        outputTokens: values.reduce((sum, value) => sum + value.outputTokens, 0),
+    } : undefined;
+}
+function workflowName(requestId) {
+    const suffix = requestId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(-64);
+    return `planned-${suffix || "workflow"}`;
+}
+export class PlanningController {
+    planner;
+    registry;
+    now;
+    constructor(planner, registry, now = () => new Date()) {
+        this.planner = planner;
+        this.registry = registry;
+        this.now = now;
+    }
+    async planAndCompile(input, target, options = {}) {
+        const resume = options.resumeCheckpoint ? PlanningCheckpointSchema.parse(options.resumeCheckpoint) : undefined;
+        if (resume && options.maxPlanningTurns !== undefined && options.maxPlanningTurns !== resume.maxPlanningTurns) {
+            throw new TypeError("maxPlanningTurns cannot change while resuming a persisted Planning Workspace");
+        }
+        const maxPlanningTurns = resume?.maxPlanningTurns ?? options.maxPlanningTurns ?? DEFAULT_MAX_PLANNING_TURNS;
+        const maxCapabilityRepairs = options.maxCapabilityRepairs ?? DEFAULT_MAX_CAPABILITY_REPAIRS;
+        const maxSelectedAtoms = options.maxSelectedAtoms ?? 128;
+        const maxErrors = options.maxErrorsPerRepair ?? DEFAULT_MAX_ERRORS;
+        for (const [name, value] of Object.entries({ maxPlanningTurns, maxCapabilityRepairs, maxSelectedAtoms, maxErrors })) {
+            if (!Number.isInteger(value) || value < 1)
+                throw new TypeError(`${name} must be a positive integer`);
+        }
+        if (maxPlanningTurns > 256)
+            throw new TypeError("maxPlanningTurns cannot exceed 256");
+        if (maxSelectedAtoms > 128)
+            throw new TypeError("maxSelectedAtoms cannot exceed 128");
+        const catalog = fullCatalog(this.registry);
+        const catalogIndex = buildPlannerCatalogIndex(catalog, this.registry.list({ includeDisabled: true }));
+        const catalogChanged = resume?.catalogIndexHash !== undefined && resume.catalogIndexHash !== catalogIndex.hash;
+        if (resume?.catalogIndexHash && resume.catalogIndexHash !== catalogIndex.hash && resume.phase !== "blocked_missing_atom") {
+            throw Object.assign(new Error("Cannot resume Planning Workspace because Atom Catalog changed"), { code: "PLANNING_CATALOG_CHANGED", retryable: false });
+        }
+        const attempts = [];
+        const rawOutputs = [];
+        const workspaceAttempts = [];
+        const validationFeedback = [];
+        let validationErrors = [...(resume?.lastValidationErrors ?? [])];
+        let planningTurns = resume?.planningTurnsConsumed ?? 0;
+        let promptPayloadBytes = 0;
+        let coverage = resume?.capabilityCoverage;
+        let selectedAtomKeys = [...(resume?.selectedAtomKeys ?? [])];
+        let planningCatalog = selectedAtomKeys.length ? selectPlannerCatalog(catalog, selectedAtomKeys) : undefined;
+        let workspace = resume?.workspaceSnapshot ? PlanningWorkspaceService.restore(this.registry, resume.workspaceSnapshot, { now: this.now }) : undefined;
+        let phase = resume?.phase ?? "capability-coverage";
+        let lastSubmittedRequestId = resume?.lastSubmittedRequestId;
+        let lastTransactionResult;
+        let plannerDraft = resume?.acceptedPlannerDraft ?? workspace?.snapshot().revisions.at(-1)?.plannerDraft;
+        if (phase === "blocked_missing_input" && workspace) {
+            workspace.resumeEditing(input.workflowInputs);
+            phase = "workspace";
+        }
+        if (phase === "blocked_missing_atom" && coverage) {
+            if (catalogChanged) {
+                coverage = undefined;
+                phase = "capability-coverage";
+                validationErrors = [];
+            }
+        }
+        const checkpoint = () => ({
+            schemaVersion: "1.0", phase, catalogIndexHash: catalogIndex.hash, selectedAtomKeys,
+            ...(planningCatalog ? { planningCatalogHash: planningCatalog.hash } : {}),
+            ...(coverage ? { capabilityCoverage: coverage } : {}),
+            ...(workspace ? { workspaceSnapshot: workspace.snapshot() } : {}),
+            planningTurnsConsumed: planningTurns, maxPlanningTurns, lastValidationErrors: validationErrors,
+            ...(lastSubmittedRequestId ? { lastSubmittedRequestId } : {}),
+            ...(plannerDraft ? { acceptedPlannerDraft: plannerDraft } : {}),
+        });
+        const audit = () => {
+            const usage = tokenSum(attempts);
+            const snapshot = workspace?.snapshot();
+            return {
+                catalogIndex,
+                ...(coverage ? { capabilityCoverage: coverage } : {}),
+                ...(planningCatalog ? { planningCatalog } : {}),
+                ...(snapshot ? { workspaceSnapshot: snapshot } : {}),
+                workspaceAttempts: [...workspaceAttempts],
+                ...(plannerDraft ? { plannerDraft } : {}),
+                validationFeedback: validationFeedback.map((errors) => [...errors]), checkpoint: checkpoint(),
+                metrics: {
+                    catalogAtomCount: catalogIndex.atoms.length, selectedAtomCount: selectedAtomKeys.length,
+                    catalogIndexBytes: Buffer.byteLength(JSON.stringify(catalogIndex)),
+                    planningCatalogBytes: planningCatalog ? Buffer.byteLength(JSON.stringify(planningCatalog)) : 0,
+                    promptPayloadBytes,
+                    capabilityTurns: attempts.filter(({ requestId }) => requestId.includes(":capability:")).length,
+                    workspaceTurns: workspaceAttempts.length,
+                    committedTransactions: workspaceAttempts.filter(({ status }) => status === "committed").length,
+                    rejectedTransactions: workspaceAttempts.filter(({ status }) => status === "rejected").length,
+                    planningTurns, maxPlanningTurns,
+                    totalDurationMs: attempts.reduce((sum, attempt) => sum + (attempt.durationMs ?? 0), 0),
+                    ...(usage ? { tokenUsage: usage } : {}),
+                },
+            };
+        };
+        const persist = async () => options.onCheckpoint?.(checkpoint(), audit(), { attempts: [...attempts], rawOutputs: [...rawOutputs] });
+        const fail = (message, code = "WORKFLOW_PLANNING_FAILED", retryable = false, cause) => new WorkflowPlanningFailedError(message, [...attempts], [...validationErrors], [...rawOutputs], audit(), { code, retryable, ...(cause !== undefined ? { cause } : {}) });
+        if (phase === "completed" && workspace) {
+            const current = workspace.snapshot().workspace;
+            const finalized = workspace.finalize({ revision: current.currentRevision, draftHash: current.currentDraftHash });
+            return { workflow: finalized.workflow, ir: finalized.ir, attempts, rawOutputs, audit: audit() };
+        }
+        if (coverage?.status === "blocked_missing_atom") {
+            phase = "blocked_missing_atom";
+            validationErrors = coverageErrors(coverage);
+            await persist();
+            throw fail(coverage.gaps[0].message, coverage.gaps[0].code);
+        }
+        try {
+            return await this.planner.withSession(target, { ...(options.model ?? {}), totalTimeoutMs: null, idleTimeoutMs: null }, async (session) => {
+                let workspaceTurnsInSession = 0;
+                if (!coverage) {
+                    for (let round = 0; round < maxCapabilityRepairs; round += 1) {
+                        const turn = {
+                            schemaVersion: "1.0", requestId: `${input.requestId}:capability:${round + 1}`, phase: "capability-coverage",
+                            payload: capabilityPayload(input, catalogIndex, options.promptReferenceDirectory),
+                            ...(validationErrors.length ? { previousValidationErrors: feedback(validationErrors, maxErrors) } : {}),
+                        };
+                        promptPayloadBytes += Buffer.byteLength(JSON.stringify(turn));
+                        try {
+                            const result = await session.plan(turn);
+                            attempts.push(result.attempt);
+                            rawOutputs.push(result.rawOutput);
+                            const parsed = PlannerCapabilityPlanSchema.safeParse(result.document);
+                            if (!parsed.success)
+                                validationErrors = schemaIssues(parsed.error.issues, "capability-schema");
+                            else {
+                                coverage = resolveCapabilityCoverage(parsed.data, this.registry);
+                                if (coverage.status === "blocked_missing_atom") {
+                                    validationErrors = coverageErrors(coverage);
+                                    validationFeedback.push(feedback(validationErrors, maxErrors));
+                                    if (round + 1 < maxCapabilityRepairs) {
+                                        coverage = undefined;
+                                        phase = "capability-coverage";
+                                        await persist();
+                                        continue;
+                                    }
+                                    phase = "blocked_missing_atom";
+                                    await persist();
+                                    throw fail(coverage.gaps[0].message, coverage.gaps[0].code);
+                                }
+                                if (coverage.selectedAtomKeys.length > maxSelectedAtoms)
+                                    validationErrors = [{
+                                            code: "PLANNING_SELECTED_ATOM_LIMIT_EXCEEDED", stage: "capability-resolution", path: "$.requirements",
+                                            message: `Capability plan selected ${coverage.selectedAtomKeys.length} Atoms; maximum is ${maxSelectedAtoms}`,
+                                            expected: maxSelectedAtoms, received: coverage.selectedAtomKeys.length, hint: "Remove unrelated optional capabilities",
+                                        }];
+                                else {
+                                    selectedAtomKeys = [...coverage.selectedAtomKeys];
+                                    planningCatalog = selectPlannerCatalog(catalog, selectedAtomKeys);
+                                    validationErrors = [];
+                                    phase = "workspace";
+                                    await persist();
+                                    break;
+                                }
+                            }
+                        }
+                        catch (error) {
+                            if (error instanceof WorkflowPlanningFailedError)
+                                throw error;
+                            if (!(error instanceof PlanningModelExecutionError))
+                                throw error;
+                            attempts.push(error.attempt);
+                            if (error.rawOutput !== undefined)
+                                rawOutputs.push(error.rawOutput);
+                            const repairable = outputFailure(error);
+                            if (!repairable)
+                                throw fail(error.message, error.code, error.retryable, error);
+                            validationErrors = [repairable];
+                        }
+                        validationFeedback.push(feedback(validationErrors, maxErrors));
+                        await persist();
+                    }
+                    if (!coverage || coverage.status !== "covered" || !planningCatalog) {
+                        throw fail(`Planner did not produce valid capability coverage after ${maxCapabilityRepairs} attempts`, "PLANNING_CAPABILITY_INVALID");
+                    }
+                }
+                if (!coverage || coverage.status !== "covered") {
+                    throw fail("Planning Workspace has no covered Capability Authority", "PLANNING_CAPABILITY_INVALID");
+                }
+                if (!planningCatalog)
+                    planningCatalog = selectPlannerCatalog(catalog, selectedAtomKeys);
+                if (workspace?.snapshot().workspace.status === "blocked_missing_atom") {
+                    workspace.updateCatalogAuthority(selectedAtomKeys, requiredAtomKeys(coverage), coverage.catalogHash);
+                }
+                if (!workspace) {
+                    workspace = PlanningWorkspaceService.create(this.registry, {
+                        workspaceId: `${input.requestId}:workspace`, requestId: input.requestId, goal: input.goal,
+                        workflowName: workflowName(input.requestId), workflowInputs: input.workflowInputs, context: input.context,
+                        runtimePolicy: input.runtimePolicy, selectedAtomKeys,
+                        requiredAtomKeys: requiredAtomKeys(coverage), catalogHash: coverage.catalogHash,
+                    }, { now: this.now });
+                    phase = "workspace";
+                    await persist();
+                }
+                while (planningTurns < maxPlanningTurns) {
+                    planningTurns += 1;
+                    workspaceTurnsInSession += 1;
+                    const requestId = `${input.requestId}:workspace:${planningTurns}`;
+                    lastSubmittedRequestId = requestId;
+                    const payload = workspacePayload({
+                        plannerInput: input,
+                        catalog: planningCatalog,
+                        workspace,
+                        target,
+                        turn: planningTurns,
+                        maximum: maxPlanningTurns,
+                        includeFullCatalog: workspaceTurnsInSession === 1,
+                        validationErrors,
+                        ...(options.promptReferenceDirectory ? { referenceDirectory: options.promptReferenceDirectory } : {}),
+                        ...(lastTransactionResult ? { previousResult: lastTransactionResult } : {}),
+                    });
+                    const turn = {
+                        schemaVersion: "1.0", requestId, phase: "workspace", payload,
+                        ...(validationErrors.length ? { previousValidationErrors: feedback(validationErrors, maxErrors) } : {}),
+                    };
+                    promptPayloadBytes += Buffer.byteLength(JSON.stringify(turn));
+                    await persist();
+                    try {
+                        const result = await session.plan(turn);
+                        attempts.push(result.attempt);
+                        rawOutputs.push(result.rawOutput);
+                        const parsed = PlanningWorkspaceActionSchema.safeParse(result.document);
+                        if (!parsed.success) {
+                            validationErrors = schemaIssues(parsed.error.issues, "draft-schema");
+                            workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "rejected", errors: validationErrors });
+                        }
+                        else if (parsed.data.kind === "workspace-plan") {
+                            lastTransactionResult = workspace.applyTransaction(parsed.data.transaction);
+                            if (lastTransactionResult.status === "committed") {
+                                validationErrors = [];
+                                plannerDraft = lastTransactionResult.revision.plannerDraft;
+                                workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "committed", result: lastTransactionResult, errors: [] });
+                                if (parsed.data.finalize) {
+                                    const finalized = workspace.finalize({ revision: lastTransactionResult.revision.revision, draftHash: lastTransactionResult.revision.draftHash });
+                                    plannerDraft = finalized.revision.plannerDraft;
+                                    phase = "completed";
+                                    workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "finalized", errors: [] });
+                                    await persist();
+                                    return Object.freeze({ workflow: Object.freeze(finalized.workflow), ir: finalized.ir, attempts: Object.freeze([...attempts]), rawOutputs: Object.freeze([...rawOutputs]), audit: audit() });
+                                }
+                            }
+                            else {
+                                validationErrors = resultErrors(lastTransactionResult);
+                                workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "rejected", result: lastTransactionResult, errors: validationErrors });
+                            }
+                        }
+                        else if (parsed.data.kind === "workspace-report-gap") {
+                            workspace.reportGap(parsed.data.report);
+                            phase = parsed.data.report.kind === "missing-atom" ? "blocked_missing_atom" : "blocked_missing_input";
+                            validationErrors = [{ code: parsed.data.report.code, stage: "data-link", path: parsed.data.report.paths[0] ?? "$", message: parsed.data.report.message, hint: parsed.data.report.resolution }];
+                            workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "blocked", errors: validationErrors });
+                            await persist();
+                            throw fail(parsed.data.report.message, parsed.data.report.code);
+                        }
+                        else {
+                            const finalized = workspace.finalize({ revision: parsed.data.revision, draftHash: parsed.data.draftHash });
+                            plannerDraft = finalized.revision.plannerDraft;
+                            phase = "completed";
+                            validationErrors = [];
+                            workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: result.rawOutput, status: "finalized", errors: [] });
+                            await persist();
+                            return Object.freeze({ workflow: Object.freeze(finalized.workflow), ir: finalized.ir, attempts: Object.freeze([...attempts]), rawOutputs: Object.freeze([...rawOutputs]), audit: audit() });
+                        }
+                    }
+                    catch (error) {
+                        if (error instanceof WorkflowPlanningFailedError)
+                            throw error;
+                        if (error instanceof PlanningModelExecutionError) {
+                            attempts.push(error.attempt);
+                            if (error.rawOutput !== undefined)
+                                rawOutputs.push(error.rawOutput);
+                            const repairable = outputFailure(error);
+                            if (!repairable)
+                                throw fail(error.message, error.code, error.retryable, error);
+                            validationErrors = [repairable];
+                            workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: error.rawOutput ?? "", status: "rejected", errors: validationErrors });
+                        }
+                        else {
+                            const code = typeof error?.code === "string" ? error.code : undefined;
+                            if (!code?.startsWith("PLANNING_"))
+                                throw error;
+                            const caused = validationErrorsFromCause(error);
+                            validationErrors = caused.length ? caused : [{ code: "PLANNER_DRAFT_NORMALIZATION_FAILED", stage: "draft-normalization", path: "$", message: `${code}: ${error instanceof Error ? error.message : String(error)}`, hint: "Use the current Workspace Revision/hash and resolve all validation issues before finalizing" }];
+                            workspaceAttempts.push({ requestId, planningTurn: planningTurns, rawOutput: "", status: "rejected", errors: validationErrors });
+                        }
+                    }
+                    validationFeedback.push(feedback(validationErrors, maxErrors));
+                    await persist();
+                }
+                validationErrors = [{
+                        code: "PLANNER_TURN_LIMIT_EXCEEDED", stage: "draft-normalization", path: "$",
+                        message: `Planning Workspace turn budget exhausted: ${maxPlanningTurns}`,
+                        expected: maxPlanningTurns, received: planningTurns,
+                        hint: "Increase maxPlanningTurns or add more complete control regions per transaction",
+                    }];
+                await persist();
+                throw fail(`Planner did not finalize the Planning Workspace after ${maxPlanningTurns} turns`, "PLANNER_TURN_LIMIT_EXCEEDED");
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkflowPlanningFailedError)
+                throw error;
+            const code = typeof error?.code === "string" ? error.code : "WORKFLOW_PLANNING_FAILED";
+            throw fail(error instanceof Error ? error.message : String(error), code, error?.retryable === true, error);
+        }
+    }
+}
+//# sourceMappingURL=planning-controller.js.map