akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/workflows/ir/schema.js

@@ -0,0 +1,540 @@
+// 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 { UsageError } from "../../core/errors.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
+import { HARNESS_BY_ID } from "../../integrations/harnesses/index.js";
+import { parseReference } from "../program/expressions.js";
+import { PROGRAM_PARAM_NAME_PATTERN, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN } from "../program/schema.js";
+import { jsonBytes, WORKFLOW_MAX_ENGINES, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_PLAN_BYTES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_STEPS, } from "../resource-limits.js";
+/** The only executable persisted workflow plan format. */
+export const WORKFLOW_IR_VERSION = 3;
+export const WORKFLOW_MAX_CONCURRENCY = 64;
+export const WORKFLOW_MAX_GATE_LOOPS = 100;
+export const WORKFLOW_MAX_RETRIES = 100;
+export const WORKFLOW_MAX_UNITS = WORKFLOW_MAX_MAP_EXPANSION;
+export const WORKFLOW_MAX_TIMEOUT_MS = 2 ** 31 - 1;
+const MAX_LIST_ITEMS = 1024;
+const MAX_STRING_LENGTH = 1_000_000;
+const ENGINE_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** Strictly decode persisted v3 data before it can drive a workflow. */
+export function decodeWorkflowPlanV3(input, hooks = {}) {
+    if (!isRecord(input) || input.irVersion !== WORKFLOW_IR_VERSION)
+        fail("irVersion must be 3");
+    assertJson(input);
+    if (jsonBytes(input) > WORKFLOW_MAX_PLAN_BYTES)
+        fail("plan exceeds the 2 MiB resource limit");
+    const plan = input;
+    assertKeys(input, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps"], "plan");
+    assertString(plan.title, "title");
+    validateParams(plan.params, plan.paramSchemas);
+    validateBudget(plan.budget);
+    if (!isRecord(plan.execution) ||
+        !Number.isInteger(plan.execution.maxConcurrency) ||
+        plan.execution.maxConcurrency < 1 ||
+        plan.execution.maxConcurrency > WORKFLOW_MAX_CONCURRENCY) {
+        fail("execution.maxConcurrency must be an integer from 1 through 64");
+    }
+    assertKeys(plan.execution, ["maxConcurrency", "engines"], "execution");
+    if (!isRecord(plan.execution.engines))
+        fail("execution.engines must be an object");
+    const engines = plan.execution.engines;
+    if (Object.keys(engines).length > WORKFLOW_MAX_ENGINES)
+        fail(`execution.engines exceeds ${WORKFLOW_MAX_ENGINES} entries`);
+    const references = new Set();
+    for (const [key, engine] of Object.entries(engines))
+        validateEngine(key, engine, references, hooks);
+    if (!Array.isArray(plan.steps) || plan.steps.length === 0 || plan.steps.length > WORKFLOW_MAX_STEPS)
+        fail("steps must contain 1 through 256 entries");
+    const stepIds = new Set();
+    const nodeIds = new Set();
+    for (let index = 0; index < plan.steps.length; index++) {
+        const step = plan.steps[index];
+        if (!isRecord(step) ||
+            typeof step.stepId !== "string" ||
+            !PROGRAM_STEP_ID_PATTERN.test(step.stepId) ||
+            stepIds.has(step.stepId))
+            fail("step ids must be unique non-empty strings");
+        stepIds.add(step.stepId);
+        if (step.sequenceIndex !== index)
+            fail("step sequence indices must be contiguous and unique");
+        assertString(step.title, `step ${step.stepId} title`);
+        if (!!step.root === !!step.route)
+            fail(`step ${step.stepId} must contain exactly one of root or route`);
+        assertKeys(step, ["stepId", "title", "sequenceIndex", "dependsOn", "root", "route", "outputSchema", "gate"], `step ${step.stepId}`);
+        validateStringArray(step.dependsOn, `step ${step.stepId} dependsOn`, WORKFLOW_MAX_STEPS, true);
+        if (step.outputSchema !== undefined)
+            validateSchema(step.outputSchema, `step ${step.stepId} outputSchema`);
+        if (step.root)
+            validateNode(step.root, step.stepId, references, nodeIds, hooks);
+        if (step.route)
+            validateRoute(step.route, step.stepId);
+        validateGate(step.gate, step.stepId, references, nodeIds, hooks);
+    }
+    const stepIndex = new Map(plan.steps.map((step, index) => [step.stepId, index]));
+    for (const [index, step] of plan.steps.entries()) {
+        for (const target of step.route
+            ? [...Object.values(step.route.when), ...(step.route.defaultStepId ? [step.route.defaultStepId] : [])]
+            : []) {
+            const targetIndex = stepIndex.get(target);
+            if (targetIndex === undefined)
+                fail(`route target ${target} does not name a step`);
+            if (targetIndex <= index)
+                fail(`route target ${target} must come after step ${step.stepId}`);
+        }
+        const dependencies = new Set();
+        for (const dependency of step.dependsOn ?? []) {
+            const dependencyIndex = stepIndex.get(dependency);
+            if (dependencyIndex === undefined || dependencyIndex >= index || dependencies.has(dependency))
+                fail(`step ${step.stepId} has an invalid dependency`);
+            dependencies.add(dependency);
+        }
+        validateStepExpressions(step, index, stepIndex);
+    }
+    for (const name of references) {
+        if (!engines[name])
+            fail(`engine reference ${name} is not in execution.engines`);
+    }
+    for (const name of Object.keys(engines))
+        if (!references.has(name))
+            fail(`engine ${name} is not referenced`);
+    for (const engine of Object.values(engines)) {
+        if (engine.kind !== "agent")
+            continue;
+        if (engine.fallbackLlmEngine !== null && engines[engine.fallbackLlmEngine]?.kind !== "llm")
+            fail(`SDK engine ${engine.name} fallback must name an LLM engine`);
+    }
+    for (const step of plan.steps) {
+        if (step.root)
+            assertUnitEngineCompatibility(step.root, engines);
+        if (step.gate.judge) {
+            const judge = engines[step.gate.judge.engine];
+            if (!judge || judge.kind !== "llm")
+                fail(`gate ${step.gate.id} must reference an LLM engine`);
+        }
+    }
+    return plan;
+}
+function validateEngine(key, engine, references, hooks) {
+    if (!ENGINE_NAME_PATTERN.test(key) ||
+        key.length > 63 ||
+        !isRecord(engine) ||
+        engine.name !== key ||
+        (engine.kind !== "llm" && engine.kind !== "agent"))
+        fail("catalog keys must equal a valid snapshot name");
+    if (engine.kind === "llm") {
+        assertKeys(engine, [
+            "name",
+            "kind",
+            "provider",
+            "endpoint",
+            "model",
+            "credential",
+            "temperature",
+            "maxTokens",
+            "concurrency",
+            "supportsJsonSchema",
+            "extraParams",
+            "contextLength",
+            "enableThinking",
+        ], `LLM engine ${key}`);
+        if (typeof engine.endpoint !== "string" ||
+            !engine.endpoint ||
+            typeof engine.model !== "string" ||
+            !engine.model ||
+            !Number.isInteger(engine.concurrency) ||
+            engine.concurrency < 1 ||
+            engine.concurrency > WORKFLOW_MAX_CONCURRENCY)
+            fail(`LLM engine ${key} is invalid`);
+        if (engine.provider !== undefined)
+            assertString(engine.provider, `LLM engine ${key} provider`);
+        validateEndpoint(engine.endpoint, key);
+        validateOptionalFiniteNumber(engine.temperature, `LLM engine ${key} temperature`);
+        validateOptionalPositiveInteger(engine.maxTokens, `LLM engine ${key} maxTokens`);
+        validateOptionalPositiveInteger(engine.contextLength, `LLM engine ${key} contextLength`);
+        if (engine.supportsJsonSchema !== undefined && typeof engine.supportsJsonSchema !== "boolean")
+            fail(`LLM engine ${key} supportsJsonSchema must be boolean`);
+        if (engine.enableThinking !== undefined && typeof engine.enableThinking !== "boolean")
+            fail(`LLM engine ${key} enableThinking must be boolean`);
+        if (engine.extraParams !== undefined) {
+            const issue = validateExtraParams(engine.extraParams)[0];
+            if (issue)
+                fail(formatExtraParamsIssue(`LLM engine ${key} extraParams`, issue));
+        }
+        validateExtraParamsValue(engine.extraParams, `LLM engine ${key} extraParams`, hooks);
+        if (engine.credential !== undefined) {
+            if (!isRecord(engine.credential) ||
+                !Array.isArray(engine.credential.names) ||
+                engine.credential.names.length === 0 ||
+                engine.credential.names.length > 32 ||
+                !engine.credential.names.every((n) => typeof n === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)) ||
+                new Set(engine.credential.names).size !== engine.credential.names.length ||
+                typeof engine.credential.required !== "boolean") {
+                fail(`LLM engine ${key} has an invalid credential descriptor`);
+            }
+            assertKeys(engine.credential, ["names", "required"], `LLM engine ${key} credential`);
+        }
+        return;
+    }
+    assertKeys(engine, [
+        "name",
+        "kind",
+        "runnerKind",
+        "platform",
+        "bin",
+        "args",
+        "workspace",
+        "envPassthrough",
+        "commandBuilder",
+        "fallbackLlmEngine",
+    ], `agent engine ${key}`);
+    if ((engine.runnerKind !== "agent" && engine.runnerKind !== "sdk") ||
+        typeof engine.platform !== "string" ||
+        !engine.platform ||
+        typeof engine.bin !== "string" ||
+        !engine.bin ||
+        !Array.isArray(engine.args) ||
+        engine.args.length > MAX_LIST_ITEMS ||
+        !engine.args.every((arg) => typeof arg === "string" && arg.length <= MAX_STRING_LENGTH) ||
+        !(typeof engine.workspace === "string" || engine.workspace === null) ||
+        !Array.isArray(engine.envPassthrough) ||
+        engine.envPassthrough.length > MAX_LIST_ITEMS ||
+        !engine.envPassthrough.every((name) => typeof name === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) ||
+        new Set(engine.envPassthrough).size !== engine.envPassthrough.length ||
+        typeof engine.commandBuilder !== "string" ||
+        engine.commandBuilder !== engine.platform ||
+        (engine.workspace !== null && !path.isAbsolute(engine.workspace)) ||
+        !HARNESS_BY_ID.get(engine.platform)?.capabilities.agentDispatch)
+        fail(`agent engine ${key} is invalid`);
+    if ((engine.platform === "opencode-sdk") !== (engine.runnerKind === "sdk"))
+        fail(`agent engine ${key} has incompatible platform and runnerKind`);
+    if (engine.runnerKind === "agent" && engine.fallbackLlmEngine !== null)
+        fail(`agent engine ${key} cannot have an SDK fallback`);
+    if (engine.fallbackLlmEngine !== null) {
+        if (typeof engine.fallbackLlmEngine !== "string" || !engine.fallbackLlmEngine)
+            fail(`agent engine ${key} has an invalid fallback`);
+        references.add(engine.fallbackLlmEngine);
+    }
+}
+function validateNode(node, stepId, references, nodeIds, hooks) {
+    if (!isRecord(node) ||
+        (node.kind !== "unit" && node.kind !== "map") ||
+        typeof node.id !== "string" ||
+        !node.id ||
+        nodeIds.has(node.id))
+        fail("node ids must be unique non-empty strings");
+    nodeIds.add(node.id);
+    if (node.kind === "map") {
+        assertKeys(node, ["kind", "id", "over", "template", "concurrency", "reducer", "source"], `map ${node.id}`);
+        if (typeof node.over !== "string" ||
+            !node.over ||
+            !Number.isInteger(node.concurrency) ||
+            node.concurrency < 1 ||
+            node.concurrency > WORKFLOW_MAX_CONCURRENCY ||
+            (node.reducer !== "collect" && node.reducer !== "vote"))
+            fail(`map ${node.id} is invalid`);
+        if (node.id !== `${stepId}.map`)
+            fail(`map ${node.id} does not match step ${stepId}`);
+        validateSource(node.source, `map ${node.id} source`);
+        validateNode(node.template, stepId, references, nodeIds, hooks);
+        if (!isRecord(node.template) || node.template.kind !== "unit")
+            fail(`map ${node.id} template must be a unit`);
+        if (node.template.id !== `${stepId}.unit`)
+            fail(`map ${node.id} template id is invalid`);
+        return;
+    }
+    assertKeys(node, [
+        "kind",
+        "id",
+        "instructions",
+        "templating",
+        "inputs",
+        "invocation",
+        "schema",
+        "retry",
+        "onError",
+        "env",
+        "isolation",
+        "source",
+    ], `unit ${node.id}`);
+    if (typeof node.instructions !== "string" ||
+        !node.instructions ||
+        (node.templating !== "expressions" && node.templating !== "verbatim") ||
+        (node.onError !== "fail" && node.onError !== "continue") ||
+        (node.isolation !== "none" && node.isolation !== "worktree"))
+        fail(`unit ${node.id} is invalid`);
+    if (node.id !== stepId && node.id !== `${stepId}.unit`)
+        fail(`unit ${node.id} does not belong to step ${stepId}`);
+    if (Buffer.byteLength(node.instructions, "utf8") > WORKFLOW_MAX_INSTRUCTION_BYTES)
+        fail(`unit ${node.id} instructions exceed the 256 KiB resource limit`);
+    if (node.schema !== undefined)
+        validateSchema(node.schema, `unit ${node.id} schema`);
+    validateRetry(node.retry, node.id);
+    validateStringArray(node.env, `unit ${node.id} env`, MAX_LIST_ITEMS, true);
+    validateStringArray(node.inputs, `unit ${node.id} inputs`, WORKFLOW_MAX_INPUTS, true);
+    validateSource(node.source, `unit ${node.id} source`);
+    validateInvocation(node.invocation, references, hooks);
+}
+function validateGate(gate, stepId, references, nodeIds, hooks) {
+    if (!isRecord(gate) ||
+        gate.kind !== "gate" ||
+        gate.id !== `${stepId}.gate` ||
+        gate.stepId !== stepId ||
+        !Array.isArray(gate.criteria) ||
+        gate.criteria.length > MAX_LIST_ITEMS ||
+        !gate.criteria.every((x) => typeof x === "string" && x.length > 0 && x.length <= MAX_STRING_LENGTH) ||
+        !Number.isInteger(gate.maxLoops) ||
+        gate.maxLoops < 1 ||
+        gate.maxLoops > WORKFLOW_MAX_GATE_LOOPS)
+        fail(`gate for step ${stepId} is invalid`);
+    if (nodeIds.has(gate.id))
+        fail(`gate id ${gate.id} collides with a node`);
+    assertKeys(gate, ["kind", "id", "stepId", "criteria", "maxLoops", "judge"], `gate ${stepId}`);
+    nodeIds.add(gate.id);
+    if (gate.criteria.length === 0 && gate.judge !== null)
+        fail(`gate ${gate.id} without criteria cannot have a judge`);
+    if (gate.judge !== null)
+        validateInvocation(gate.judge, references, hooks);
+}
+function validateInvocation(invocation, references, hooks) {
+    if (!isRecord(invocation) ||
+        typeof invocation.engine !== "string" ||
+        !invocation.engine ||
+        !((typeof invocation.model === "string" && invocation.model.length > 0) || invocation.model === null) ||
+        !(invocation.timeoutMs === null ||
+            (Number.isSafeInteger(invocation.timeoutMs) &&
+                invocation.timeoutMs >= 1 &&
+                invocation.timeoutMs <= WORKFLOW_MAX_TIMEOUT_MS)))
+        fail("invocation is invalid");
+    references.add(invocation.engine);
+    assertKeys(invocation, ["engine", "model", "timeoutMs", "llm"], "invocation");
+    validateLlmOverrides(invocation.llm, hooks);
+}
+function validateRoute(route, stepId) {
+    if (!isRecord(route) ||
+        typeof route.input !== "string" ||
+        !route.input ||
+        !isRecord(route.when) ||
+        Object.keys(route.when).length === 0 ||
+        Object.keys(route.when).length > WORKFLOW_MAX_ROUTE_BRANCHES ||
+        !Object.keys(route.when).every((match) => match.length > 0 && match.length <= MAX_STRING_LENGTH) ||
+        !Object.values(route.when).every((target) => typeof target === "string" && target))
+        fail(`route for step ${stepId} is invalid`);
+    assertKeys(route, ["input", "when", "defaultStepId"], `route ${stepId}`);
+    if (route.defaultStepId !== undefined && (typeof route.defaultStepId !== "string" || !route.defaultStepId))
+        fail(`route for step ${stepId} has an invalid default target`);
+}
+function assertUnitEngineCompatibility(node, engines) {
+    const unit = node.kind === "map" ? node.template : node;
+    const engine = unit.invocation ? engines[unit.invocation.engine] : undefined;
+    if (!engine)
+        return;
+    if (engine.kind === "llm" && unit.invocation?.model === null)
+        fail(`LLM unit ${unit.id} has no exact model`);
+    if (engine.kind === "agent" && unit.invocation?.llm !== undefined)
+        fail(`agent unit ${unit.id} cannot carry LLM invocation settings`);
+    if (engine.kind === "llm" && ((unit.env?.length ?? 0) > 0 || unit.isolation === "worktree")) {
+        fail(`LLM unit ${unit.id} cannot use env injection or worktree isolation`);
+    }
+}
+function assertKeys(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            fail(`${label} contains unknown key ${key}`);
+}
+function assertJson(value, depth = 0) {
+    if (depth > WORKFLOW_MAX_JSON_DEPTH)
+        fail("plan exceeds JSON depth limit of 64");
+    if (value === null || typeof value === "boolean")
+        return;
+    if (typeof value === "string") {
+        if (value.length > MAX_STRING_LENGTH)
+            fail("plan contains an oversized string");
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            fail("plan contains a non-finite number");
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertJson(item, depth + 1);
+        return;
+    }
+    if (isRecord(value)) {
+        for (const item of Object.values(value))
+            assertJson(item, depth + 1);
+        return;
+    }
+    fail("plan contains a non-JSON value");
+}
+function validateParams(params, schemas) {
+    validateStringArray(params, "params", WORKFLOW_MAX_PARAMS, true);
+    if (params?.some((name) => !PROGRAM_PARAM_NAME_PATTERN.test(name)))
+        fail("params contains an invalid name");
+    if (schemas !== undefined) {
+        if (!isRecord(schemas) || Object.keys(schemas).length > WORKFLOW_MAX_PARAMS)
+            fail("paramSchemas must be a bounded object");
+        for (const [name, schema] of Object.entries(schemas)) {
+            if (!PROGRAM_PARAM_NAME_PATTERN.test(name))
+                fail(`paramSchemas.${name} is invalid`);
+            validateSchema(schema, `paramSchemas.${name}`);
+        }
+    }
+    const names = params ?? [];
+    if (schemas && (names.length !== Object.keys(schemas).length || names.some((name) => !Object.hasOwn(schemas, name))))
+        fail("params and paramSchemas must name the same parameters");
+    if (!schemas && names.length > 0) {
+        // Markdown workflows have named parameters but no schemas, which is valid.
+        return;
+    }
+}
+function validateBudget(budget) {
+    if (budget === undefined)
+        return;
+    if (!isRecord(budget))
+        fail("budget must be an object");
+    assertKeys(budget, ["maxTokens", "maxUnits"], "budget");
+    if (budget.maxTokens === undefined && budget.maxUnits === undefined)
+        fail("budget must declare a ceiling");
+    validateOptionalPositiveInteger(budget.maxTokens, "budget.maxTokens");
+    const maxUnits = budget.maxUnits;
+    if (maxUnits !== undefined &&
+        (!Number.isSafeInteger(maxUnits) || maxUnits < 1 || maxUnits > WORKFLOW_MAX_UNITS))
+        fail(`budget.maxUnits must be an integer from 1 through ${WORKFLOW_MAX_UNITS}`);
+}
+function validateRetry(retry, nodeId) {
+    if (retry === undefined)
+        return;
+    if (!isRecord(retry))
+        fail(`unit ${nodeId} retry must be an object`);
+    assertKeys(retry, ["max", "on"], `unit ${nodeId} retry`);
+    if (!Number.isSafeInteger(retry.max) || retry.max < 0 || retry.max > WORKFLOW_MAX_RETRIES)
+        fail(`unit ${nodeId} retry.max is invalid`);
+    validateStringArray(retry.on, `unit ${nodeId} retry.on`, PROGRAM_RETRY_REASONS.length, true);
+    if (retry.on === undefined ||
+        retry.on.length === 0 ||
+        retry.on.some((reason) => !PROGRAM_RETRY_REASONS.includes(reason)))
+        fail(`unit ${nodeId} retry.on is invalid`);
+}
+function validateLlmOverrides(value, hooks) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail("invocation.llm must be an object");
+    assertKeys(value, ["temperature", "maxTokens", "supportsJsonSchema", "extraParams", "contextLength", "enableThinking"], "invocation.llm");
+    validateOptionalFiniteNumber(value.temperature, "invocation.llm.temperature");
+    validateOptionalPositiveInteger(value.maxTokens, "invocation.llm.maxTokens");
+    validateOptionalPositiveInteger(value.contextLength, "invocation.llm.contextLength");
+    if (value.supportsJsonSchema !== undefined && typeof value.supportsJsonSchema !== "boolean")
+        fail("invocation.llm.supportsJsonSchema must be boolean");
+    if (value.enableThinking !== undefined && typeof value.enableThinking !== "boolean")
+        fail("invocation.llm.enableThinking must be boolean");
+    if (value.extraParams !== undefined) {
+        const issue = validateExtraParams(value.extraParams)[0];
+        if (issue)
+            fail(formatExtraParamsIssue("invocation.llm.extraParams", issue));
+    }
+    validateExtraParamsValue(value.extraParams, "invocation.llm.extraParams", hooks);
+}
+function validateSchema(value, label) {
+    if (!isRecord(value))
+        fail(`${label} must be an object`);
+    if (jsonBytes(value) > WORKFLOW_MAX_SCHEMA_BYTES)
+        fail(`${label} exceeds the 256 KiB resource limit`);
+}
+function validateExtraParamsValue(value, label, hooks) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail(`${label} must be an object`);
+    if (jsonBytes(value) > WORKFLOW_MAX_EXTRA_PARAMS_BYTES)
+        fail(`${label} exceeds the 64 KiB resource limit`);
+    const issue = validateExtraParams(value)[0];
+    if (issue)
+        fail(formatExtraParamsIssue(label, issue));
+    const policyError = hooks.validateExtraParams?.(value, label);
+    if (policyError)
+        fail(`${label}: ${policyError}`);
+}
+function validateStepExpressions(step, index, steps) {
+    const validateReference = (text, label, paramsAllowed) => {
+        const parsed = parseReference(text);
+        if (!parsed.ok)
+            fail(`${label} contains an invalid reference`);
+        if (parsed.expr.kind === "param" && !paramsAllowed)
+            fail(`${label} must reference a step output`);
+        if (parsed.expr.kind === "stepOutput") {
+            const referenced = steps.get(parsed.expr.stepId);
+            if (referenced === undefined || referenced >= index)
+                fail(`${label} references a non-earlier step`);
+        }
+    };
+    if (step.root) {
+        const unit = step.root.kind === "map" ? step.root.template : step.root;
+        if (step.root.kind === "map")
+            validateReference(step.root.over, `map ${step.root.id} over`, true);
+        for (const reference of unit.inputs ?? [])
+            validateReference(reference, `unit ${unit.id} inputs`, false);
+    }
+    if (step.route)
+        validateReference(step.route.input, `route ${step.stepId} input`, true);
+}
+function validateSource(value, label) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail(`${label} must be an object`);
+    assertKeys(value, ["path", "start", "end"], label);
+    if (typeof value.path !== "string" ||
+        !value.path ||
+        !Number.isSafeInteger(value.start) ||
+        !Number.isSafeInteger(value.end) ||
+        value.start < 1 ||
+        value.end < value.start)
+        fail(`${label} is invalid`);
+}
+function validateStringArray(value, label, max, unique) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) ||
+        value.length > max ||
+        !value.every((item) => typeof item === "string" && item.length > 0 && item.length <= MAX_STRING_LENGTH) ||
+        (unique && new Set(value).size !== value.length))
+        fail(`${label} is invalid`);
+}
+function validateOptionalFiniteNumber(value, label) {
+    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))
+        fail(`${label} must be finite`);
+}
+function validateOptionalPositiveInteger(value, label) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+        fail(`${label} must be a positive safe integer`);
+}
+function validateEndpoint(value, engine) {
+    try {
+        const url = new URL(value);
+        if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            !url.pathname.endsWith("/chat/completions"))
+            fail(`LLM engine ${engine} endpoint is not canonical`);
+    }
+    catch {
+        fail(`LLM engine ${engine} endpoint is invalid`);
+    }
+}
+function assertString(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_STRING_LENGTH)
+        fail(`${label} must be a non-empty bounded string`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(message) {
+    throw new UsageError(`Invalid frozen workflow plan: ${message}.`);
+}