akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/workflows/ir/schema-v4.js

@@ -12,27 +12,48 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { UsageError } from "../../core/errors.js";
 import { decodeFrozenExecutableIdentity } from "../../execution/executable-identity.js";
+import { INPUT_NAME_PATTERN } from "../../execution/input-contract.js";
 import { canonicalResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
 import { decodeExecutionSourceIdentity } from "../../execution/source.js";
 import { decodeFrozenRunnerSpec } from "../../integrations/agent/execution-lowering.js";
+import { parseReference } from "../program/expressions.js";
+import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
+import { utf8Bytes, WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES } from "../resource-limits.js";
 import { decodeWorkflowExecSpec, validateWorkflowPlanStructure, } from "./schema.js";
-export const WORKFLOW_IR_V4_VERSION = 4;
-/** Strict v4 corruption gate. No authored source or config is consulted here. */
-export function decodeWorkflowPlanV4(input, hooks = {}) {
+export const WORKFLOW_IR_V5_VERSION = 5;
+/**
+ * Strict v4 corruption gate. No authored source or config is consulted here.
+ *
+ * `depth` is the composition-depth recursion counter (0 at the root
+ * workflow plan; +1 for every embedded child-workflow plan), and `budget` is
+ * a MUTABLE, tree-wide running total of embedded child-plan bytes charged so
+ * far. Both are internal to the recursive child-workflow decode path below
+ * (`decodeChildWorkflowTarget` calls this function again on an embedded
+ * `frozenPlan`, sharing the SAME `budget` object across the whole recursion —
+ * mirroring `ChildCompositionContext.budget` on the freeze side) — every
+ * external caller decodes a plan at the top level and relies on the
+ * defaults. Re-enforces the composition depth bound AND the aggregate
+ * embedded-bytes bound at decode as corruption gates (spec docs/plans/specs/
+ * p3a-plan-v5-child-freeze.md §3.6 step 6, rows A-23, A-N6); the actionable
+ * freeze-time `COMPOSITION_INVALID` gates live in
+ * `src/workflows/freeze/targets/child-workflow.ts` (Lane B).
+ */
+export function decodeWorkflowPlanV4(input, hooks = {}, depth = 0, budget = { embeddedBytes: 0 }) {
     const raw = record(input, "plan");
-    if (raw.irVersion !== WORKFLOW_IR_V4_VERSION)
-        fail("irVersion must be 4");
-    assertKeys(raw, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps", "sourceReadSet"], "plan");
+    if (raw.irVersion !== WORKFLOW_IR_V5_VERSION)
+        fail("irVersion must be 5");
+    assertKeys(raw, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps", "sourceReadSet", "outputs"], "plan");
     if (!Object.hasOwn(raw, "sourceReadSet"))
         fail("sourceReadSet is required");
     const sourceReadSet = decodeSourceReadSet(raw.sourceReadSet);
     validateWorkflowPlanStructure(raw, {
-        expectedVersion: WORKFLOW_IR_V4_VERSION,
-        planExtraKeys: ["sourceReadSet"],
+        expectedVersion: WORKFLOW_IR_V5_VERSION,
+        planExtraKeys: ["sourceReadSet", "outputs"],
         unitExtraKeys: ["frozenTarget", "environment"],
         gateExtraKeys: ["frozenJudge"],
     }, hooks);
     const rawSteps = raw.steps;
+    const stepIds = new Set(rawSteps.map((rawStep) => rawStep.stepId));
     const requiredSources = [];
     const steps = rawSteps.map((rawStep, index) => {
         const step = rawStep;
@@ -46,28 +67,68 @@ export function decodeWorkflowPlanV4(input, hooks = {}) {
                 const { template: _template, ...map } = rawRoot;
                 return {
                     ...map,
-                    template: decodeUnitV4(record(rawRoot.template, `map ${String(rawRoot.id)} template`), requiredSources),
+                    template: decodeUnitV4(record(rawRoot.template, `map ${String(rawRoot.id)} template`), requiredSources, depth, budget),
                 };
             })()
-            : decodeUnitV4(rawRoot, requiredSources);
+            : decodeUnitV4(rawRoot, requiredSources, depth, budget);
         return Object.freeze({ ...step, root, gate });
     });
     assertRequiredSources(sourceReadSet, requiredSources);
+    const outputs = Object.hasOwn(raw, "outputs") ? decodeWorkflowOutputs(raw.outputs, stepIds) : undefined;
+    const { outputs: _rawOutputs, ...restRaw } = raw;
     return Object.freeze({
-        ...raw,
-        irVersion: WORKFLOW_IR_V4_VERSION,
+        ...restRaw,
+        irVersion: WORKFLOW_IR_V5_VERSION,
         sourceReadSet,
         steps,
+        ...(outputs ? { outputs } : {}),
     });
 }
-function decodeUnitV4(raw, requiredSources) {
+/**
+ * Decode a plan's `outputs` (P3b, spec §4.2): a corruption gate mirroring
+ * {@link decodeInputBindings} — non-empty, sorted-unique keys (canonical wire
+ * order, same rule `inputBindings` enforces), each name matching the
+ * `params:` name pattern, each entry's closed key set, `from` re-parsing as a
+ * `stepOutput` reference whose step id is declared in `plan.steps`.
+ */
+function decodeWorkflowOutputs(value, stepIds) {
+    const raw = record(value, "plan outputs");
+    const names = Object.keys(raw);
+    if (names.length === 0)
+        fail("plan outputs must be a non-empty object");
+    let prior;
+    const outputs = {};
+    for (const name of names) {
+        if (!PROGRAM_PARAM_NAME_PATTERN.test(name))
+            fail(`plan outputs has invalid name ${name}`);
+        if (prior !== undefined && compareCodePoints(prior, name) >= 0) {
+            fail("plan outputs must be sorted by unique name");
+        }
+        prior = name;
+        const entry = record(raw[name], `plan outputs.${name}`);
+        assertKeys(entry, ["from", "schema"], `plan outputs.${name}`);
+        if (typeof entry.from !== "string" || !entry.from)
+            fail(`plan outputs.${name} from is invalid`);
+        const parsed = parseReference(entry.from);
+        if (!parsed.ok || parsed.expr.kind !== "stepOutput") {
+            fail(`plan outputs.${name} from must be a steps.<id>.output reference`);
+        }
+        if (!stepIds.has(parsed.expr.stepId)) {
+            fail(`plan outputs.${name} from names step ${parsed.expr.stepId}, which is not in plan.steps`);
+        }
+        const schema = Object.hasOwn(entry, "schema") ? record(entry.schema, `plan outputs.${name} schema`) : undefined;
+        outputs[name] = Object.freeze({ from: entry.from, ...(schema ? { schema: Object.freeze(schema) } : {}) });
+    }
+    return Object.freeze(outputs);
+}
+function decodeUnitV4(raw, requiredSources, depth, budget) {
     const id = raw.id;
     if (!Object.hasOwn(raw, "frozenTarget"))
         fail(`unit ${id} frozenTarget is required`);
     if (!Object.hasOwn(raw, "environment"))
         fail(`unit ${id} environment is required`);
     const environment = decodeEnvironment(raw.environment, id);
-    const frozenTarget = decodeFrozenTarget(raw.frozenTarget, raw, environment, requiredSources);
+    const frozenTarget = decodeFrozenTarget(raw.frozenTarget, raw, environment, requiredSources, depth, budget);
     const { frozenTarget: _target, environment: _environment, ...core } = raw;
     return Object.freeze({
         ...core,
@@ -109,7 +170,7 @@ function decodeGateV4(value, stepId, requiredSources) {
         frozenJudge: decodeCommandTarget(record(gate.frozenJudge, `gate ${stepId} frozenJudge`), identity, requiredSources),
     });
 }
-function decodeFrozenTarget(value, unit, environment, requiredSources) {
+function decodeFrozenTarget(value, unit, environment, requiredSources, depth, budget) {
     const target = record(value, `unit ${unit.id} frozenTarget`);
     if (target.kind === "command")
         return decodeCommandTarget(target, unit, requiredSources);
@@ -117,10 +178,121 @@ function decodeFrozenTarget(value, unit, environment, requiredSources) {
         return decodeShellTarget(target, unit, environment);
     if (target.kind === "script")
         return decodeScriptTarget(target, unit, requiredSources);
+    if (target.kind === "child-workflow")
+        return decodeChildWorkflowTarget(target, unit, depth, budget);
     fail(`unit ${unit.id} frozenTarget has unsupported kind ${String(target.kind)}`);
 }
+/**
+ * Composition-depth corruption bound (spec §3.6 step 6, §4.5, row A-23).
+ * Mirrors `WORKFLOW_MAX_COMPOSITION_DEPTH` (= 8), which Lane B adds to
+ * `src/workflows/resource-limits.ts` in a later commit as the freeze-time
+ * `COMPOSITION_INVALID` gate. Reproduced here — the decode-time corruption
+ * gate — rather than imported across the lane boundary, matching
+ * `tests/workflows/plan-v5-schema.test.ts`'s own header comment.
+ */
+const CHILD_WORKFLOW_DECODE_MAX_DEPTH = 8;
+/**
+ * Decode a `kind: "child-workflow"` frozen target (§3.5): the embedded
+ * COMPLETE child plan, re-verified against its own `planHash` and this
+ * target's own `contentHash` on every decode (rows A-20, A-21), recursively
+ * enforcing `irVersion` 5 (row A-22, via the recursive
+ * {@link decodeWorkflowPlanV4} call), the composition depth bound (row A-23),
+ * and the AGGREGATE embedded-plan-bytes bound (§3.6 step 6, A-N6) as the
+ * decoder recurses. `WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES` — unlike the
+ * depth bound above — is imported directly from
+ * `src/workflows/resource-limits.ts` rather than reproduced: that constant
+ * was already Lane B's when this decode-time re-enforcement was added (no
+ * lane-ordering constraint left to honor), and re-deriving a byte cap by
+ * hand invites drift a depth integer does not. `budget` is charged with
+ * THIS child's own full canonical byte length AFTER it decodes (so any
+ * further-nested grandchildren it embeds have already charged themselves,
+ * mirroring the freeze-side `chargeEmbeddedBudget`'s post-recursion charge
+ * order in `src/workflows/freeze/targets/child-workflow.ts`) — a rejected
+ * plan therefore never partially charges the budget. `frozenPlan` is
+ * covered wholesale through `planHash`, so it is deliberately NOT
+ * re-serialized into `contentHash` (§3.5). No `requiredSources`
+ * contribution: unlike a command/script target's own referenced source, the
+ * child's transitive sources live in the child's OWN `sourceReadSet`,
+ * verified by the recursive decode call itself; the PARENT's
+ * `sourceReadSet` absorbing the child's files (row B-05) is a freeze-time
+ * concern (Lane B), not a decode-time structural one.
+ */
+function decodeChildWorkflowTarget(target, unit, depth, budget) {
+    assertKeys(target, ["kind", "ref", "planHash", "frozenPlan", "contentHash", "via", "taskRef", "inputBindings"], `unit ${unit.id} child workflow target`);
+    if (typeof target.ref !== "string" || !target.ref)
+        fail(`unit ${unit.id} child workflow ref is invalid`);
+    const planHash = digest(target.planHash, `unit ${unit.id} child workflow planHash`);
+    if (target.via !== "direct" && target.via !== "task")
+        fail(`unit ${unit.id} child workflow via is invalid`);
+    const via = target.via;
+    if (via === "task") {
+        if (typeof target.taskRef !== "string" || !target.taskRef) {
+            fail(`unit ${unit.id} child workflow via "task" requires a taskRef`);
+        }
+    }
+    else if (target.taskRef !== undefined) {
+        fail(`unit ${unit.id} child workflow via "direct" cannot carry a taskRef`);
+    }
+    const taskRef = target.taskRef;
+    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} child workflow target`);
+    const contentHash = digest(target.contentHash, `unit ${unit.id} child workflow contentHash`);
+    const expectedContentHash = childWorkflowContentHash({ ref: target.ref, planHash, via, taskRef, inputBindings });
+    if (contentHash !== expectedContentHash) {
+        fail(`unit ${unit.id} child workflow contentHash does not match its frozen dispatch`);
+    }
+    const childDepth = depth + 1;
+    if (childDepth > CHILD_WORKFLOW_DECODE_MAX_DEPTH) {
+        fail(`unit ${unit.id} child workflow ${target.ref} exceeds the max composition depth of ${CHILD_WORKFLOW_DECODE_MAX_DEPTH}`);
+    }
+    const frozenPlan = decodeWorkflowPlanV4(target.frozenPlan, {}, childDepth, budget);
+    const embeddedPlanJson = canonicalJsonLocal(frozenPlan);
+    const actualPlanHash = sha256(embeddedPlanJson);
+    if (actualPlanHash !== planHash) {
+        fail(`unit ${unit.id} child workflow embedded plan does not match its frozen planHash`);
+    }
+    const projectedBytes = budget.embeddedBytes + utf8Bytes(embeddedPlanJson);
+    if (projectedBytes > WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES) {
+        fail(`unit ${unit.id} child workflow ${target.ref} embedded plans total ${projectedBytes} bytes, over the ` +
+            `${WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES}-byte limit`);
+    }
+    budget.embeddedBytes = projectedBytes;
+    return Object.freeze({
+        kind: "child-workflow",
+        ref: target.ref,
+        planHash,
+        frozenPlan,
+        contentHash,
+        via,
+        ...(taskRef !== undefined ? { taskRef } : {}),
+        ...(inputBindings ? { inputBindings } : {}),
+    });
+}
+/** §3.5's exact `contentHash` formula. */
+function childWorkflowContentHash(fields) {
+    return createHash("sha256")
+        .update("akm.workflow.child-workflow\0v1\0")
+        .update(canonicalJsonLocal({
+        ref: fields.ref,
+        planHash: fields.planHash,
+        via: fields.via,
+        taskRef: fields.taskRef ?? null,
+        inputBindings: fields.inputBindings ?? null,
+    }))
+        .digest("hex");
+}
 function decodeCommandTarget(target, unit, requiredSources) {
-    assertKeys(target, ["kind", "ref", "contentHash", "request", "runner", "concurrency", "cwdIdentity", "executable", "gitCommitOid"], `unit ${unit.id} command target`);
+    assertKeys(target, [
+        "kind",
+        "ref",
+        "contentHash",
+        "request",
+        "runner",
+        "concurrency",
+        "cwdIdentity",
+        "executable",
+        "gitCommitOid",
+        "inputBindings",
+    ], `unit ${unit.id} command target`);
     if (target.ref !== null && typeof target.ref !== "string")
         fail(`unit ${unit.id} command target ref is invalid`);
     const request = decodeResolvedExecutionRequest(target.request);
@@ -171,6 +343,7 @@ function decodeCommandTarget(target, unit, requiredSources) {
         fail(`unit ${unit.id} non-CLI target cannot carry a host executable`);
     }
     const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
+    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} command target`);
     // Force the shared request canonicalizer across every accepted wire request.
     canonicalResolvedExecutionRequest(request);
     return Object.freeze({
@@ -183,10 +356,11 @@ function decodeCommandTarget(target, unit, requiredSources) {
         ...(cwdIdentity ? { cwdIdentity } : {}),
         ...(executable ? { executable } : {}),
         ...(gitCommitOid ? { gitCommitOid } : {}),
+        ...(inputBindings ? { inputBindings } : {}),
     });
 }
 function decodeShellTarget(target, unit, environment) {
-    assertKeys(target, ["kind", "contentHash", "exec", "cwdIdentity", "executable", "gitCommitOid"], `unit ${unit.id} shell target`);
+    assertKeys(target, ["kind", "contentHash", "exec", "cwdIdentity", "executable", "gitCommitOid", "inputBindings"], `unit ${unit.id} shell target`);
     const exec = decodeWorkflowExecSpec(target.exec, `unit ${unit.id} shell target exec`);
     const cwdIdentity = decodeDirectoryIdentity(target.cwdIdentity, unit.id);
     const executable = Object.hasOwn(target, "executable")
@@ -197,12 +371,16 @@ function decodeShellTarget(target, unit, environment) {
     }
     const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
     const contentHash = digest(target.contentHash, `unit ${unit.id} shell contentHash`);
+    // inputBindings deliberately sits OUTSIDE this preimage (P2b A-N7): identity
+    // coverage for a task-composed unit comes from computeUnitInputHash's own
+    // frozenTarget field (step-work.ts), which hashes this whole target anyway.
     const expected = createHash("sha256")
         .update("akm.workflow.shell.v1\0")
         .update(canonicalJsonLocal({ exec, environment, cwdIdentity }))
         .digest("hex");
     if (contentHash !== expected)
         fail(`unit ${unit.id} shell contentHash does not match its frozen dispatch`);
+    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} shell target`);
     return Object.freeze({
         kind: "shell",
         contentHash,
@@ -210,6 +388,7 @@ function decodeShellTarget(target, unit, environment) {
         cwdIdentity,
         ...(executable ? { executable } : {}),
         ...(gitCommitOid ? { gitCommitOid } : {}),
+        ...(inputBindings ? { inputBindings } : {}),
     });
 }
 function decodeScriptTarget(target, unit, requiredSources) {
@@ -226,6 +405,7 @@ function decodeScriptTarget(target, unit, requiredSources) {
         "materialization",
         "executable",
         "gitCommitOid",
+        "inputBindings",
     ], `unit ${unit.id} script target`);
     const exec = decodeWorkflowExecSpec(target.exec, `unit ${unit.id} script target exec`);
     if (typeof target.ref !== "string" || !target.ref.includes("//"))
@@ -253,6 +433,7 @@ function decodeScriptTarget(target, unit, requiredSources) {
         ? decodeFrozenExecutableIdentity(target.executable, `unit ${unit.id} executable`)
         : undefined;
     const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
+    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} script target`);
     requiredSources.push({ ref: target.ref, bundle: "", adapter: "", file: "", hash: contentHash });
     return Object.freeze({
         kind: "script",
@@ -267,7 +448,55 @@ function decodeScriptTarget(target, unit, requiredSources) {
         materialization: "ephemeral-0700-delete",
         ...(executable ? { executable } : {}),
         ...(gitCommitOid ? { gitCommitOid } : {}),
+        ...(inputBindings ? { inputBindings } : {}),
+    });
+}
+/**
+ * Decode a frozen target's `inputBindings` (P2b §3.2 A-N7): a composing
+ * step's `with:` normalized against the composed task's declared inputs.
+ * Closed `kind`, `INPUT_NAME_PATTERN` name, unique and sorted by name (never
+ * `[]` — absence is the identity-preserving default). A `literal` entry
+ * requires `value`; a `reference` entry requires a `parseReference`-valid
+ * `from` plus the declaration's bounded `schema` (§3.6's widened reference
+ * arm, `src/execution/input-contract.ts`).
+ */
+function decodeInputBindings(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length === 0)
+        fail(`${label} inputBindings must be a non-empty array`);
+    let prior;
+    const bindings = value.map((raw, index) => {
+        const binding = record(raw, `${label} inputBindings[${index}]`);
+        if (typeof binding.name !== "string" || !INPUT_NAME_PATTERN.test(binding.name)) {
+            fail(`${label} inputBindings[${index}] name is invalid`);
+        }
+        if (prior !== undefined && compareCodePoints(prior, binding.name) >= 0) {
+            fail(`${label} inputBindings must be sorted by unique name`);
+        }
+        prior = binding.name;
+        if (binding.kind === "literal") {
+            assertKeys(binding, ["kind", "name", "value"], `${label} inputBindings[${index}]`);
+            if (!Object.hasOwn(binding, "value"))
+                fail(`${label} inputBindings[${index}] literal binding requires value`);
+            return Object.freeze({ kind: "literal", name: binding.name, value: binding.value });
+        }
+        if (binding.kind === "reference") {
+            assertKeys(binding, ["kind", "name", "from", "schema"], `${label} inputBindings[${index}]`);
+            if (typeof binding.from !== "string" || !parseReference(binding.from).ok) {
+                fail(`${label} inputBindings[${index}] from is not a valid reference`);
+            }
+            const schema = record(binding.schema, `${label} inputBindings[${index}] schema`);
+            return Object.freeze({
+                kind: "reference",
+                name: binding.name,
+                from: binding.from,
+                schema: Object.freeze(schema),
+            });
+        }
+        return fail(`${label} inputBindings[${index}] has unsupported kind ${String(binding.kind)}`);
     });
+    return Object.freeze(bindings);
 }
 function decodeGitCommitOid(value, unit) {
     if (unit.isolation === "worktree") {

package/dist/workflows/parser.js

@@ -38,7 +38,7 @@ import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-param
 import { checkJsonSchemaDefinition, JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS } from "../core/json-schema.js";
 import { parseReference } from "./program/expressions.js";
 import { PROGRAM_ISOLATION_KINDS, PROGRAM_ON_ERROR, PROGRAM_PARAM_NAME_PATTERN, PROGRAM_REDUCERS, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN, } from "./program/schema.js";
-import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_STEPS, WORKFLOW_MAX_TIMEOUT_MS, } from "./resource-limits.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_OUTPUTS, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_STEPS, WORKFLOW_MAX_TIMEOUT_MS, } from "./resource-limits.js";
 import { WORKFLOW_SCHEMA_VERSION, } from "./schema.js";
 import { runSemanticChecks } from "./validator.js";
 /** Envelope keys every AKM markdown asset carries ($ref'd from schemas/akm-asset-envelope.json). */
@@ -56,7 +56,7 @@ const ENVELOPE_KEYS = [
     "status",
     "stale_after",
 ];
-const WORKFLOW_KEYS = ["params", "defaults", "budget", "steps"];
+const WORKFLOW_KEYS = ["params", "outputs", "defaults", "budget", "steps"];
 const TOP_LEVEL_KEYS = [...ENVELOPE_KEYS, ...WORKFLOW_KEYS];
 const DEFAULTS_KEYS = ["engine", "model", "timeout", "on_error", "llm"];
 const BUDGET_KEYS = ["max_tokens", "max_units"];
@@ -70,6 +70,8 @@ const ROUTE_KEYS = ["input", "when", "default"];
 const RETRY_KEYS = ["max", "on"];
 const GATE_KEYS = ["max_loops"];
 const ROUTE_BRANCH_KEYS = ["match", "step"];
+/** Closed key set of one `outputs:` entry — mirrors `params:`'s bare-schema shape, plus `from`. */
+const OUTPUT_ENTRY_KEYS = ["from", "schema"];
 const ACTOR_STAMP_KEYS = ["by", "at"];
 const TIMEOUT_VALUE = /^(\d+)(ms|s|m)?$/;
 const TIMEOUT_HINT = `Use "<n>ms", "<n>s", "<n>m" (e.g. "10m"), or "none"`;
@@ -174,6 +176,7 @@ export function parseWorkflow(markdown, source) {
     const description = typeof root.description === "string" ? root.description : undefined;
     const tags = readTags(ctx, root.tags, frontmatterEndLine);
     const params = parseParams(ctx, root.params);
+    const outputs = parseOutputs(ctx, root.outputs);
     const defaults = parseDefaults(ctx, root.defaults);
     const budget = parseBudget(ctx, root.budget);
     const parsedSteps = parseSteps(ctx, root.steps);
@@ -220,6 +223,7 @@ export function parseWorkflow(markdown, source) {
         ...(description ? { description } : {}),
         ...(tags ? { tags } : {}),
         ...(params ? { params } : {}),
+        ...(outputs ? { outputs } : {}),
         ...(defaults ? { defaults } : {}),
         ...(budget ? { budget } : {}),
         steps,
@@ -423,6 +427,74 @@ function parseParams(ctx, raw) {
     }
     return Object.keys(params).length > 0 ? params : undefined;
 }
+/**
+ * `outputs:` (P3b, spec §4.2): named, optionally schema-validated projections
+ * of step artifacts, exported when the run completes. Symmetrical with
+ * `parseParams` above (B-N4) — same authoring surface, same name grammar,
+ * same schema-subset validator, same per-schema byte bound — but each entry
+ * is a STRUCTURED `{from, schema?}` mapping rather than a bare JSON Schema.
+ *
+ * `from` is validated for GRAMMAR only here: it must parse and it must be a
+ * `steps.<id>.output(.<seg>)*` reference (never `params.<name>` — an output
+ * projects a step artifact, never a param, B-07). Whether the named step is
+ * actually DECLARED in this document is a semantic, cross-step check left to
+ * `ir/compile.ts`'s reference validation (B-06), mirroring how `inputs[]` /
+ * `map.over` / `route.input` already split "syntax here, semantics there".
+ */
+function parseOutputs(ctx, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainRecord(raw)) {
+        ctx.err(["outputs"], `"outputs" must be a mapping of output name to { from, schema? } (e.g. report: { from: steps.summarize.output }).`);
+        return undefined;
+    }
+    if (Object.keys(raw).length > WORKFLOW_MAX_OUTPUTS) {
+        ctx.err(["outputs"], `"outputs" must contain at most ${WORKFLOW_MAX_OUTPUTS} entries.`);
+    }
+    const outputs = {};
+    for (const [outputName, value] of Object.entries(raw)) {
+        const path = ["outputs", outputName];
+        if (!PROGRAM_PARAM_NAME_PATTERN.test(outputName)) {
+            ctx.err(path, `Output name "${outputName}" is invalid. Use letters, digits, and underscores, starting with a letter or ` +
+                `underscore, so "steps.<child>.output.${outputName}" can address it.`);
+            continue;
+        }
+        if (!isPlainRecord(value)) {
+            ctx.err(path, `Output "${outputName}" must be a mapping with "from" (and optional "schema").`);
+            continue;
+        }
+        checkUnknownKeys(ctx, value, path, OUTPUT_ENTRY_KEYS, `output "${outputName}"`);
+        if (typeof value.from !== "string" || value.from.trim() === "") {
+            ctx.err([...path, "from"], `Output "${outputName}" must declare "from": a steps.<id>.output(.<seg>)* reference.`);
+            continue;
+        }
+        const parsedFrom = parseReference(value.from);
+        if (!parsedFrom.ok) {
+            ctx.err([...path, "from"], `Output "${outputName}" "from": ${parsedFrom.message}`);
+            continue;
+        }
+        if (parsedFrom.expr.kind !== "stepOutput") {
+            ctx.err([...path, "from"], `Output "${outputName}" "from" must reference a step output (steps.<id>.output...), not a param — an ` +
+                `output projects a step artifact, never a param (got "${value.from}").`);
+            continue;
+        }
+        const entry = { from: value.from };
+        if (value.schema !== undefined) {
+            if (!isPlainRecord(value.schema)) {
+                ctx.err([...path, "schema"], `Output "${outputName}" "schema" must be a JSON Schema object.`);
+            }
+            else {
+                if (jsonBytes(value.schema) > WORKFLOW_MAX_SCHEMA_BYTES) {
+                    ctx.err([...path, "schema"], `Output "${outputName}" schema exceeds the 256 KiB resource limit.`);
+                }
+                checkSchemaDefinition(ctx, value.schema, [...path, "schema"], `Output "${outputName}" schema`);
+                entry.schema = value.schema;
+            }
+        }
+        outputs[outputName] = entry;
+    }
+    return Object.keys(outputs).length > 0 ? outputs : undefined;
+}
 function parseDefaults(ctx, raw) {
     if (raw === undefined)
         return undefined;

package/dist/workflows/program/schema.js

@@ -46,9 +46,12 @@ export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
 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).
+ * identifiers (no dots/dashes). Re-exported from the shared input contract
+ * (`src/execution/input-contract.ts`'s `INPUT_NAME_PATTERN`) so task source
+ * v4's `inputs:` declarations share the exact same name pattern rather than a
+ * second, hand-maintained copy (P2a, D3-N1).
  */
-export const PROGRAM_PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export { INPUT_NAME_PATTERN as PROGRAM_PARAM_NAME_PATTERN } from "../../execution/input-contract.js";
 /**
  * The ONE structural projection of an exec spec — ONE encoding per state.
  *

package/dist/workflows/resource-limits.js

@@ -15,6 +15,8 @@ export const WORKFLOW_MAX_JSON_DEPTH = 64;
 export const WORKFLOW_MAX_MAP_EXPANSION = 10_000;
 /** Max declared `inputs:` reference strings on one unit/map step. */
 export const WORKFLOW_MAX_INPUTS = 64;
+/** Max declared `outputs:` entries on one workflow document (P3b, spec §4.1). */
+export const WORKFLOW_MAX_OUTPUTS = 64;
 // ── Dispatch-significant bounds shared across validation layers ──────────────
 //
 // Defined ONCE here so the three enforcement layers cannot drift:
@@ -201,3 +203,21 @@ export function utf8Bytes(value) {
 export function jsonBytes(value) {
     return utf8Bytes(JSON.stringify(value));
 }
+// ── Recursive child-workflow composition bounds (spec docs/plans/specs/
+// ── p3a-plan-v5-child-freeze.md §4.5, A-N6) ──────────────────────────────────
+//
+// Enforced ONCE, at freeze, before publication, in
+// `src/workflows/freeze/targets/child-workflow.ts` — the ONE resolver both the
+// direct `uses: workflows/<ref>` form and the task-wrapped form route through
+// — and re-enforced as a corruption gate whenever a parent plan is DECODED
+// (`src/workflows/ir/schema-v4.ts`'s recursive `decodeChildWorkflowTarget`).
+// Full design history, including the rejected alternative for the byte cap:
+// docs/architecture/decisions/0007-workflow-composition-bounds.md.
+/** Max workflow composition depth (root = depth 0; a 9th descendant level fails). */
+export const WORKFLOW_MAX_COMPOSITION_DEPTH = 8;
+/**
+ * Max AGGREGATE canonical-JSON bytes of every embedded child plan in ONE root
+ * freeze (the sum across the whole composition tree, not per child).
+ * Deliberately HALF of {@link WORKFLOW_MAX_PLAN_BYTES} — see ADR 0007.
+ */
+export const WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES = 1024 * 1024;

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

@@ -3,7 +3,7 @@
 // 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_V4_VERSION } from "../ir/schema-v4.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)";
@@ -16,14 +16,19 @@ export function classifyWorkflowRunPlan(row) {
     }
     if (row.plan_ir_version !== null &&
         row.plan_ir_version !== undefined &&
-        row.plan_ir_version !== WORKFLOW_IR_V4_VERSION) {
+        row.plan_ir_version !== WORKFLOW_IR_V5_VERSION) {
         return {
             support: "unsupported-version",
             irVersion: row.plan_ir_version,
-            error: `Workflow run ${runId} uses unsupported workflow IR version ${row.plan_ir_version}; this runtime supports only workflow IR version 4. Start a new run from the authored workflow.`,
+            // §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.
+            error: `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. Complete them before upgrading, 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.`,
         };
     }
-    if (row.plan_ir_version !== WORKFLOW_IR_V4_VERSION) {
+    if (row.plan_ir_version !== WORKFLOW_IR_V5_VERSION) {
         return {
             support: "corrupt-plan",
             irVersion: null,
@@ -45,11 +50,20 @@ export function classifyWorkflowRunPlan(row) {
         };
     }
 }
-/** Reject any operation that requires a valid current frozen plan. */
+/**
+ * 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. */
@@ -108,8 +122,11 @@ export function assertWorkflowSpineMatchesPlan(plan, run, rows) {
     }
     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"))
+        // 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") {