akm-cli 0.9.16 → 0.9.17-alpha.10

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")