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

package/dist/workflows/program/parser.js

@@ -24,15 +24,17 @@
  */
 import { createRequire } from "node:module";
 import { isMap, isScalar, LineCounter, parseDocument } from "yaml";
-import { PROGRAM_ISOLATION_KINDS, PROGRAM_ON_ERROR, PROGRAM_PARAM_NAME_PATTERN, PROGRAM_REDUCERS, PROGRAM_RETRY_REASONS, PROGRAM_RUNNER_KINDS, PROGRAM_STEP_ID_PATTERN, } from "./schema.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_STEPS, } from "../resource-limits.js";
+import { PROGRAM_ISOLATION_KINDS, PROGRAM_ON_ERROR, PROGRAM_PARAM_NAME_PATTERN, PROGRAM_REDUCERS, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN, WORKFLOW_PROGRAM_VERSION, } from "./schema.js";
 const TOP_LEVEL_KEYS = ["version", "name", "description", "params", "defaults", "budget", "steps"];
-const DEFAULTS_KEYS = ["runner", "model", "timeout", "on_error"];
+const DEFAULTS_KEYS = ["engine", "model", "timeout", "on_error", "llm"];
 const BUDGET_KEYS = ["max_tokens", "max_units"];
 const STEP_KEYS = ["id", "title", "unit", "map", "route", "output", "gate"];
 const UNIT_KEYS = [
-    "runner",
-    "profile",
+    "engine",
     "model",
+    "llm",
     "timeout",
     "retry",
     "on_error",
@@ -51,13 +53,19 @@ const TIMEOUT_HINT = `Use "<n>ms", "<n>s", "<n>m" (e.g. "10m"), or "none"`;
 /**
  * Cheap structural probe for the indexer matcher (mirrors `looksLikeWorkflow`
  * in ../parser.ts). Returns true if the text has the unmistakable top-level
- * shape of a YAML workflow program: `version: 1` and a `steps:` key, both at
+ * shape of a YAML workflow program: `version: 2` and a `steps:` key, both at
  * column 0. Used so the matcher and parser cannot drift.
  */
 export function looksLikeWorkflowProgram(yamlText) {
-    return /^version[ \t]*:[ \t]*['"]?1['"]?[ \t]*(#.*)?$/m.test(yamlText) && /^steps[ \t]*:/m.test(yamlText);
+    return /^version[ \t]*:[ \t]*['"]?(?:1|2)['"]?[ \t]*(#.*)?$/m.test(yamlText) && /^steps[ \t]*:/m.test(yamlText);
 }
 export function parseWorkflowProgram(yamlText, source) {
+    if (utf8Bytes(yamlText) > WORKFLOW_MAX_SOURCE_BYTES) {
+        return {
+            ok: false,
+            errors: [{ line: 1, message: "Workflow source exceeds the 1 MiB resource limit." }],
+        };
+    }
     const errors = [];
     const lineCounter = new LineCounter();
     let doc;
@@ -116,14 +124,19 @@ export function parseWorkflowProgram(yamlText, source) {
         return {
             ok: false,
             errors: [
-                { line: 1, message: `A workflow program must be a YAML mapping with "version: 1", "name", and "steps".` },
+                { line: 1, message: `A workflow program must be a YAML mapping with "version: 2", "name", and "steps".` },
             ],
         };
     }
     checkUnknownKeys(ctx, root, [], TOP_LEVEL_KEYS, "top-level");
-    if (root.version !== 1) {
-        const got = root.version === undefined ? "it is missing" : `got ${JSON.stringify(root.version)}`;
-        ctx.err(["version"], `"version: 1" is required at the top level (${got}). Only the number 1 is a valid version.`);
+    if (root.version !== WORKFLOW_PROGRAM_VERSION) {
+        if (root.version === 1) {
+            ctx.err(["version"], `Workflow version 1 retired; version 2 is required. Replace runner/profile selectors with engine.`);
+        }
+        else {
+            const got = root.version === undefined ? "it is missing" : `got ${JSON.stringify(root.version)}`;
+            ctx.err(["version"], `"version: 2" is required at the top level (${got}). Only the number 2 is a valid version.`);
+        }
     }
     let name = "";
     if (typeof root.name === "string" && root.name.trim() !== "") {
@@ -150,7 +163,7 @@ export function parseWorkflowProgram(yamlText, source) {
     if (errors.length > 0)
         return { ok: false, errors };
     const program = {
-        version: 1,
+        version: WORKFLOW_PROGRAM_VERSION,
         name,
         ...(description !== undefined ? { description } : {}),
         ...(params !== undefined ? { params } : {}),
@@ -171,6 +184,9 @@ function parseParams(ctx, raw) {
         ctx.err(["params"], `"params" must be a mapping of param name to a JSON Schema object (e.g. changed_files: { type: array }).`);
         return undefined;
     }
+    if (Object.keys(raw).length > WORKFLOW_MAX_PARAMS) {
+        ctx.err(["params"], `"params" must contain at most ${WORKFLOW_MAX_PARAMS} entries.`);
+    }
     const params = {};
     for (const [paramName, value] of Object.entries(raw)) {
         if (!PROGRAM_PARAM_NAME_PATTERN.test(paramName)) {
@@ -195,9 +211,12 @@ function parseDefaults(ctx, raw) {
     }
     checkUnknownKeys(ctx, raw, path, DEFAULTS_KEYS, `"defaults"`);
     const defaults = {};
-    const runner = parseEnumField(ctx, raw.runner, [...path, "runner"], `"defaults.runner"`, PROGRAM_RUNNER_KINDS);
-    if (runner !== undefined)
-        defaults.runner = runner;
+    if (raw.engine !== undefined) {
+        if (typeof raw.engine === "string" && raw.engine.trim() !== "")
+            defaults.engine = raw.engine.trim();
+        else
+            ctx.err([...path, "engine"], `"defaults.engine" must be a non-empty engine name.`);
+    }
     if (raw.model !== undefined) {
         if (typeof raw.model === "string" && raw.model.trim() !== "")
             defaults.model = raw.model.trim();
@@ -210,6 +229,9 @@ function parseDefaults(ctx, raw) {
     const onError = parseEnumField(ctx, raw.on_error, [...path, "on_error"], `"defaults.on_error"`, PROGRAM_ON_ERROR);
     if (onError !== undefined)
         defaults.onError = onError;
+    const llm = parseLlmOverrides(ctx, raw.llm, [...path, "llm"], `"defaults.llm"`);
+    if (llm !== undefined)
+        defaults.llm = llm;
     return Object.keys(defaults).length > 0 ? defaults : undefined;
 }
 function parseBudget(ctx, raw) {
@@ -231,11 +253,14 @@ function parseBudget(ctx, raw) {
         }
     }
     if (raw.max_units !== undefined) {
-        if (typeof raw.max_units === "number" && Number.isInteger(raw.max_units) && raw.max_units >= 1) {
+        if (typeof raw.max_units === "number" &&
+            Number.isInteger(raw.max_units) &&
+            raw.max_units >= 1 &&
+            raw.max_units <= WORKFLOW_MAX_MAP_EXPANSION) {
             budget.maxUnits = raw.max_units;
         }
         else {
-            ctx.err([...path, "max_units"], `"budget.max_units" must be an integer >= 1.`);
+            ctx.err([...path, "max_units"], `"budget.max_units" must be an integer from 1 through ${WORKFLOW_MAX_MAP_EXPANSION}.`);
         }
     }
     return Object.keys(budget).length > 0 ? budget : undefined;
@@ -245,6 +270,9 @@ function parseSteps(ctx, raw) {
         ctx.err(["steps"], `"steps" is required and must be a list with at least one step.`);
         return [];
     }
+    if (raw.length > WORKFLOW_MAX_STEPS) {
+        ctx.err(["steps"], `"steps" must contain at most ${WORKFLOW_MAX_STEPS} entries.`);
+    }
     // First pass: collect ids so route targets can be checked against ALL steps
     // (including ones that fail their own validation).
     const idIndex = new Map();
@@ -359,18 +387,18 @@ function parseUnit(ctx, raw, path, stepLabel) {
     if (typeof raw.instructions === "string" && raw.instructions.trim() !== "") {
         unit.instructions = raw.instructions;
         ctx.checkTemplates(raw.instructions, [...path, "instructions"], `${stepLabel} "instructions"`);
+        if (utf8Bytes(raw.instructions) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+            ctx.err([...path, "instructions"], `${stepLabel} "instructions" exceeds the 256 KiB resource limit.`);
+        }
     }
     else {
         ctx.err([...path, "instructions"], `${stepLabel} "unit" requires non-empty string "instructions".`);
     }
-    const runner = parseEnumField(ctx, raw.runner, [...path, "runner"], `${stepLabel} "runner"`, PROGRAM_RUNNER_KINDS);
-    if (runner !== undefined)
-        unit.runner = runner;
-    if (raw.profile !== undefined) {
-        if (typeof raw.profile === "string" && raw.profile.trim() !== "")
-            unit.profile = raw.profile.trim();
+    if (raw.engine !== undefined) {
+        if (typeof raw.engine === "string" && raw.engine.trim() !== "")
+            unit.engine = raw.engine.trim();
         else
-            ctx.err([...path, "profile"], `${stepLabel} "profile" must be a non-empty string.`);
+            ctx.err([...path, "engine"], `${stepLabel} "engine" must be a non-empty engine name.`);
     }
     if (raw.model !== undefined) {
         if (typeof raw.model === "string" && raw.model.trim() !== "")
@@ -378,6 +406,9 @@ function parseUnit(ctx, raw, path, stepLabel) {
         else
             ctx.err([...path, "model"], `${stepLabel} "model" must be a non-empty string (a model alias or exact id).`);
     }
+    const llm = parseLlmOverrides(ctx, raw.llm, [...path, "llm"], `${stepLabel} "llm"`);
+    if (llm !== undefined)
+        unit.llm = llm;
     const timeoutMs = parseTimeoutField(ctx, raw.timeout, [...path, "timeout"], `${stepLabel} "timeout"`);
     if (timeoutMs !== undefined)
         unit.timeoutMs = timeoutMs;
@@ -461,6 +492,9 @@ function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
         ctx.err(whenPath, `${stepLabel} "route" requires "when": a mapping of match value to target step id (e.g. when: { pass: ship }).`);
     }
     else if (isMap(whenNode)) {
+        if (whenNode.items.length > WORKFLOW_MAX_ROUTE_BRANCHES) {
+            ctx.err(whenPath, `${stepLabel} "when" must contain at most ${WORKFLOW_MAX_ROUTE_BRANCHES} branches.`);
+        }
         // Walk the AST pairs (not the JS object) so duplicate matches that only
         // collide after stringification ("true" vs true) are still caught.
         const seenMatches = new Map();
@@ -501,6 +535,9 @@ function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
                 ctx.err(whenPath, `${stepLabel} "when: ${match}" must map to a step id string.`);
             }
         }
+        if (Object.keys(raw.when).length > WORKFLOW_MAX_ROUTE_BRANCHES) {
+            ctx.err(whenPath, `${stepLabel} "when" must contain at most ${WORKFLOW_MAX_ROUTE_BRANCHES} branches.`);
+        }
         if (Object.keys(raw.when).length === 0) {
             ctx.err(whenPath, `${stepLabel} "when" must contain at least one match → step-id entry.`);
         }
@@ -634,6 +671,75 @@ function parseEnumField(ctx, raw, path, label, allowed) {
     ctx.err(path, `${label} must be one of: ${allowed.join(" | ")} (got ${JSON.stringify(raw)}).`);
     return undefined;
 }
+/** Parse only invocation tuning. Connection identity belongs to a named engine. */
+function parseLlmOverrides(ctx, raw, path, label) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainRecord(raw)) {
+        ctx.err(path, `${label} must be a mapping of LLM invocation overrides.`);
+        return undefined;
+    }
+    const keys = [
+        "temperature",
+        "max_tokens",
+        "supports_json_schema",
+        "extra_params",
+        "context_length",
+        "enable_thinking",
+    ];
+    checkUnknownKeys(ctx, raw, path, keys, label);
+    const result = {};
+    if (raw.temperature !== undefined) {
+        if (typeof raw.temperature === "number" && Number.isFinite(raw.temperature))
+            result.temperature = raw.temperature;
+        else
+            ctx.err([...path, "temperature"], `${label}.temperature must be a finite number.`);
+    }
+    if (raw.max_tokens !== undefined) {
+        if (typeof raw.max_tokens === "number" && Number.isInteger(raw.max_tokens) && raw.max_tokens > 0) {
+            result.maxTokens = raw.max_tokens;
+        }
+        else
+            ctx.err([...path, "max_tokens"], `${label}.max_tokens must be a positive integer.`);
+    }
+    if (raw.supports_json_schema !== undefined) {
+        if (typeof raw.supports_json_schema === "boolean")
+            result.supportsJsonSchema = raw.supports_json_schema;
+        else
+            ctx.err([...path, "supports_json_schema"], `${label}.supports_json_schema must be a boolean.`);
+    }
+    if (raw.extra_params !== undefined) {
+        if (!isPlainRecord(raw.extra_params)) {
+            ctx.err([...path, "extra_params"], `${label}.extra_params must be a JSON object.`);
+        }
+        else {
+            const issues = validateExtraParams(raw.extra_params);
+            for (const issue of issues) {
+                ctx.err([...path, "extra_params", ...issue.path], `${formatExtraParamsIssue(`${label}.extra_params`, issue)}.`);
+            }
+            if (jsonBytes(raw.extra_params) > WORKFLOW_MAX_EXTRA_PARAMS_BYTES) {
+                ctx.err([...path, "extra_params"], `${label}.extra_params exceeds the 64 KiB resource limit.`);
+            }
+            if (issues.length === 0 && jsonBytes(raw.extra_params) <= WORKFLOW_MAX_EXTRA_PARAMS_BYTES) {
+                result.extraParams = raw.extra_params;
+            }
+        }
+    }
+    if (raw.context_length !== undefined) {
+        if (typeof raw.context_length === "number" && Number.isInteger(raw.context_length) && raw.context_length > 0) {
+            result.contextLength = raw.context_length;
+        }
+        else
+            ctx.err([...path, "context_length"], `${label}.context_length must be a positive integer.`);
+    }
+    if (raw.enable_thinking !== undefined) {
+        if (typeof raw.enable_thinking === "boolean")
+            result.enableThinking = raw.enable_thinking;
+        else
+            ctx.err([...path, "enable_thinking"], `${label}.enable_thinking must be a boolean.`);
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function parseSchemaObject(ctx, raw, path, label) {
     if (raw === undefined)
         return undefined;
@@ -641,6 +747,9 @@ function parseSchemaObject(ctx, raw, path, label) {
         ctx.err(path, `${label} must be a JSON Schema object (e.g. { type: object, properties: { … } }).`);
         return undefined;
     }
+    if (jsonBytes(raw) > WORKFLOW_MAX_SCHEMA_BYTES) {
+        ctx.err(path, `${label} exceeds the 256 KiB resource limit.`);
+    }
     return raw;
 }
 function checkUnknownKeys(ctx, obj, path, allowed, label) {

package/dist/workflows/program/project.js

@@ -65,19 +65,18 @@ export function projectProgramParameters(program) {
 /**
  * Compact, show-facing orchestration summary for one program step, reusing
  * the existing `WorkflowStepOrchestrationSummary` shape. Field mapping:
- * `runner`/`model`/`timeoutMs` merge the run-level `defaults` exactly like
+ * `engine`/`model`/`timeoutMs` merge the run-level `defaults` exactly like
  * the compiler does (per-unit wins), `fanOut.over` carries the raw `${{ … }}`
  * expression, and `route` carries the explicit input + branch table.
  * Returns undefined when the step declares nothing worth summarizing.
  */
 export function summarizeProgramStepOrchestration(step, defaults) {
     const unit = step.unit ?? step.map?.unit;
-    const runner = unit?.runner ?? defaults?.runner;
+    const engine = unit?.engine ?? defaults?.engine;
     const model = unit?.model ?? defaults?.model;
     const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
     const summary = {
-        ...(runner !== undefined ? { runner } : {}),
-        ...(unit?.profile !== undefined ? { profile: unit.profile } : {}),
+        ...(engine !== undefined ? { engine } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(step.map

package/dist/workflows/program/schema.js

@@ -1,8 +1,8 @@
 // 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_PROGRAM_VERSION = 1;
-/** Execution backend for a unit. `inherit` defers to the run-level default. */
+export const WORKFLOW_PROGRAM_VERSION = 2;
+/** @deprecated source v2 rejects runner; retained for TypeScript migration only. */
 export const PROGRAM_RUNNER_KINDS = ["llm", "agent", "sdk", "inherit"];
 /** How a map step folds its per-item unit results into the step artifact. */
 export const PROGRAM_REDUCERS = ["collect", "vote"];

package/dist/workflows/resource-limits.js

@@ -0,0 +1,20 @@
+// 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_MAX_PLAN_BYTES = 2 * 1024 * 1024;
+export const WORKFLOW_MAX_SOURCE_BYTES = 1024 * 1024;
+export const WORKFLOW_MAX_STEPS = 256;
+export const WORKFLOW_MAX_ENGINES = 64;
+export const WORKFLOW_MAX_PARAMS = 128;
+export const WORKFLOW_MAX_ROUTE_BRANCHES = 256;
+export const WORKFLOW_MAX_INSTRUCTION_BYTES = 256 * 1024;
+export const WORKFLOW_MAX_SCHEMA_BYTES = 256 * 1024;
+export const WORKFLOW_MAX_EXTRA_PARAMS_BYTES = 64 * 1024;
+export const WORKFLOW_MAX_JSON_DEPTH = 64;
+export const WORKFLOW_MAX_MAP_EXPANSION = 10_000;
+export function utf8Bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+export function jsonBytes(value) {
+    return utf8Bytes(JSON.stringify(value));
+}

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

@@ -0,0 +1,187 @@
+// 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 { decodeCanonicalPlan } from "../ir/plan-hash.js";
+import { WORKFLOW_IR_VERSION } from "../ir/schema.js";
+/** One policy authority for executable versus inspection-only historical runs. */
+export function classifyWorkflowRunPlan(row) {
+    const runId = row.id ?? "(unknown)";
+    if (!row.plan_json) {
+        if (row.plan_ir_version === WORKFLOW_IR_VERSION) {
+            return {
+                support: "corrupt-plan",
+                irVersion: row.plan_ir_version,
+                error: `Workflow run ${runId} declares workflow IR version ${row.plan_ir_version} but has no frozen plan.`,
+            };
+        }
+        return {
+            support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
+            irVersion: row.plan_ir_version ?? null,
+            error: row.plan_ir_version === null || row.plan_ir_version === undefined
+                ? `Workflow run ${runId} has no executable workflow IR plan.`
+                : `Workflow run ${runId} uses unsupported workflow IR version ${String(row.plan_ir_version)} and has no frozen plan.`,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(row.plan_json);
+    }
+    catch {
+        if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+            return {
+                support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
+                irVersion: row.plan_ir_version ?? null,
+                error: `Workflow run ${runId} has malformed historical frozen plan JSON that cannot be executed.`,
+            };
+        }
+        return {
+            support: "corrupt-plan",
+            irVersion: row.plan_ir_version ?? null,
+            error: `Workflow run ${runId} has corrupt frozen plan JSON.`,
+        };
+    }
+    const decodedVersion = typeof raw === "object" && raw !== null ? raw.irVersion : null;
+    if (!Number.isSafeInteger(decodedVersion) || decodedVersion < 1) {
+        if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+            return {
+                support: row.plan_ir_version === null || row.plan_ir_version === undefined ? "missing-plan" : "unsupported-version",
+                irVersion: row.plan_ir_version ?? null,
+                error: `Workflow run ${runId} has historical frozen plan data with no supported IR version.`,
+            };
+        }
+        return {
+            support: "corrupt-plan",
+            irVersion: row.plan_ir_version ?? null,
+            error: `Workflow run ${runId} has a missing or invalid frozen plan IR version.`,
+        };
+    }
+    if (row.plan_ir_version !== null && row.plan_ir_version !== undefined && row.plan_ir_version !== decodedVersion) {
+        if (row.plan_ir_version !== WORKFLOW_IR_VERSION && decodedVersion !== WORKFLOW_IR_VERSION) {
+            return {
+                support: "unsupported-version",
+                irVersion: decodedVersion,
+                error: `Workflow run ${runId} uses unsupported workflow IR version ${String(decodedVersion)} with mismatched historical metadata.`,
+            };
+        }
+        return {
+            support: "corrupt-plan",
+            irVersion: decodedVersion,
+            error: `Workflow run ${runId} has mismatched stored plan IR version (${String(row.plan_ir_version)} != ${String(decodedVersion)}).`,
+        };
+    }
+    if (decodedVersion !== WORKFLOW_IR_VERSION) {
+        return {
+            support: "unsupported-version",
+            irVersion: decodedVersion,
+            error: `Workflow run ${runId} uses unsupported workflow IR version ${String(decodedVersion)}.`,
+        };
+    }
+    if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+        return {
+            support: "corrupt-plan",
+            irVersion: row.plan_ir_version ?? null,
+            error: `Workflow run ${runId} has no stored plan IR version.`,
+        };
+    }
+    try {
+        return {
+            support: "supported",
+            irVersion: WORKFLOW_IR_VERSION,
+            plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash),
+        };
+    }
+    catch (cause) {
+        return { support: "corrupt-plan", irVersion: 3, error: cause instanceof Error ? cause.message : String(cause) };
+    }
+}
+/** Reject an execution mutation while preserving inspection and abandon access. */
+export function requireExecutableWorkflowPlan(row) {
+    const classified = classifyWorkflowRunPlan(row);
+    if (classified.support === "supported")
+        return classified.plan;
+    if (classified.support === "missing-plan" || classified.support === "unsupported-version") {
+        throw new UsageError(`${classified.error} This historical run is inspection-only; abandon it with \`akm workflow abandon ${row.id ?? "<run>"}\` and start a new run.`, "WORKFLOW_IR_VERSION_UNSUPPORTED");
+    }
+    throw new UsageError(classified.error, "INVALID_JSON_ARGUMENT");
+}
+/** Abandon is the sole mutation allowed for a historical run; corrupt v3 data is never mutated. */
+export function requireAbandonableWorkflowPlan(row) {
+    const classified = classifyWorkflowRunPlan(row);
+    if (classified.support === "corrupt-plan")
+        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 still agrees with the decoded/hash-verified plan before any mutation. */
+export function assertWorkflowSpineMatchesPlan(plan, run, rows) {
+    const expected = frozenStepRows(plan);
+    if (rows.length !== expected.length)
+        corruptSpine(run.id, "step count differs from the frozen plan");
+    for (let index = 0; index < expected.length; index++) {
+        const actual = rows[index];
+        const planned = expected[index];
+        if (!actual ||
+            !planned ||
+            actual.step_id !== planned.stepId ||
+            actual.step_title !== planned.stepTitle ||
+            actual.instructions !== planned.instructions ||
+            actual.completion_json !== planned.completionJson ||
+            actual.sequence_index !== planned.sequenceIndex) {
+            const fields = [
+                actual.step_id !== planned.stepId ? "step_id" : "",
+                actual.step_title !== planned.stepTitle ? "step_title" : "",
+                actual.instructions !== planned.instructions ? "instructions" : "",
+                actual.completion_json !== planned.completionJson ? "completion_json" : "",
+                actual.sequence_index !== planned.sequenceIndex ? "sequence_index" : "",
+            ].filter(Boolean);
+            corruptSpine(run.id, `step row ${index} differs from the frozen plan (${fields.join(", ") || "missing row"})`);
+        }
+    }
+    if (run.current_step_id !== null && !expected.some((step) => step.stepId === run.current_step_id))
+        corruptSpine(run.id, `current step ${run.current_step_id} is not in the frozen plan`);
+    const current = run.current_step_id ? rows.find((row) => row.step_id === run.current_step_id) : undefined;
+    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 pending so `resume` can reopen the same work.
+        if (!current || (current.status !== "failed" && current.status !== "pending"))
+            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");
+}