akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/workflows/ir/compile.js

@@ -0,0 +1,375 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Frontends -> unresolved workflow plan compilers.
+ *
+ * Two frontends, one source-plan shape. Engine resolution in `freeze.ts`
+ * lowers this shape into the only executable format, workflow IR v3.
+ *
+ *   - {@link compileWorkflowProgram} — YAML orchestration programs
+ *     (`program/parser.ts`). Pure and deterministic; performs FULL expression
+ *     validation (closed `${{ … }}` grammar, earlier-step references,
+ *     whole-value contexts, `item`/`item_index` scoping) and MERGES the
+ *     Returns accumulated `WorkflowError`s rather than throwing.
+ *   - {@link compileWorkflowPlan} — classic LINEAR markdown workflows
+ *     (`parser.ts`), the stable CLI contract: one unit node per step with the
+ *     fail-fast default. The P1
+ *     markdown orchestration grammar is gone — this path is linear-only.
+ *
+ * Node-id convention (stable, unique within a plan):
+ *   step root  → `<stepId>`          (agent) or `<stepId>.map` (map)
+ *   map unit   → `<stepId>.unit`     (template instantiated per item)
+ *   gate       → `<stepId>.gate`
+ */
+import { formatReference, listReferences, parseTemplate } from "../program/expressions.js";
+/**
+ * Compile a parsed YAML program into a frozen-plan-ready graph. Assumes the
+ * program came out of `parseWorkflowProgram` ok (structure already valid);
+ * this pass owns the expression-language rules the parser deliberately does
+ * not check:
+ *
+ *   - every `${{ … }}` in instructions / `map.over` / `route.input` parses
+ *     against the CLOSED grammar;
+ *   - `steps.<id>` references name an EARLIER step (a producer that has
+ *     already run when the reference resolves);
+ *   - `map.over` and `route.input` are single whole-value references — a bare
+ *     `${{ … }}` with no surrounding text;
+ *   - `item` / `item_index` appear only inside a map unit's instructions.
+ */
+export function compileWorkflowProgram(program) {
+    const errors = [];
+    const allStepIds = new Set(program.steps.map((s) => s.id));
+    const earlierStepIds = new Set();
+    const steps = [];
+    program.steps.forEach((step, index) => {
+        const check = { allStepIds, earlierStepIds, errors };
+        if (step.unit) {
+            checkTemplateExpressions(step.unit.instructions, {
+                ...check,
+                line: step.unit.source.start,
+                label: `Step "${step.id}" instructions`,
+                inMapUnit: false,
+            });
+        }
+        if (step.map) {
+            checkWholeValueExpression(step.map.over, {
+                ...check,
+                line: step.source.start,
+                label: `Step "${step.id}" map.over`,
+            });
+            checkTemplateExpressions(step.map.unit.instructions, {
+                ...check,
+                line: step.map.unit.source.start,
+                label: `Step "${step.id}" instructions`,
+                inMapUnit: true,
+            });
+        }
+        if (step.route) {
+            checkWholeValueExpression(step.route.input, {
+                ...check,
+                line: step.source.start,
+                label: `Step "${step.id}" route.input`,
+            });
+        }
+        steps.push(compileProgramStep(step, index, program.defaults));
+        earlierStepIds.add(step.id);
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const paramNames = program.params ? Object.keys(program.params) : [];
+    return {
+        ok: true,
+        // Non-fatal advisories (redesign addendum). Warnings NEVER change the plan
+        // or its hash — they are computed alongside the frozen plan and surfaced by
+        // `workflow validate` / `workflow start`, never persisted onto the run row.
+        warnings: collectProgramWarnings(program),
+        plan: {
+            title: program.name,
+            ...(paramNames.length > 0 ? { params: paramNames } : {}),
+            // Reviewer #12: freeze the per-param schemas into the plan so `--params`
+            // can be validated at start and re-asserted at brief/report against the
+            // exact schemas the run was created with (the plan hash covers them).
+            ...(program.params && paramNames.length > 0 ? { paramSchemas: program.params } : {}),
+            // Budget ceilings (addendum R2): frozen onto the plan so enforcement is
+            // a pure function of (frozen plan, journal) — never the live asset.
+            ...(program.budget
+                ? {
+                    budget: {
+                        ...(program.budget.maxTokens !== undefined ? { maxTokens: program.budget.maxTokens } : {}),
+                        ...(program.budget.maxUnits !== undefined ? { maxUnits: program.budget.maxUnits } : {}),
+                    },
+                }
+                : {}),
+            steps,
+        },
+    };
+}
+function compileProgramStep(step, index, defaults) {
+    const gate = {
+        kind: "gate",
+        id: `${step.id}.gate`,
+        stepId: step.id,
+        criteria: step.gate?.criteria ?? [],
+        // TODO(R2): maxLoops execution (bounded evaluator-optimizer) is engine
+        // rework scope; carried through the frozen plan now.
+        ...(step.gate?.maxLoops !== undefined ? { maxLoops: step.gate.maxLoops } : {}),
+        // Reviewer #18: a required gate rides the frozen plan so BOTH surfaces
+        // (engine + report) enforce it identically.
+        ...(step.gate?.required !== undefined ? { required: step.gate.required } : {}),
+    };
+    let root;
+    if (step.unit) {
+        root = compileProgramUnit(step.unit, step.id, defaults);
+    }
+    else if (step.map) {
+        root = {
+            kind: "map",
+            id: `${step.id}.map`,
+            over: step.map.over,
+            template: compileProgramUnit(step.map.unit, `${step.id}.unit`, defaults),
+            ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+            reducer: step.map.reducer ?? "collect",
+            source: step.source,
+        };
+    }
+    return {
+        stepId: step.id,
+        title: step.title ?? step.id,
+        sequenceIndex: index,
+        ...(root ? { root } : {}),
+        ...(step.route
+            ? {
+                route: {
+                    input: step.route.input,
+                    when: Object.fromEntries(step.route.branches.map((b) => [b.match, b.stepId])),
+                    ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
+                },
+            }
+            : {}),
+        // TODO(R2): validating the reducer result against this schema (typed step
+        // artifacts) is engine-rework scope; the frozen plan carries it now.
+        ...(step.output !== undefined ? { outputSchema: step.output } : {}),
+        gate,
+    };
+}
+/**
+ * Lower one source unit into the unresolved structural plan. Engine/model/time
+ * settings remain on the parsed source until the single freeze boundary.
+ */
+function compileProgramUnit(unit, id, defaults) {
+    return {
+        kind: "unit",
+        id,
+        instructions: unit.instructions,
+        // YAML program instructions are `${{ … }}` templates (validated above);
+        // the executor resolves them per unit.
+        templating: "expressions",
+        ...(unit.output !== undefined ? { schema: unit.output } : {}),
+        // TODO(R2): retry dispatch is engine-rework scope; carried through now.
+        ...(unit.retry ? { retry: { max: unit.retry.max, on: [...unit.retry.on] } } : {}),
+        onError: unit.onError ?? defaults?.onError ?? "fail",
+        ...(unit.env ? { env: [...unit.env] } : {}),
+        ...(unit.isolation !== undefined ? { isolation: unit.isolation } : {}),
+        source: unit.source,
+    };
+}
+/** Validate every `${{ … }}` in a free-text template (instructions). */
+function checkTemplateExpressions(text, check) {
+    const parsed = parseTemplate(text);
+    if (!parsed.ok) {
+        for (const err of parsed.errors) {
+            check.errors.push({ line: check.line, message: `${check.label}: ${err.message}` });
+        }
+        return;
+    }
+    for (const ref of listReferences(parsed.segments)) {
+        checkReference(ref, check, check.inMapUnit);
+    }
+}
+/**
+ * Validate a whole-value field (`map.over`, `route.input`): the text must be
+ * exactly one `${{ … }}` reference with no surrounding literal text, so the
+ * engine can resolve it to a RAW value (array/object), never a string splice.
+ */
+function checkWholeValueExpression(text, check) {
+    const parsed = parseTemplate(text);
+    if (!parsed.ok) {
+        for (const err of parsed.errors) {
+            check.errors.push({ line: check.line, message: `${check.label}: ${err.message}` });
+        }
+        return;
+    }
+    const [first] = parsed.segments;
+    if (parsed.segments.length !== 1 || first?.kind !== "reference") {
+        check.errors.push({
+            line: check.line,
+            message: `${check.label} must be a single whole-value \${{ … }} reference with no surrounding text ` +
+                `(e.g. "\${{ steps.discover.output.files }}"), got ${JSON.stringify(text)}.`,
+        });
+        return;
+    }
+    // `item`/`item_index` never exist where a whole-value field resolves (the
+    // item list itself, or a spine route input), so inMapUnit is always false.
+    checkReference(first.expr, check, false);
+}
+function checkReference(ref, check, inMapUnit) {
+    switch (ref.kind) {
+        case "item":
+        case "itemIndex": {
+            if (!inMapUnit) {
+                check.errors.push({
+                    line: check.line,
+                    message: `${check.label}: "\${{ ${formatReference(ref)} }}" is only valid inside a map unit's instructions.`,
+                });
+            }
+            return;
+        }
+        case "stepOutput": {
+            if (!check.earlierStepIds.has(ref.stepId)) {
+                const why = check.allStepIds.has(ref.stepId)
+                    ? `step "${ref.stepId}" does not come before this step — references must name an earlier step (a producer that has already run)`
+                    : `"${ref.stepId}" is not a step in this workflow`;
+                check.errors.push({
+                    line: check.line,
+                    message: `${check.label}: "\${{ ${formatReference(ref)} }}" cannot be resolved — ${why}.`,
+                });
+            }
+            return;
+        }
+        case "param": {
+            // Param presence is a RUN-SCOPE concern, never a compile-time one. A
+            // declared `params:` block is NOT a closed set of legal references: the
+            // runtime resolves any param SUPPLIED at start (`resolveReference`), and
+            // `validateWorkflowParams` documents that undeclared params are permitted
+            // — so `${{ params.mode }}` with `mode` passed via `--params` runs fine
+            // even when only `files` is declared. At compile time an undeclared
+            // reference is indistinguishable from that legitimate start-supplied
+            // extra, so treating the block as closed would reject a runtime-supported
+            // authoring pattern and put the two layers in disagreement. A genuine typo
+            // (`params.changed_file` for `changed_files`) surfaces at run time with a
+            // precise "is not defined in the run's params" error instead. As a lint-time
+            // heads-up short of rejection, `collectProgramWarnings` (below) emits a
+            // non-fatal WARNING for an undeclared reference when a `params:` block is
+            // declared — never an error, so the runtime-supported pattern still compiles.
+            return;
+        }
+    }
+}
+// ── Non-fatal warnings ───────────────────────────────────────────────────────
+/**
+ * Collect the program's non-fatal WARNINGS — advisories that never fail
+ * compilation, never change the frozen plan or its hash, and are surfaced by
+ * `workflow validate` (human + JSON) and as `warn()` lines at `workflow start`.
+ *
+ * Two promised-but-previously-missing warnings (redesign addendum):
+ *
+ *   A. A unit/map step with NO step-level `output:` schema carries its units'
+ *      raw results as an untyped artifact — permitted, but the addendum says
+ *      "the validator warns". Anchored on the STEP's `output` (the reducer /
+ *      step-artifact schema); a per-unit `output:` types the unit result but
+ *      leaves the step artifact untyped.
+ *   B. A `${{ params.<name> }}` reference to an UNDECLARED param, but ONLY when
+ *      the program declares a `params:` block. Compile-time REJECTION was tried
+ *      and reverted (see the `case "param"` note above): the runtime legitimately
+ *      resolves any param supplied at start, declared or not. The agreed middle
+ *      ground is a warning — a likely typo (`changed_file` for `changed_files`)
+ *      surfaces at lint time, while a genuinely start-supplied extra still runs.
+ *      With no `params:` block there is nothing to compare against, so B is silent.
+ *
+ * Pure and deterministic; the returned order is document order per step
+ * (warning A, then each undeclared-param reference in field/document order).
+ * Only called on an OK compile, so every template here already parsed cleanly.
+ */
+export function collectProgramWarnings(program) {
+    const warnings = [];
+    const declaredParams = program.params ? new Set(Object.keys(program.params)) : undefined;
+    for (const step of program.steps) {
+        // Warning A — a unit/map step with no step-level output schema.
+        if ((step.unit || step.map) && step.output === undefined) {
+            warnings.push({
+                line: step.source.start,
+                message: `Step "${step.id}" declares no \`output:\` schema — its unit results are carried as an untyped ` +
+                    `artifact (permitted). Add an \`output:\` JSON Schema to type and validate the step artifact.`,
+            });
+        }
+        // Warning B — references to a param the declared `params:` block omits.
+        if (declaredParams)
+            collectUndeclaredParamWarnings(step, declaredParams, warnings);
+    }
+    return warnings;
+}
+/**
+ * Push a warning for every `${{ params.<name> }}` reference in `step` whose
+ * name is not in the declared param set. Walks the same template-bearing
+ * fields the compiler validates (unit / map.over + map unit / route.input) so
+ * the step + field context in the message matches the error labels.
+ */
+function collectUndeclaredParamWarnings(step, declared, warnings) {
+    const declaredList = [...declared].join(", ");
+    const scan = (text, line, label) => {
+        const parsed = parseTemplate(text);
+        if (!parsed.ok)
+            return; // OK compile guarantees this parses; defensive only.
+        for (const ref of listReferences(parsed.segments)) {
+            if (ref.kind !== "param" || declared.has(ref.name))
+                continue;
+            warnings.push({
+                line,
+                message: `${label}: "\${{ ${formatReference(ref)} }}" references a param not declared in \`params:\` ` +
+                    `(declared: ${declaredList || "none"}) — likely a typo. An undeclared param supplied at start still ` +
+                    `resolves at run time.`,
+            });
+        }
+    };
+    if (step.unit)
+        scan(step.unit.instructions, step.unit.source.start, `Step "${step.id}" instructions`);
+    if (step.map) {
+        scan(step.map.over, step.source.start, `Step "${step.id}" map.over`);
+        scan(step.map.unit.instructions, step.map.unit.source.start, `Step "${step.id}" instructions`);
+    }
+    if (step.route)
+        scan(step.route.input, step.source.start, `Step "${step.id}" route.input`);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontend B — classic markdown workflow
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Compile a markdown `WorkflowDocument` to an unresolved structural plan. Pure
+ * and deterministic: the same document always compiles to the same plan.
+ * Linear workflows produce one fail-fast unit per step guarded by its gate.
+ */
+export function compileWorkflowPlan(document) {
+    const params = document.parameters?.map((p) => p.name);
+    return {
+        title: document.title,
+        ...(params && params.length > 0 ? { params } : {}),
+        steps: document.steps.map(compileMarkdownStep),
+    };
+}
+function compileMarkdownStep(step) {
+    const gate = {
+        kind: "gate",
+        id: `${step.id}.gate`,
+        stepId: step.id,
+        criteria: step.completionCriteria?.map((c) => c.text) ?? [],
+    };
+    return {
+        stepId: step.id,
+        title: step.title,
+        sequenceIndex: step.sequenceIndex,
+        root: {
+            kind: "unit",
+            id: step.id,
+            instructions: step.instructions.text,
+            // Stable contract: markdown instructions are opaque data, passed to the
+            // agent byte-exact. A literal `${{ … }}` (GitHub Actions syntax, docs of
+            // the YAML format) is content here, never expression grammar.
+            templating: "verbatim",
+            // Markdown has no failure-policy surface; the fail-fast default applies.
+            onError: "fail",
+            source: step.instructions.source,
+        },
+        gate,
+    };
+}

package/dist/workflows/ir/freeze.js

@@ -0,0 +1,243 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import path from "node:path";
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { resolveLlmEngineUse, } from "../../integrations/agent/engine-resolution.js";
+import { resolveLlmModel, resolveModel } from "../../integrations/agent/model-aliases.js";
+import { getBuiltinAgentProfile } from "../../integrations/agent/profiles.js";
+import { HARNESS_BY_ID } from "../../integrations/harnesses/index.js";
+import { workflowMaxConcurrency } from "../concurrency-policy.js";
+import { compileWorkflowPlan, compileWorkflowProgram, } from "./compile.js";
+import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "./schema.js";
+/**
+ * The only source-to-runtime boundary. Source compilation remains pure; engine
+ * selection and every dispatch-significant setting are resolved here once.
+ */
+export function compileResolveFreezeWorkflow(asset, config) {
+    const preliminary = asset.program ? compileProgram(asset) : compileMarkdown(asset);
+    const engines = {};
+    const maxConcurrency = frozenConcurrency(config);
+    const programDefaults = asset.program?.defaults;
+    const freezeInvocation = (unit) => {
+        const layers = [...(programDefaults ? [programDefaults] : []), ...(unit ? [unit] : [])];
+        const name = selectedEngine(config, layers);
+        if (!name)
+            throw new ConfigError("No workflow engine is selected. Set defaults.engine or workflow defaults.engine.", "INVALID_CONFIG_FILE");
+        const engine = engineDefinition(config, name);
+        addSnapshot(config, name, engines);
+        const model = exactModel(config, name, engine, layers);
+        const timeoutMs = effectiveTimeout(config, engine, layers);
+        const llm = engine.kind === "llm" ? mergedLlmOverrides(layers) : undefined;
+        if (engine.kind !== "llm" && llm !== undefined) {
+            throw new ConfigError(`Workflow engine "${name}" is an agent engine and cannot receive llm overrides.`, "INVALID_CONFIG_FILE");
+        }
+        return { engine: name, model, timeoutMs, ...(llm ? { llm } : {}) };
+    };
+    const freezeUnit = (node, unit) => ({
+        kind: "unit",
+        id: node.id,
+        instructions: node.instructions,
+        templating: node.templating ?? "verbatim",
+        invocation: freezeInvocation(unit),
+        ...(node.schema ? { schema: node.schema } : {}),
+        ...(node.retry ? { retry: node.retry } : {}),
+        onError: node.onError,
+        ...(node.env ? { env: node.env } : {}),
+        isolation: node.isolation ?? "none",
+        ...(node.source ? { source: node.source } : {}),
+    });
+    const steps = preliminary.steps.map((step, index) => {
+        const sourceStep = asset.program?.steps[index];
+        const sourceUnit = sourceStep?.unit ?? sourceStep?.map?.unit;
+        const root = step.root
+            ? step.root.kind === "map"
+                ? {
+                    kind: "map",
+                    id: step.root.id,
+                    over: step.root.over,
+                    template: freezeUnit(step.root.template, sourceUnit),
+                    concurrency: step.root.concurrency ?? 1,
+                    reducer: step.root.reducer,
+                    ...(step.root.source ? { source: step.root.source } : {}),
+                }
+                : freezeUnit(step.root, sourceUnit)
+            : undefined;
+        const criteria = step.gate.criteria;
+        const judge = criteria.length === 0 ? null : freezeGateJudge(config, engines, step.gate.required === true);
+        const gate = {
+            kind: "gate",
+            id: `${step.stepId}.gate`,
+            stepId: step.stepId,
+            criteria,
+            maxLoops: step.gate.maxLoops ?? 1,
+            required: step.gate.required === true,
+            judge,
+        };
+        return {
+            stepId: step.stepId,
+            title: step.title,
+            sequenceIndex: step.sequenceIndex,
+            ...(root ? { root } : {}),
+            ...(step.route ? { route: step.route } : {}),
+            ...(step.outputSchema ? { outputSchema: step.outputSchema } : {}),
+            gate,
+        };
+    });
+    const plan = decodeWorkflowPlanV3({
+        irVersion: WORKFLOW_IR_VERSION,
+        title: preliminary.title,
+        ...(preliminary.params ? { params: preliminary.params } : {}),
+        ...(preliminary.paramSchemas ? { paramSchemas: preliminary.paramSchemas } : {}),
+        ...(preliminary.budget ? { budget: preliminary.budget } : {}),
+        execution: { maxConcurrency, engines },
+        steps,
+    });
+    return {
+        warnings: asset.program ? preliminary.warnings : [],
+        plan,
+    };
+}
+function compileProgram(asset) {
+    if (!asset.program)
+        throw new UsageError(`Workflow asset ${asset.ref} has no YAML program.`);
+    const compiled = compileWorkflowProgram(asset.program);
+    if (!compiled.ok)
+        throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"));
+    return { ...compiled.plan, warnings: compiled.warnings };
+}
+function compileMarkdown(asset) {
+    if (!asset.document)
+        throw new UsageError(`Workflow asset ${asset.ref} has no source document.`);
+    return { ...compileWorkflowPlan(asset.document), warnings: [] };
+}
+function selectedEngine(config, layers) {
+    for (let index = layers.length - 1; index >= 0; index--)
+        if (layers[index]?.engine !== undefined)
+            return layers[index]?.engine;
+    return config.defaults?.engine;
+}
+function engineDefinition(config, name) {
+    const engine = config.engines?.[name];
+    if (!engine)
+        throw new ConfigError(`Engine "${name}" is not configured.`, "INVALID_CONFIG_FILE");
+    return engine;
+}
+function exactModel(config, name, engine, layers) {
+    let selected;
+    for (const layer of layers)
+        if (layer.model !== undefined)
+            selected = layer.model;
+    selected ??= engine.model;
+    if (!selected) {
+        if (engine.kind === "llm")
+            throw new ConfigError(`LLM engine "${name}" has no model.`, "INVALID_CONFIG_FILE");
+        if (engine.platform === "opencode-sdk") {
+            const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+            if (fallbackName) {
+                const fallback = engineDefinition(config, fallbackName);
+                if (fallback.kind !== "llm") {
+                    throw new ConfigError(`SDK engine "${name}" fallback "${fallbackName}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+                }
+                return exactModel(config, fallbackName, fallback, []);
+            }
+        }
+        return null;
+    }
+    if (engine.kind === "llm")
+        return resolveLlmModel(selected, name, config.modelAliases);
+    return resolveModel(selected, engine.platform, engine.modelAliases, config.modelAliases);
+}
+function effectiveTimeout(config, engine, layers) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (Object.hasOwn(layers[index] ?? {}, "timeoutMs"))
+            return layers[index]?.timeoutMs ?? null;
+    }
+    if (Object.hasOwn(engine, "timeoutMs"))
+        return engine.timeoutMs ?? null;
+    if (engine.kind === "llm")
+        return DEFAULT_LLM_TIMEOUT_MS;
+    if (engine.platform === "opencode-sdk") {
+        const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+        if (fallbackName) {
+            const fallback = engineDefinition(config, fallbackName);
+            if (fallback.kind === "llm") {
+                return Object.hasOwn(fallback, "timeoutMs") ? (fallback.timeoutMs ?? null) : DEFAULT_LLM_TIMEOUT_MS;
+            }
+        }
+    }
+    return DEFAULT_AGENT_TIMEOUT_MS;
+}
+function mergedLlmOverrides(layers) {
+    let merged;
+    for (const layer of layers)
+        if (layer.llm)
+            merged = deepMergeConfig(merged ?? {}, layer.llm);
+    return merged;
+}
+function addSnapshot(config, name, target) {
+    if (target[name])
+        return;
+    const engine = engineDefinition(config, name);
+    if (engine.kind === "llm") {
+        const resolved = resolveLlmEngineUse(config, [{ engine: name }]);
+        const snapshot = {
+            name,
+            kind: "llm",
+            endpoint: engine.endpoint,
+            model: exactModel(config, name, engine, []),
+            concurrency: engine.concurrency ?? 1,
+            ...(engine.provider ? { provider: engine.provider } : {}),
+            ...(resolved.credential ? { credential: resolved.credential } : {}),
+            ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
+            ...(engine.maxTokens !== undefined ? { maxTokens: engine.maxTokens } : {}),
+            ...(engine.supportsJsonSchema !== undefined ? { supportsJsonSchema: engine.supportsJsonSchema } : {}),
+            ...(engine.extraParams ? { extraParams: engine.extraParams } : {}),
+            ...(engine.contextLength !== undefined ? { contextLength: engine.contextLength } : {}),
+            ...(engine.enableThinking !== undefined ? { enableThinking: engine.enableThinking } : {}),
+        };
+        target[name] = snapshot;
+        return;
+    }
+    const harness = HARNESS_BY_ID.get(engine.platform);
+    if (!harness?.capabilities.agentDispatch)
+        throw new ConfigError(`Engine "${name}" cannot dispatch platform ${engine.platform}.`, "INVALID_CONFIG_FILE");
+    const sdk = engine.platform === "opencode-sdk";
+    const builtin = getBuiltinAgentProfile(engine.platform);
+    const fallback = sdk ? (engine.llmEngine ?? config.defaults?.llmEngine ?? null) : null;
+    if (fallback)
+        addSnapshot(config, fallback, target);
+    const snapshot = {
+        name,
+        kind: "agent",
+        runnerKind: sdk ? "sdk" : "agent",
+        platform: engine.platform,
+        bin: engine.bin ?? builtin?.bin ?? (sdk ? "opencode" : engine.platform),
+        args: [...(engine.args ?? builtin?.args ?? [])],
+        workspace: engine.workspace ? path.resolve(engine.workspace) : null,
+        envPassthrough: [...(builtin?.envPassthrough ?? [])],
+        commandBuilder: engine.platform,
+        fallbackLlmEngine: fallback,
+    };
+    target[name] = snapshot;
+}
+function freezeGateJudge(config, engines, required) {
+    const resolved = resolveLlmEngineUse(config, [], { optional: true });
+    if (!resolved) {
+        if (required)
+            throw new ConfigError("A required workflow gate needs defaults.llmEngine at start.", "LLM_NOT_CONFIGURED");
+        return null;
+    }
+    addSnapshot(config, resolved.engine, engines);
+    return {
+        engine: resolved.engine,
+        model: exactModel(config, resolved.engine, engineDefinition(config, resolved.engine), []),
+        timeoutMs: resolved.timeoutMs,
+    };
+}
+function frozenConcurrency(config) {
+    const configured = config.workflow?.maxConcurrency;
+    return workflowMaxConcurrency(typeof configured === "number" && Number.isFinite(configured) ? configured : undefined);
+}

package/dist/workflows/ir/params.js

@@ -0,0 +1,54 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Run-parameter validation against the frozen plan's param schemas (reviewer
+ * #12). A program can declare `params.files: { type: array }`; supplying
+ * `--params '{"files":"not-an-array"}'` must be rejected at start rather than
+ * silently flowing into a unit prompt. The schemas are frozen into the plan
+ * ({@link WorkflowPlanGraph.paramSchemas}, program path only) so validation is
+ * a pure function of the frozen plan and the supplied params — no live-asset
+ * re-read.
+ *
+ * Uses the same bounded {@link validateJsonSchemaSubset} the engine applies to
+ * unit output: undeclared params are permitted (the schema map only constrains
+ * the params it names), and a workflow with no declared schemas (every Markdown
+ * workflow, and programs without a `params:` block) validates trivially.
+ *
+ * Pure module: no IO, no engine imports.
+ */
+import { UsageError } from "../../core/errors.js";
+import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+/**
+ * Validate a run's supplied params against the plan's frozen param schemas.
+ * Returns a flat list of human-readable, path-prefixed error strings (empty =
+ * valid). Params the plan does not declare a schema for are not constrained.
+ */
+export function validateWorkflowParams(plan, params) {
+    const schemas = plan.paramSchemas;
+    if (!schemas || Object.keys(schemas).length === 0)
+        return [];
+    // Validate the params object as a whole against a synthetic object schema
+    // whose `properties` are the declared param schemas. Missing declared params
+    // are NOT required (params may be optional / defaulted downstream); only a
+    // PRESENT param that violates its declared schema is an error.
+    // Re-root the validator's `$` JSON-pointer prefix to `params` for messages
+    // that read naturally in a start/CLI error (e.g. `params.files: expected …`).
+    return validateJsonSchemaSubset(params, { type: "object", properties: schemas }).map((e) => e.replace(/^\$/, "params"));
+}
+/**
+ * Brief/report integrity assert (reviewer #12): the journaled `params_json`
+ * row must STILL satisfy the frozen param schemas. `startWorkflowRun` already
+ * validated the params it stored, so a violation here means the row was edited
+ * after the run started — loud corruption, exactly like the frozen-plan hash
+ * mismatch and the tampered-params replay-divergence path. Refuse to describe
+ * or drive the run rather than resolve prompts from schema-violating params.
+ */
+export function assertRunParamsSatisfyPlan(runId, plan, params) {
+    const errors = validateWorkflowParams(plan, params);
+    if (errors.length === 0)
+        return;
+    throw new UsageError(`Workflow run ${runId} failed the frozen param-schema integrity check: the journaled params row no longer ` +
+        `satisfies the workflow's declared parameter schemas (edited after the run started). Refusing to execute it. ` +
+        `Start a new run.\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+}