akm-cli 0.9.16 → 0.9.17-alpha.10

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

@@ -2,23 +2,13 @@
 // 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).
+ * Pure freeze-time binding of a composing step's inputs.
+ * {@link freezeTaskInputBindings} classifies an authored `with:` against a
+ * contract; {@link rebindTaskInputBindings} re-binds already-classified
+ * bindings by name against another contract (a task's effective inputs
+ * against a child workflow's `params:`) without re-deriving their kind. A
+ * reference's resolved value is validated before each attempt (`exec/step-work.ts`).
+ * See docs/architecture/decisions/0008-task-binding-normalization.md.
  */
 import { isRecord } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
@@ -32,14 +22,9 @@ function unknownBindingNameError(stepId, targetRef, name, declaredNames) {
         `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).
+ * Normalize an authored `with:` into the sorted `TaskInputBinding[]` a frozen
+ * target carries: one entry per declared input with an effective value
+ * (literal, reference, or default). Throws `INPUT_BINDING_INVALID` on the first violation.
  */
 export function freezeTaskInputBindings(input) {
     const { stepId, targetRef, contract, earlierStepIds, declaredParamNames } = input;
@@ -57,28 +42,11 @@ export function freezeTaskInputBindings(input) {
     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.
+ * Re-bind already-normalized bindings by name against a different contract,
+ * keeping each entry's kind (a literal shaped like `{from}` stays a literal).
+ * A literal is validated against the new contract; a reference keeps its
+ * `from` and takes the new contract's schema; undeclared names are
+ * `INPUT_BINDING_INVALID`; missing keys are defaulted or required as usual.
  */
 export function rebindTaskInputBindings(input) {
     const { stepId, targetRef, contract } = input;
@@ -97,14 +65,7 @@ export function rebindTaskInputBindings(input) {
     }
     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.
- */
+/** Shared tail: apply defaults (or require), schema-validate every literal, and sort by name. */
 function finalizeBindings(stepId, targetRef, contract, byName) {
     for (const [name, declaration] of Object.entries(contract)) {
         if (byName.has(name))
@@ -118,11 +79,7 @@ function finalizeBindings(stepId, targetRef, contract, byName) {
                 `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.
+    // Validate literals only: a reference's value is not known until the attempt.
     const literalContract = {};
     const literalValues = {};
     for (const binding of byName.values()) {
@@ -141,13 +98,9 @@ function finalizeBindings(stepId, targetRef, contract, byName) {
     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.
+ * Classify one authored `with:` entry: exactly `{ from: <valid reference> }`
+ * is a reference; any other object with an own `from` key is
+ * `INPUT_BINDING_INVALID`, never a literal.
  */
 function normalizeOneEntry(stepId, targetRef, name, value, schema, earlierStepIds, declaredParamNames) {
     if (!isRecord(value) || !Object.hasOwn(value, "from")) {

package/dist/workflows/{source-ir/github-yaml.js → github-yaml.js}

@@ -1,19 +1,32 @@
 // 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 GitHub-shaped YAML workflow grammar: a strict `name`/`on`/`jobs`
+ * document with exactly one job, compiled straight to a {@link WorkflowPlan}.
+ * It is an AKM workflow format executed by AKM's own engine, not GitHub
+ * Actions: no expressions, no service events, `runs-on: [self-hosted]` only.
+ */
 import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from "yaml";
-import { utf8Bytes, WORKFLOW_MAX_SOURCE_BYTES } from "../resource-limits.js";
-import { WorkflowSourceFailure } from "./result.js";
-import { WORKFLOW_SOURCE_HOST_SHELLS, } from "./schema.js";
-import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, } from "./semantics.js";
-import { classifyWorkflowSourceUses, } from "./uses.js";
+import { WORKFLOW_PLAN_VERSION, } from "./plan.js";
+import { utf8Bytes, WORKFLOW_MAX_SOURCE_BYTES } from "./resource-limits.js";
+import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, workflowShellCommand, } from "./source-semantics.js";
+/** A located compile failure; `compile.ts` turns it into a `WorkflowSourceError`. */
+export class WorkflowSourceFailure extends Error {
+    error;
+    constructor(code, message, source) {
+        super(message);
+        this.name = "WorkflowSourceFailure";
+        this.error = { code, message, path: source.path, line: source.start };
+    }
+}
 const ROOT_KEYS = ["name", "on", "jobs"];
 const TRIGGER_KEYS = ["schedule", "workflow_dispatch"];
 const SCHEDULE_KEYS = ["cron"];
 const JOB_KEYS = ["name", "needs", "runs-on", "steps"];
 const STEP_KEYS = ["id", "name", "uses", "run", "with", "env", "shell", "working-directory"];
 const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
-const HOST_SHELLS = new Set(WORKFLOW_SOURCE_HOST_SHELLS);
+const HOST_SHELLS = new Set(["bash", "sh", "zsh", "pwsh", "powershell", "cmd"]);
 const SOURCE_ID = /^[A-Za-z_][A-Za-z0-9_-]{0,127}$/;
 const INPUT_KEY = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
 const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -80,16 +93,10 @@ export function parseGithubWorkflowSource(source, options) {
     reader.rejectAliases(parsedRoot);
     reader.checkTree(parsedRoot);
     const root = reader.fields(parsedRoot, ROOT_KEYS, "workflow");
-    const name = reader.requiredString(root, "name", "workflow");
-    const triggers = parseTriggers(reader, parsedRoot, reader.required(root, "on", "workflow"), options);
-    const jobs = parseJobs(reader, reader.required(root, "jobs", "workflow"), options);
-    return {
-        sourceIrVersion: 1,
-        name,
-        triggers,
-        jobs,
-        source: documentSource,
-    };
+    reader.requiredString(root, "name", "workflow");
+    const schedules = parseTriggers(reader, reader.required(root, "on", "workflow"));
+    const steps = parseJob(reader, reader.required(root, "jobs", "workflow"), options);
+    return { irVersion: WORKFLOW_PLAN_VERSION, title: options.title, schedules, steps };
 }
 class StrictYamlReader {
     filePath;
@@ -226,29 +233,6 @@ class StrictYamlReader {
         }
         this.fail("invalid-yaml-node", `${context} contains an unsupported YAML node.`, node);
     }
-    lineAt(root, structuralPath) {
-        let current = root;
-        for (const [index, segment] of structuralPath.entries()) {
-            if (typeof segment === "string" && isMap(current)) {
-                const pair = current.items.find((candidate) => isScalar(candidate.key) && candidate.key.value === segment);
-                if (!pair)
-                    return undefined;
-                if (pair.value === null) {
-                    return index === structuralPath.length - 1 ? this.span(pair.key).start : undefined;
-                }
-                current = pair.value;
-                continue;
-            }
-            if (typeof segment === "number" && isSeq(current)) {
-                current = current.items[segment] ?? null;
-                if (current === null)
-                    return undefined;
-                continue;
-            }
-            return undefined;
-        }
-        return this.span(current).start;
-    }
     required(fields, key, context) {
         const pair = fields.get(key);
         if (!pair)
@@ -301,7 +285,7 @@ class StrictYamlReader {
         throw new WorkflowSourceFailure(code, message, this.span(node));
     }
 }
-function parseTriggers(reader, root, node, options) {
+function parseTriggers(reader, node) {
     const fields = reader.arbitraryFields(node, "workflow.on");
     for (const [key, pair] of fields) {
         if (!TRIGGER_KEYS.includes(key)) {
@@ -310,7 +294,7 @@ function parseTriggers(reader, root, node, options) {
     }
     if (fields.size === 0)
         reader.fail("trigger-required", "workflow.on must declare schedule or workflow_dispatch.", node);
-    const triggers = [];
+    const schedules = [];
     const schedule = fields.get("schedule");
     if (schedule) {
         const records = reader.sequence(schedule.value, "workflow.on.schedule", 64);
@@ -318,7 +302,7 @@ function parseTriggers(reader, root, node, options) {
             const scheduleFields = reader.fields(record, SCHEDULE_KEYS, `workflow.on.schedule[${ordinal}]`);
             const cronNode = reader.required(scheduleFields, "cron", `workflow.on.schedule[${ordinal}]`);
             const cron = validateCron(reader, reader.string(cronNode, `workflow.on.schedule[${ordinal}].cron`), cronNode);
-            triggers.push({ kind: "schedule", cron, ordinal, source: reader.span(cronNode) });
+            schedules.push({ cron, ordinal, line: reader.span(cronNode).start });
         }
     }
     const manual = fields.get("workflow_dispatch");
@@ -332,62 +316,8 @@ function parseTriggers(reader, root, node, options) {
                 reader.fail("workflow-dispatch-inputs-unsupported", "workflow_dispatch inputs are not supported for local execution.", manual.value.items[0]?.key);
             }
         }
-        triggers.push({ kind: "workflow_dispatch", source: reader.span(manual.key) });
-    }
-    if (options.classifyTriggers) {
-        verifyOwnerTriggerPlan(reader, root, node, triggers, options);
-    }
-    return triggers;
-}
-function verifyOwnerTriggerPlan(reader, root, onNode, triggers, options) {
-    const classifier = options.classifyTriggers;
-    if (!classifier)
-        return;
-    let lastLine = reader.span(onNode).start;
-    let plan;
-    try {
-        plan = classifier({ on: reader.plain(onNode, "workflow.on") }, {
-            filePath: options.path,
-            lineAt: (structuralPath) => {
-                const line = reader.lineAt(root, structuralPath);
-                if (line !== undefined)
-                    lastLine = line;
-                return line;
-            },
-        });
-    }
-    catch (cause) {
-        const message = cause instanceof Error ? cause.message : String(cause);
-        throw new WorkflowSourceFailure("invalid-trigger", message, {
-            path: options.path,
-            start: lastLine,
-            end: lastLine,
-        });
-    }
-    const expectedSchedules = triggers.filter((trigger) => trigger.kind === "schedule");
-    const expectedManual = triggers.some((trigger) => trigger.kind === "workflow_dispatch");
-    const matches = plan !== null &&
-        typeof plan === "object" &&
-        plan.manual === expectedManual &&
-        Array.isArray(plan.schedules) &&
-        plan.schedules.length === expectedSchedules.length &&
-        plan.schedules.every((binding, index) => {
-            const expected = expectedSchedules[index];
-            let canonicalBindingCron;
-            try {
-                canonicalBindingCron = canonicalizeWorkflowCron(binding.cron);
-            }
-            catch {
-                return false;
-            }
-            return (expected !== undefined &&
-                canonicalBindingCron === expected.cron &&
-                binding.ordinal === expected.ordinal &&
-                binding.source === `on.schedule[${expected.ordinal}].cron`);
-        });
-    if (!matches) {
-        throw new WorkflowSourceFailure("trigger-classifier-drift", "The workflow trigger parser disagrees with the canonical workflow YAML trigger classifier.", reader.span(onNode));
     }
+    return schedules;
 }
 function validateCron(reader, cron, node) {
     try {
@@ -398,77 +328,45 @@ function validateCron(reader, cron, node) {
     }
 }
 /**
- * The ONE place a job-count or job-dependency policy is enforced (P4 §3.3,
- * docs/plans/specs/p4-deletions-closeout.md): AKM's YAML adapter accepts a
- * familiar GitHub-step-shaped `name:`/`on:`/`jobs:` document, but requires
- * exactly one job (brief §10) — it is an AKM workflow format executed by
- * AKM's native engine, not a GitHub Actions graph. Job ordering, dependency
- * validation and the 256-job bound all existed only to support MULTIPLE
- * jobs; they are gone with the machinery, not relocated.
+ * Exactly one job: AKM's YAML is an AKM workflow format executed by AKM's
+ * native engine, not a GitHub Actions job graph.
  */
-function parseJobs(reader, node, options) {
-    const fields = reader.arbitraryFields(node, "workflow.jobs");
-    let first;
-    let second;
-    for (const entry of fields) {
-        if (!first)
-            first = entry;
-        else if (!second)
-            second = entry;
-    }
-    if (fields.size !== 1 || !first) {
-        reader.fail("multi-job-unsupported", `AKM workflow YAML requires exactly one job; this document declares ${fields.size}. AKM's YAML is an AKM workflow format executed by AKM's native engine, not GitHub Actions — split the jobs into separate workflows.`, second ? second[1].key : node);
+function parseJob(reader, node, options) {
+    const jobs = reader.arbitraryFields(node, "workflow.jobs");
+    const [first, second] = [...jobs];
+    if (jobs.size !== 1 || !first) {
+        reader.fail("multi-job-unsupported", `AKM workflow YAML requires exactly one job; this document declares ${jobs.size}. AKM's YAML is an AKM workflow format executed by AKM's native engine, not GitHub Actions — split the jobs into separate workflows.`, second ? second[1].key : node);
     }
     const [id, pair] = first;
-    const job = parseJob(reader, id, pair, options);
-    if (job.needs.length > 0) {
-        reader.fail("multi-job-unsupported", `Job ${job.id} declares needs, but an AKM workflow has exactly one job; remove needs.`, pair.key);
-    }
-    return [job];
-}
-function parseJob(reader, id, pair, options) {
-    const node = pair.value;
+    const jobNode = pair.value;
     if (!SOURCE_ID.test(id))
-        reader.fail("invalid-job-id", `Invalid job id ${JSON.stringify(id)}.`, node);
-    const fields = reader.fields(node, JOB_KEYS, `workflow.jobs.${id}`);
-    validateRunner(reader, reader.required(fields, "runs-on", `workflow.jobs.${id}`), id);
-    const needs = parseNeeds(reader, fields.get("needs"), id);
+        reader.fail("invalid-job-id", `Invalid job id ${JSON.stringify(id)}.`, jobNode);
+    const fields = reader.fields(jobNode, JOB_KEYS, `workflow.jobs.${id}`);
+    const runner = reader.required(fields, "runs-on", `workflow.jobs.${id}`);
+    if (!isSeq(runner) ||
+        runner.items.length !== 1 ||
+        !isScalar(runner.items[0]) ||
+        runner.items[0].value !== "self-hosted") {
+        reader.fail("unsupported-runner", `Job ${JSON.stringify(id)} must declare exactly runs-on: [self-hosted].`, runner);
+    }
+    const needs = fields.get("needs");
+    if (needs) {
+        const values = isSeq(needs.value)
+            ? reader
+                .sequence(needs.value, `workflow.jobs.${id}.needs`, 256)
+                .map((item) => reader.string(item, `workflow.jobs.${id}.needs`))
+            : [reader.string(needs.value, `workflow.jobs.${id}.needs`)];
+        for (const need of values)
+            if (!SOURCE_ID.test(need))
+                reader.fail("invalid-job-id", `Invalid needs id ${need}.`, needs.value);
+        if (values.length > 0) {
+            reader.fail("multi-job-unsupported", `Job ${id} declares needs, but an AKM workflow has exactly one job; remove needs.`, pair.key);
+        }
+    }
+    reader.optionalString(fields, "name", `workflow.jobs.${id}`);
     const stepNodes = reader.sequence(reader.required(fields, "steps", `workflow.jobs.${id}`), `workflow.jobs.${id}.steps`, MAX_STEPS_PER_JOB);
     const stepIds = new Set();
-    const steps = stepNodes.map((step, index) => parseStep(reader, step, id, index, stepIds, options));
-    const name = reader.optionalString(fields, "name", `workflow.jobs.${id}`);
-    const keySource = reader.span(pair.key);
-    const valueSource = reader.span(node);
-    return {
-        id,
-        ...(name ? { name } : {}),
-        needs,
-        steps,
-        extensions: { "github.com/actions-workflow": { runsOn: ["self-hosted"] } },
-        source: { path: keySource.path, start: keySource.start, end: valueSource.end },
-    };
-}
-function validateRunner(reader, node, jobId) {
-    if (!isSeq(node) || node.items.length !== 1 || !isScalar(node.items[0]) || node.items[0].value !== "self-hosted") {
-        reader.fail("unsupported-runner", `Job ${JSON.stringify(jobId)} must declare exactly runs-on: [self-hosted].`, node);
-    }
-}
-function parseNeeds(reader, pair, jobId) {
-    if (!pair)
-        return [];
-    const values = isSeq(pair.value)
-        ? reader
-            .sequence(pair.value, `workflow.jobs.${jobId}.needs`, 256)
-            .map((item) => reader.string(item, `workflow.jobs.${jobId}.needs`))
-        : [reader.string(pair.value, `workflow.jobs.${jobId}.needs`)];
-    for (const need of values)
-        if (!SOURCE_ID.test(need))
-            reader.fail("invalid-job-id", `Invalid needs id ${need}.`, pair.value);
-    // Duplicate-entry checking (code duplicate-job-dependency) deleted with the
-    // rest of the multi-job dependency machinery (P4 §3.3): ANY non-empty
-    // needs — duplicated or not — is multi-job-unsupported at the caller
-    // (parseJobs), since a single-job workflow has nothing to depend on.
-    return values.sort();
+    return stepNodes.map((step, index) => parseStep(reader, step, id, index, stepIds, options));
 }
 function parseStep(reader, node, jobId, index, stepIds, options) {
     const context = `workflow.jobs.${jobId}.steps[${index}]`;
@@ -484,33 +382,35 @@ function parseStep(reader, node, jobId, index, stepIds, options) {
     if ((usesPair === undefined) === (runPair === undefined)) {
         reader.fail("step-target-xor", `${context} must declare exactly one of uses or run.`, node);
     }
-    const common = parseStepCommon(reader, fields, context);
-    if (usesPair)
-        return parseUsesStep(reader, usesPair, fields, options, { id, ...common, source: reader.span(node) });
-    if (!runPair)
-        reader.fail("step-target-xor", `${context} must declare exactly one of uses or run.`, node);
-    return parseRunStep(reader, runPair, fields, options, { id, ...common, source: reader.span(node) });
-}
-function parseStepCommon(reader, fields, context) {
-    const name = reader.optionalString(fields, "name", context);
+    reader.optionalString(fields, "name", context);
     const env = parseScalarMap(reader, fields.get("env"), `${context}.env`, ENV_KEY, false);
-    return { ...(name ? { name } : {}), ...(env ? { env } : {}) };
+    const target = usesPair
+        ? parseUsesStep(reader, usesPair, fields)
+        : parseRunStep(reader, runPair, fields, options);
+    const spec = { ...target, ...(env ? { env } : {}), source: reader.span(node) };
+    return {
+        stepId: id,
+        title: id,
+        sequenceIndex: index,
+        spec,
+        gate: { kind: "gate", id: `${id}.gate`, stepId: id, criteria: [], maxLoops: 1, frozenJudge: null },
+    };
 }
-function parseUsesStep(reader, usesPair, fields, options, common) {
+function parseUsesStep(reader, usesPair, fields) {
     if (fields.has("shell") || fields.has("working-directory")) {
         reader.fail("uses-field-conflict", "shell and working-directory are legal only with run.", usesPair.value);
     }
     const uses = reader.string(usesPair.value, "step.uses");
-    const target = classifyUses(reader, uses, usesPair.value, options.classifyUses ?? classifyWorkflowSourceUses);
-    // A-N3 (P2b, docs/plans/specs/p2b-input-bindings.md §1.7), widened in P3a
-    // (docs/plans/specs/p3a-plan-v5-child-freeze.md §4.2 step 7, row B-10) to
-    // ALSO cover a workflows/<ref> target: a tasks/<ref> or workflows/<ref>
-    // step's with: may bind any JSON value the composed target's declared
-    // input/param needs (an object/array literal, or a {from: "..."}
-    // reference) — decoding it through the scalar-only parseScalarMap would
-    // reject the very shapes both A-N3 and A-N8 exist to accept before
-    // decodeWorkflowSourceIrV1 (schema.ts) is ever reached. Every other target
-    // keeps the byte-identical scalar-only grammar.
+    let target;
+    try {
+        target = classifyWorkflowStepUses(uses);
+    }
+    catch (cause) {
+        semanticReaderFail(reader, cause, usesPair.value);
+    }
+    // A tasks/<ref> or workflows/<ref> step's with: may bind any JSON value the
+    // composed target's declared input/param needs (an object/array literal, or
+    // a {from: "..."} reference); every other target keeps the scalar grammar.
     const withValues = target.kind === "task" || target.kind === "workflow"
         ? parsePlainMap(reader, fields.get("with"), "step.with", INPUT_KEY)
         : parseScalarMap(reader, fields.get("with"), "step.with", INPUT_KEY, true);
@@ -518,20 +418,11 @@ function parseUsesStep(reader, usesPair, fields, options, common) {
         ? validateBuiltinCommand(reader, withValues, fields.get("with")?.value ?? usesPair.value)
         : undefined;
     return {
-        ...common,
         uses,
         ...(commandMode ? { commandMode } : {}),
         ...(withValues ? { with: withValues } : {}),
     };
 }
-function classifyUses(reader, uses, node, classifier) {
-    try {
-        return classifyWorkflowStepUses(uses, classifier);
-    }
-    catch (cause) {
-        semanticReaderFail(reader, cause, node);
-    }
-}
 function validateBuiltinCommand(reader, values, node) {
     try {
         const action = validateWorkflowBuiltinCommand(values);
@@ -543,7 +434,8 @@ function validateBuiltinCommand(reader, values, node) {
         semanticReaderFail(reader, cause, node);
     }
 }
-function parseRunStep(reader, runPair, fields, options, common) {
+/** A `run:` step lowers to its shell's argv now; `instructions` keeps the authored command for display. */
+function parseRunStep(reader, runPair, fields, options) {
     if (fields.has("with"))
         reader.fail("run-field-conflict", "with is legal only with uses.", fields.get("with")?.value);
     let run;
@@ -568,10 +460,8 @@ function parseRunStep(reader, runPair, fields, options, common) {
         }
     }
     return {
-        ...common,
-        run,
-        ...(shell ? { shell: shell } : {}),
-        ...(workingDirectory ? { workingDirectory } : {}),
+        exec: { command: workflowShellCommand(shell ?? "sh", run), ...(workingDirectory ? { cwd: workingDirectory } : {}) },
+        instructions: `Run ${run}.`,
     };
 }
 function parseScalarMap(reader, pair, context, keyPattern, allowNull) {
@@ -586,15 +476,7 @@ function parseScalarMap(reader, pair, context, keyPattern, allowNull) {
     }
     return out;
 }
-/**
- * Like {@link parseScalarMap} but accepts an arbitrary JSON value per key —
- * a task-composition with: binding may be the declared input's own shape (an
- * object/array literal, or a `{from: "..."}` reference), not just a scalar
- * (A-N3). Depth/node bounds are already enforced document-wide by
- * `checkTree`/`rejectAliases` before any field-level parsing runs, so this
- * adds no new bound. `decodeWorkflowSourceIrV1` (schema.ts) decides what a
- * declared input actually accepts.
- */
+/** Like {@link parseScalarMap} but any JSON value per key (bounded document-wide by `checkTree`). */
 function parsePlainMap(reader, pair, context, keyPattern) {
     if (!pair)
         return undefined;

package/dist/workflows/ir/params.js

@@ -2,33 +2,13 @@
 // 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/.
 /**
- * Run-parameter validation against the frozen plan's param schemas. A workflow
- * can declare `params.files: { type: array }`; supplying a non-array through
- * the exact-name `--files` flag must be rejected at start rather than silently
- * flowing into a unit prompt. The schemas are frozen into the plan, so
- * validation is a pure function of the frozen plan and supplied params.
- *
- * P2a (docs/plans/specs/p2a-task-source-v4.md §4.3, D3): this module is now a
- * THIN CONSUMER of the shared input contract, `src/execution/input-contract.ts`
- * (§4, D3, D3-N1/D3-N2/D3-N3). Every export below keeps its existing name,
- * signature, message, code, and hint byte-identically —
- * `tests/workflows/workflow-param-flags.test.ts` and
- * `tests/integration/workflows/params-validation.test.ts` pin that with zero
- * diff. `contractFromPlan` adapts a `WorkflowParameterPlan` into an
- * `InputContract` (every declared param, `required: false` — workflow params
- * declare nothing required). `WORKFLOW_PARAMETER_DIAGNOSTICS` reproduces
- * today's five workflow-parameter messages/codes for the shared
- * `materializeInputFlags` (D3-N3); its `contractViolation` formatter
- * re-roots each `"$"`-prefixed error from the shared module's internal check
- * to `"params."`, matching what `validateWorkflowParams` (called directly,
- * already `"params."`-rooted) has always produced. No coercion or validation
- * logic lives in this file — it lives once, in the shared module.
- *
- * Pure module: no IO, no engine imports.
+ * Run-parameter validation against the frozen plan's param schemas, a thin
+ * consumer of the shared input contract (`src/execution/input-contract.ts`):
+ * every declared param is optional, and the messages are the workflow ones.
  */
 import { UsageError } from "../../core/errors.js";
 import { materializeInputFlags, validateInputs, } from "../../execution/input-contract.js";
-/** Every declared workflow param as an `InputDeclaration`, `required: false` — workflow params declare nothing required (§4.3). */
+/** Every declared workflow param as an `InputDeclaration`, `required: false` — workflow params declare nothing required. */
 function contractFromPlan(plan) {
     const names = plan.params ?? Object.keys(plan.paramSchemas ?? {});
     const contract = {};
@@ -37,16 +17,7 @@ function contractFromPlan(plan) {
     }
     return contract;
 }
-/**
- * `contractFromPlan`, exported under its P3a-facing name (spec
- * docs/plans/specs/p3a-plan-v5-child-freeze.md A-N8): a child workflow has no
- * `inputs:` contract of its own (that is task source v4's vocabulary) — it
- * declares `params:`, and this is the SAME adapter this file already uses
- * for run-parameter validation, reused so `freezeTaskInputBindings`
- * (`src/workflows/freeze/task-bindings.ts`, generic over `InputContract`) has
- * exactly one normalizer for every binding surface. Additive; no behavior
- * change to this file's own exports.
- */
+/** A child workflow's `params:` as an input contract, so one normalizer binds every composition surface. */
 export { contractFromPlan as workflowParamContract };
 function invalidParameter(name, message) {
     return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
@@ -81,25 +52,9 @@ export function materializeWorkflowParameterFlags(plan, flags) {
  */
 export function validateWorkflowParams(plan, params) {
     // A plan with no schemas must not start emitting `properties: {}` noise —
-    // preserved as an explicit early return (§4.3 binding constraint), even
+    // preserved as an explicit early return, even
     // though an empty contract would validate to `[]` regardless.
     if (!plan.paramSchemas || Object.keys(plan.paramSchemas).length === 0)
         return [];
     return validateInputs(contractFromPlan(plan), params, { pathRoot: "params" });
 }
-/**
- * Run-integrity assert (reviewer #12): the journaled `params_json`
- * row must STILL satisfy the frozen param schemas. `startWorkflowRun` already
- * validated the params it stored, so a violation here means the row was edited
- * after the run started — loud corruption, exactly like the frozen-plan hash
- * mismatch and the tampered-params replay-divergence path. Refuse to describe
- * or drive the run rather than resolve prompts from schema-violating params.
- */
-export function assertRunParamsSatisfyPlan(runId, plan, params) {
-    const errors = validateWorkflowParams(plan, params);
-    if (errors.length === 0)
-        return;
-    throw new UsageError(`Workflow run ${runId} failed the frozen param-schema integrity check: the journaled params row no longer ` +
-        `satisfies the workflow's declared parameter schemas (edited after the run started). Refusing to execute it. ` +
-        `Start a new run.\n${errors.map((e) => `  - ${e}`).join("\n")}`);
-}