akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/workflows/freeze/targets/command.js

@@ -0,0 +1,81 @@
+// 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 { createHash } from "node:crypto";
+import { prepareCommandInvocation } from "../../../commands/command/command-execution.js";
+import { captureFrozenDirectoryIdentity } from "../../../execution/directory-identity.js";
+import { freezeExecutableIdentity } from "../../../execution/executable-identity.js";
+import { canonicalResolvedExecutionRequest, } from "../../../execution/resolved-request.js";
+import { fallbackAnnouncement } from "../../../integrations/agent/engine-fallback.js";
+import { requireAuthorizedExecutionPlan } from "../../../integrations/agent/execution-cascade.js";
+import { lowerResolvedExecutionRequest } from "../../../integrations/agent/execution-lowering.js";
+import { prepareInlineExecution } from "../../../integrations/agent/inline-execution.js";
+import { freezeEnvironment, guardedExecutionSource } from "../environment.js";
+import { gitIdentity } from "../identity.js";
+import { durableRequest, executionUnitValues, executionValues, targetConcurrency, } from "../step-values.js";
+export async function commandDispatch(source, baseUnit, action, context) {
+    const prepared = await prepareCommandInvocation({
+        action,
+        config: context.config,
+        invocationKind: "workflow",
+        ...(context.sourceIr.defaults
+            ? { invocationDefaults: executionUnitValues(context.sourceIr.defaults, context.asset.sourcePath) }
+            : {}),
+        ...(source.commandMode === "literal" ? { inlineContentMode: "literal" } : {}),
+        current: executionValues(source, context.asset.sourcePath),
+        sourceLoader: (ref, kind) => guardedExecutionSource(ref, kind, context),
+    });
+    return commandResult(source, baseUnit, prepared, context);
+}
+export function inlineDispatch(source, baseUnit, context) {
+    const content = source.instructions ?? `Execute workflow step ${source.id}.`;
+    const prepared = prepareInlineExecution({
+        content,
+        config: context.config,
+        invocationKind: "workflow",
+        ...(context.sourceIr.defaults
+            ? { invocationDefaults: executionUnitValues(context.sourceIr.defaults, context.asset.sourcePath) }
+            : {}),
+        current: executionValues(source, context.asset.sourcePath),
+    });
+    return commandResult(source, baseUnit, prepared, context);
+}
+export function commandResult(source, baseUnit, prepared, context, literals = []) {
+    const request = durableRequest(requireAuthorizedExecutionPlan(prepared.plan));
+    const lowered = lowerResolvedExecutionRequest(request, prepared.config);
+    const cwdIdentity = captureFrozenDirectoryIdentity(context.asset.sourcePath);
+    let runner = lowered.runner;
+    let executable;
+    if (runner.kind === "agent") {
+        executable = freezeExecutableIdentity(runner.profile.bin, { cwd: cwdIdentity.realCwd });
+        runner = Object.freeze({ ...runner, profile: Object.freeze({ ...runner.profile, bin: executable.absolutePath }) });
+    }
+    const unit = {
+        ...baseUnit,
+        engine: request.engine.name,
+        ...(request.model ? { model: request.model.resolved } : {}),
+        ...(Object.hasOwn(request.runtime, "timeoutMs") ? { timeoutMs: request.runtime.timeoutMs } : {}),
+        ...(request.inference ? { llm: request.inference } : {}),
+        ...(request.outputSchema ? { output: request.outputSchema } : {}),
+    };
+    const environment = Object.freeze([...literals, ...freezeEnvironment(source, undefined, context)]);
+    const target = Object.freeze({
+        kind: "command",
+        ref: request.command.source?.ref ?? null,
+        contentHash: createHash("sha256").update(request.command.content).digest("hex"),
+        request: JSON.parse(canonicalResolvedExecutionRequest(request)),
+        runner,
+        ...(targetConcurrency(runner, context.config) ? { concurrency: targetConcurrency(runner, context.config) } : {}),
+        cwdIdentity,
+        ...(executable ? { executable } : {}),
+        ...gitIdentity(baseUnit, cwdIdentity.realRoot),
+    });
+    const engineAnnouncement = fallbackAnnouncement(prepared.fallbackEngineName, request.engine.name);
+    return {
+        target,
+        environment,
+        unit,
+        instructions: request.command.content,
+        ...(engineAnnouncement ? { engineAnnouncement } : {}),
+    };
+}

package/dist/workflows/freeze/targets/script.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 { freezeExecutableIdentity } from "../../../execution/executable-identity.js";
+import { prepareScriptTarget } from "../../../tasks/prepare/prepare-script-target.js";
+import { captureOwned, freezeEnvironment, resolveOwnedAsset } from "../environment.js";
+import { gitIdentity, scriptExecutable } from "../identity.js";
+import { freezeExecSpec } from "../step-values.js";
+export async function directScript(source, baseUnit, refInput, context) {
+    const owned = await resolveOwnedAsset(refInput, "script", context);
+    captureOwned(owned, context.collector);
+    // Typed preparer (P1b spec §4.3) — no synthetic task YAML, no parseTaskV3Yaml
+    // call, no fabricated schedule/filePath/taskId/taskRef. The script's own
+    // owned identity (ref/file/bundleRoot) is all prepareScriptTarget needs.
+    const captured = prepareScriptTarget({
+        ref: owned.ref,
+        file: owned.file,
+        bundleRoot: owned.root,
+        readFile: () => context.collector.readBytes(owned.file, owned.root),
+    });
+    return scriptResult(source, baseUnit, {
+        sourceRef: captured.ref,
+        interpreter: captured.interpreter,
+        extension: captured.extension,
+        bytesBase64: captured.bytesBase64,
+        byteLength: captured.byteLength,
+        sha256: captured.sha256,
+        cwdIdentity: captured.cwdIdentity,
+    }, context, []);
+}
+export function scriptResult(source, baseUnit, prepared, context, literals) {
+    const requestedExecutable = scriptExecutable(prepared.interpreter);
+    const executable = freezeExecutableIdentity(requestedExecutable, { cwd: prepared.cwdIdentity.realCwd });
+    const authoredExec = { command: [executable.absolutePath, "<frozen-script>"] };
+    const exec = freezeExecSpec(source, authoredExec, context);
+    const environment = Object.freeze([...literals, ...freezeEnvironment(source, authoredExec, context)]);
+    const target = Object.freeze({
+        kind: "script",
+        ref: prepared.sourceRef,
+        contentHash: prepared.sha256,
+        exec,
+        interpreter: prepared.interpreter,
+        extension: prepared.extension,
+        bytesBase64: prepared.bytesBase64,
+        byteLength: prepared.byteLength,
+        cwdIdentity: prepared.cwdIdentity,
+        materialization: "ephemeral-0700-delete",
+        executable,
+        ...gitIdentity(baseUnit, prepared.cwdIdentity.realRoot),
+    });
+    return {
+        target,
+        environment,
+        unit: { ...baseUnit, exec: authoredExec },
+        instructions: source.instructions ?? `Run script ${prepared.sourceRef}.`,
+    };
+}

package/dist/workflows/freeze/targets/shell.js

@@ -0,0 +1,31 @@
+// 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 { captureFrozenDirectoryIdentity } from "../../../execution/directory-identity.js";
+import { freezeExecutableIdentity } from "../../../execution/executable-identity.js";
+import { freezeEnvironment } from "../environment.js";
+import { gitIdentity } from "../identity.js";
+import { freezeExecSpec } from "../step-values.js";
+export function directShell(source, baseUnit, context) {
+    const authoredExec = baseUnit.exec;
+    if (!authoredExec)
+        throw new Error(`workflow shell step ${source.id} lost its source-IR execution spec`);
+    const exec = freezeExecSpec(source, authoredExec, context);
+    const cwdIdentity = captureFrozenDirectoryIdentity(context.asset.sourcePath, authoredExec.cwd);
+    const executable = freezeExecutableIdentity(authoredExec.command[0], { cwd: cwdIdentity.realCwd });
+    const environment = Object.freeze(freezeEnvironment(source, authoredExec, context));
+    const target = Object.freeze({
+        kind: "shell",
+        contentHash: "",
+        exec,
+        cwdIdentity,
+        executable,
+        ...gitIdentity(baseUnit, cwdIdentity.realRoot),
+    });
+    return {
+        target,
+        environment,
+        unit: { ...baseUnit, exec },
+        instructions: source.instructions ?? `Run ${source.run ?? authoredExec.command.join(" ")}.`,
+    };
+}

package/dist/workflows/freeze/targets/task.js

@@ -0,0 +1,179 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import path from "node:path";
+import { parseBundleRef } from "../../../core/asset/asset-ref.js";
+import { UsageError } from "../../../core/errors.js";
+import { freezeExecutableIdentity } from "../../../execution/executable-identity.js";
+import { prepareTaskV3Execution } from "../../../tasks/prepare/prepare.js";
+import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
+import { projectTaskSourceV4 } from "../../../tasks/source/project-v4.js";
+import { workflowShellCommand } from "../../source-ir/program.js";
+import { captureOwned, freezeEnvironment, guardedExecutionSource, resolveOwnedAsset } from "../environment.js";
+import { gitIdentity } from "../identity.js";
+import { declaredParamNames, earlierStepIds, freezeExecSpec, } from "../step-values.js";
+import { freezeTaskInputBindings } from "../task-bindings.js";
+import { childWorkflowDispatch } from "./child-workflow.js";
+import { commandResult } from "./command.js";
+import { scriptResult } from "./script.js";
+/** The one message shared by every "cannot prove this is a valid binding surface" rejection (A-N5). */
+function noDeclaredInputsError(stepId, ref) {
+    return new UsageError(`Workflow step ${stepId} cannot pass with: to task target ${ref}; ${ref} declares no inputs.`, "COMPOSITION_INVALID");
+}
+/**
+ * A-N6 (spec docs/plans/specs/p2b-input-bindings.md §1.7): LC-N1's
+ * peek-and-throw (p2a §1.5) is GONE — a version: 4 target now composes.
+ * `parseTaskSource` parses the YAML ONCE and routes on the SAME {root,
+ * lineAt} the v3 arm always used, so a v3 composition stays byte-identical
+ * (B-07, B-08). `contract` is undefined for a v3 task (which can never
+ * declare `inputs:`, P2a §1.2 D2) or a v4 task with no `inputs:` key at all —
+ * either way, "no declared inputs" (A-N5).
+ *
+ * RECORDED TENSION (spec §0, Review log): A-N5's "no declared inputs"
+ * rejection is reasoned from the target's PARSED `inputs:` contract, which
+ * needs the target to resolve — yet `tests/workflows/with-rejection.test.ts`
+ * B-02b pins `COMPOSITION_INVALID` (not an asset-resolution error) for an
+ * UNRESOLVABLE task ref with an authored `with:`. Reconciled here: an
+ * authored `with:` whose target cannot even be resolved/parsed "cannot be
+ * proven a valid binding surface", so it is refused the same
+ * no-declared-inputs way — a `with:`-free step's resolution failure is
+ * untouched and propagates as before.
+ *
+ * Code-review finding: that reconciliation must stay scoped to ASSET
+ * resolution (`resolveOwnedAsset`/`captureOwned`) only. Once the target
+ * resolves to a real file, `parseTaskSource`/`projectTaskSourceV4` reports a
+ * genuine, path-and-line-anchored defect in the composed task's OWN source
+ * (e.g. `TASK_SOURCE_INVALID` for an unsupported `inputs.<name>` field) —
+ * that is never "cannot be proven a valid binding surface" and must not be
+ * repainted as `noDeclaredInputsError`. Parsing therefore happens OUTSIDE
+ * the try/catch below, so its errors propagate unchanged regardless of
+ * whether this step authored a `with:`.
+ */
+async function resolveTaskForComposition(source, refInput, context) {
+    const { owned, retained } = await resolveAndCaptureTaskAsset(source, refInput, context);
+    const parsed = parseTaskSource({ yaml: retained.content, filePath: owned.file, workspaceRoot: owned.root });
+    const contract = parsed.v4.inputs;
+    const task = projectTaskSourceV4(parsed.v4);
+    return { owned, task, contract };
+}
+/** The asset-resolution-only half of {@link resolveTaskForComposition} — the sole failure mode an authored `with:` on an unresolvable ref may repaint as `noDeclaredInputsError` (A-N5's `with-rejection.test.ts` B-02b). */
+async function resolveAndCaptureTaskAsset(source, refInput, context) {
+    try {
+        const owned = await resolveOwnedAsset(refInput, "task", context);
+        const retained = captureOwned(owned, context.collector);
+        return { owned, retained };
+    }
+    catch (cause) {
+        if (source.with !== undefined)
+            throw noDeclaredInputsError(source.id, refInput);
+        throw cause;
+    }
+}
+export async function taskDispatch(source, baseUnit, refInput, context) {
+    const { owned, task, contract } = await resolveTaskForComposition(source, refInput, context);
+    // A-N5: a with: on a target that declares no inputs: at all is
+    // COMPOSITION_INVALID. Fires on ANY authored with: shape, including `{}`
+    // (the check is `!== undefined`, not "non-empty").
+    if (source.with !== undefined && contract === undefined) {
+        throw noDeclaredInputsError(source.id, refInput);
+    }
+    // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §4.2, row B-12): a task
+    // whose OWN target is `uses: workflows/<ref>` used to fast-fail here,
+    // before ever calling prepareTaskV3Execution. That rejection is REMOVED —
+    // flow continues to the bindings computation and the prepare call exactly
+    // as for any other task target, and `prepared.kind === "workflow"` below
+    // routes to the ONE child-workflow resolver instead.
+    // Lane A2 (§3.2-§3.5): normalize THIS step's own with: against THIS task's
+    // OWN declared inputs — no merge across a composition chain (B-29). A task
+    // with no inputs: has contract === undefined, so an empty {} contract is
+    // used; freezeTaskInputBindings then produces no bindings for it (there is
+    // nothing to bind, and the COMPOSITION_INVALID check above already fired
+    // for any authored with:).
+    const bindings = freezeTaskInputBindings({
+        stepId: source.id,
+        targetRef: refInput,
+        with: source.with,
+        contract: contract ?? {},
+        earlierStepIds: earlierStepIds(context.sourceIr, source.id),
+        declaredParamNames: declaredParamNames(context.sourceIr),
+    });
+    const prepared = await prepareTaskV3Execution(task, {
+        taskId: parseBundleRef(owned.ref).conceptId.slice("tasks/".length),
+        taskRef: owned.ref,
+        bundleName: owned.bundle,
+        bundleRoot: owned.root,
+        config: context.config,
+        commandSourceLoader: (ref, kind) => guardedExecutionSource(ref, kind, context),
+        resolveAsset: async ({ ref, type }) => {
+            const target = await resolveOwnedAsset(ref, type, context);
+            captureOwned(target, context.collector);
+            return { file: target.file, bundleRoot: target.root };
+        },
+        readFile: (file, root = owned.root) => context.collector.readBytes(file, root),
+    });
+    if (prepared.kind === "workflow") {
+        // P3a (spec §4.2, rows B-12/B-13): routes to the ONE child-workflow
+        // resolver instead of rejecting. `prepared.ref`/`prepared.taskRef` are
+        // already qualified (§4.2 step 1 re-resolves and re-canonicalizes them
+        // regardless). Always hands over the bindings just computed above — this
+        // task's OWN effective inputs, already classified once against its own
+        // contract — to be RE-bound against the child's declared `params:`
+        // (never round-tripped through the `with:` grammar: doing so would let a
+        // literal value shaped like `{from: ...}` be silently reinterpreted as a
+        // reference, code-review finding). Task source v4 rejects `with:` on any
+        // target but `uses: akm/command` (row B-28), so a workflow-target task
+        // can no longer author `with:` at all — the `{kind:"with"}` arm this
+        // ternary used to reach for a v3 task, or a v4 task with no `inputs:`,
+        // is unreachable from here and deleted (P4 §3.2.7, row B-30).
+        // `AuthoredChildInputs`'s `{kind:"with"}` member itself stays — the
+        // DIRECT composition path (`resolve-steps.ts`) still produces it.
+        return childWorkflowDispatch({
+            source,
+            baseUnit,
+            childRefInput: prepared.ref,
+            context,
+            via: "task",
+            taskRef: prepared.taskRef,
+            authoredInputs: { kind: "bindings", value: bindings },
+        });
+    }
+    const taskLiterals = Object.entries(prepared.environment).map(([name, value]) => Object.freeze({ kind: "literal", name, value }));
+    if (prepared.kind === "command") {
+        return withInputBindings(commandResult(source, baseUnit, prepared.invocation, context, taskLiterals), bindings);
+    }
+    if (prepared.kind === "shell") {
+        const authoredExec = {
+            command: workflowShellCommand(prepared.shell, prepared.command),
+            ...(prepared.cwdIdentity.realCwd !== prepared.cwdIdentity.realRoot
+                ? { cwd: path.relative(prepared.cwdIdentity.realRoot, prepared.cwdIdentity.realCwd) }
+                : {}),
+        };
+        const exec = freezeExecSpec(source, authoredExec, context);
+        const environment = Object.freeze([...taskLiterals, ...freezeEnvironment(source, authoredExec, context)]);
+        const executable = freezeExecutableIdentity(exec.command[0], { cwd: prepared.cwdIdentity.realCwd });
+        const target = Object.freeze({
+            kind: "shell",
+            contentHash: "",
+            exec,
+            cwdIdentity: prepared.cwdIdentity,
+            executable,
+            ...gitIdentity(baseUnit, prepared.cwdIdentity.realRoot),
+        });
+        return withInputBindings({
+            target,
+            environment,
+            unit: { ...baseUnit, exec: authoredExec },
+            instructions: source.instructions ?? `Run task ${owned.ref}.`,
+        }, bindings);
+    }
+    return withInputBindings(scriptResult(source, baseUnit, prepared, context, taskLiterals), bindings);
+}
+/** Attach the frozen inputBindings (A-N7) to whichever target shape taskDispatch produced. Absent, never [], when empty. */
+function withInputBindings(resolved, bindings) {
+    if (bindings.length === 0)
+        return resolved;
+    return {
+        ...resolved,
+        target: Object.freeze({ ...resolved.target, inputBindings: bindings }),
+    };
+}

package/dist/workflows/freeze/task-bindings.js

@@ -0,0 +1,180 @@
+// 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 pure `with:` -> `TaskInputBinding[]` normalizer, plus the pure
+ * re-binder a recursive composition needs on top of it.
+ * {@link freezeTaskInputBindings} classifies a genuinely AUTHORED `with:`
+ * record against a contract (called by `freeze/targets/task.ts`'s
+ * `taskDispatch`, this step's own `with:` against the composed task's own
+ * contract only — no merge across a composition chain).
+ * {@link rebindTaskInputBindings} instead re-binds an ALREADY-classified
+ * `TaskInputBinding[]` by name against a DIFFERENT contract, trusting each
+ * entry's existing `kind` rather than re-deriving it from the value's shape
+ * (`freeze/targets/child-workflow.ts`'s only caller). Everything decidable
+ * at FREEZE time is decided here; a reference's *resolved* value is
+ * validated PRE-ATTEMPT instead (`exec/step-work.ts`). Pure function: no IO,
+ * no config reads.
+ *
+ * See docs/architecture/decisions/0008-task-binding-normalization.md for the
+ * full design history, including why re-binding cannot reuse the
+ * shape-driven normalizer (a code-review finding).
+ */
+import { UsageError } from "../../core/errors.js";
+import { validateInputs } from "../../execution/input-contract.js";
+import { parseReference } from "../program/expressions.js";
+function inputBindingInvalid(message) {
+    return new UsageError(message, "INPUT_BINDING_INVALID");
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unknownBindingNameError(stepId, targetRef, name, declaredNames) {
+    return inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name}, which is not a declared input. ` +
+        `Declared inputs: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}.`);
+}
+/**
+ * Normalize the workflow source front end's authored `with:` record into the
+ * `TaskInputBinding[]` a task-composing step's frozen target carries (spec
+ * §3.3). Throws `UsageError`/`INPUT_BINDING_INVALID` for the first violation
+ * found — per authored entry first (B-11, B-15, B-16, B-17, B-18), then over
+ * the whole contract (B-12, B-13). The result is sorted by name; an entry
+ * exists only for a declared input with an effective value (authored
+ * literal, authored reference, or an applied default) — never for an
+ * unsupplied optional input with no default (B-20).
+ */
+export function freezeTaskInputBindings(input) {
+    const { stepId, targetRef, contract, earlierStepIds, declaredParamNames } = input;
+    const authored = input.with ?? {};
+    const declaredNames = Object.keys(contract).sort();
+    const byName = new Map();
+    for (const [name, value] of Object.entries(authored)) {
+        if (!Object.hasOwn(contract, name))
+            throw unknownBindingNameError(stepId, targetRef, name, declaredNames);
+        const declaration = contract[name];
+        if (!declaration)
+            throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name} is invalid.`);
+        byName.set(name, normalizeOneEntry(stepId, targetRef, name, value, declaration.schema, earlierStepIds, declaredParamNames));
+    }
+    return finalizeBindings(stepId, targetRef, contract, byName);
+}
+/**
+ * Re-bind an ALREADY-NORMALIZED `TaskInputBinding[]` — a v4 task's own
+ * effective inputs, classified once against the TASK's own declared
+ * `inputs:` contract by {@link freezeTaskInputBindings} — against a
+ * DIFFERENT contract (the child workflow's declared `params:`) by NAME,
+ * without re-deriving each entry's literal/reference classification from
+ * its value's shape (a code-review finding — see
+ * docs/architecture/decisions/0008-task-binding-normalization.md for why a
+ * shape-shifting round-trip through {@link normalizeOneEntry} would
+ * silently misclassify a literal value shaped like a reference).
+ *
+ * Per-entry rules, otherwise identical to {@link freezeTaskInputBindings}:
+ * an entry naming a key the new `contract` does not declare is
+ * `INPUT_BINDING_INVALID` (same message shape); a `kind: "literal"` entry
+ * keeps its value verbatim and is validated against the NEW contract's
+ * declared schema for that name; a `kind: "reference"` entry keeps its
+ * `from` verbatim (the reference target — an earlier step or declared param
+ * of the composing workflow — does not change with which contract it is
+ * bound against) and its `schema` is re-derived from the NEW contract,
+ * matching {@link normalizeOneEntry}'s existing rule that a reference
+ * binding's schema always comes from the contract it is bound against; a
+ * contract key absent from `bindings` is defaulted or required exactly as
+ * {@link freezeTaskInputBindings} does.
+ */
+export function rebindTaskInputBindings(input) {
+    const { stepId, targetRef, contract } = input;
+    const declaredNames = Object.keys(contract).sort();
+    const byName = new Map();
+    for (const binding of input.bindings ?? []) {
+        if (!Object.hasOwn(contract, binding.name)) {
+            throw unknownBindingNameError(stepId, targetRef, binding.name, declaredNames);
+        }
+        const declaration = contract[binding.name];
+        if (!declaration)
+            throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${binding.name} is invalid.`);
+        byName.set(binding.name, binding.kind === "literal"
+            ? binding
+            : Object.freeze({ kind: "reference", name: binding.name, from: binding.from, schema: declaration.schema }));
+    }
+    return finalizeBindings(stepId, targetRef, contract, byName);
+}
+/**
+ * The tail shared by {@link freezeTaskInputBindings} and
+ * {@link rebindTaskInputBindings} once `byName` holds one classified entry
+ * per AUTHORED/bound name: apply declared defaults for every remaining
+ * contract key (or throw for a required one with none), schema-validate
+ * every literal (authored, re-bound, or defaulted) against the contract, and
+ * return the result sorted by name.
+ */
+function finalizeBindings(stepId, targetRef, contract, byName) {
+    for (const [name, declaration] of Object.entries(contract)) {
+        if (byName.has(name))
+            continue;
+        if (Object.hasOwn(declaration, "default")) {
+            byName.set(name, Object.freeze({ kind: "literal", name, value: declaration.default }));
+            continue;
+        }
+        if (declaration.required) {
+            throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef}, which declares required input "${name}" with no default; ` +
+                `supply it with with.${name}.`);
+        }
+    }
+    // Every LITERAL value (authored, re-bound, or defaulted) is validated
+    // against its own declared schema — a contract NARROWED to just the
+    // literal-bound names, so a required input bound via REFERENCE (whose
+    // value is not known until pre-attempt, §3.6) is never wrongly flagged
+    // "missing" here.
+    const literalContract = {};
+    const literalValues = {};
+    for (const binding of byName.values()) {
+        if (binding.kind !== "literal")
+            continue;
+        const declaration = contract[binding.name];
+        if (declaration)
+            literalContract[binding.name] = declaration;
+        literalValues[binding.name] = binding.value;
+    }
+    const schemaErrors = validateInputs(literalContract, literalValues, { pathRoot: "with" });
+    if (schemaErrors.length > 0) {
+        throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef}: ${schemaErrors.join("; ")}`);
+    }
+    const sorted = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return Object.freeze(sorted);
+}
+/**
+ * Classify and validate ONE authored `with:` entry whose key is already
+ * known to be a declared input name. §3.3 point 2/3: a value is a
+ * `{kind:"reference"}` binding IFF it is a non-null, non-array plain object
+ * whose OWN key set is exactly `["from"]` and whose `from` is a string
+ * `parseReference` accepts — the hard-fail band (B-15, B-16) means any OTHER
+ * shape carrying an own `from` key is `INPUT_BINDING_INVALID`, never
+ * reinterpreted as a literal.
+ */
+function normalizeOneEntry(stepId, targetRef, name, value, schema, earlierStepIds, declaredParamNames) {
+    if (!isPlainObject(value) || !Object.hasOwn(value, "from")) {
+        return Object.freeze({ kind: "literal", name, value });
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || typeof value.from !== "string") {
+        throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name} looks like a reference binding ({from: ...}) ` +
+            `but is not one: it must have exactly one key, "from", whose value is a reference string.`);
+    }
+    const parsed = parseReference(value.from);
+    if (!parsed.ok) {
+        throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name} reference ${JSON.stringify(value.from)} is ` +
+            `invalid: ${parsed.message}`);
+    }
+    if (parsed.expr.kind === "stepOutput") {
+        if (!earlierStepIds.has(parsed.expr.stepId)) {
+            throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name} reference ${value.from} does not name an ` +
+                `earlier step of this workflow.`);
+        }
+    }
+    else if (!declaredParamNames.has(parsed.expr.name)) {
+        const sortedParams = [...declaredParamNames].sort();
+        throw inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name} reference ${value.from} does not name a ` +
+            `declared workflow param; declared params: ${sortedParams.length > 0 ? sortedParams.join(", ") : "(none)"}.`);
+    }
+    return Object.freeze({ kind: "reference", name, from: value.from, schema });
+}

package/dist/workflows/ir/compile.js

@@ -38,17 +38,9 @@ import { decodeWorkflowSourceIrV1, } from "../source-ir/schema.js";
 export function compileWorkflowPlan(input, title, resolvedUnits = new Map()) {
     const sourceIr = decodeWorkflowSourceIrV1(input);
     const errors = [];
-    if (sourceIr.jobs.length !== 1) {
-        return {
-            ok: false,
-            errors: [
-                {
-                    line: sourceIr.jobs[1]?.source.start ?? sourceIr.source.start,
-                    message: "Current workflow execution requires exactly one source-IR job.",
-                },
-            ],
-        };
-    }
+    // The decoder guarantees exactly one job (P4 §3.3, docs/plans/specs/
+    // p4-deletions-closeout.md, row B-43) — a 2+-job document is rejected at
+    // the adapter boundary and never reaches this compiler.
     const sourceSteps = sourceIr.jobs[0]?.steps ?? [];
     const allStepIds = new Set(sourceSteps.map((step) => step.id));
     const earlierStepIds = new Set();
@@ -75,6 +67,13 @@ export function compileWorkflowPlan(input, title, resolvedUnits = new Map()) {
         steps.push(compileStep(step, sequenceIndex, sourceIr.defaults, resolvedUnits.get(step.id)));
         earlierStepIds.add(step.id);
     });
+    // P3b (spec §4.2, rows B-06/B-07): `outputs:` references are validated
+    // against the FULL step id set (never `earlierStepIds` — resolution happens
+    // at RUN COMPLETION, after every step has run, so an output may legitimately
+    // name any declared step regardless of its position).
+    for (const [name, declaration] of Object.entries(sourceIr.outputs ?? {})) {
+        checkOutputReference(name, declaration.from, { errors, allStepIds, line: sourceIr.source.start });
+    }
     if (errors.length > 0)
         return { ok: false, errors };
     const paramNames = sourceIr.params ? Object.keys(sourceIr.params) : [];
@@ -87,6 +86,7 @@ export function compileWorkflowPlan(input, title, resolvedUnits = new Map()) {
             ...(sourceIr.params && paramNames.length > 0
                 ? { paramSchemas: sourceIr.params }
                 : {}),
+            ...(sourceIr.outputs ? { outputs: sortedOutputs(sourceIr.outputs) } : {}),
             ...(sourceIr.budget
                 ? {
                     budget: {
@@ -99,6 +99,24 @@ export function compileWorkflowPlan(input, title, resolvedUnits = new Map()) {
         },
     };
 }
+/**
+ * Re-key `outputs:` into canonical wire order (code-point-ascending by name)
+ * — the order {@link decodeWorkflowOutputs} in `ir/schema-v4.ts` requires,
+ * mirroring how `freeze/task-bindings.ts`'s `finalizeBindings` sorts
+ * `inputBindings` before freezing. The source parser preserves AUTHOR order
+ * (P3b spec §4.2 places no ordering requirement on authoring), so this is the
+ * one place that must impose it.
+ */
+function sortedOutputs(outputs) {
+    const sorted = {};
+    for (const name of Object.keys(outputs).sort(compareCodePoints)) {
+        sorted[name] = outputs[name];
+    }
+    return sorted;
+}
+function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 function compileStep(step, sequenceIndex, defaults, resolved) {
     const gate = {
         kind: "gate",
@@ -213,6 +231,36 @@ function checkInputReference(text, index, check) {
         });
     }
 }
+/**
+ * Validate one `outputs.<name>.from` reference (P3b, spec §4.2, rows
+ * B-06/B-07): it must parse, it must name a STEP output — never a param (an
+ * output projects a step artifact; a param is already on the run row) — and
+ * that step must be DECLARED somewhere in the document. Unlike
+ * {@link checkInputReference}, the named step need not be EARLIER: an output
+ * resolves at run completion, after every step has already run.
+ */
+function checkOutputReference(name, text, check) {
+    const parsed = parseReference(text);
+    if (!parsed.ok) {
+        check.errors.push({ line: check.line, message: `Output "${name}" from: ${parsed.message}` });
+        return;
+    }
+    if (parsed.expr.kind === "param") {
+        check.errors.push({
+            line: check.line,
+            message: `Output "${name}" from: "${formatReference(parsed.expr)}" names a param, not a step output — an output ` +
+                `projects a STEP artifact, never a param. "outputs:" only names step outputs (steps.<id>.output...).`,
+        });
+        return;
+    }
+    if (!check.allStepIds.has(parsed.expr.stepId)) {
+        check.errors.push({
+            line: check.line,
+            message: `Output "${name}" from: "${formatReference(parsed.expr)}" cannot be resolved — "${parsed.expr.stepId}" is ` +
+                `not a step in this workflow.`,
+        });
+    }
+}
 // ── Non-fatal warnings ───────────────────────────────────────────────────────
 /**
  * Collect the document's non-fatal WARNINGS — advisories that never fail

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

@@ -30,10 +30,10 @@ export function freezeWorkflowEnvironment(refs, options) {
         const resolved = options.resolveRef(inputRef);
         const match = QUALIFIED_ENV_REF_RE.exec(resolved.ref);
         if (!match || match[1] !== resolved.bundle) {
-            throw new UsageError(`Workflow env ref ${JSON.stringify(inputRef)} did not resolve to a canonical fully-qualified owner.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`Workflow env ref ${JSON.stringify(inputRef)} did not resolve to a canonical fully-qualified owner.`, "WORKFLOW_SOURCE_INVALID");
         }
         if (logical.has(resolved.ref)) {
-            throw new UsageError(`Workflow environment contains duplicate ref ${resolved.ref}.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`Workflow environment contains duplicate ref ${resolved.ref}.`, "WORKFLOW_SOURCE_INVALID");
         }
         logical.add(resolved.ref);
         trackParentDirectories(collector, resolved.root, resolved.path);
@@ -324,5 +324,5 @@ function physicalIdentity(realPath, stat) {
     return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
 }
 function invalid(message) {
-    throw new UsageError(`Invalid frozen workflow environment: ${message}.`, "INVALID_FLAG_VALUE");
+    throw new UsageError(`Invalid frozen workflow environment: ${message}.`, "WORKFLOW_SOURCE_INVALID");
 }