akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/workflows/freeze/environment.js

@@ -0,0 +1,174 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+import { loadAdapterExecutionSource } from "../../commands/command/execution-source-loader.js";
+import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { parseEnvRef } from "../../core/env-secret-ref.js";
+import { UsageError } from "../../core/errors.js";
+import { deriveInstallations } from "../../indexer/installations.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
+import { freezeWorkflowEnvironment } from "../ir/environment-v4.js";
+export function freezeEnvironment(source, exec, context) {
+    const literals = Object.entries(source.env ?? {}).map(([name, value]) => Object.freeze({ kind: "literal", name, value: String(value) }));
+    const passThrough = (exec?.passEnv ?? []).map((name) => Object.freeze({ kind: "pass-through", name }));
+    const refs = source.unit?.env ?? [];
+    const envRefs = freezeWorkflowEnvironment(refs, {
+        collector: context.collector,
+        resolveRef: (ref) => {
+            const parsedEnv = parseEnvRef(ref);
+            if (parsedEnv.type !== "env")
+                throw new UsageError(`Expected an env ref; got ${ref}.`, "WORKFLOW_SOURCE_INVALID");
+            const owned = resolveOwnedAssetSync(ref, "env", context);
+            return { ref: owned.ref, bundle: owned.bundle, adapter: owned.adapter, root: owned.root, path: owned.file };
+        },
+    });
+    return [...literals, ...passThrough, ...envRefs];
+}
+export async function guardedExecutionSource(ref, kind, context) {
+    const owned = await resolveOwnedAsset(ref, kind === "command" ? "command" : "agent", context);
+    captureOwned(owned, context.collector);
+    const options = {
+        config: context.config,
+        fileContext: () => context.collector.fileContext(owned.root, owned.file),
+    };
+    const rendered = kind === "command"
+        ? await loadAdapterExecutionSource(owned.ref, "command", options)
+        : await loadAdapterExecutionSource(owned.ref, "persona", options);
+    context.collector.bindIdentity(owned.file, owned.root, rendered.identity);
+    return rendered;
+}
+export async function resolveOwnedAsset(ref, type, context) {
+    return resolveOwnedAssetCore(ref, type, context, false);
+}
+export function resolveOwnedAssetSync(ref, type, context) {
+    return resolveOwnedAssetCore(ref, type, context, true);
+}
+export function resolveOwnedAssetCore(refInput, type, context, sync) {
+    const parsed = parseBundleRef(refInput);
+    const plural = type === "env" ? "env" : `${type}s`;
+    const conceptId = parsed.conceptId.startsWith(`${plural}/`) ? parsed.conceptId : `${plural}/${parsed.conceptId}`;
+    const name = conceptId.slice(plural.length + 1);
+    const direct = parsed.bundle ? configuredOwner(parsed.bundle, context.config) : undefined;
+    const sources = resolveSourceEntries(undefined, context.config);
+    const installations = deriveInstallations(sources);
+    const candidates = direct
+        ? [direct]
+        : sources.flatMap((source, index) => {
+            const installation = installations[index];
+            if (!installation || (parsed.bundle && installation.id !== parsed.bundle))
+                return [];
+            return [
+                {
+                    bundle: installation.id,
+                    root: source.path,
+                    adapter: source.adapterId ?? installation.components[0]?.adapter ?? "akm",
+                },
+            ];
+        });
+    const findSync = () => {
+        for (const candidate of candidates) {
+            const directory = path.join(candidate.root, plural);
+            for (const extension of assetExtensions(type)) {
+                const file = path.resolve(directory, `${name}${extension}`);
+                if (fs.existsSync(file) && fs.statSync(file).isFile()) {
+                    return { ...candidate, ref: makeBundleRef(candidate.bundle, conceptId), file };
+                }
+            }
+        }
+        // P4 (docs/plans/specs/p4-deletions-closeout.md §5.2, row B-11 preservation
+        // gate): PRESERVED, not re-coded — tests/workflows/child-workflow-freeze.test.ts's
+        // "B-11: workflows/<ref> that does not resolve fails the existing
+        // asset-resolution failure, unchanged in code and shape" pins this exact
+        // code by name and by its own title. Recorded deviation from §5.2's flat
+        // "→ WORKFLOW_SOURCE_INVALID" for this file's 3 sites.
+        throw new UsageError(`Workflow source target ${refInput} was not found.`, "INVALID_FLAG_VALUE");
+    };
+    if (sync)
+        return findSync();
+    return (async () => {
+        for (const candidate of candidates) {
+            try {
+                const file = await resolveAssetPath(candidate.root, type, name);
+                return { ...candidate, ref: makeBundleRef(candidate.bundle, conceptId), file };
+            }
+            catch {
+                // Continue in installation priority order.
+            }
+        }
+        return findSync();
+    })();
+}
+export function configuredOwner(bundle, config) {
+    const entry = config.bundles?.[bundle];
+    if (!entry || typeof entry.path !== "string")
+        return undefined;
+    const components = entry.components ? Object.values(entry.components) : [];
+    const component = components[0];
+    return {
+        bundle,
+        root: path.resolve(entry.path, component?.root ?? "."),
+        adapter: component?.adapter ?? "akm",
+    };
+}
+export function assetExtensions(type) {
+    if (type === "script")
+        return [
+            "",
+            ".sh",
+            ".ts",
+            ".js",
+            ".py",
+            ".rb",
+            ".go",
+            ".pl",
+            ".php",
+            ".lua",
+            ".r",
+            ".swift",
+            ".kt",
+            ".kts",
+            ".ps1",
+            ".cmd",
+            ".bat",
+        ];
+    if (type === "env")
+        return ["", ".env"];
+    return ["", ".md", ".yml"];
+}
+export function captureOwned(owned, collector) {
+    trackAncestry(collector, owned.root, owned.file);
+    const retained = collector.capture(owned.file, owned.root, { authored: true });
+    return collector.bindIdentity(owned.file, owned.root, {
+        ref: owned.ref,
+        bundle: owned.bundle,
+        adapter: owned.adapter,
+        file: retained.relativePath,
+        hash: retained.sha256,
+    });
+}
+export function trackAncestry(collector, rootInput, file) {
+    const root = path.resolve(rootInput);
+    collector.trackDirectory(root, root);
+    const relative = path.relative(root, path.dirname(file));
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new UsageError(`${file} resolves outside its owning root.`, "PATH_ESCAPE_VIOLATION");
+    }
+    let current = root;
+    for (const segment of relative === "" ? [] : relative.split(path.sep)) {
+        current = path.join(current, segment);
+        collector.trackDirectory(current, root);
+    }
+}
+export function qualifyRef(ref, plural, asset, config) {
+    const parsed = parseBundleRef(ref);
+    if (parsed.bundle)
+        return ref;
+    const bundle = parseBundleRef(asset.ref).bundle ?? config.defaultBundle;
+    if (!bundle)
+        throw new UsageError(`Workflow ref ${ref} has no owning bundle.`, "WORKFLOW_SOURCE_INVALID");
+    const concept = parsed.conceptId.startsWith(`${plural}/`) ? parsed.conceptId : `${plural}/${parsed.conceptId}`;
+    return makeBundleRef(bundle, concept);
+}

package/dist/workflows/freeze/identity.js

@@ -0,0 +1,22 @@
+// 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 { spawnSync } from "node:child_process";
+import { UsageError } from "../../core/errors.js";
+export function scriptExecutable(interpreter) {
+    if (interpreter === "bun" || interpreter === "bun-standalone")
+        return process.execPath;
+    if (interpreter === "kotlin")
+        return "kotlin";
+    return interpreter;
+}
+export function gitIdentity(unit, root) {
+    if (unit.isolation !== "worktree")
+        return {};
+    const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const oid = result.status === 0 ? result.stdout.trim() : "";
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(oid)) {
+        throw new UsageError(`Worktree-isolated workflow root ${root} has no immutable Git HEAD OID.`, "WORKFLOW_SOURCE_INVALID");
+    }
+    return { gitCommitOid: oid };
+}

package/dist/workflows/freeze/resolve-steps.js

@@ -0,0 +1,78 @@
+// 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 { ConfigError, UsageError } from "../../core/errors.js";
+import { prepareInlineExecution } from "../../integrations/agent/inline-execution.js";
+import { sourceStepProgramUnit, sourceStepRef } from "../source-ir/program.js";
+import { classifyWorkflowStepUses } from "../source-ir/semantics.js";
+import { qualifyRef } from "./environment.js";
+import { childWorkflowDispatch } from "./targets/child-workflow.js";
+import { commandDispatch, commandResult, inlineDispatch } from "./targets/command.js";
+import { directScript } from "./targets/script.js";
+import { directShell } from "./targets/shell.js";
+import { taskDispatch } from "./targets/task.js";
+export async function resolveStep(source, context) {
+    const baseUnit = sourceStepProgramUnit(source);
+    if (source.exec || source.run !== undefined)
+        return directShell(source, baseUnit, context);
+    if (!source.uses)
+        return inlineDispatch(source, baseUnit, context);
+    const target = classifyWorkflowStepUses(source.uses);
+    if (target.kind === "task")
+        return taskDispatch(source, baseUnit, target.ref, context);
+    // A direct `uses: workflows/<ref>` step (spec docs/plans/specs/
+    // p3a-plan-v5-child-freeze.md §4.2, row B-01/B-04). `with:` on this target
+    // IS a valid binding surface (A-N8) — unlike scripts/commands below,
+    // `rejectNonTaskBindingWith` must NOT be extended to it.
+    if (target.kind === "workflow") {
+        return childWorkflowDispatch({
+            source,
+            baseUnit,
+            childRefInput: target.ref,
+            context,
+            via: "direct",
+            authoredInputs: { kind: "with", value: source.with },
+        });
+    }
+    if (target.kind === "script") {
+        rejectNonTaskBindingWith(source, target.ref, "script");
+        return directScript(source, baseUnit, target.ref, context);
+    }
+    if (target.kind === "command" || target.kind === "builtin-command") {
+        if (target.kind === "command")
+            rejectNonTaskBindingWith(source, target.ref, "command");
+        const action = target.kind === "builtin-command"
+            ? source.with
+            : { ref: qualifyRef(target.ref, "commands", context.asset, context.config) };
+        return commandDispatch(source, baseUnit, action, context);
+    }
+    throw new UsageError(`Workflow target ${source.uses} is not executable in 0.9.2.`, "WORKFLOW_SOURCE_INVALID");
+}
+/**
+ * A-N5 (spec docs/plans/specs/p2b-input-bindings.md §1.7): `commands/<ref>`
+ * and `scripts/<ref>` are not binding surfaces — a `with:` authored on either
+ * now fails closed instead of being silently dropped (the same defect P1a
+ * closed for `tasks/<ref>`, now repeated for these two targets, B-22/B-23).
+ * `akm/command`'s `with:` is its own argument bag
+ * (`parseBuiltinCommandAction`) and never routes through here.
+ */
+function rejectNonTaskBindingWith(source, ref, kind) {
+    if (source.with === undefined)
+        return;
+    const family = kind === "command" ? "commands" : "scripts";
+    throw new UsageError(`Workflow step ${source.id} cannot pass with: to ${family} target ${ref}; a ${kind} ref is not a binding surface.`, "COMPOSITION_INVALID");
+}
+export function resolveJudge(source, context) {
+    const engine = context.config.workflow?.judgeEngine;
+    if (!engine) {
+        throw new ConfigError("This workflow declares completion criteria but no verification engine is configured. Set workflow.judgeEngine to a named LLM or agent engine.", "INVALID_CONFIG_FILE");
+    }
+    const content = source.gate?.rubric?.trim() ?? "Judge workflow completion.";
+    const prepared = prepareInlineExecution({
+        content,
+        config: context.config,
+        invocationKind: "workflow",
+        current: { engine },
+    });
+    return commandResult(source, { onError: "fail", source: sourceStepRef(source) }, prepared, context);
+}

package/dist/workflows/freeze/source-freeze.js

@@ -0,0 +1,57 @@
+// 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 { COMPOSITION_INVALID_MULTI_JOB_HINT, UsageError } from "../../core/errors.js";
+import { compileWorkflowSource } from "../source-ir/compile.js";
+import { resolveJudge, resolveStep } from "./resolve-steps.js";
+/**
+ * Resolve every authored target through the shared command/task authorities
+ * before v4 publication.
+ *
+ * `composition` and `freezeChild` (spec docs/plans/specs/
+ * p3a-plan-v5-child-freeze.md §4.1/§4.3) thread the recursive
+ * child-workflow-freeze state down into every step's `ResolutionContext`;
+ * `ir/freeze-v4.ts`'s `compileResolveFreezeWorkflowV4` is this function's
+ * ONLY caller (directly — P4 deleted the `ir/source-freeze-v4.ts` shim that
+ * used to sit on this edge) and supplies both — the root default
+ * composition, or the composition
+ * `targets/child-workflow.ts` built for a recursive child freeze.
+ */
+export async function resolveWorkflowSourceV4(asset, workflowSource, config, collector, composition, freezeChild) {
+    const compiled = compileWorkflowSource(workflowSource.content, { path: asset.path, workspaceRoot: asset.sourcePath });
+    if (!compiled.ok) {
+        // P4-N2 (docs/plans/specs/p4-deletions-closeout.md §3.3.4): a compile
+        // result whose single error is the adapter's multi-job rejection
+        // surfaces as COMPOSITION_INVALID — one authoritative composition
+        // policy; every other compile failure (a YAML syntax error, an
+        // unsupported trigger, …) is WORKFLOW_SOURCE_INVALID. Never blanket-recode.
+        const isMultiJob = compiled.errors.length === 1 && compiled.errors[0]?.code === "multi-job-unsupported";
+        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
+        throw new UsageError(`Workflow source cannot be frozen: ${compiled.errors.map((error) => error.message).join("; ")}`, code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
+    }
+    const context = { asset, config, collector, sourceIr: compiled.ir, composition, freezeChild };
+    const units = new Map();
+    const judges = new Map();
+    let engineAnnouncement;
+    const sourceSteps = compiled.ir.jobs[0]?.steps ?? [];
+    for (const sourceStep of sourceSteps) {
+        if (!sourceStep.route) {
+            const resolved = await resolveStep(sourceStep, context);
+            units.set(sourceStep.id, Object.freeze(resolved));
+            engineAnnouncement ??= resolved.engineAnnouncement;
+        }
+        if (sourceStep.gate?.rubric?.trim()) {
+            const judge = resolveJudge(sourceStep, context);
+            if (judge.target.kind !== "command")
+                throw new Error(`workflow judge ${sourceStep.id} did not resolve to a command target`);
+            judges.set(sourceStep.id, judge.target);
+            engineAnnouncement ??= judge.engineAnnouncement;
+        }
+    }
+    return Object.freeze({
+        sourceIr: compiled.ir,
+        units,
+        judges,
+        ...(engineAnnouncement ? { engineAnnouncement } : {}),
+    });
+}

package/dist/workflows/freeze/step-values.js

@@ -0,0 +1,68 @@
+// 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 { canonicalResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
+import { defaultLlmEngineConcurrency } from "../concurrency-policy.js";
+import { DEFAULT_EXEC_TIMEOUT_MS } from "../resource-limits.js";
+export function freezeExecSpec(source, exec, context) {
+    const declared = Object.hasOwn(source.unit ?? {}, "timeoutMs")
+        ? source.unit?.timeoutMs
+        : context.sourceIr.defaults && Object.hasOwn(context.sourceIr.defaults, "timeoutMs")
+            ? context.sourceIr.defaults.timeoutMs
+            : undefined;
+    return {
+        ...exec,
+        command: exec.command,
+        timeoutMs: declared === undefined ? DEFAULT_EXEC_TIMEOUT_MS : declared,
+    };
+}
+export function targetConcurrency(runner, config) {
+    if (runner.kind === "llm") {
+        const configured = typeof runner.engine === "string" ? config.engines?.[runner.engine] : undefined;
+        return defaultLlmEngineConcurrency(runner.connection.endpoint, configured?.kind === "llm" ? configured.concurrency : undefined);
+    }
+    if (runner.kind !== "sdk" || !runner.fallbackConnection)
+        return undefined;
+    const selected = typeof runner.engine === "string" ? config.engines?.[runner.engine] : undefined;
+    const fallbackName = selected?.kind === "agent" ? (selected.llmEngine ?? config.defaults?.llmEngine) : undefined;
+    const fallback = fallbackName ? config.engines?.[fallbackName] : undefined;
+    return defaultLlmEngineConcurrency(runner.fallbackConnection.endpoint, fallback?.kind === "llm" ? fallback.concurrency : undefined);
+}
+export function durableRequest(request) {
+    const wire = JSON.parse(canonicalResolvedExecutionRequest(request));
+    const runtime = { ...wire.runtime };
+    delete runtime.environment;
+    wire.runtime = runtime;
+    return decodeResolvedExecutionRequest(wire);
+}
+export function executionValues(source, workspace) {
+    return executionUnitValues(source.unit, workspace);
+}
+export function executionUnitValues(unit, workspace) {
+    return Object.freeze({
+        ...(unit && Object.hasOwn(unit, "engine") ? { engine: unit.engine } : {}),
+        ...(unit && Object.hasOwn(unit, "model") ? { model: unit.model } : {}),
+        ...(unit && Object.hasOwn(unit, "llm") ? { inference: unit.llm } : {}),
+        ...(unit && Object.hasOwn(unit, "timeoutMs") ? { timeout: unit.timeoutMs } : {}),
+        ...(unit && "output" in unit && Object.hasOwn(unit, "output") ? { outputSchema: unit.output } : {}),
+        workspace,
+    });
+}
+/**
+ * Step ids that appear BEFORE `stepId` in the frozen step order (A-N4) — the
+ * SAME ordering map.over/inputs[] rely on. Shared by `targets/task.ts` (a
+ * step's own `with:` against its composed task's declared `inputs:`) and
+ * `targets/child-workflow.ts` (the SAME step's effective inputs, re-bound
+ * against a composed child workflow's declared `params:`, spec A-N8) — moved
+ * here rather than duplicated so both can import it without either importing
+ * the other.
+ */
+export function earlierStepIds(sourceIr, stepId) {
+    const steps = sourceIr.jobs[0]?.steps ?? [];
+    const index = steps.findIndex((step) => step.id === stepId);
+    return new Set(index < 0 ? [] : steps.slice(0, index).map((step) => step.id));
+}
+/** THIS workflow's own declared param names (A-N4) — never an outer composing task's. See {@link earlierStepIds}. */
+export function declaredParamNames(sourceIr) {
+    return new Set(sourceIr.params ? Object.keys(sourceIr.params) : []);
+}

package/dist/workflows/freeze/targets/child-workflow.js

@@ -0,0 +1,206 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The ONE recursive child-workflow resolver (spec docs/plans/specs/
+ * p3a-plan-v5-child-freeze.md §4). BOTH composition forms lower here:
+ *
+ *  - a direct step `uses: workflows/<ref>` (`resolve-steps.ts`'s
+ *    `resolveStep`, `via: "direct"`);
+ *  - a task-wrapped workflow target — a `uses: tasks/<ref>` step whose task's
+ *    OWN target is a workflow (`targets/task.ts`'s `taskDispatch`,
+ *    `via: "task"`).
+ *
+ * `childWorkflowDispatch` resolves and qualifies the child ref, enforces the
+ * three composition bounds (depth, cycle, aggregate embedded bytes — all
+ * FREEZE-time, before publication, `COMPOSITION_INVALID`), recursively
+ * freezes the child COMPLETELY through the injected `ResolutionContext.freezeChild`
+ * (never a direct import of `compileResolveFreezeWorkflowV4` —
+ * `freeze/step-values.ts`'s `ChildCompositionContext` doc explains why: this
+ * module is downstream of `ir/freeze-v4.ts`, so importing back from it would
+ * close a static cycle), absorbs the child's own fresh source collector into
+ * the parent's (A-N7), binds the composing step's effective inputs against
+ * the child's declared `params:` (A-N8 — see `AuthoredChildInputs` below for
+ * the two ways that mapping arrives), and returns the standard
+ * `ResolvedDispatch` envelope carrying a `FrozenChildWorkflowTarget`
+ * (`ir/schema-v4.ts`).
+ */
+import { createHash } from "node:crypto";
+import { parseBundleRef } from "../../../core/asset/asset-ref.js";
+import { UsageError } from "../../../core/errors.js";
+import { GuardedExecutionSourceCollector } from "../../../execution/guarded-source.js";
+import { workflowParamContract } from "../../ir/params.js";
+import { canonicalJson, canonicalPlanJson } from "../../ir/plan-hash.js";
+import { utf8Bytes, WORKFLOW_MAX_COMPOSITION_DEPTH, WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES, } from "../../resource-limits.js";
+import { loadWorkflowAsset } from "../../runtime/workflow-asset-loader.js";
+import { resolveOwnedAsset } from "../environment.js";
+import { declaredParamNames, earlierStepIds } from "../step-values.js";
+import { freezeTaskInputBindings, rebindTaskInputBindings } from "../task-bindings.js";
+/** §3.5's exact `contentHash` formula — mirrors `ir/schema-v4.ts`'s private decode-side `childWorkflowContentHash` byte-for-byte (the decoder re-verifies what this produces); duplicated rather than imported so this freeze-side module needs no edit to Lane A's already-landed decoder file. */
+function childWorkflowContentHash(fields) {
+    return createHash("sha256")
+        .update("akm.workflow.child-workflow\0v1\0")
+        .update(canonicalJson({
+        ref: fields.ref,
+        planHash: fields.planHash,
+        via: fields.via,
+        taskRef: fields.taskRef ?? null,
+        inputBindings: fields.inputBindings.length > 0 ? fields.inputBindings : null,
+    }))
+        .digest("hex");
+}
+/**
+ * Code-review finding (see this file's `environment: []` return field): a
+ * step composing a child workflow has no path to honor its own authored
+ * `env:` — the child run carries its own frozen environment inside its own
+ * plan, so `freezeEnvironment` (the ONE mechanism a step's `env:` reaches a
+ * frozen unit through, `../environment.ts`) is never called for this
+ * target. Leaving that silent would repeat exactly the defect A-N5 already
+ * closed for `with:` on a non-binding surface — an authored construct that
+ * cannot be honored on this composing target now rejects instead of
+ * vanishing. Checks BOTH shapes a step's `env:` can take (`../environment.ts`'s
+ * `freezeEnvironment`): literal `env:` values and `unit: {env: [...]}` refs.
+ * An absent/empty `env:` is not authored and stays valid.
+ */
+function assertNoStepEnvironment(stepId, childRef, source) {
+    const hasLiteralEnv = Object.keys(source.env ?? {}).length > 0;
+    const hasEnvRefs = (source.unit?.env ?? []).length > 0;
+    if (!hasLiteralEnv && !hasEnvRefs)
+        return;
+    throw new UsageError(`Workflow step ${stepId} cannot pass env: while composing ${childRef}: a child run carries its own frozen ` +
+        `environment inside its own plan, so a parent-level env: on the composing step cannot be honored. Remove ` +
+        `env: from this step, or move it into ${childRef}'s own source.`, "COMPOSITION_INVALID", "Remove the env: (or unit: env:) block from this step, or set those variables inside the child workflow's " +
+        "own source — a composing step's environment is never delivered into a child run.");
+}
+/** A workflow entry of a composition `refPath` — the only entries a cycle can close through (§4.5: a task target can never itself be a task, so no task->task chain exists to close one). */
+function isWorkflowRef(ref) {
+    try {
+        return parseBundleRef(ref).conceptId.startsWith("workflows/");
+    }
+    catch {
+        return false;
+    }
+}
+function compositionPath(refPath, childRef) {
+    return [...refPath, childRef].join(" -> ");
+}
+function assertNoCompositionCycle(stepId, childRef, refPath) {
+    if (!refPath.filter(isWorkflowRef).includes(childRef))
+        return;
+    throw new UsageError(`Workflow step ${stepId} cannot compose ${childRef}: that would create a composition cycle. ` +
+        `Path: ${compositionPath(refPath, childRef)}.`, "COMPOSITION_INVALID", "Break the cycle: remove or redirect one of the compositions in the path above so no workflow ends up " +
+        "composing itself, directly or through intermediates.");
+}
+function assertCompositionDepthAllowed(stepId, childRef, childDepth, refPath) {
+    if (childDepth <= WORKFLOW_MAX_COMPOSITION_DEPTH)
+        return;
+    throw new UsageError(`Workflow step ${stepId} cannot compose ${childRef}: workflow composition is limited to ` +
+        `${WORKFLOW_MAX_COMPOSITION_DEPTH} levels. Path: ${compositionPath(refPath, childRef)}.`, "COMPOSITION_INVALID", `Flatten the composition chain to ${WORKFLOW_MAX_COMPOSITION_DEPTH} levels or fewer — inline one of the ` +
+        "intermediate workflows, or restructure the chain so fewer child compositions are nested.");
+}
+/**
+ * Add the child's embedded plan bytes to the shared, tree-wide budget
+ * (A-N6) and fail before publication if the AGGREGATE crosses the cap.
+ * Mutates `budget` only on success — a rejected step leaves the running
+ * total exactly as it was, matching every other freeze-time failure's
+ * no-partial-effect shape.
+ */
+function chargeEmbeddedBudget(stepId, childRef, childPlanBytes, budget) {
+    const projected = budget.embeddedBytes + childPlanBytes;
+    if (projected > WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES) {
+        throw new UsageError(`Workflow step ${stepId} cannot compose ${childRef}: the embedded child plans would total ${projected} ` +
+            `bytes, over the ${WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES}-byte limit for one workflow run.`, "COMPOSITION_INVALID", "Reduce the number or size of workflows composed into this run — split the work across separate " +
+            "top-level runs, or trim the composed children's own plans.");
+    }
+    budget.embeddedBytes = projected;
+}
+export async function childWorkflowDispatch(input) {
+    const { source, baseUnit, childRefInput, context, via, taskRef, authoredInputs } = input;
+    // §4.2 step 1: resolve + qualify. Resolution failures propagate unchanged,
+    // in code and shape (row B-11) — the same authority every other
+    // composition target (command/script/task) already resolves through.
+    const owned = await resolveOwnedAsset(childRefInput, "workflow", context);
+    const childAsset = await loadWorkflowAsset(owned.ref);
+    const childRef = childAsset.ref;
+    // Code-review finding: an authored env: on the composing step has no
+    // path to reach the child run and must reject, not vanish (see
+    // assertNoStepEnvironment's doc comment).
+    assertNoStepEnvironment(source.id, childRef, source);
+    // §4.2 steps 2-3: the composition bounds, before any child compilation.
+    assertNoCompositionCycle(source.id, childRef, context.composition.refPath);
+    const childDepth = context.composition.depth + 1;
+    assertCompositionDepthAllowed(source.id, childRef, childDepth, context.composition.refPath);
+    // §4.2 step 4: freeze the child COMPLETELY (compile -> validate -> freeze),
+    // with its OWN fresh collector (A-N7) so its plan is a pure function of its
+    // own source, and the SAME mutable budget object so the aggregate bound
+    // sees every descendant across the whole tree.
+    const childRefPath = via === "task" && taskRef !== undefined
+        ? [...context.composition.refPath, taskRef, childRef]
+        : [...context.composition.refPath, childRef];
+    const child = await context.freezeChild({
+        asset: childAsset,
+        sourceCollector: new GuardedExecutionSourceCollector(),
+        composition: { depth: childDepth, refPath: childRefPath, budget: context.composition.budget },
+    });
+    // The embedded `frozenPlan` must be a PLAIN, symbol-free JSON structure —
+    // exactly the shape `decodeWorkflowPlanV4` will (recursively) re-verify it
+    // as, both right now (the PARENT's own top-level `decodeWorkflowPlanV4`
+    // call in `ir/freeze-v4.ts` walks straight into this target) and later,
+    // read back from a stored run's `plan_json`. `child.plan` — the in-memory
+    // result of the child's OWN already-decoded freeze — carries internal
+    // resolved-request construction brands (`execution/resolved-request.ts`)
+    // that `decodeResolvedExecutionRequest` deliberately rejects on ANY
+    // "fresh rehydrate" input; round-tripping through canonical JSON strips
+    // them, the same way persisting and re-reading `plan_json` naturally would.
+    const embeddedPlanJson = canonicalPlanJson(child.plan);
+    const frozenPlan = JSON.parse(embeddedPlanJson);
+    // §4.2 step 5.
+    chargeEmbeddedBudget(source.id, childRef, utf8Bytes(embeddedPlanJson), context.composition.budget);
+    // §4.2 step 6 (A-N7): absorb the child's captured sources so the parent's
+    // final pre-publication CAS (`revalidate()`) covers every child file too.
+    context.collector.absorb(child.sourceCollector);
+    // §4.2 step 7 (A-N8): bind the composing step's effective inputs against
+    // the child's declared params:. A genuinely authored `with:` goes through
+    // the SAME normalizer every other binding surface uses; an
+    // already-classified binding set (a v4 task's effective inputs) is
+    // RE-bound instead, never round-tripped back through the `with:` grammar
+    // (code-review finding — see AuthoredChildInputs above).
+    const inputBindings = authoredInputs.kind === "bindings"
+        ? rebindTaskInputBindings({
+            stepId: source.id,
+            targetRef: childRef,
+            bindings: authoredInputs.value,
+            contract: workflowParamContract(frozenPlan),
+        })
+        : freezeTaskInputBindings({
+            stepId: source.id,
+            targetRef: childRef,
+            with: authoredInputs.value,
+            contract: workflowParamContract(frozenPlan),
+            earlierStepIds: earlierStepIds(context.sourceIr, source.id),
+            declaredParamNames: declaredParamNames(context.sourceIr),
+        });
+    // §4.2 step 8: build the frozen target.
+    const planHash = createHash("sha256").update(embeddedPlanJson).digest("hex");
+    const contentHash = childWorkflowContentHash({ ref: childRef, planHash, via, taskRef, inputBindings });
+    const target = Object.freeze({
+        kind: "child-workflow",
+        ref: childRef,
+        planHash,
+        frozenPlan,
+        contentHash,
+        via,
+        ...(taskRef !== undefined ? { taskRef } : {}),
+        ...(inputBindings.length > 0 ? { inputBindings } : {}),
+    });
+    return {
+        target,
+        // A child run carries its own frozen environment inside its own plan.
+        // A composing step's own env: cannot reach it, so assertNoStepEnvironment
+        // above rejects one instead of it silently vanishing here (§4.2 step 8).
+        environment: [],
+        unit: baseUnit,
+        instructions: source.instructions ??
+            (via === "task" && taskRef !== undefined ? `Run task ${taskRef}.` : `Run workflow ${childRef}.`),
+    };
+}