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

package/dist/workflows/program/project.js

@@ -0,0 +1,104 @@
+// 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/.
+/**
+ * Renderer name for YAML workflow programs. Lives in this leaf module (not
+ * `../renderer.ts`) so the indexer matcher can name it without importing the
+ * renderer module and its registration side effects.
+ */
+export const WORKFLOW_PROGRAM_RENDERER_NAME = "workflow-program-yaml";
+/** File extensions that mark a workflow asset as a YAML program. */
+const WORKFLOW_PROGRAM_PATH_RE = /\.ya?ml$/i;
+/** True when a workflow asset path holds a YAML program (vs. markdown). */
+export function isWorkflowProgramPath(filePath) {
+    return WORKFLOW_PROGRAM_PATH_RE.test(filePath);
+}
+/**
+ * The instruction text a step contributes to the flat step projection.
+ * Unit and map steps carry their unit's RAW instruction template; route
+ * steps have no unit, so a deterministic description of the routing table
+ * stands in (the spine still needs a non-empty instructions string).
+ */
+export function programStepInstructions(step) {
+    if (step.unit)
+        return step.unit.instructions;
+    if (step.map)
+        return step.map.unit.instructions;
+    if (step.route) {
+        const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
+        if (step.route.defaultStepId !== undefined)
+            branches.push(`default -> ${step.route.defaultStepId}`);
+        return `Route on ${step.route.input}: ${branches.join(", ")}.`;
+    }
+    return "";
+}
+/**
+ * Project the program's steps into flat `WorkflowStepDefinition`s.
+ *
+ * `gate.criteria` MUST project into `completionCriteria`: `startWorkflowRun`
+ * persists this projection as the step rows' `completion_json`, which is what
+ * `completeWorkflowStep` reads to run the summary-validation gate (fail-open
+ * when empty). Dropping the criteria here silently disarms every YAML gate.
+ */
+export function projectProgramStepDefinitions(program) {
+    return program.steps.map((step, index) => ({
+        id: step.id,
+        title: step.title ?? step.id,
+        instructions: programStepInstructions(step),
+        ...(step.gate && step.gate.criteria.length > 0 ? { completionCriteria: [...step.gate.criteria] } : {}),
+        sequenceIndex: index,
+    }));
+}
+/** Project the `params` block into the flat `WorkflowParameter` list. */
+export function projectProgramParameters(program) {
+    if (!program.params)
+        return undefined;
+    const parameters = Object.entries(program.params).map(([name, schema]) => {
+        const description = schema.description;
+        return {
+            name,
+            ...(typeof description === "string" && description !== "" ? { description } : {}),
+        };
+    });
+    return parameters.length > 0 ? parameters : undefined;
+}
+/**
+ * Compact, show-facing orchestration summary for one program step, reusing
+ * the existing `WorkflowStepOrchestrationSummary` shape. Field mapping:
+ * `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 engine = unit?.engine ?? defaults?.engine;
+    const model = unit?.model ?? defaults?.model;
+    const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
+    const summary = {
+        ...(engine !== undefined ? { engine } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(step.map
+            ? {
+                fanOut: {
+                    over: step.map.over,
+                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+                    reducer: step.map.reducer ?? "collect",
+                },
+            }
+            : {}),
+        ...(unit?.output !== undefined || step.output !== undefined ? { hasSchema: true } : {}),
+        ...(unit?.env !== undefined ? { env: [...unit.env] } : {}),
+        ...(step.route
+            ? {
+                route: {
+                    input: step.route.input,
+                    branches: step.route.branches.map((b) => ({ match: b.match, stepId: b.stepId })),
+                    ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
+                },
+            }
+            : {}),
+    };
+    return Object.keys(summary).length > 0 ? summary : undefined;
+}

package/dist/workflows/program/schema.js

@@ -0,0 +1,54 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+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"];
+/** Failure policy: fail the step on first unit failure, or record and go on. */
+export const PROGRAM_ON_ERROR = ["fail", "continue"];
+/** Filesystem isolation for file-mutating units (enforcement is R2). */
+export const PROGRAM_ISOLATION_KINDS = ["none", "worktree"];
+/**
+ * `retry.on` vocabulary — exactly the persisted `AgentFailureReason` taxonomy
+ * from `src/integrations/agent/spawn.ts`. The `satisfies` clause fails the
+ * typecheck if spawn.ts adds/renames a reason without this list (and the JSON
+ * Schema, via the drift test) being updated.
+ */
+const RETRY_REASON_SET = {
+    timeout: true,
+    spawn_failed: true,
+    non_zero_exit: true,
+    parse_error: true,
+    cooldown: true,
+    llm_rate_limit: true,
+    llm_content_filter: true,
+    llm_invalid_json: true,
+    content_policy_reject: true,
+    unsupported_type: true,
+    no_change: true,
+    aborted: true,
+};
+export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
+/**
+ * Step ids: `[A-Za-z_][A-Za-z0-9_-]*` (also pinned in the JSON Schema).
+ *
+ * This is EXACTLY the `<ident>` grammar `readIdent` accepts in
+ * `program/expressions.ts` for `${{ steps.<id>.output }}` references: a
+ * letter/underscore first char, then letters/digits/underscores/dashes, and
+ * NO dots (the expression parser treats `.` as the `.output` path separator,
+ * so a dotted id could never be addressed). Keeping step ids inside the
+ * addressable grammar guarantees every step can be referenced from map
+ * inputs, routes, and unit templates without renaming.
+ *
+ * Forbidding dots additionally keeps the engine's internal gate-row node id
+ * `<stepId>.gate` collision-free: no user step id can contain a dot, so it can
+ * never equal another step's `<stepId>.gate` synthetic id.
+ */
+export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Param names must be `${{ params.<ident> }}`-addressable, so they are plain
+ * identifiers (no dots/dashes).
+ */
+export const PROGRAM_PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/dist/workflows/renderer.js

@@ -2,18 +2,28 @@
 // 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/.
 /**
- * Show + indexing renderer for workflow assets.
+ * Show + indexing renderers for workflow assets.
  *
- * Reads the markdown via `parseWorkflow` and projects the validated
- * `WorkflowDocument` down to the public `ShowResponse` shape (which still
- * uses the flat `WorkflowStepDefinition` type for backwards compatibility)
- * and into search hints for the indexer.
+ * Two formats, one asset type:
+ *
+ *   - `workflow-md` — reads the classic linear markdown via `parseWorkflow`
+ *     and projects the validated `WorkflowDocument` down to the public
+ *     `ShowResponse` shape (which still uses the flat
+ *     `WorkflowStepDefinition` type for backwards compatibility) and into
+ *     search hints for the indexer.
+ *   - `workflow-program-yaml` — reads a YAML workflow *program* (redesign
+ *     addendum, R1) via `parseWorkflowProgram` and projects it through
+ *     `program/project.ts`, including a compact orchestration summary per
+ *     step (runner/model, `fanOut.over` expression, route table).
  */
 import { makeAssetRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";
 import { registerMetadataContributor } from "../indexer/passes/metadata-contributors.js";
 import { parseWorkflow } from "./parser.js";
+import { parseWorkflowProgram } from "./program/parser.js";
+import { programStepInstructions, projectProgramParameters, summarizeProgramStepOrchestration, WORKFLOW_PROGRAM_RENDERER_NAME, } from "./program/project.js";
 import { cacheWorkflowDocument } from "./runtime/document-cache.js";
+export { WORKFLOW_PROGRAM_RENDERER_NAME };
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -59,6 +69,43 @@ export const workflowMdRenderer = {
         };
     },
 };
+function loadProgram(ctx) {
+    const result = parseWorkflowProgram(ctx.content(), { path: ctx.relPath });
+    if (result.ok)
+        return result.program;
+    const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
+    throw new UsageError(`Workflow has errors:\n${summary}`);
+}
+/** Show renderer for YAML workflow programs — mirrors `workflowMdRenderer`. */
+export const workflowProgramRenderer = {
+    name: WORKFLOW_PROGRAM_RENDERER_NAME,
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const program = loadProgram(ctx);
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        const parameters = projectProgramParameters(program);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: program.description,
+            workflowTitle: program.name,
+            ...(parameters ? { parameters: parameters.map((p) => p.name), workflowParameters: parameters } : {}),
+            steps: program.steps.map((step, index) => {
+                const orchestration = summarizeProgramStepOrchestration(step, program.defaults);
+                return {
+                    id: step.id,
+                    title: step.title ?? step.id,
+                    instructions: programStepInstructions(step),
+                    ...(step.gate ? { completionCriteria: [...step.gate.criteria] } : {}),
+                    sequenceIndex: index,
+                    ...(orchestration ? { orchestration } : {}),
+                };
+            }),
+        };
+    },
+};
 registerMetadataContributor({
     name: "workflow-document-metadata",
     appliesTo: ({ rendererName }) => rendererName === "workflow-md",
@@ -84,3 +131,33 @@ registerMetadataContributor({
         cacheWorkflowDocument(entry, doc);
     },
 });
+registerMetadataContributor({
+    name: "workflow-program-metadata",
+    appliesTo: ({ rendererName }) => rendererName === WORKFLOW_PROGRAM_RENDERER_NAME,
+    contribute(entry, { renderContext }) {
+        // Parse failures throw, which the metadata pass turns into a
+        // skip-with-warning — broken programs never land in the index, mirroring
+        // markdown workflows. No workflow_documents cache row is written: YAML
+        // programs are re-parsed from disk by the runtime loader.
+        const program = loadProgram(renderContext);
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(program.name);
+        for (const step of program.steps) {
+            hints.add(step.id);
+            if (step.title)
+                hints.add(step.title);
+            hints.add(programStepInstructions(step));
+            for (const criterion of step.gate?.criteria ?? []) {
+                hints.add(criterion);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (!entry.description && program.description) {
+            entry.description = program.description;
+        }
+        const parameters = projectProgramParameters(program);
+        if (parameters?.length) {
+            entry.parameters = parameters;
+        }
+    },
+});

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/agent-identity.js

@@ -11,14 +11,42 @@
  * already exposes via the environment.
  *
  * Resolution is best-effort and environment-driven:
- *   - harness:    AKM_AGENT_HARNESS, else inferred from a known harness env var.
+ *   - harness:    AKM_AGENT_HARNESS, else inferred from a harness session-id
+ *                 env var (`identityEnv`), else from a harness presence flag
+ *                 (`presenceEnv`).
  *   - sessionId:  AKM_SESSION_ID, else the harness-native session env var.
+ *                 Presence flags NEVER contribute a session id — their values
+ *                 (`CODEX_SANDBOX=seatbelt`, `GEMINI_CLI=1`) are modes/flags,
+ *                 not sessions, and must not be persisted as agent_session_id.
  *
  * Explicit values passed to `startWorkflowRun` always win over the environment.
  *
+ * The harness-native markers are DERIVED from `HARNESS_REGISTRY` (plan §"Kill
+ * registry drift", P2): each harness declares its session-id env vars via
+ * `identityEnv` and its presence-only flags via `presenceEnv`, so adding a
+ * harness never touches this module. Only the `AKM_*` explicit-override vars
+ * are non-registry (they are akm's own, not any harness's) and stay hardcoded
+ * here.
+ *
  * @module workflows/agent-identity
  */
-import { denormalizeRuntimeIdentity } from "../../integrations/harnesses/index.js";
+import { denormalizeRuntimeIdentity, HARNESS_REGISTRY } from "../../integrations/harnesses/index.js";
+/**
+ * Derive a marker table from one registry env-var field, ordered by canonical
+ * id. The sort keeps the pre-derivation precedence byte-identical ('claude'
+ * before 'opencode' — the old if/else chain's order) and independent of
+ * `HARNESS_REGISTRY` declaration order, which is pinned for JSON-schema enum
+ * stability, not detection precedence.
+ */
+function deriveMarkers(pick) {
+    return HARNESS_REGISTRY.filter((h) => (pick(h)?.length ?? 0) > 0)
+        .map((h) => ({ harnessId: h.id, envKeys: pick(h) ?? [] }))
+        .sort((a, b) => a.harnessId.localeCompare(b.harnessId));
+}
+/** Session-id-bearing markers — usable for BOTH harness inference and sessionId. */
+const SESSION_MARKERS = deriveMarkers((h) => h.identityEnv);
+/** Presence-only flags — harness inference ONLY; their values are never a session id. */
+const PRESENCE_MARKERS = deriveMarkers((h) => h.presenceEnv);
 function firstNonEmpty(env, keys) {
     for (const key of keys) {
         const value = env[key];
@@ -37,20 +65,37 @@ export function resolveAgentIdentity(env = process.env) {
     // Explicit override always wins.
     let harness = firstNonEmpty(env, ["AKM_AGENT_HARNESS"]);
     if (!harness) {
-        // Infer the harness from a harness-specific *session* env var. We only
-        // infer when a concrete session id is present: the bare "this process is
-        // Claude Code" flag does not mean a given run is owned by an agent session,
-        // so it must not silently stamp identity onto manual CLI invocations.
-        if (firstNonEmpty(env, ["CLAUDE_SESSION_ID"])) {
-            // Runtime identity for Claude Code is "claude-code" (vs the canonical
-            // config id "claude"). Derived from the unified registry's bridge (#562)
-            // so the persisted runtime string can't drift — still emits "claude-code".
-            harness = denormalizeRuntimeIdentity("claude");
+        // Infer the harness from a harness-specific *session* env var first
+        // (registry `identityEnv` markers). A concrete session id is the
+        // strongest evidence of the immediate driver, so it outranks any
+        // presence flag — e.g. opencode launched inside a codex sandbox
+        // (OPENCODE_SESSION_ID + CODEX_SANDBOX) attributes to opencode.
+        for (const marker of SESSION_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                // Report the harness's RUNTIME identity (e.g. canonical 'claude' →
+                // 'claude-code') via the registry's #562 bridge so the persisted
+                // runtime string can't drift.
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
-        else if (firstNonEmpty(env, ["OPENCODE_SESSION_ID"])) {
-            harness = denormalizeRuntimeIdentity("opencode");
+    }
+    if (!harness) {
+        // Fall back to presence-only flags (registry `presenceEnv`). These are
+        // stamped by the harness on its OWN child processes (CODEX_SANDBOX,
+        // GEMINI_CLI=1), so they cannot mis-attribute manual CLI invocations —
+        // but they carry no session id, so sessionId stays null below.
+        for (const marker of PRESENCE_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
     }
-    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", "CLAUDE_SESSION_ID", "OPENCODE_SESSION_ID"]);
+    // Session id: the explicit AKM override first, then the session-id-bearing
+    // registry markers in the same precedence order as harness inference (so
+    // harness and session id agree when multiple harness env vars are present).
+    // Presence flags are deliberately excluded — their values are not sessions.
+    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", ...SESSION_MARKERS.flatMap((m) => [...m.envKeys])]);
     return { harness, sessionId };
 }

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