akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/tasks/source/parse-task-source.js

@@ -2,35 +2,185 @@
 // 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/.
 /**
- * Current task-source router.
+ * The task source version router.
  *
- * Runtime code accepts only the current v4 grammar. Historical v2/v3 files
- * and the former source-owned `schedule[].enabled` field are handled only by
- * the explicit `akm migrate` executable; execution never translates legacy
- * bytes in memory.
+ * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
+ * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
+ * routes through the in-memory read shim below — no second parse of the v4
+ * grammar itself, no re-serialization back to disk, no synthetic document
+ * (the shim adds a pure bytes-in/bytes-out detour, never a disk write).
+ *
+ * The terminal routing table:
+ *
+ *   | root `version`        | outcome                                                        |
+ *   |------------------------|-----------------------------------------------------------------|
+ *   | `4`, no retired `schedule[].enabled` | `parseTaskSourceV4Document` — the current grammar |
+ *   | `4`, some `schedule[]` entry carries `enabled` | in-memory read shim (below): the SAME `planTaskToV4File` call `akm migrate apply` uses for this exact case (`./task-to-v4.ts`'s `version === 4` branch, which strips every `schedule[].enabled` and reports `source-enablement-removed`) runs on the bytes already in hand; the result is parsed and returned with a one-line stderr deprecation warning (once per file per process). The value is never read either way — `enabled: false` cannot suppress a granted task and `enabled: true` cannot schedule an ungranted one, since activation is host-local `scheduler.enabled`. Version 4 is supported, so if the planner cannot produce a valid document it is an ordinary grammar defect: falls back to `TASK_SOURCE_INVALID` with the v4 parser's own error, not the unmigratable-version decision |
+ *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning (once per file per process). If the deterministic conversion itself fails (an unmigratable shape — the file needs a human decision, not a re-run), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED` naming the specific blocked reason — the shim removes friction for the deterministic case, it never hides a real problem |
+ *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator          |
+ *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording |
+ *
+ * A missing or non-numeric `version:` is a MALFORMED v4 document, not a
+ * legacy one — it routes into the v4 parser so the field error names the
+ * one grammar `src` still accepts, rather than a generic "unsupported"
+ * message that would send the user to the migrator for a document that was
+ * never task v2 or v3 in the first place.
+ *
+ * task v2 and task v3 sources are no longer read as their own standing
+ * grammar anywhere else in `src` — the only readers of that grammar are the
+ * pure, byte-producing planners (`./task-to-v3.ts`, `./task-to-v4.ts`, and
+ * the frozen v3 reader `./task-source-v3-frozen.ts`), reached either through
+ * this shim (bytes in, bytes out, never touches disk) or through
+ * `akm migrate apply` / `akm-migrate` (`scripts/akm-migrate`, which
+ * additionally rewrites the file on disk once the user asks for that).
+ * Policy: a deterministic byte transform is the tool's job, not the user's —
+ * upgrading past a schema bump must not silently break a scheduled task, so
+ * v2/v3 files keep reading successfully at the cost of a one-line
+ * deprecation warning, and `akm migrate apply` remains available to rewrite
+ * the file and silence it. Activation itself is host-local (scheduler
+ * config, `src/core/activation-policy.ts`) and this shim never touches it:
+ * the v3->v4 planner never hoists the retired `akm.enabled` field to v4's
+ * top level and never carries a schedule entry's `enabled` key, so the
+ * document this shim hands back carries no enablement at all — the same
+ * shape a native v4 document has. A declared `version: 4` document that
+ * still carries a `schedule[].enabled` key (0.9.15's v4 grammar accepted
+ * it; this release's does not) gets the identical treatment: routed
+ * through `planTaskToV4File`'s own `version === 4` branch, which strips
+ * every `schedule[].enabled` key without reading its value and reports
+ * `source-enablement-removed`, then re-parsed and returned with the same
+ * one-line deprecation warning. The front end's own pre-version failures
+ * (source not a string, source too large, YAML parse/warning/expansion)
+ * render with the label `task source`.
  */
 import { UsageError } from "../../core/errors.js";
+import { warnOnce } from "../../core/warn.js";
 import { readBoundedTaskSourceYaml } from "./bounded-document.js";
-import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
+import { parseTaskSourceV4, parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION, } from "./task-source-v4.js";
+import { planTaskToV3File } from "./task-to-v3.js";
+import { planTaskToV4File } from "./task-to-v4.js";
+/** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
 export function peekTaskSourceVersion(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
         return undefined;
     const value = root.version;
     return typeof value === "number" ? value : undefined;
 }
+const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+/**
+ * Thrown only when the deterministic conversion itself could not produce a
+ * task source v4 document — a case where a person must decide the intended
+ * behavior (e.g. an ambiguous shell command), not one the migrator can just
+ * be re-run to fix. `reason`/`detail` are the SAME blocked outcome
+ * `akm migrate status`/`apply` reports for this file, so the message names
+ * the actual decision instead of pointing at a command that will report the
+ * identical block.
+ */
+function unmigratableVersionError(filePath, version, reason, detail) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run — the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
+}
 function unsupportedVersionError(filePath, version) {
-    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Run `akm migrate apply --dry-run`, review the plan, then run `akm migrate apply`.");
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
+/**
+ * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
+ * chained v2->v3->v4) migration planner(s) — never touches disk, never
+ * writes the file, never re-reads it from disk. `version === 4` runs the
+ * identical bytes straight through `planTaskToV4File`'s own `version === 4`
+ * branch instead (the retired `schedule[].enabled` case, `./task-to-v4.ts`),
+ * so there is exactly one helper for every version this shim reads, not a
+ * second one for the v4-only case. Returns the produced v4 YAML text, or the
+ * blocked reason/detail when the deterministic conversion cannot proceed
+ * (an unmigratable v2/v3 shape, or a v4 document `planTaskToV4File` cannot
+ * revalidate once `schedule[].enabled` is stripped) — the caller falls back
+ * to the same hard error this gate threw before the shim existed, now
+ * naming that reason.
+ */
+function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
+    const bytes = Buffer.from(yaml, "utf8");
+    // `writable`/`onDiskWritable` gate the DISK apply path's "don't touch a
+    // read-only file" check inside the planners; this shim never writes
+    // anything to disk, so that check does not apply here and must not block
+    // an otherwise-legal read of a task file that happens to be read-only.
+    const baseInput = {
+        filePath,
+        bytes,
+        mode: 0o644,
+        writable: true,
+        onDiskWritable: true,
+        ...(workspaceRoot ? { containmentRoot: workspaceRoot } : {}),
+    };
+    let v3Bytes;
+    if (version === 3 || version === 4) {
+        v3Bytes = bytes;
+    }
+    else {
+        const v3Outcome = planTaskToV3File(baseInput);
+        if (v3Outcome.status !== "changed")
+            return { reason: v3Outcome.reason, detail: v3Outcome.detail };
+        v3Bytes = v3Outcome.after;
+    }
+    const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
+    if (v4Outcome.status !== "changed")
+        return { reason: v4Outcome.reason, detail: v4Outcome.detail };
+    return v4Outcome.after.toString("utf8");
+}
+/**
+ * True when `root`'s `schedule:` is a sequence with at least one mapping
+ * entry that carries an `enabled` key, regardless of that key's value or
+ * type — the shape 0.9.15's v4 grammar accepted and this release's does
+ * not (`schedule[].enabled`). The value is never inspected: activation is
+ * host-local `scheduler.enabled`, so this is purely a presence check that
+ * decides whether to route through the in-memory shim.
+ */
+export function v4ScheduleHasRetiredEnabledKey(root) {
+    if (root === null || typeof root !== "object" || Array.isArray(root))
+        return false;
+    const schedule = root.schedule;
+    if (!Array.isArray(schedule))
+        return false;
+    return schedule.some((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry) && Object.hasOwn(entry, "enabled"));
+}
+/** Parse task source YAML, routing per the terminal table above. */
 export function parseTaskSource(input) {
     const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
+        if (version === 2 || version === 3) {
+            const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+            if (typeof shimmed === "string") {
+                const v4 = parseTaskSourceV4({
+                    yaml: shimmed,
+                    filePath: input.filePath,
+                    ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
+                });
+                warnOnce(`task-source:v${version}-shim:${input.filePath}`, `akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
+                return Object.freeze({ version: 4, v4 });
+            }
+            throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
+        }
         throw unsupportedVersionError(input.filePath, version);
     }
-    const v4 = parseTaskSourceV4Document(root, {
+    if (version === TASK_SOURCE_V4_VERSION && v4ScheduleHasRetiredEnabledKey(root)) {
+        const shimmed = planInMemoryV4Bytes(4, input.yaml, input.filePath, input.workspaceRoot);
+        if (typeof shimmed === "string") {
+            const v4 = parseTaskSourceV4({
+                yaml: shimmed,
+                filePath: input.filePath,
+                ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
+            });
+            warnOnce(`task-source:v4-schedule-enabled-shim:${input.filePath}`, `akm: task ${input.filePath} uses the retired schedule[].enabled field — auto-read with it ignored; run \`akm migrate apply\` to rewrite it and silence this`);
+            return Object.freeze({ version: 4, v4 });
+        }
+        // Version 4 is supported; a blocked outcome here means the file itself
+        // is malformed (`generated-v4-validation-failed`), not that this
+        // version needs a human decision — throw the v4 grammar error, not
+        // `unmigratableVersionError`.
+        throw new UsageError(shimmed.detail ?? shimmed.reason, "TASK_SOURCE_INVALID");
+    }
+    const documentOptions = {
         filePath: input.filePath,
         ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
         lineAt,
-    });
-    return Object.freeze({ version: 4, v4 });
+    };
+    return Object.freeze({ version: 4, v4: parseTaskSourceV4Document(root, documentOptions) });
 }

package/dist/tasks/source/task-source-v3-frozen.js

@@ -312,10 +312,9 @@ function parseTaskV3TriggerFields(input, ctx) {
  * the original file this was moved body-intact from, and because
  * `parseTaskV3Document` shares its trigger-parsing helpers
  * (`parseTaskV3TriggerFields`/`compileTriggers`/`parseOn`/`parseAkm`) with
- * it. The LIVE, `src`-side classifier this was re-homed from is
- * `classifyWorkflowYamlTriggers` (`src/workflows/source-ir/triggers.ts`,
- * P4-N3) — that one, not this frozen copy, is what
- * `src/workflows/source-ir/compile.ts` injects.
+ * it. The LIVE, `src`-side `on:` parser is `parseTriggers`
+ * (`src/workflows/github-yaml.ts`, P4-N3) — that one, not this frozen copy,
+ * is what workflow compilation uses.
  */
 export function classifyTaskV3Triggers(value, options) {
     const ctx = ctxFrom(options);

package/dist/tasks/source/task-to-v4.js

@@ -318,8 +318,8 @@ function planV3DataToV4(input, data) {
             // `uses: workflows/` it was equally inert there — nothing ever consumed
             // it. Hoisting it unconditionally would therefore emit bytes the real
             // parseTaskSourceV4 below rejects, blocking a valid, previously-runnable
-            // v3 file — and one blocked file aborts the whole plan
-            // (`applyTaskToV4MigrationPlan`, ./task-files-to-v4.ts). Dropping an
+            // v3 file from both the in-memory read shim and `akm migrate apply`
+            // (scripts/akm-migrate/migrate/task-files.ts). Dropping an
             // already-inert field and SAYING SO is the faithful translation, and
             // keeps spec row B-66 / §5.3's `changed` guarantee intact.
             if (usesTarget !== undefined && (usesTarget.kind === "command" || usesTarget.kind === "builtin-command")) {

package/dist/workflows/authoring/authoring.js

@@ -13,8 +13,7 @@ import { defaultBundleForTarget } from "../../core/mutation-target.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { warn } from "../../core/warn.js";
 import { prepareWriteTargetForMutation, resolveWriteTarget, withWriteTargetMutation } from "../../core/write-source.js";
-import { compileWorkflowPlan } from "../ir/compile.js";
-import { compileWorkflowSource } from "../source-ir/compile.js";
+import { checkWorkflowPlan, compileWorkflowSource } from "../compile.js";
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate("New Workflow");
 export function getWorkflowTemplate() {
     return DEFAULT_WORKFLOW_TEMPLATE;
@@ -37,7 +36,7 @@ function validateWorkflowContent(content, sourcePath) {
     if (!result.ok) {
         throw new UsageError(formatWorkflowErrors(sourcePath, result.errors));
     }
-    const compiled = compileWorkflowPlan(result.ir, slugifyWorkflowStepId(sourcePath));
+    const compiled = checkWorkflowPlan(result.plan);
     if (!compiled.ok) {
         throw new UsageError(formatWorkflowErrors(sourcePath, compiled.errors));
     }
@@ -98,7 +97,7 @@ export function createWorkflowAsset(input) {
     const mode = fs.existsSync(assetPath) ? fs.lstatSync(assetPath).mode & 0o777 : 0o644;
     const defaultBundle = defaultBundleForTarget(config);
     const ref = makeBundleRef(target.source.name === defaultBundle ? undefined : target.source.name, conceptId);
-    withWriteTargetMutation(target, [assetPath], { ignored: "reject", purpose: "workflow-authoring", message: `Create ${ref}` }, () => {
+    withWriteTargetMutation(target, [assetPath], { purpose: "workflow-authoring", message: `Create ${ref}` }, () => {
         fs.mkdirSync(path.dirname(assetPath), { recursive: true });
         writeFileAtomic(assetPath, authoredContent.endsWith("\n") ? authoredContent : `${authoredContent}\n`, mode);
     });
@@ -154,14 +153,6 @@ function humanizeWorkflowName(name) {
         .replace(/\b\w/g, (match) => match.toUpperCase())
         .trim() || "New Workflow");
 }
-function slugifyWorkflowStepId(name) {
-    return (name
-        .split("/")
-        .pop()
-        ?.toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "") || "workflow");
-}
 export function formatWorkflowErrors(path, errors) {
     const lines = errors.map((e) => `  ${path}:${e.line} — ${e.message}`);
     const heading = errors.length === 1 ? "Workflow has 1 error:" : `Workflow has ${errors.length} errors:`;

package/dist/workflows/compile.js

@@ -0,0 +1,211 @@
+// 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/.
+/**
+ * The workflow compiler's front door. `.md` goes through the Markdown grammar
+ * (`parser.ts`), `.yml` through the GitHub-shaped YAML grammar
+ * (`github-yaml.ts`); both produce a {@link WorkflowPlan} directly.
+ *
+ * {@link checkWorkflowPlan} is the one cross-step pass the grammars do not
+ * run: every `steps.<id>` reference must name an earlier step (outputs may
+ * name any step), `inputs:` never name a param, and two non-fatal advisories.
+ */
+import path from "node:path";
+import { parseBuiltinCommandAction } from "../commands/command/builtin-action.js";
+import { PORTABLE_ARGUMENTS_PLACEHOLDER } from "../commands/command/portable-template.js";
+import { parseGithubWorkflowSource, WorkflowSourceFailure } from "./github-yaml.js";
+import { parseWorkflow } from "./parser.js";
+import { formatReference, parseReference } from "./program/expressions.js";
+import { canonicalizeWorkflowWorkingDirectory, WorkflowSourceSemanticError } from "./source-semantics.js";
+export { looksLikeGithubWorkflowSource } from "./github-yaml.js";
+/** Compile by authoritative source extension. */
+export function compileWorkflowSource(source, options) {
+    const extension = path.extname(options.path).toLowerCase();
+    const title = options.title ?? path.basename(options.path, path.extname(options.path));
+    if (extension === ".yml") {
+        try {
+            return { ok: true, plan: parseGithubWorkflowSource(source, { ...options, title }) };
+        }
+        catch (cause) {
+            if (cause instanceof WorkflowSourceFailure)
+                return { ok: false, errors: [cause.error] };
+            const message = cause instanceof Error ? cause.message : String(cause);
+            return { ok: false, errors: [{ code: "invalid-workflow-source", message, path: options.path, line: 1 }] };
+        }
+    }
+    if (extension !== ".md") {
+        return {
+            ok: false,
+            errors: [
+                {
+                    code: "unsupported-workflow-extension",
+                    message: `Workflow source ${options.path} must use .md or .yml.`,
+                    path: options.path,
+                    line: 1,
+                },
+            ],
+        };
+    }
+    const parsed = parseWorkflow(source, {
+        path: options.path,
+        title,
+        validateExecCwd: (value) => {
+            try {
+                return { ok: true, value: canonicalizeWorkflowWorkingDirectory(value, options.workspaceRoot) };
+            }
+            catch (cause) {
+                if (cause instanceof WorkflowSourceSemanticError)
+                    return { ok: false, code: cause.code, message: cause.message };
+                return { ok: false, code: "working-directory-unverifiable", message: "cwd cannot be physically verified." };
+            }
+        },
+    });
+    if (parsed.ok)
+        return parsed;
+    return {
+        ok: false,
+        errors: parsed.errors.map((error) => ({
+            code: error.code ?? "invalid-markdown-workflow",
+            message: error.message,
+            path: options.path,
+            line: error.line,
+        })),
+    };
+}
+/**
+ * The display text a step contributes to `show`, search hints, and the run
+ * spine: its authored prose, else what its target does. Empty for a route
+ * step with no section.
+ */
+export function workflowStepInstructions(step) {
+    const spec = step.spec;
+    if (!spec)
+        return "";
+    if (spec.instructions !== undefined)
+        return spec.instructions;
+    if (spec.uses === "akm/command") {
+        const action = parseBuiltinCommandAction(spec.with);
+        if (action.kind === "stored") {
+            return `Invoke stored command ${action.ref}${action.arguments === undefined ? "" : " with arguments"}.`;
+        }
+        if (spec.commandMode === "literal")
+            return action.content;
+        return action.content.split(PORTABLE_ARGUMENTS_PLACEHOLDER).join(action.arguments ?? "");
+    }
+    if (spec.uses !== undefined)
+        return `Invoke local target ${spec.uses}.`;
+    return "";
+}
+/** A route step's deterministic one-line description of its branch table. */
+export function routeDescription(route) {
+    const branches = Object.entries(route.when).map(([match, stepId]) => `"${match}" -> ${stepId}`);
+    if (route.defaultStepId !== undefined)
+        branches.push(`default -> ${route.defaultStepId}`);
+    return `Route on ${route.input}: ${branches.join(", ")}.`;
+}
+/** Cross-step reference validation plus the non-fatal advisories. Pure. */
+export function checkWorkflowPlan(plan) {
+    const errors = [];
+    const allStepIds = new Set(plan.steps.map((step) => step.stepId));
+    const earlierStepIds = new Set();
+    const check = (text, line, label, paramsAllowed) => {
+        const parsed = parseReference(text);
+        if (!parsed.ok) {
+            errors.push({ line, message: `${label}: ${parsed.message}` });
+            return;
+        }
+        if (parsed.expr.kind === "param") {
+            if (paramsAllowed)
+                return;
+            errors.push({
+                line,
+                message: `${label}: "${formatReference(parsed.expr)}" names a param, not a step output — params are already ` +
+                    `attached to every unit, so declaring one as an input is redundant. "inputs:" only names step outputs ` +
+                    `(steps.<id>.output...).`,
+            });
+            return;
+        }
+        if (earlierStepIds.has(parsed.expr.stepId))
+            return;
+        const why = allStepIds.has(parsed.expr.stepId)
+            ? `step "${parsed.expr.stepId}" does not come before this step — references must name an earlier step (a producer that has already run)`
+            : `"${parsed.expr.stepId}" is not a step in this workflow`;
+        errors.push({ line, message: `${label}: "${formatReference(parsed.expr)}" cannot be resolved — ${why}.` });
+    };
+    for (const step of plan.steps) {
+        const line = step.spec?.source.start ?? 1;
+        if (step.spec?.map)
+            check(step.spec.map.over, line, `Step "${step.stepId}" map.over`, true);
+        if (step.route)
+            check(step.route.input, line, `Step "${step.stepId}" route.input`, true);
+        for (const [index, reference] of (step.spec?.inputs ?? []).entries()) {
+            check(reference, line, `Step "${step.stepId}" inputs[${index}]`, false);
+        }
+        earlierStepIds.add(step.stepId);
+    }
+    // Outputs resolve at run completion, so they may name any declared step.
+    for (const [name, declaration] of Object.entries(plan.outputs ?? {})) {
+        const parsed = parseReference(declaration.from);
+        const label = `Output "${name}" from`;
+        if (!parsed.ok)
+            errors.push({ line: 1, message: `${label}: ${parsed.message}` });
+        else if (parsed.expr.kind === "param") {
+            errors.push({
+                line: 1,
+                message: `${label}: "${formatReference(parsed.expr)}" names a param, not a step output — an output projects a ` +
+                    `STEP artifact, never a param. "outputs:" only names step outputs (steps.<id>.output...).`,
+            });
+        }
+        else if (!allStepIds.has(parsed.expr.stepId)) {
+            errors.push({
+                line: 1,
+                message: `${label}: "${formatReference(parsed.expr)}" cannot be resolved — "${parsed.expr.stepId}" is not a step in this workflow.`,
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, warnings: workflowWarnings(plan) };
+}
+/**
+ * Advisories that never fail compilation or change the plan:
+ *   A. a `params.<name>` reference (in `map.over`/`route.input`) to a param the
+ *      document's `params:` block does not declare — a likely typo;
+ *   B. `gate.max_loops` above 1 on an exec step, which is judged but never
+ *      looped (a frozen argv cannot read the judge's feedback).
+ */
+function workflowWarnings(plan) {
+    const warnings = [];
+    const declared = plan.paramSchemas ? new Set(Object.keys(plan.paramSchemas)) : undefined;
+    for (const step of plan.steps) {
+        const line = step.spec?.source.start ?? 1;
+        const maxLoops = step.gate.maxLoops;
+        if (maxLoops > 1 && step.spec?.exec && step.gate.criteria.length > 0) {
+            warnings.push({
+                line,
+                message: `Step "${step.stepId}" declares \`gate.max_loops: ${maxLoops}\` on an \`exec\` step — it runs its command ` +
+                    `ONCE. A gate loop re-executes the step so it can address the judge's feedback, and a frozen argv cannot ` +
+                    `read that feedback; looping would only repeat the command's side effects. The gate still evaluates and ` +
+                    `can still fail the step.`,
+            });
+        }
+        if (!declared)
+            continue;
+        const scan = (text, label) => {
+            if (!text)
+                return;
+            const parsed = parseReference(text);
+            if (!parsed.ok || parsed.expr.kind !== "param" || declared.has(parsed.expr.name))
+                return;
+            warnings.push({
+                line,
+                message: `${label}: "${formatReference(parsed.expr)}" references a param not declared in \`params:\` ` +
+                    `(declared: ${[...declared].join(", ") || "none"}) — likely a typo. An undeclared param supplied at start ` +
+                    `still resolves at run time.`,
+            });
+        };
+        scan(step.spec?.map?.over, `Step "${step.stepId}" map.over`);
+        scan(step.route?.input, `Step "${step.stepId}" route.input`);
+    }
+    return warnings;
+}

package/dist/workflows/concurrency-policy.js

@@ -4,13 +4,7 @@
 import os from "node:os";
 import { isLoopbackEndpoint } from "../core/loopback.js";
 import { WORKFLOW_MAX_CONCURRENCY } from "./resource-limits.js";
-/**
- * Run-level ceiling on `workflow.maxConcurrency`. It is deliberately the SAME
- * value the frozen-plan decoder enforces on `execution.maxConcurrency` and on
- * per-step `map.concurrency` — a clamp above the decoder's bound would freeze
- * plans the decoder then rejects — so it reads the single shared constant
- * (`./resource-limits`) rather than repeating the literal.
- */
+/** Run-level ceiling on `workflow.maxConcurrency` (the same bound as `map.concurrency`). */
 export const WORKFLOW_MAX_CONCURRENCY_CEILING = WORKFLOW_MAX_CONCURRENCY;
 export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
     return Math.min(16, Math.max(1, cpuCount - 2));
@@ -24,84 +18,29 @@ export function workflowMaxConcurrency(configured, cpuCount = os.cpus()?.length
 }
 // ── Fan-out defaults ─────────────────────────────────────────────────────────
 //
-// Four independent limits clamp a `map` step's real width, and the effective
-// value is their minimum:
-//
-//   1. the step's own `map.concurrency`            (this file's default below)
-//   2. the run's frozen `execution.maxConcurrency` ({@link workflowMaxConcurrency})
-//   3. the selected LLM engine's frozen concurrency ({@link defaultLlmEngineConcurrency})
-//   4. the CURRENT host's CPU safety cap           ({@link cpuDerivedUnitConcurrency})
-//
-// (1) and (3) both defaulted to 1 before 0.9.1, which made every fan-out serial
-// unless the author opted in at BOTH layers — so (2) and (4), the limits that
-// actually encode machine capacity, never bound anything. The defaults below
-// replace those two 1s. They are deliberately modest rather than "as wide as
-// the host allows": a `map` is independent by construction, but its units call
-// out to rate-limited providers and RAM-hungry agent processes, so the value
-// that a plan freezes should be one a laptop and a CI box can both survive.
+// A `map` step's real width is the minimum of its own `map.concurrency`, the
+// run's frozen `execution.maxConcurrency`, the LLM engine's frozen
+// concurrency, and the host CPU cap. The defaults are modest: map units call
+// rate-limited providers and RAM-hungry agents.
 /**
- * Default width of a `map` step that declares no `concurrency:` (0.9.1+).
- *
- * 4 is chosen over the host cap on purpose. It is a real, predictable speedup
- * (4× on any fan-out longer than four items) while staying below
- * {@link cpuDerivedUnitConcurrency} on every machine with ≥6 cores, so the
- * frozen number — not the host — is what an author reasons about, and a plan
- * frozen on a 32-core CI box behaves the same when it resumes on a laptop.
- *
- * Overridable in both directions:
- *   - per step: `map.concurrency: <n>` (an explicit `1` still means serial),
- *   - per install: `workflow.defaultMapConcurrency` — set it to `1` to restore
- *     the pre-0.9.1 serial default for every workflow at once.
+ * Default width of a `map` step with no `concurrency:` — a predictable number
+ * rather than the host cap, so a plan behaves the same wherever it resumes.
+ * Overridden per step (`map.concurrency`) or per install
+ * (`workflow.defaultMapConcurrency`; `1` restores serial fan-out).
  */
 export const DEFAULT_MAP_CONCURRENCY = 4;
-/**
- * Default `engines.<name>.concurrency` for an LLM engine on a LOOPBACK
- * endpoint. Stays at 1, matching `getDefaultLlmConcurrency`
- * (`src/indexer/indexer.ts`) and AGENTS.md's "lowest common denominator — a
- * slow local model on a single-threaded server" rule. A local model server
- * (LM Studio, Ollama) holds ONE loaded model; parallel inference triggers
- * reload thrash and HTTP 500s, which is a hard failure, not a slow one.
- */
+/** Default concurrency for an LLM engine on a loopback endpoint: a local model server runs one inference. */
 export const DEFAULT_LOCAL_LLM_ENGINE_CONCURRENCY = 1;
-/**
- * Default `engines.<name>.concurrency` for an LLM engine on a REMOTE endpoint.
- *
- * Deliberately equal to {@link DEFAULT_MAP_CONCURRENCY} so this limit does not
- * silently re-serialize a fan-out the author already asked for: the step's own
- * `concurrency:` stays the number that decides. Indexing's remote default is a
- * lower 2 because indexing fans out implicitly over the whole stash; a
- * workflow `map` is an explicit, bounded, author-declared fan-out, and four
- * concurrent completions sit far inside any hosted provider's entry tier.
- * Rate-limited installs set `engines.<name>.concurrency` to pin their own.
- */
+/** Default concurrency for a remote LLM engine: equal to {@link DEFAULT_MAP_CONCURRENCY}, so it never re-serializes a map. */
 export const DEFAULT_REMOTE_LLM_ENGINE_CONCURRENCY = 4;
-// ── Loopback classification ──────────────────────────────────────────────────
-//
-// Everything above turns on ONE question: does this endpoint name a model
-// server running on THIS machine? The classifier lives in `core/loopback.ts`
-// (shared with the indexer's LLM pool default); the re-export keeps this
-// module the policy surface workflow callers and the boundary-case table in
-// `tests/workflows/concurrency-defaults.test.ts` import from. The check is
-// purely syntactic — no DNS, no interface list — so freeze produces the same
-// plan on a laptop, on CI, and on a machine with no network.
 export { isLoopbackEndpoint, isLoopbackHost } from "../core/loopback.js";
-/**
- * Concurrency to freeze for an LLM engine. An explicit
- * `engines.<name>.concurrency` always wins (clamped into the decoder's
- * `[1, 64]` range so a fat-fingered config cannot freeze an unloadable plan);
- * otherwise the endpoint decides.
- */
+/** Concurrency to freeze for an LLM engine: an explicit `engines.<name>.concurrency` (clamped), else by endpoint. */
 export function defaultLlmEngineConcurrency(endpoint, configured) {
     if (typeof configured === "number" && Number.isFinite(configured))
         return clampMaxConcurrency(configured);
     return isLoopbackEndpoint(endpoint) ? DEFAULT_LOCAL_LLM_ENGINE_CONCURRENCY : DEFAULT_REMOTE_LLM_ENGINE_CONCURRENCY;
 }
-/**
- * Width to freeze for a `map` step that declared no `concurrency:`. `configured`
- * is `workflow.defaultMapConcurrency`; unset means {@link DEFAULT_MAP_CONCURRENCY}.
- * An explicit `map.concurrency` never reaches this function — the caller keeps
- * "author wrote 1" distinguishable from "author wrote nothing".
- */
+/** Width to freeze for a `map` step with no `concurrency:` (`configured` is `workflow.defaultMapConcurrency`). */
 export function defaultMapConcurrency(configured) {
     return configured === undefined || !Number.isFinite(configured)
         ? DEFAULT_MAP_CONCURRENCY

package/dist/workflows/exec/child-invocation.js

@@ -2,26 +2,12 @@
 // 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/.
 /**
- * A child workflow run's idempotency key (spec
- * docs/plans/specs/p3a-plan-v5-child-freeze.md §3.4, rows A-17…A-19). Pure:
- * no IO, no config, no clock, no randomness — imports exactly node:crypto
- * and canonicalJson.
- *
- * P3a has no production caller: P3b's child executor derives this key from
- * the parent unit's `hashVersion` 7 input hash and passes it to
- * `publishChildWorkflowRun` (src/storage/repositories/workflow-runs-repository.ts,
- * Lane C) as the `(parent_run_id, invocation_key)` idempotency pair.
+ * A child workflow run's idempotency key, derived from the parent unit's input
+ * hash: `publishChildWorkflowRun` is idempotent on `(parent_run_id, invocation_key)`.
  */
 import { createHash } from "node:crypto";
 import { canonicalJson } from "../ir/plan-hash.js";
-/**
- * `sha256hex("akm.workflow.child-invocation\0v1\0" + canonicalJson({parentRunId, parentUnitId, unitInputHash}))`.
- *
- * The `\0v1\0` here is this helper's OWN vocabulary version, deliberately
- * independent of `hashVersion`: `unitInputHash` enters this preimage as an
- * opaque value, so this key's preimage does not change when the unit-hash
- * vocabulary itself bumps.
- */
+/** `sha256hex("akm.workflow.child-invocation\0v1\0" + canonicalJson({parentRunId, parentUnitId, unitInputHash}))`. */
 export function computeChildInvocationKey(input) {
     return createHash("sha256")
         .update("akm.workflow.child-invocation\0v1\0")