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

package/dist/workflows/runtime/plan-classifier.js

@@ -1,196 +0,0 @@
-// 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 { UsageError } from "../../core/errors.js";
-import { warnOnce } from "../../core/warn.js";
-import { decodeCanonicalPlan } from "../ir/plan-hash.js";
-import { WORKFLOW_IR_V5_VERSION } from "../ir/schema-v4.js";
-/** Validate that a live run carries exactly the current frozen-plan format. */
-export function classifyWorkflowRunPlan(row) {
-    const runId = row.id ?? "(unknown)";
-    if (!row.plan_json) {
-        return {
-            support: "missing-plan",
-            irVersion: row.plan_ir_version ?? null,
-            error: `Workflow run ${runId} has no frozen workflow plan.`,
-        };
-    }
-    if (row.plan_ir_version !== null &&
-        row.plan_ir_version !== undefined &&
-        row.plan_ir_version !== WORKFLOW_IR_V5_VERSION) {
-        return {
-            support: "unsupported-version",
-            irVersion: row.plan_ir_version,
-            // §3.2's exact complete-or-abandon policy string (A-N2): pre-irVersion-5
-            // plans keep status/list/abandon working but can no longer execute. A
-            // version ABOVE the current one (#919) is a distinct situation — never
-            // an "upgrade" problem — so it gets its own text below rather than
-            // being folded into the pre-5 wording.
-            error: row.plan_ir_version < WORKFLOW_IR_V5_VERSION
-                ? // Issue 8: leads with the remedy available to a user who has
-                    `Workflow run ${runId} was frozen as workflow plan irVersion ${row.plan_ir_version}; pre-irVersion-5 ` +
-                        `plans cannot execute after the 0.9.2 upgrade. Run 'akm workflow abandon ${runId}' and start a new ` +
-                        `run from the authored workflow to continue. 'akm workflow status' and 'akm workflow list' still ` +
-                        `work on this run.`
-                : `Workflow run ${runId} was frozen with workflow plan irVersion ${row.plan_ir_version}, which this akm ` +
-                    `(irVersion ${WORKFLOW_IR_V5_VERSION}) does not understand; it was probably written by a newer akm. ` +
-                    `Complete it with that akm version, or run 'akm workflow abandon ${runId}' and start a new run from ` +
-                    `the authored workflow. 'akm workflow status' and 'akm workflow list' still work on this run.`,
-        };
-    }
-    try {
-        return {
-            support: "supported",
-            irVersion: WORKFLOW_IR_V5_VERSION,
-            plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash, row.plan_ir_version),
-        };
-    }
-    catch (cause) {
-        return {
-            support: "corrupt-plan",
-            irVersion: row.plan_ir_version ?? null,
-            error: cause instanceof Error ? cause.message : String(cause),
-        };
-    }
-}
-/**
- * Reject any operation that requires a valid current frozen plan. A
- * non-current stored `plan_ir_version` (`unsupported-version`) fails closed
- * under `WORKFLOW_IR_VERSION_UNSUPPORTED` (A-N2) — distinct from the
- * `missing-plan` / `corrupt-plan` decode-corruption family, which keeps
- * `INVALID_JSON_ARGUMENT`.
- */
-export function requireExecutableWorkflowPlan(row) {
-    const classified = classifyWorkflowRunPlan(row);
-    if (classified.support === "supported")
-        return classified.plan;
-    if (classified.support === "unsupported-version") {
-        throw new UsageError(classified.error, "WORKFLOW_IR_VERSION_UNSUPPORTED");
-    }
-    throw new UsageError(classified.error, "INVALID_JSON_ARGUMENT");
-}
-/** Project persisted spine rows from the decoded plan, never from the mutable source asset. */
-export function frozenStepRows(plan) {
-    return plan.steps.map((step) => ({
-        stepId: step.stepId,
-        stepTitle: step.title,
-        instructions: step.root
-            ? step.root.kind === "map"
-                ? step.root.template.instructions
-                : step.root.instructions
-            : routeInstructions(step.route),
-        completionJson: step.gate.criteria.length > 0 ? JSON.stringify(step.gate.criteria) : null,
-        sequenceIndex: step.sequenceIndex,
-    }));
-}
-/**
- * Verify the durable spine's STEP IDENTITY still agrees with the
- * decoded/hash-verified plan: the same number of steps, and the same set of
- * step ids. A published plan's own step ids are fixed forever at freeze
- * time, so a mismatch here means the row set itself is wrong — genuine
- * corruption, not something a later akm release could have caused by
- * changing how a field is FORMATTED (that is
- * {@link reconcileWorkflowSpineWithPlan}'s concern, issue 7).
- */
-function assertSpineIdentityMatchesPlan(runId, expected, rows) {
-    if (rows.length !== expected.length)
-        corruptSpine(runId, "step count differs from the frozen plan");
-    const expectedIds = new Set(expected.map((step) => step.stepId));
-    for (const row of rows) {
-        if (!expectedIds.has(row.step_id))
-            corruptSpine(runId, `step "${row.step_id}" is not in the frozen plan`);
-    }
-}
-/**
- * Reconcile the durable spine's PURE-DERIVATION fields (title, instructions,
- * completion criteria, sequence position) against the plan (issue 7).
- *
- * These are recomputed from the plan by {@link frozenStepRows} on every
- * read; a later akm release changing how one of them is FORMATTED from the
- * SAME plan data used to mark every in-flight run from the previous release
- * "corrupt" the moment anything (`akm workflow status`, `resume`, a step
- * completion) touched it. A mismatch here is warned about, once per run,
- * rather than blocking the caller — never step identity (row count, which
- * step ids exist), which stays a hard failure in
- * {@link assertSpineIdentityMatchesPlan} because the plan cannot have
- * produced a different step id for an already-frozen run.
- *
- * The durable row — not the plan — is what a driving agent actually acts
- * on: `getNextWorkflowStep` reads `instructions` straight off this row
- * (`toWorkflowRunStepState`/`projectNextResult` in `runtime/runs.ts`), and
- * `exec/run-workflow.ts`/`exec/step-work.ts` dispatch from that result. So
- * warning and proceeding with the STORED row (rather than rewriting it to
- * match the plan's current formatting) is the conservative choice: the
- * durable spine is the contract this run has been executing against since
- * freeze, and a newer akm formatting the same plan data differently should
- * not retroactively change an in-flight run's instructions out from under
- * it mid-execution. This module has no write path for that anyway
- * (`workflow_run_steps` is owned by
- * `storage/repositories/workflow-runs-repository.ts`) — and it should not
- * gain one for this purpose. Step
- * identity (row count, which step ids exist) is the part that would
- * actually desynchronize execution from the plan, which is exactly why
- * {@link assertSpineIdentityMatchesPlan} keeps that a hard failure.
- */
-export function reconcileWorkflowSpineWithPlan(plan, run, rows) {
-    const expected = frozenStepRows(plan);
-    assertSpineIdentityMatchesPlan(run.id, expected, rows);
-    const expectedById = new Map(expected.map((step) => [step.stepId, step]));
-    const drifted = [];
-    for (const row of rows) {
-        const planned = expectedById.get(row.step_id);
-        if (!planned)
-            continue; // unreachable after assertSpineIdentityMatchesPlan; kept defensive.
-        if (row.step_title !== planned.stepTitle ||
-            row.instructions !== planned.instructions ||
-            row.completion_json !== planned.completionJson ||
-            row.sequence_index !== planned.sequenceIndex) {
-            drifted.push(row.step_id);
-        }
-    }
-    if (drifted.length > 0) {
-        warnOnce(`workflow-spine-drift:${run.id}`, `Workflow run ${run.id}: durable step row(s) [${drifted.join(", ")}] no longer match the frozen plan's ` +
-            "title/instructions/completion-criteria/sequence derivation (an akm upgrade likely changed how one of " +
-            "these is formatted from the same plan data). Continuing with the stored row(s) as-is — this run keeps " +
-            "executing against the instructions it was frozen with, rather than having them rewritten mid-flight.");
-    }
-}
-export function assertRunStatusMatchesSpine(run, rows) {
-    const current = run.current_step_id ? rows.find((row) => row.step_id === run.current_step_id) : undefined;
-    if (run.current_step_id !== null && !current)
-        corruptSpine(run.id, `current step ${run.current_step_id} is not in the frozen plan`);
-    if (run.status === "active") {
-        const firstPending = rows.find((row) => row.status === "pending");
-        if (!current || current.status !== "pending" || firstPending?.step_id !== current.step_id)
-            corruptSpine(run.id, "active status/current step does not match the first pending plan step");
-    }
-    else if (run.status === "blocked") {
-        if (!current || current.status !== "blocked")
-            corruptSpine(run.id, `${run.status} status does not match the current plan step`);
-    }
-    else if (run.status === "failed") {
-        // `workflow abandon` marks the run failed while intentionally leaving its
-        // current step unchanged so `resume` can reopen the same work. An active
-        // run leaves a pending step; a blocked run leaves a blocked step; and an
-        // execution failure already carries a failed step. All three are honest
-        // failed-run spines that `resumeWorkflowRun` normalizes back to pending.
-        if (!current || (current.status !== "failed" && current.status !== "pending" && current.status !== "blocked"))
-            corruptSpine(run.id, `${run.status} status does not match the current plan step`);
-    }
-    else if (run.status === "completed") {
-        if (run.current_step_id !== null ||
-            rows.some((row) => row.status === "pending" || row.status === "blocked" || row.status === "failed"))
-            corruptSpine(run.id, "completed status disagrees with the plan spine");
-    }
-}
-function routeInstructions(route) {
-    const branches = Object.entries(route.when)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([match, stepId]) => `"${match}" -> ${stepId}`);
-    if (route.defaultStepId !== undefined)
-        branches.push(`default -> ${route.defaultStepId}`);
-    return `Route on ${route.input}: ${branches.join(", ")}.`;
-}
-function corruptSpine(runId, detail) {
-    throw new UsageError(`Workflow run ${runId} has a corrupt durable step spine: ${detail}. Refusing to mutate state that disagrees with its frozen plan.`, "INVALID_JSON_ARGUMENT");
-}

package/dist/workflows/runtime/unit-checkin.js

@@ -1,45 +0,0 @@
-// 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 { GATE_EVALUATION_PHASE } from "./unit-phases.js";
-/**
- * Default staleness window. A unit claimed `running` whose last heartbeat (or,
- * absent any heartbeat, its first claim) is older than this is surfaced as
- * stale. Matches the run-level {@link ../runtime/checkin.CHECKIN_STALL_MS}.
- */
-export const UNIT_STALE_MS = 90_000;
-function parseIso(value) {
-    if (!value)
-        return null;
-    const ms = Date.parse(value);
-    return Number.isNaN(ms) ? null : ms;
-}
-/**
- * Pure stale-unit evaluator. Returns every `running` DISPATCH unit whose last
- * heartbeat (`last_checkin_at`, else the first-claim `started_at`) is older than
- * `staleMs`. Gate-evaluation rows (`phase = "gate"`) are excluded — they are
- * synchronous engine judge calls, never separately claimed work. A running row with
- * no usable timestamp at all is treated as stale (a claim we can no longer age).
- * Deterministic in `now` — free of timer flakiness.
- */
-export function evaluateStaleUnits(rows, now = Date.now(), staleMs = UNIT_STALE_MS) {
-    const stale = [];
-    for (const row of rows) {
-        if (row.status !== "running")
-            continue;
-        if (row.phase === GATE_EVALUATION_PHASE)
-            continue;
-        const lastSeenAt = row.last_checkin_at ?? row.started_at;
-        const lastSeen = parseIso(lastSeenAt);
-        const idleMs = lastSeen === null ? Number.POSITIVE_INFINITY : now - lastSeen;
-        if (idleMs < staleMs)
-            continue;
-        stale.push({
-            unitId: row.unit_id,
-            stepId: row.step_id,
-            idleMs,
-            lastSeenAt: lastSeenAt ?? null,
-        });
-    }
-    return stale;
-}

package/dist/workflows/runtime/unit-phases.js

@@ -1,20 +0,0 @@
-// 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/.
-/**
- * Unit-row phase markers — a leaf module (imports nothing) so both the exec
- * modules (step-work, run-workflow) and the runtime (unit-checkin) can key on
- * the phase discriminator without an exec ↔ runtime import cycle.
- * Extracting {@link GATE_EVALUATION_PHASE} here broke the last workflows-
- * runtime knot (step-work → runs → unit-checkin → step-work; chunk-8 WI-8.6,
- * DoD 11).
- */
-/**
- * `phase` marker stamped on gate-evaluation unit rows. Step ids cannot contain
- * dots (`PROGRAM_STEP_ID_PATTERN`), so a step can never be NAMED `x.gate` and
- * the synthetic `<stepId>.gate` node id is collision-free against user step
- * ids. The phase column is nonetheless the discriminator we key on — an
- * explicit marker, not a `node_id` suffix match, so recovery stays robust even
- * if the id scheme evolves. Dispatch rows always journal `phase: null`.
- */
-export const GATE_EVALUATION_PHASE = "gate";

package/dist/workflows/schema.js

@@ -1,4 +0,0 @@
-// 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_SCHEMA_VERSION = 2;

package/dist/workflows/source-ir/compile.js

@@ -1,200 +0,0 @@
-// 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 { parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
-import { parseWorkflow } from "../parser.js";
-import { projectExecCore } from "../program/schema.js";
-import { parseGithubWorkflowSource } from "./github-yaml.js";
-import { sourceFailureResult, WorkflowSourceFailure } from "./result.js";
-import { decodeWorkflowSourceIrV1, } from "./schema.js";
-import { canonicalizeWorkflowWorkingDirectory, WorkflowSourceSemanticError } from "./semantics.js";
-import { classifyWorkflowYamlTriggers } from "./triggers.js";
-import { classifyWorkflowSourceUses } from "./uses.js";
-export { looksLikeGithubWorkflowSource } from "./github-yaml.js";
-export function compileGithubWorkflowSource(source, options) {
-    try {
-        return {
-            ok: true,
-            ir: decodeWorkflowSourceIrV1(parseGithubWorkflowSource(source, {
-                ...options,
-                classifyUses: options.classifyUses ?? classifyWorkflowSourceUses,
-                classifyTriggers: options.classifyTriggers ?? classifyWorkflowYamlTriggers,
-            }), {
-                workspaceRoot: options.workspaceRoot,
-            }),
-        };
-    }
-    catch (cause) {
-        return sourceFailureResult(cause, options.path);
-    }
-}
-export function compileMarkdownWorkflowSource(source, options) {
-    const parsed = parseWorkflow(source, {
-        path: options.path,
-        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: cause instanceof Error ? cause.message : "working-directory cannot be physically verified.",
-                };
-            }
-        },
-    });
-    if (!parsed.ok) {
-        return {
-            ok: false,
-            errors: parsed.errors.map((error) => ({
-                code: error.code ?? "invalid-markdown-workflow",
-                message: error.message,
-                path: options.path,
-                line: error.line,
-            })),
-        };
-    }
-    try {
-        const sourceSpan = wholeSourceSpan(source, options.path);
-        const steps = parsed.document.steps.map((step) => markdownStep(step, options.path));
-        const ir = {
-            sourceIrVersion: 1,
-            name: markdownName(source, options.path),
-            ...(parsed.document.description ? { description: parsed.document.description } : {}),
-            ...(parsed.document.tags ? { tags: [...parsed.document.tags] } : {}),
-            ...(parsed.document.params ? { params: jsonClone(parsed.document.params) } : {}),
-            ...(parsed.document.outputs
-                ? { outputs: jsonClone(parsed.document.outputs) }
-                : {}),
-            ...(parsed.document.defaults
-                ? { defaults: jsonClone(parsed.document.defaults) }
-                : {}),
-            ...(parsed.document.budget ? { budget: jsonClone(parsed.document.budget) } : {}),
-            ...(parsed.document.preamble ? { preamble: parsed.document.preamble } : {}),
-            triggers: [{ kind: "workflow_dispatch", source: sourceSpan }],
-            jobs: [
-                {
-                    id: "contract",
-                    needs: [],
-                    steps,
-                    source: sourceSpan,
-                },
-            ],
-            extensions: {
-                "akm.dev/workflow-markdown": jsonExtension({
-                    workflowSchemaVersion: parsed.document.schemaVersion,
-                }),
-            },
-            source: sourceSpan,
-        };
-        return {
-            ok: true,
-            ir: decodeWorkflowSourceIrV1(ir, { workspaceRoot: options.workspaceRoot }),
-        };
-    }
-    catch (cause) {
-        return sourceFailureResult(cause, options.path);
-    }
-}
-/** Compile by authoritative source extension without rewriting either format. */
-export function compileWorkflowSource(source, options) {
-    const extension = path.extname(options.path).toLowerCase();
-    if (extension === ".md")
-        return compileMarkdownWorkflowSource(source, options);
-    if (extension === ".yml")
-        return compileGithubWorkflowSource(source, options);
-    return {
-        ok: false,
-        errors: [
-            {
-                code: "unsupported-workflow-extension",
-                message: `Workflow source ${options.path} must use .md or .yml.`,
-                path: options.path,
-                line: 1,
-            },
-        ],
-    };
-}
-function markdownStep(step, filePath) {
-    const source = step.source ?? { path: filePath, start: 1, end: 1 };
-    const dispatchUnit = step.map?.unit ?? step.unit;
-    const unit = markdownUnit(dispatchUnit);
-    const common = {
-        id: step.id,
-        ...(unit ? { unit } : {}),
-        ...(step.map
-            ? {
-                map: {
-                    over: step.map.over,
-                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
-                    ...(step.map.reducer !== undefined ? { reducer: step.map.reducer } : {}),
-                },
-            }
-            : {}),
-        ...(step.route ? { route: jsonClone(step.route) } : {}),
-        ...(step.inputs ? { inputs: [...step.inputs] } : {}),
-        ...(step.output ? { output: jsonClone(step.output) } : {}),
-        ...(step.gate || step.gateRubric
-            ? {
-                gate: {
-                    ...(step.gate?.maxLoops !== undefined ? { maxLoops: step.gate.maxLoops } : {}),
-                    ...(step.gateRubric?.text.trim() ? { rubric: step.gateRubric.text } : {}),
-                },
-            }
-            : {}),
-        source,
-    };
-    if (step.route) {
-        return {
-            ...common,
-            ...(step.instructions?.text.trim() ? { instructions: step.instructions.text } : {}),
-        };
-    }
-    if (dispatchUnit?.exec) {
-        return {
-            ...common,
-            exec: projectExecCore(dispatchUnit.exec),
-            ...(step.instructions?.text.trim() ? { instructions: step.instructions.text } : {}),
-        };
-    }
-    const content = step.instructions?.text ?? "";
-    if (content.trim() === "") {
-        throw new WorkflowSourceFailure("markdown-command-content-required", `Markdown step ${JSON.stringify(step.id)} has no executable command content.`, source);
-    }
-    return {
-        ...common,
-        uses: "akm/command",
-        commandMode: "literal",
-        with: { content },
-    };
-}
-function markdownUnit(value) {
-    if (!value)
-        return undefined;
-    const { exec: _exec, source: _source, ...unit } = value;
-    return Object.keys(unit).length > 0
-        ? jsonClone(unit)
-        : undefined;
-}
-function markdownName(source, filePath) {
-    const block = parseFrontmatterBlock(source);
-    const body = block?.content ?? source;
-    const title = body.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim();
-    if (title)
-        return title;
-    return path.basename(filePath, path.extname(filePath));
-}
-function wholeSourceSpan(source, filePath) {
-    return { path: filePath, start: 1, end: Math.max(1, source.split(/\r?\n/).length) };
-}
-function jsonClone(value) {
-    return JSON.parse(JSON.stringify(value));
-}
-function jsonExtension(value) {
-    return JSON.parse(JSON.stringify(value));
-}

package/dist/workflows/source-ir/program.js

@@ -1,50 +0,0 @@
-// 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 { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { PORTABLE_ARGUMENTS_PLACEHOLDER } from "../../commands/command/portable-template.js";
-/** Lower one adapter-neutral source-IR step into the shared execution unit. */
-export function sourceStepProgramUnit(source) {
-    const unit = {
-        ...(source.unit ? structuredClone(source.unit) : {}),
-        source: sourceStepRef(source),
-    };
-    if (source.exec)
-        unit.exec = { ...source.exec };
-    if (source.run !== undefined) {
-        unit.exec = {
-            command: workflowShellCommand(source.shell ?? "sh", source.run),
-            ...(source.workingDirectory ? { cwd: source.workingDirectory } : {}),
-        };
-    }
-    return unit;
-}
-/** Derive the instruction bytes consumed by the one workflow engine. */
-export function sourceStepInstructions(source) {
-    if (source.instructions !== undefined)
-        return source.instructions;
-    if (source.run !== undefined)
-        return `Run ${source.run}.`;
-    if (source.uses === "akm/command") {
-        const action = parseBuiltinCommandAction(source.with);
-        if (action.kind === "stored") {
-            return `Invoke stored command ${action.ref}${action.arguments === undefined ? "" : " with arguments"}.`;
-        }
-        if (source.commandMode === "literal")
-            return action.content;
-        return action.content.split(PORTABLE_ARGUMENTS_PLACEHOLDER).join(action.arguments ?? "");
-    }
-    if (source.uses !== undefined)
-        return `Invoke local target ${source.uses}.`;
-    return "";
-}
-export function workflowShellCommand(shell, content) {
-    if (shell === "cmd")
-        return ["cmd", "/d", "/s", "/c", content];
-    if (shell === "pwsh" || shell === "powershell")
-        return [shell, "-Command", content];
-    return [shell, "-c", content];
-}
-export function sourceStepRef(source) {
-    return { path: source.source.path, start: source.source.start, end: source.source.end };
-}

package/dist/workflows/source-ir/result.js

@@ -1,26 +0,0 @@
-// 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 class WorkflowSourceFailure extends Error {
-    error;
-    constructor(code, message, source) {
-        super(message);
-        this.name = "WorkflowSourceFailure";
-        this.error = { code, message, path: source.path, line: source.start };
-    }
-}
-export function sourceFailureResult(cause, path) {
-    if (cause instanceof WorkflowSourceFailure)
-        return { ok: false, errors: [cause.error] };
-    return {
-        ok: false,
-        errors: [
-            {
-                code: "invalid-workflow-source",
-                message: cause instanceof Error ? cause.message : String(cause),
-                path,
-                line: 1,
-            },
-        ],
-    };
-}