akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

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

@@ -1,786 +0,0 @@
-// 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/.
-/**
- * Strict, adapter-neutral workflow source IR.
- *
- * This is deliberately separate from the durable workflow plan in `../ir`.
- * Source adapters produce this representation; the durable freeze lane owns
- * resolving executable targets and creating resumable dispatch state.
- */
-import { types as utilTypes } from "node:util";
-import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
-import { compareCodePoints, wellFormedUnicode } from "../../core/common.js";
-import { validateExtraParams } from "../../core/extra-params.js";
-import { checkJsonSchemaDefinition } from "../../core/json-schema.js";
-import { parseReference } from "../program/expressions.js";
-import { PROGRAM_RETRY_REASONS } from "../program/schema.js";
-import { jsonBytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
-import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, rejectNulInArgv, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, } from "./semantics.js";
-export const WORKFLOW_SOURCE_IR_VERSION = 1;
-export const WORKFLOW_SOURCE_IR_MAX_BYTES = 2 * 1024 * 1024;
-export const WORKFLOW_SOURCE_IR_MAX_DEPTH = 64;
-export const WORKFLOW_SOURCE_IR_MAX_NODES = 50_000;
-export const WORKFLOW_SOURCE_EXTENSION_OWNER_PATTERN = /^(?:[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)\/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
-export const WORKFLOW_SOURCE_HOST_SHELLS = ["bash", "sh", "zsh", "pwsh", "powershell", "cmd"];
-const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
-const HOST_SHELLS = new Set(WORKFLOW_SOURCE_HOST_SHELLS);
-/** Strictly decode untrusted plain data before it reaches source lowering. */
-export function decodeWorkflowSourceIrV1(input, options = {}) {
-    const decoded = snapshotPlainData(input);
-    const root = record(decoded, "source IR");
-    keys(root, [
-        "sourceIrVersion",
-        "name",
-        "description",
-        "tags",
-        "params",
-        "outputs",
-        "defaults",
-        "budget",
-        "preamble",
-        "triggers",
-        "jobs",
-        "extensions",
-        "source",
-    ], "source IR");
-    if (root.sourceIrVersion !== WORKFLOW_SOURCE_IR_VERSION)
-        fail("sourceIrVersion must be 1");
-    nonEmptyString(root.name, "name");
-    optionalString(root.description, "description");
-    optionalString(root.preamble, "preamble");
-    optionalStringList(root.tags, "tags", 256);
-    validateParams(root.params);
-    validateOutputs(root.outputs);
-    validateUnit(root.defaults, "defaults", true);
-    validateBudget(root.budget);
-    span(root.source, "source");
-    extensions(root.extensions, "extensions");
-    if (!Array.isArray(root.triggers) || root.triggers.length === 0 || root.triggers.length > 64) {
-        fail("triggers must contain 1 through 64 entries");
-    }
-    validateTriggers(root.triggers);
-    if (!Array.isArray(root.jobs) || root.jobs.length !== 1) {
-        fail("jobs must contain exactly 1 entry");
-    }
-    const jobIds = new Set();
-    for (const [index, job] of root.jobs.entries())
-        validateJob(job, index, jobIds, options);
-    for (const job of root.jobs) {
-        for (const need of job.needs)
-            if (!jobIds.has(need))
-                fail(`job ${job.id} needs missing job ${need}`);
-    }
-    return decoded;
-}
-function validateTrigger(value, index) {
-    const trigger = record(value, `trigger ${index}`);
-    if (trigger.kind === "workflow_dispatch") {
-        keys(trigger, ["kind", "source"], `trigger ${index}`);
-        span(trigger.source, `trigger ${index} source`);
-        return;
-    }
-    if (trigger.kind !== "schedule")
-        fail(`trigger ${index} has an unsupported kind`);
-    keys(trigger, ["kind", "cron", "ordinal", "source"], `trigger ${index}`);
-    nonEmptyString(trigger.cron, `trigger ${index} cron`);
-    try {
-        trigger.cron = canonicalizeWorkflowCron(trigger.cron);
-    }
-    catch (cause) {
-        semanticFail(cause, `trigger ${index} cron`);
-    }
-    if (!Number.isSafeInteger(trigger.ordinal) || trigger.ordinal < 0) {
-        fail(`trigger ${index} ordinal must be a non-negative integer`);
-    }
-    span(trigger.source, `trigger ${index} source`);
-}
-function validateTriggers(value) {
-    let nextScheduleOrdinal = 0;
-    let manualSeen = false;
-    for (const [index, trigger] of value.entries()) {
-        validateTrigger(trigger, index);
-        const decoded = trigger;
-        if (decoded.kind === "schedule") {
-            if (manualSeen || decoded.ordinal !== nextScheduleOrdinal) {
-                fail("triggers are not in canonical schedule-then-manual order");
-            }
-            nextScheduleOrdinal++;
-        }
-        else {
-            if (manualSeen)
-                fail("triggers contain duplicate workflow_dispatch entries");
-            manualSeen = true;
-        }
-    }
-}
-function validateJob(value, index, jobIds, options) {
-    const job = record(value, `job ${index}`);
-    keys(job, ["id", "name", "needs", "steps", "extensions", "source"], `job ${index}`);
-    const id = sourceId(job.id, `job ${index} id`);
-    if (jobIds.has(id))
-        fail(`duplicate job id ${id}`);
-    jobIds.add(id);
-    optionalString(job.name, `job ${id} name`);
-    stringList(job.needs, `job ${id} needs`, 256, true);
-    const needs = job.needs;
-    if (needs.some((need, needIndex) => needIndex > 0 && compareCodePoints(needs[needIndex - 1] ?? "", need) > 0)) {
-        fail(`job ${id} needs are not in canonical order`);
-    }
-    if (!Array.isArray(job.steps) || job.steps.length === 0 || job.steps.length > 256) {
-        fail(`job ${id} steps must contain 1 through 256 entries`);
-    }
-    const stepIds = new Set();
-    for (const [stepIndex, step] of job.steps.entries()) {
-        validateStep(step, id, stepIndex, stepIds, options);
-    }
-    validateRouteTargets(job.steps, id);
-    extensions(job.extensions, `job ${id} extensions`);
-    span(job.source, `job ${id} source`);
-}
-function validateStep(value, jobId, index, stepIds, options) {
-    const step = record(value, `job ${jobId} step ${index}`);
-    keys(step, [
-        "id",
-        "name",
-        "uses",
-        "run",
-        "commandMode",
-        "exec",
-        "with",
-        "env",
-        "shell",
-        "workingDirectory",
-        "unit",
-        "map",
-        "route",
-        "inputs",
-        "output",
-        "gate",
-        "instructions",
-        "extensions",
-        "source",
-    ], `job ${jobId} step ${index}`);
-    const id = sourceId(step.id, `job ${jobId} step ${index} id`);
-    if (stepIds.has(id))
-        fail(`job ${jobId} has duplicate step id ${id}`);
-    stepIds.add(id);
-    optionalString(step.name, `step ${id} name`);
-    const hasUses = typeof step.uses === "string" && step.uses.length > 0;
-    const hasRun = typeof step.run === "string" && step.run.length > 0;
-    const hasExec = step.exec !== undefined;
-    const hasRoute = step.route !== undefined;
-    const targetCount = Number(hasUses) + Number(hasRun) + Number(hasExec);
-    if ((hasRoute && targetCount !== 0) || (!hasRoute && targetCount !== 1)) {
-        fail(`step ${id} must contain exactly one of uses, run, or exec unless it is a route`);
-    }
-    if (step.uses !== undefined && !hasUses)
-        fail(`step ${id} uses must be a non-empty string`);
-    if (step.run !== undefined && !hasRun)
-        fail(`step ${id} run must be a non-empty string`);
-    // A-N3: captured at the outer scope so scalarRecord's task-scoped widening
-    // (below) can consult it without re-classifying `step.uses`.
-    let usesTarget;
-    if (hasUses) {
-        let target;
-        try {
-            target = classifyWorkflowStepUses(step.uses);
-        }
-        catch (cause) {
-            semanticFail(cause, `step ${id} uses`);
-        }
-        usesTarget = target;
-        if (target.kind === "builtin-command") {
-            if (step.commandMode !== "literal" &&
-                step.commandMode !== "portable-template" &&
-                step.commandMode !== "stored-ref") {
-                fail(`step ${id} akm/command requires an explicit commandMode`);
-            }
-            try {
-                validateWorkflowBuiltinCommand(step.with, step.commandMode);
-            }
-            catch (cause) {
-                semanticFail(cause, `step ${id} uses`);
-            }
-        }
-        else if (step.commandMode !== undefined) {
-            fail(`step ${id} commandMode is legal only with uses akm/command`);
-        }
-    }
-    else if (step.commandMode !== undefined) {
-        fail(`step ${id} commandMode is legal only with uses akm/command`);
-    }
-    if (hasRun) {
-        try {
-            step.run = canonicalizeWorkflowRun(step.run);
-        }
-        catch (cause) {
-            semanticFail(cause, `step ${id} run`);
-        }
-    }
-    validateExec(step.exec, `step ${id} exec`, options);
-    // A-N3, widened in P3a (spec docs/plans/specs/p3a-plan-v5-child-freeze.md
-    // §4.2 step 7, row B-10, A-N8): the "must be a scalar" restriction narrows
-    // to non-task, non-workflow targets only. A tasks/<ref> or workflows/<ref>
-    // step's with: may carry any JSON value the bounded document front end
-    // already accepts; freeze (src/workflows/freeze/**) decides what a
-    // declared input/param actually accepts.
-    scalarRecord(step.with, `step ${id} with`, true, usesTarget?.kind === "task" || usesTarget?.kind === "workflow");
-    environment(step.env, `step ${id} env`);
-    rejectStepWithExpressions(step, id);
-    rejectExpressionsInRecord(step.env, `step ${id} env`);
-    if (step.with !== undefined && !hasUses)
-        fail(`step ${id} with is legal only with uses`);
-    if ((step.shell !== undefined || step.workingDirectory !== undefined) && !hasRun) {
-        fail(`step ${id} shell and workingDirectory are legal only with run`);
-    }
-    if (step.shell !== undefined && (typeof step.shell !== "string" || !HOST_SHELLS.has(step.shell))) {
-        fail(`step ${id} has an unsupported shell`);
-    }
-    optionalString(step.workingDirectory, `step ${id} workingDirectory`);
-    if (step.workingDirectory !== undefined) {
-        try {
-            step.workingDirectory = canonicalizeWorkflowWorkingDirectory(step.workingDirectory, options.workspaceRoot);
-        }
-        catch (cause) {
-            semanticFail(cause, `step ${id} workingDirectory`);
-        }
-    }
-    validateUnit(step.unit, `step ${id} unit`, false);
-    if (hasExec && step.unit !== undefined) {
-        const unit = step.unit;
-        if (unit.engine !== undefined || unit.model !== undefined || unit.llm !== undefined) {
-            fail(`step ${id} exec cannot also select an engine, model, or llm override`);
-        }
-    }
-    validateMap(step.map, `step ${id} map`);
-    validateRoute(step.route, `step ${id} route`);
-    optionalStringList(step.inputs, `step ${id} inputs`, Infinity);
-    if (Array.isArray(step.inputs)) {
-        for (const [inputIndex, input] of step.inputs.entries())
-            validateReference(input, `step ${id} inputs[${inputIndex}]`);
-    }
-    validateSchema(step.output, `step ${id} output`);
-    validateGate(step.gate, `step ${id} gate`);
-    optionalString(step.instructions, `step ${id} instructions`);
-    if (hasRoute && (step.map !== undefined || step.unit !== undefined || step.inputs !== undefined)) {
-        fail(`step ${id} route cannot contain map, unit, or inputs`);
-    }
-    extensions(step.extensions, `step ${id} extensions`);
-    span(step.source, `step ${id} source`);
-}
-function validateExec(value, location, options) {
-    if (value === undefined)
-        return;
-    const exec = record(value, location);
-    keys(exec, ["command", "cwd", "passEnv"], location);
-    stringList(exec.command, `${location}.command`, Infinity, false);
-    try {
-        rejectNulInArgv(exec.command);
-    }
-    catch (cause) {
-        semanticFail(cause, location);
-    }
-    optionalString(exec.cwd, `${location}.cwd`);
-    if (exec.cwd !== undefined) {
-        try {
-            exec.cwd = canonicalizeWorkflowWorkingDirectory(exec.cwd, options.workspaceRoot);
-        }
-        catch (cause) {
-            semanticFail(cause, `${location}.cwd`);
-        }
-    }
-    if (exec.passEnv !== undefined) {
-        stringList(exec.passEnv, `${location}.passEnv`, Infinity, false);
-    }
-    if (Array.isArray(exec.passEnv)) {
-        for (const name of exec.passEnv) {
-            if (!WORKFLOW_ENV_VAR_NAME_PATTERN.test(name))
-                fail(`${location}.passEnv has invalid environment name ${name}`);
-        }
-    }
-}
-function validateUnit(value, location, defaults) {
-    if (value === undefined)
-        return;
-    const unit = record(value, location);
-    const allowed = defaults
-        ? ["engine", "model", "llm", "timeoutMs", "onError"]
-        : ["engine", "model", "llm", "timeoutMs", "retry", "onError", "output", "env", "isolation"];
-    keys(unit, allowed, location);
-    optionalString(unit.engine, `${location}.engine`);
-    if (typeof unit.engine === "string") {
-        const engine = unit.engine.trim();
-        unit.engine = engine;
-        if (!WORKFLOW_ENGINE_NAME_PATTERN.test(engine) || engine.length > WORKFLOW_MAX_ENGINE_NAME_LENGTH) {
-            fail(`${location}.engine has an invalid engine name`);
-        }
-    }
-    optionalString(unit.model, `${location}.model`);
-    if (typeof unit.model === "string")
-        unit.model = unit.model.trim();
-    validateLlm(unit.llm, `${location}.llm`);
-    if (unit.timeoutMs !== undefined &&
-        unit.timeoutMs !== null &&
-        (!Number.isSafeInteger(unit.timeoutMs) ||
-            unit.timeoutMs < 1 ||
-            unit.timeoutMs > WORKFLOW_MAX_TIMEOUT_MS)) {
-        fail(`${location}.timeoutMs must be null or an integer from 1 through ${WORKFLOW_MAX_TIMEOUT_MS}`);
-    }
-    if (unit.onError !== undefined && unit.onError !== "fail" && unit.onError !== "continue") {
-        fail(`${location}.onError must be fail or continue`);
-    }
-    if (!defaults) {
-        validateRetry(unit.retry, `${location}.retry`);
-        validateSchema(unit.output, `${location}.output`);
-        optionalStringList(unit.env, `${location}.env`, 256);
-        if (Array.isArray(unit.env)) {
-            for (const [index, ref] of unit.env.entries())
-                validateAssetRef(ref, `${location}.env[${index}]`);
-        }
-        if (unit.isolation !== undefined && unit.isolation !== "none" && unit.isolation !== "worktree") {
-            fail(`${location}.isolation must be none or worktree`);
-        }
-    }
-}
-function validateRetry(value, location) {
-    if (value === undefined)
-        return;
-    const retry = record(value, location);
-    keys(retry, ["max", "on"], location);
-    if (!Number.isSafeInteger(retry.max) || retry.max < 0) {
-        fail(`${location}.max must be a non-negative integer`);
-    }
-    stringList(retry.on, `${location}.on`, PROGRAM_RETRY_REASONS.length, false);
-    for (const reason of retry.on) {
-        if (!PROGRAM_RETRY_REASONS.includes(reason)) {
-            fail(`${location}.on contains unknown failure reason ${reason}`);
-        }
-    }
-}
-function validateMap(value, location) {
-    if (value === undefined)
-        return;
-    const map = record(value, location);
-    keys(map, ["over", "concurrency", "reducer"], location);
-    nonEmptyString(map.over, `${location}.over`);
-    validateReference(map.over, `${location}.over`);
-    if (map.concurrency !== undefined &&
-        (!Number.isSafeInteger(map.concurrency) ||
-            map.concurrency < 1 ||
-            map.concurrency > WORKFLOW_MAX_CONCURRENCY)) {
-        fail(`${location}.concurrency must be an integer from 1 through ${WORKFLOW_MAX_CONCURRENCY}`);
-    }
-    if (map.reducer !== undefined && map.reducer !== "collect" && map.reducer !== "vote") {
-        fail(`${location}.reducer must be collect or vote`);
-    }
-}
-function validateRoute(value, location) {
-    if (value === undefined)
-        return;
-    const route = record(value, location);
-    keys(route, ["input", "branches", "defaultStepId"], location);
-    nonEmptyString(route.input, `${location}.input`);
-    validateReference(route.input, `${location}.input`);
-    if (!Array.isArray(route.branches) || route.branches.length === 0) {
-        fail(`${location}.branches must be a non-empty array`);
-    }
-    const matches = new Set();
-    for (const [index, value] of route.branches.entries()) {
-        const branch = record(value, `${location}.branches[${index}]`);
-        keys(branch, ["match", "stepId"], `${location}.branches[${index}]`);
-        nonEmptyString(branch.match, `${location}.branches[${index}].match`);
-        sourceId(branch.stepId, `${location}.branches[${index}].stepId`);
-        if (matches.has(branch.match))
-            fail(`${location} contains duplicate match ${branch.match}`);
-        matches.add(branch.match);
-    }
-    if (route.defaultStepId !== undefined)
-        sourceId(route.defaultStepId, `${location}.defaultStepId`);
-}
-function validateGate(value, location) {
-    if (value === undefined)
-        return;
-    const gate = record(value, location);
-    keys(gate, ["maxLoops", "rubric"], location);
-    if (gate.maxLoops !== undefined && (!Number.isSafeInteger(gate.maxLoops) || gate.maxLoops < 1)) {
-        fail(`${location}.maxLoops must be an integer of at least 1`);
-    }
-    optionalString(gate.rubric, `${location}.rubric`);
-}
-function validateRouteTargets(steps, jobId) {
-    const indexById = new Map(steps.map((step, index) => [step.id, index]));
-    for (const [index, step] of steps.entries()) {
-        if (!step.route)
-            continue;
-        const targets = [...step.route.branches.map(({ stepId }) => stepId)];
-        if (step.route.defaultStepId !== undefined)
-            targets.push(step.route.defaultStepId);
-        for (const target of targets) {
-            const targetIndex = indexById.get(target);
-            if (targetIndex === undefined)
-                fail(`job ${jobId} route ${step.id} targets missing step ${target}`);
-            if (targetIndex <= index)
-                fail(`job ${jobId} route ${step.id} must target a later step`);
-        }
-    }
-}
-function validateReference(value, location, expectedKind) {
-    const parsed = parseReference(value);
-    if (!parsed.ok)
-        fail(`${location} is invalid: ${parsed.message}`);
-    if (expectedKind && parsed.expr.kind !== expectedKind) {
-        fail(`${location} must reference a step output (steps.<id>.output...), not a param`);
-    }
-}
-function validateParams(value) {
-    if (value === undefined)
-        return;
-    const params = record(value, "params");
-    if (Object.keys(params).length === 0) {
-        fail(`params must contain at least one entry`);
-    }
-    for (const [name, schema] of Object.entries(params)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
-            fail(`params has invalid name ${name}`);
-        validateSchema(schema, `params.${name}`, false);
-    }
-}
-/**
- * Structural re-validation of `outputs:` (P3b, spec §4.2) — the parser
- * (`../parser.ts`) already enforces the same rules at authoring time; this is
- * the corruption-gate re-check every source-IR field gets, mirroring
- * `validateParams` immediately above.
- */
-function validateOutputs(value) {
-    if (value === undefined)
-        return;
-    const outputs = record(value, "outputs");
-    if (Object.keys(outputs).length === 0) {
-        fail(`outputs must contain at least one entry`);
-    }
-    for (const [name, declaration] of Object.entries(outputs)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
-            fail(`outputs has invalid name ${name}`);
-        const decl = record(declaration, `outputs.${name}`);
-        keys(decl, ["from", "schema"], `outputs.${name}`);
-        nonEmptyString(decl.from, `outputs.${name}.from`);
-        validateReference(decl.from, `outputs.${name}.from`, "stepOutput");
-        if (decl.schema !== undefined)
-            validateSchema(decl.schema, `outputs.${name}.schema`, false);
-    }
-}
-function validateBudget(value) {
-    if (value === undefined)
-        return;
-    const budget = record(value, "budget");
-    keys(budget, ["maxTokens", "maxUnits"], "budget");
-    for (const key of ["maxTokens", "maxUnits"]) {
-        if (budget[key] !== undefined && (!Number.isSafeInteger(budget[key]) || budget[key] < 1)) {
-            fail(`budget.${key} must be a positive integer`);
-        }
-    }
-}
-function validateLlm(value, location) {
-    if (value === undefined)
-        return;
-    const llm = record(value, location);
-    keys(llm, [
-        "temperature",
-        "maxTokens",
-        "supportsJsonSchema",
-        "extraParams",
-        "contextLength",
-        "enableThinking",
-        "reasoningEffort",
-    ], location);
-    if (llm.temperature !== undefined && typeof llm.temperature !== "number") {
-        fail(`${location}.temperature must be a finite number`);
-    }
-    for (const key of ["maxTokens", "contextLength"]) {
-        if (llm[key] !== undefined && (!Number.isSafeInteger(llm[key]) || llm[key] < 1)) {
-            fail(`${location}.${key} must be a positive integer`);
-        }
-    }
-    for (const key of ["supportsJsonSchema", "enableThinking"]) {
-        if (llm[key] !== undefined && typeof llm[key] !== "boolean")
-            fail(`${location}.${key} must be a boolean`);
-    }
-    if (llm.reasoningEffort !== undefined &&
-        (typeof llm.reasoningEffort !== "string" || llm.reasoningEffort.trim() === "")) {
-        fail(`${location}.reasoningEffort must be a non-empty string`);
-    }
-    if (llm.extraParams !== undefined) {
-        const extra = record(llm.extraParams, `${location}.extraParams`);
-        const issues = validateExtraParams(extra);
-        if (issues.length > 0)
-            fail(`${location}.extraParams is invalid: ${issues[0]?.message ?? "invalid value"}`);
-        if (jsonBytes(extra) > WORKFLOW_MAX_EXTRA_PARAMS_BYTES) {
-            fail(`${location}.extraParams exceeds ${WORKFLOW_MAX_EXTRA_PARAMS_BYTES} bytes`);
-        }
-    }
-}
-function validateSchema(value, location, optional = true) {
-    if (value === undefined && optional)
-        return;
-    const schema = record(value, location);
-    if (jsonBytes(schema) > WORKFLOW_MAX_SCHEMA_BYTES)
-        fail(`${location} exceeds ${WORKFLOW_MAX_SCHEMA_BYTES} bytes`);
-    const issue = checkJsonSchemaDefinition(schema)[0];
-    if (issue)
-        fail(`${location} is invalid: ${issue.message}`);
-}
-function validateAssetRef(value, location) {
-    try {
-        const parsed = parseBundleRef(value);
-        if (parsed.fragment !== undefined || bundleRefToString(parsed) !== value)
-            fail(`${location} is not canonical`);
-    }
-    catch (cause) {
-        fail(`${location} is invalid: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-}
-function optionalStringList(value, location, max) {
-    if (value === undefined)
-        return;
-    stringList(value, location, max, true);
-}
-function rejectExpressionsInRecord(value, location) {
-    if (value === undefined)
-        return;
-    for (const [key, item] of Object.entries(record(value, location))) {
-        if (typeof item === "string" && item.includes("${{"))
-            fail(`${location}.${key} contains an unsupported expression`);
-    }
-}
-/** A-N3: recurses into nested values, since a task step's with: may now carry an object/array. */
-function containsUnsupportedExpression(value) {
-    if (typeof value === "string")
-        return value.includes("${{");
-    if (Array.isArray(value))
-        return value.some((item) => containsUnsupportedExpression(item));
-    if (value !== null && typeof value === "object") {
-        return Object.values(value).some((item) => containsUnsupportedExpression(item));
-    }
-    return false;
-}
-function rejectStepWithExpressions(step, id) {
-    if (step.with === undefined)
-        return;
-    for (const [key, item] of Object.entries(record(step.with, `step ${id} with`))) {
-        if (step.uses === "akm/command" && step.commandMode === "literal" && key === "content")
-            continue;
-        if (!containsUnsupportedExpression(item))
-            continue;
-        fail(`step ${id} with.${key} contains an unsupported expression`);
-    }
-}
-function semanticFail(cause, location) {
-    if (cause instanceof WorkflowSourceSemanticError)
-        fail(`${location}: ${cause.message}`);
-    fail(`${location}: ${cause instanceof Error ? cause.message : String(cause)}`);
-}
-function snapshotPlainData(input) {
-    return snapshotValue(input, 0, "source IR", { nodes: 0, bytes: 0 });
-}
-function snapshotValue(value, depth, location, state) {
-    state.nodes++;
-    if (state.nodes > WORKFLOW_SOURCE_IR_MAX_NODES)
-        fail("source IR exceeds the node limit");
-    if (depth > WORKFLOW_SOURCE_IR_MAX_DEPTH)
-        fail("source IR exceeds the depth limit");
-    if (value === null || typeof value === "boolean") {
-        countJsonBytes(state, value === null ? "null" : String(value));
-        return value;
-    }
-    if (typeof value === "string") {
-        if (!wellFormedUnicode(value))
-            fail(`${location} must contain well-formed Unicode`);
-        countJsonBytes(state, JSON.stringify(value));
-        return value;
-    }
-    if (typeof value === "number") {
-        if (!Number.isFinite(value))
-            fail(`${location} contains a non-finite number`);
-        const canonical = Object.is(value, -0) ? 0 : value;
-        countJsonBytes(state, JSON.stringify(canonical));
-        return canonical;
-    }
-    if (typeof value !== "object")
-        fail(`${location} contains non-JSON data`);
-    if (utilTypes.isProxy(value))
-        fail(`${location} must not be a Proxy object`);
-    return Array.isArray(value)
-        ? snapshotArray(value, depth, location, state)
-        : snapshotObject(value, depth, location, state);
-}
-function snapshotArray(value, depth, location, state) {
-    if (Object.getPrototypeOf(value) !== Array.prototype)
-        fail(`${location} must be a plain array`);
-    const ownKeys = Reflect.ownKeys(value);
-    const lengthDescriptor = Reflect.getOwnPropertyDescriptor(value, "length");
-    if (!lengthDescriptor || !("value" in lengthDescriptor) || !Number.isSafeInteger(lengthDescriptor.value)) {
-        fail(`${location} has an invalid array length`);
-    }
-    const length = lengthDescriptor.value;
-    if (length < 0 || length > WORKFLOW_SOURCE_IR_MAX_NODES)
-        fail(`${location} exceeds the array length limit`);
-    const expected = new Set(["length", ...Array.from({ length }, (_, index) => String(index))]);
-    for (const key of ownKeys) {
-        if (typeof key === "symbol")
-            fail(`${location} contains symbol keys`);
-        if (!expected.has(key))
-            fail(`${location} contains unexpected array property ${key}`);
-    }
-    const snapshot = new Array(length);
-    countJsonBytes(state, "[");
-    for (let index = 0; index < length; index++) {
-        const descriptor = Reflect.getOwnPropertyDescriptor(value, String(index));
-        if (!descriptor)
-            fail(`${location} contains a sparse array`);
-        if (!("value" in descriptor))
-            fail(`${location}[${index}] is an accessor property`);
-        if (!descriptor.enumerable)
-            fail(`${location}[${index}] is non-enumerable`);
-        if (index > 0)
-            countJsonBytes(state, ",");
-        snapshot[index] = snapshotValue(descriptor.value, depth + 1, `${location}[${index}]`, state);
-    }
-    countJsonBytes(state, "]");
-    return snapshot;
-}
-function snapshotObject(value, depth, location, state) {
-    if (Object.getPrototypeOf(value) !== Object.prototype)
-        fail(`${location} must be a plain object`);
-    const ownKeys = Reflect.ownKeys(value);
-    if (ownKeys.length > WORKFLOW_SOURCE_IR_MAX_NODES)
-        fail(`${location} exceeds the object key limit`);
-    const snapshot = {};
-    countJsonBytes(state, "{");
-    for (const [index, key] of ownKeys.entries()) {
-        if (typeof key === "symbol")
-            fail(`${location} contains symbol keys`);
-        if (!wellFormedUnicode(key))
-            fail(`${location} contains an ill-formed key`);
-        if (UNSAFE_KEYS.has(key))
-            fail(`${location} contains unsafe key ${key}`);
-        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
-        if (!descriptor)
-            fail(`${location}.${key} has no stable own descriptor`);
-        if (!("value" in descriptor))
-            fail(`${location}.${key} is an accessor property`);
-        if (!descriptor.enumerable)
-            fail(`${location}.${key} is non-enumerable`);
-        if (index > 0)
-            countJsonBytes(state, ",");
-        countJsonBytes(state, `${JSON.stringify(key)}:`);
-        Object.defineProperty(snapshot, key, {
-            configurable: true,
-            enumerable: true,
-            value: snapshotValue(descriptor.value, depth + 1, `${location}.${key}`, state),
-            writable: true,
-        });
-    }
-    countJsonBytes(state, "}");
-    return snapshot;
-}
-function countJsonBytes(state, token) {
-    state.bytes += Buffer.byteLength(token, "utf8");
-    if (state.bytes > WORKFLOW_SOURCE_IR_MAX_BYTES)
-        fail("source IR exceeds the byte limit");
-}
-function record(value, location) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        fail(`${location} must be an object`);
-    return value;
-}
-function keys(value, allowed, location) {
-    const accepted = new Set(allowed);
-    for (const key of Object.keys(value))
-        if (!accepted.has(key))
-            fail(`${location} has unknown key ${key}`);
-}
-function sourceId(value, location) {
-    nonEmptyString(value, location);
-    if (!/^[A-Za-z_][A-Za-z0-9_-]{0,127}$/.test(value))
-        fail(`${location} has an invalid identifier`);
-    return value;
-}
-function nonEmptyString(value, location) {
-    if (typeof value !== "string" || value.trim() === "")
-        fail(`${location} must be a non-empty string`);
-}
-function optionalString(value, location) {
-    if (value !== undefined)
-        nonEmptyString(value, location);
-}
-function stringList(value, location, max, allowEmpty) {
-    if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || value.length > max) {
-        fail(`${location} must be ${allowEmpty ? "an" : "a non-empty"} array with at most ${max} entries`);
-    }
-    const seen = new Set();
-    for (const [index, item] of value.entries()) {
-        nonEmptyString(item, `${location}[${index}]`);
-        if (seen.has(item))
-            fail(`${location} contains duplicate ${item}`);
-        seen.add(item);
-    }
-}
-/**
- * `allowNonScalar` (A-N3, P2b; widened in P3a, A-N8): when true (a
- * `tasks/<ref>` or `workflows/<ref>` step's `with:`), the key-grammar check
- * still runs but the scalar/null value restriction is skipped entirely — a
- * declared object/array-typed input or param, or a `{from: "..."}`
- * reference, may decode. Every other target keeps the byte-identical
- * scalar-or-null restriction.
- */
-function scalarRecord(value, location, allowNull, allowNonScalar = false) {
-    if (value === undefined)
-        return;
-    const map = record(value, location);
-    for (const [key, item] of Object.entries(map)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/.test(key))
-            fail(`${location} has invalid key ${key}`);
-        if (allowNonScalar)
-            continue;
-        if (item === null && allowNull)
-            continue;
-        if (typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {
-            fail(`${location}.${key} must be a scalar`);
-        }
-    }
-}
-function environment(value, location) {
-    if (value === undefined)
-        return;
-    const map = record(value, location);
-    for (const [key, item] of Object.entries(map)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
-            fail(`${location} has invalid environment name ${key}`);
-        if (typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {
-            fail(`${location}.${key} must be a string, number, or boolean`);
-        }
-    }
-}
-function extensions(value, location) {
-    if (value === undefined)
-        return;
-    const map = record(value, location);
-    for (const owner of Object.keys(map)) {
-        if (!WORKFLOW_SOURCE_EXTENSION_OWNER_PATTERN.test(owner))
-            fail(`${location} has invalid owner ${owner}`);
-    }
-}
-function span(value, location) {
-    const source = record(value, location);
-    keys(source, ["path", "start", "end"], location);
-    nonEmptyString(source.path, `${location}.path`);
-    if (!Number.isSafeInteger(source.start) || source.start < 1)
-        fail(`${location}.start is invalid`);
-    if (!Number.isSafeInteger(source.end) || source.end < source.start) {
-        fail(`${location}.end is invalid`);
-    }
-}
-function fail(message) {
-    throw new Error(`Invalid workflow source IR v1: ${message}`);
-}