akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/workflows/ir/compile.js

@@ -0,0 +1,388 @@
+// 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 → Workflow Plan Graph (IR v2) compilers.
+ *
+ * Two frontends, one IR (redesign addendum, R1):
+ *
+ *   - {@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
+ *     program's `defaults` block into every unit node so the frozen plan is
+ *     self-contained. Returns accumulated `WorkflowError`s rather than
+ *     throwing.
+ *   - {@link compileWorkflowPlan} — classic LINEAR markdown workflows
+ *     (`parser.ts`), the stable CLI contract: one `agent` node per step with
+ *     `runner: inherit` and the fail-fast default, exactly as today. 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";
+import { WORKFLOW_IR_VERSION, } from "./schema.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: {
+            irVersion: WORKFLOW_IR_VERSION,
+            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 program unit into an agent node, merging the run-level `defaults`
+ * block (frozen resolution — addendum: "the plan is self-contained"). Per-unit
+ * declarations always win; the fail-fast `on_error` default applies last.
+ */
+function compileProgramUnit(unit, id, defaults) {
+    const model = unit.model ?? defaults?.model;
+    const timeoutMs = unit.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
+    return {
+        kind: "agent",
+        id,
+        instructions: unit.instructions,
+        // YAML program instructions are `${{ … }}` templates (validated above);
+        // the executor resolves them per unit.
+        templating: "expressions",
+        runner: unit.runner ?? defaults?.runner ?? "inherit",
+        ...(unit.profile !== undefined ? { profile: unit.profile } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(unit.output !== undefined ? { schema: unit.output } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        // 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 IR v2. Pure and deterministic: the
+ * same document always compiles to the same plan. Linear workflows — the
+ * stable contract — produce one `agent` node per step (`runner: inherit`,
+ * fail-fast) guarded by its gate, identical behavior to today's step loop.
+ */
+export function compileWorkflowPlan(document) {
+    const params = document.parameters?.map((p) => p.name);
+    return {
+        irVersion: WORKFLOW_IR_VERSION,
+        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: "agent",
+            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",
+            runner: "inherit",
+            // Markdown has no failure-policy surface; the fail-fast default applies.
+            onError: "fail",
+            source: step.instructions.source,
+        },
+        gate,
+    };
+}

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")}`);
+}

package/dist/workflows/ir/plan-hash.js

@@ -0,0 +1,33 @@
+// 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/.
+/**
+ * Plan hashing for the frozen-plan contract (redesign addendum, R1).
+ *
+ * `workflow start` persists `plan_json` + `plan_hash` on the run row
+ * (migration 006); every later invocation executes that snapshot. The hash is
+ * the sha256 (hex) of the plan's CANONICAL JSON — object keys recursively
+ * sorted — so two structurally-equal plans hash identically regardless of key
+ * insertion order, and the same program always freezes to the same hash.
+ *
+ * Pure module: no IO beyond node:crypto, no engine imports.
+ */
+import { createHash } from "node:crypto";
+/** sha256 hex of the canonical (recursively sorted-keys) JSON of the plan. */
+export function computePlanHash(plan) {
+    return createHash("sha256").update(canonicalPlanJson(plan)).digest("hex");
+}
+/** The canonical JSON string the hash is computed over (also what to persist). */
+export function canonicalPlanJson(plan) {
+    return JSON.stringify(sortKeys(plan));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, sortKeys(v)]));
+    }
+    return value;
+}

package/dist/workflows/ir/schema.js

@@ -0,0 +1,4 @@
+// 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/.
+export const WORKFLOW_IR_VERSION = 2;

package/dist/workflows/parser.js

@@ -233,7 +233,9 @@ function collectStepBody(subsections, lines, path, stepTitle, errors) {
         }
         errors.push({
             line: sub.headingLine,
-            message: `Step "${stepTitle}" has an unknown "### ${sub.name}" section. Only "### Instructions" and "### Completion Criteria" are supported.`,
+            message: `Step "${stepTitle}" has an unknown "### ${sub.name}" section. Supported sections: ` +
+                `"### Instructions", "### Completion Criteria". For orchestrated workflows (runners, ` +
+                `fan-out, routing), author a YAML workflow program instead — see \`akm workflow template --yaml\`.`,
         });
     }
     return {