@async/pipeline 0.2.3 → 0.3.0

package/dist/internal/core/index.js

@@ -1,10 +1,12 @@
 import { assertCacheStore, defaultPipelineCache, defineCache, isCacheDirective, mergeWithDefaultCacheStores, parseCacheRef } from "./cache.js";
+import { assertSupportedDeclaration, brandDeclaration, hasDeclarationKind, readDeclaration } from "./declaration.js";
 import { pipelineError } from "./errors.js";
 export * from "./cache.js";
+export * from "./declaration.js";
 export * from "./errors.js";
 export function sh(first, ...values) {
     if (typeof first === "function") {
-        return { kind: "deferred-shell", command: first };
+        return brandDeclaration({ kind: "deferred-shell", command: first }, "deferred-shell");
     }
     let command = "";
     for (let index = 0; index < first.length; index += 1) {
@@ -13,9 +15,11 @@ export function sh(first, ...values) {
             command += String(values[index]);
         }
     }
-    return { kind: "shell", command };
+    return brandDeclaration({ kind: "shell", command }, "shell");
 }
-const AGENT_STEP_FIELDS = new Set(["use", "prompt", "model"]);
+const AGENT_STEP_FIELDS = new Set(["use", "prompt", "model", "stdoutTo"]);
+const DECLARED_AGENT_STEP_FIELDS = new Set(["kind", ...AGENT_STEP_FIELDS]);
+const SHELL_STEP_FIELDS = new Set(["kind", "command"]);
 export function agent(options) {
     rejectUnknownFields(AGENT_STEP_FIELDS, options, "agent() step");
     const use = options.use;
@@ -25,9 +29,19 @@ export function agent(options) {
     if (typeof options.prompt !== "string" || options.prompt.length === 0) {
         throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent() requires a non-empty "prompt" string.');
     }
-    const step = { kind: "agent", use, prompt: options.prompt };
+    if (options.stdoutTo !== undefined) {
+        if (typeof options.stdoutTo !== "string" || options.stdoutTo.length === 0) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent() "stdoutTo" must be a non-empty path string.');
+        }
+        if (options.stdoutTo.startsWith("/") || /^[A-Za-z]:[\\/]/.test(options.stdoutTo) || options.stdoutTo.split(/[\\/]+/).includes("..")) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent() "stdoutTo" must be a relative path inside the task\'s working directory; absolute paths and ".." segments are rejected.');
+        }
+    }
+    const step = brandDeclaration({ kind: "agent", use, prompt: options.prompt }, "agent");
     if (options.model !== undefined)
         step.model = options.model;
+    if (options.stdoutTo !== undefined)
+        step.stdoutTo = options.stdoutTo;
     return step;
 }
 export function isAgentStep(step) {
@@ -40,118 +54,176 @@ export function task(definition, run) {
     if (definition.run !== undefined && run !== undefined) {
         throw pipelineError("ASYNC_PIPELINE_TASK_ARGUMENT_CONFLICT", "Do not pass a second task argument when config.run is defined.");
     }
-    return run === undefined ? definition : { ...definition, run };
+    return brandDeclaration(run === undefined ? definition : { ...definition, run }, "task");
 }
 export function job(definition) {
-    return definition;
+    return brandDeclaration(definition, "job");
 }
 function envVar(name, valuesOrOptions, options = {}) {
     if (!valuesOrOptions)
-        return { kind: "async-pipeline.env.var", name };
+        return brandDeclaration({ kind: "async-pipeline.env.var", name }, "env.var");
     if (isDefaultOnlyEnvOptions(valuesOrOptions) && Object.keys(valuesOrOptions).length === 1) {
-        return { kind: "async-pipeline.env.var", name, default: valuesOrOptions.default };
+        return brandDeclaration({ kind: "async-pipeline.env.var", name, default: valuesOrOptions.default }, "env.var");
     }
-    return {
+    return brandDeclaration({
         kind: "async-pipeline.env.var",
         name,
         values: { ...valuesOrOptions },
         default: options.default
-    };
+    }, "env.var");
 }
 export const env = {
     secret(name) {
-        return { kind: "async-pipeline.env.secret", name };
+        return brandDeclaration({ kind: "async-pipeline.env.secret", name }, "env.secret");
     },
     var: envVar
 };
 export const sandbox = {
     host() {
-        return { kind: "host" };
+        return brandDeclaration({ kind: "host" }, "sandbox.host");
     },
     lima(options = {}) {
-        return { kind: "lima", vm: options.vm };
+        return brandDeclaration({ kind: "lima", vm: options.vm }, "sandbox.lima");
     },
     docker(options) {
-        return {
+        return brandDeclaration({
             kind: "docker",
             image: options.image,
             workdir: options.workdir,
             volumes: options.volumes ? options.volumes.map((volume) => ({ ...volume })) : undefined
-        };
+        }, "sandbox.docker");
+    },
+    container(options) {
+        return brandDeclaration({
+            kind: "container",
+            image: options.image,
+            workdir: options.workdir,
+            volumes: options.volumes ? options.volumes.map((volume) => ({ ...volume })) : undefined
+        }, "sandbox.container");
+    }
+};
+export const execution = {
+    local(options = {}) {
+        return brandDeclaration({
+            kind: "local",
+            sandbox: options.sandbox,
+            provider: options.provider
+        }, "execution.local");
+    },
+    github(options) {
+        return brandDeclaration({
+            kind: "github",
+            sandbox: options.sandbox,
+            provider: options.provider,
+            runsOn: options.runsOn ? cloneRunsOnEntry(options.runsOn) : undefined,
+            runsOnMatrix: options.runsOnMatrix ? options.runsOnMatrix.map(cloneRunsOnEntry) : undefined
+        }, "execution.github");
     }
 };
 export const command = {
     policy(options = {}) {
-        return {
+        return brandDeclaration({
             rules: options.rules ? options.rules.map(cloneCommandRule) : [],
             fallback: options.fallback ? cloneCommandAction(options.fallback) : undefined,
             record: options.record,
             output: options.output ? { ...options.output } : undefined,
             shims: options.shims ? [...options.shims] : undefined
-        };
+        }, "command.policy");
     },
     rule(options) {
-        return cloneCommandRule(options);
+        return brandDeclaration(cloneCommandRule(options), "command.rule");
     },
     allow(options = {}) {
-        return { kind: "async-pipeline.command.allow", output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.allow", output: options.output ? { ...options.output } : undefined }, "command.allow");
     },
     deny(options = {}) {
-        return { kind: "async-pipeline.command.deny", message: options.message, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.deny", message: options.message, output: options.output ? { ...options.output } : undefined }, "command.deny");
     },
     mock(options = {}) {
-        return {
+        return brandDeclaration({
             kind: "async-pipeline.command.mock",
             code: options.code,
             stdout: options.stdout,
             stderr: options.stderr,
             output: options.output ? { ...options.output } : undefined
-        };
+        }, "command.mock");
     },
     requireApproval(options = {}) {
-        return { kind: "async-pipeline.command.requireApproval", message: options.message, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.requireApproval", message: options.message, output: options.output ? { ...options.output } : undefined }, "command.requireApproval");
     },
     requireEnvironment(options) {
-        return { kind: "async-pipeline.command.requireEnvironment", name: options.name, output: options.output ? { ...options.output } : undefined };
+        return brandDeclaration({ kind: "async-pipeline.command.requireEnvironment", name: options.name, output: options.output ? { ...options.output } : undefined }, "command.requireEnvironment");
     }
 };
 export const trigger = {
     manual() {
-        return { type: "manual" };
+        return brandDeclaration({ type: "manual" }, "trigger.manual");
     },
     github(options) {
-        return {
+        return brandDeclaration({
             type: "github",
             events: [...options.events],
             branches: options.branches ? [...options.branches] : undefined,
             paths: options.paths ? [...options.paths] : undefined,
             tags: options.tags ? [...options.tags] : undefined
-        };
+        }, "trigger.github");
     },
     cron(cron, options = {}) {
-        return { type: "schedule", cron, timezone: options.timezone };
+        return brandDeclaration({ type: "schedule", cron, timezone: options.timezone }, "trigger.cron");
     },
     schedule(cron) {
-        return { type: "schedule", cron };
+        return brandDeclaration({ type: "schedule", cron }, "trigger.schedule");
     }
 };
 export function dependsOn(...taskIds) {
-    return { kind: "async-pipeline.directive.dependsOn", taskIds };
+    return brandDeclaration({ kind: "async-pipeline.directive.dependsOn", taskIds }, "directive.dependsOn");
 }
 export const source = {
     git(definition) {
-        return { ...definition, type: "git" };
+        return brandDeclaration({ ...definition, type: "git" }, "source.git");
     },
     path(definition) {
-        return { ...definition, type: "path" };
+        return brandDeclaration({ ...definition, type: "path" }, "source.path");
     }
 };
-const PIPELINE_FIELDS = new Set(["name", "env", "commands", "agents", "sandboxes", "cache", "namedInputs", "taskDefaults", "triggers", "sync", "sources", "tasks", "jobs"]);
+export function tasks(definitions) {
+    return brandDeclaration(definitions, "section.tasks");
+}
+export function jobs(definitions) {
+    return brandDeclaration(definitions, "section.jobs");
+}
+export function triggers(definitions) {
+    return brandDeclaration(definitions, "section.triggers");
+}
+export function sources(definitions) {
+    return brandDeclaration(definitions, "section.sources");
+}
+export function taskDefaults(definitions) {
+    return brandDeclaration(definitions, "section.taskDefaults");
+}
+export function agents(definitions) {
+    return brandDeclaration(definitions, "section.agents");
+}
+export function sandboxes(definitions) {
+    return brandDeclaration(definitions, "section.sandboxes");
+}
+const PIPELINE_FIELDS = new Set(["name", "env", "commands", "agents", "sandboxes", "execution", "cache", "namedInputs", "taskDefaults", "triggers", "sync", "sources", "tasks", "jobs"]);
 const AGENT_PROFILE_FIELDS = new Set(["command", "model"]);
 const TASK_FIELDS = new Set(["description", "dependsOn", "inputs", "outputs", "cache", "retry", "timeout", "requires", "run", "steps"]);
-const JOB_FIELDS = new Set(["description", "target", "trigger", "environment", "env", "requires", "github"]);
+const JOB_FIELDS = new Set(["description", "target", "trigger", "environment", "env", "requires", "execution", "github"]);
+const EXECUTION_PROFILE_FIELDS = new Set(["kind", "sandbox", "provider", "runsOn", "runsOnMatrix"]);
 const GITHUB_JOB_FIELDS = new Set(["environment", "permissions", "runsOn", "runsOnMatrix"]);
 const GITHUB_PERMISSION_FIELDS = new Set(["contents", "idToken", "issues", "packages", "pullRequests"]);
+const CONTAINER_PROVIDERS = new Set(["auto", "docker", "apple-container", "lima"]);
+const SECTION_KINDS = {
+    agents: "section.agents",
+    sandboxes: "section.sandboxes",
+    taskDefaults: "section.taskDefaults",
+    triggers: "section.triggers",
+    sources: "section.sources",
+    tasks: "section.tasks",
+    jobs: "section.jobs"
+};
 function rejectUnknownFields(known, value, where) {
     for (const key of Object.keys(value)) {
         if (!known.has(key)) {
@@ -177,12 +249,21 @@ function validateDefinitionShape(definition) {
             throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", `Agent profile "${id}" requires "model": a non-empty string or env.var(...). The model is the profile's cache identity; the command is deliberately not.`);
         }
     }
-    for (const [id, taskDefinition] of Object.entries(definition.tasks ?? {})) {
-        rejectUnknownFields(TASK_FIELDS, taskDefinition, `Task "${id}"`);
-    }
     for (const [id, defaults] of Object.entries(definition.taskDefaults ?? {})) {
         rejectUnknownFields(TASK_FIELDS, defaults, `taskDefaults["${id}"]`);
     }
+    for (const [id, profile] of Object.entries(definition.execution ?? {})) {
+        rejectUnknownFields(EXECUTION_PROFILE_FIELDS, profile, `Execution profile "${id}"`);
+        if (profile.kind !== "local" && profile.kind !== "github") {
+            throw pipelineError("ASYNC_PIPELINE_EXECUTION_INVALID", `Execution profile "${id}" requires kind "local" or "github".`);
+        }
+        if (profile.provider !== undefined && !CONTAINER_PROVIDERS.has(profile.provider)) {
+            throw pipelineError("ASYNC_PIPELINE_EXECUTION_INVALID", `Execution profile "${id}" has unsupported provider "${profile.provider}". Use auto, docker, apple-container, or lima.`);
+        }
+        if (profile.kind === "local" && ("runsOn" in profile || "runsOnMatrix" in profile)) {
+            throw pipelineError("ASYNC_PIPELINE_EXECUTION_INVALID", `Execution profile "${id}" is local and cannot set GitHub runner fields. Use execution.github(...) for runsOn or runsOnMatrix.`);
+        }
+    }
     for (const [id, jobDefinition] of Object.entries(definition.jobs ?? {})) {
         rejectUnknownFields(JOB_FIELDS, jobDefinition, `Job "${id}"`);
         if (jobDefinition.github) {
@@ -193,10 +274,112 @@ function validateDefinitionShape(definition) {
         }
     }
 }
+function normalizePipelineSections(definition) {
+    return {
+        ...definition,
+        agents: normalizeSection("agents", definition.agents),
+        sandboxes: normalizeSection("sandboxes", definition.sandboxes),
+        taskDefaults: normalizeSection("taskDefaults", definition.taskDefaults),
+        triggers: normalizeSection("triggers", definition.triggers),
+        sources: normalizeSection("sources", definition.sources),
+        tasks: normalizeSection("tasks", definition.tasks),
+        jobs: normalizeSection("jobs", definition.jobs)
+    };
+}
+function normalizeSection(key, value) {
+    if (value === undefined)
+        return value;
+    if (!isObjectRecord(value)) {
+        throw pipelineError("ASYNC_PIPELINE_SECTION_INVALID", `Pipeline section "${key}" must be an object.`);
+    }
+    const expectedKind = SECTION_KINDS[key];
+    const metadata = assertSupportedDeclaration(value);
+    if (metadata) {
+        if (metadata.kind !== expectedKind) {
+            throw pipelineError("ASYNC_PIPELINE_SECTION_KIND_MISMATCH", `Pipeline section "${key}" expected declaration kind "${expectedKind}", received "${metadata.kind}".`);
+        }
+        return value;
+    }
+    return brandDeclaration(value, expectedKind);
+}
+function flattenTaskDefinitions(definitions) {
+    const tasks = [];
+    const seen = new Set();
+    function visit(node, path) {
+        for (const [key, value] of Object.entries(node)) {
+            validateTaskTreeKey(key, path);
+            if (!isObjectRecord(value)) {
+                throw pipelineError("ASYNC_PIPELINE_TASK_TREE_INVALID", `Task tree entry "${[...path, key].join(".")}" must be an object.`);
+            }
+            const isTask = isTaskDefinitionNode(value, path);
+            if (isTask) {
+                const id = taskTreeId(path, key);
+                validateLocalTaskId(id);
+                if (seen.has(id)) {
+                    throw pipelineError("ASYNC_PIPELINE_TASK_ID_COLLISION", `Task group entry "${[...path, key].join(".")}" normalizes to duplicate task id "${id}".`);
+                }
+                seen.add(id);
+                rejectUnknownFields(TASK_FIELDS, value, `Task "${id}"`);
+                tasks.push({ id, definition: value, groupPath: path });
+                continue;
+            }
+            if (key.includes(".")) {
+                throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Task group key "${key}" cannot contain ".". Use nested objects instead.`);
+            }
+            visit(value, [...path, key]);
+        }
+    }
+    visit(definitions, []);
+    return tasks;
+}
+function validateTaskTreeKey(key, path) {
+    if (!key.trim()) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", "Task group key cannot be empty.");
+    }
+    if (key.includes(":")) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Task group key "${key}" cannot contain ":". Use source namespaces through dependsOn instead.`);
+    }
+    if (path.length > 0 && key.includes(".")) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_GROUP_INVALID_KEY", `Nested task group key "${key}" cannot contain ".". Use nested objects instead.`);
+    }
+}
+function taskTreeId(path, key) {
+    const segments = path.length > 0 && (key === "default" || key === "index") ? path : [...path, key];
+    return segments.join(".");
+}
+function isTaskDefinitionNode(value, path) {
+    const metadata = assertSupportedDeclaration(value);
+    if (metadata?.kind === "task")
+        return true;
+    if (metadata?.kind.startsWith("section."))
+        return false;
+    if (metadata)
+        return false;
+    if (Object.keys(value).some((key) => TASK_FIELDS.has(key)))
+        return true;
+    return path.length === 0 && Object.keys(value).length === 0;
+}
+function resolveTaskDependencies(taskId, groupPath, dependencies, knownTaskIds) {
+    return dependencies.map((dependency) => resolveTaskDependency(taskId, groupPath, dependency, knownTaskIds));
+}
+function resolveTaskDependency(taskId, groupPath, dependency, knownTaskIds) {
+    if (isNamespacedTaskRef(dependency) || groupPath.length === 0)
+        return dependency;
+    const groupCandidate = [...groupPath, dependency].join(".");
+    const groupMatch = knownTaskIds.has(groupCandidate);
+    const rootMatch = knownTaskIds.has(dependency);
+    if (groupMatch && rootMatch && groupCandidate !== dependency) {
+        throw pipelineError("ASYNC_PIPELINE_TASK_DEPENDENCY_AMBIGUOUS", `Task "${taskId}" depends on ambiguous local task "${dependency}". Use "${groupCandidate}" or "${dependency}" explicitly.`);
+    }
+    if (groupMatch)
+        return groupCandidate;
+    return dependency;
+}
 export function definePipeline(definition) {
     return normalizePipeline(definition);
 }
 export function normalizePipeline(definition) {
+    definition = normalizePipelineSections(definition);
     validateDefinitionShape(definition);
     const namedInputs = definition.namedInputs ?? {};
     const cacheRegistry = normalizeCacheRegistry(definition.cache);
@@ -206,16 +389,18 @@ export function normalizePipeline(definition) {
         sources[id] = normalizeSource(id, sourceDefinition);
     }
     const tasks = {};
-    for (const [id, taskDefinition] of Object.entries(definition.tasks)) {
+    const flattenedTaskDefinitions = flattenTaskDefinitions(definition.tasks);
+    const knownTaskIds = new Set(flattenedTaskDefinitions.map((entry) => entry.id));
+    for (const { id, definition: taskDefinition, groupPath } of flattenedTaskDefinitions) {
         validateLocalTaskId(id);
         const defaults = definition.taskDefaults?.[id] ?? definition.taskDefaults?.[taskName(id)] ?? {};
         const merged = { ...defaults, ...taskDefinition };
         const runItems = merged.steps ? [...merged.steps] : runItemsFromDefinition(merged.run);
         const { steps, cacheDirectives, dependsOnDirectives } = partitionRunItems(runItems);
-        const liftedDependsOn = uniqueTaskIds([
+        const liftedDependsOn = resolveTaskDependencies(id, groupPath, uniqueTaskIds([
             ...(merged.dependsOn ?? []),
             ...dependsOnDirectives.flatMap((directive) => directive.taskIds)
-        ]);
+        ]), knownTaskIds);
         const cache = normalizeCache(merged.cache ?? cacheDirectives[0], cacheRegistry);
         const retry = normalizeRetry(merged.retry);
         const timeoutMs = normalizeTimeout(merged.timeout);
@@ -246,6 +431,7 @@ export function normalizePipeline(definition) {
         commands: definition.commands ? normalizeCommandPolicy(definition.commands) : undefined,
         agents: normalizeAgents(definition.agents),
         sandboxes: normalizeSandboxes(definition.sandboxes),
+        execution: normalizeExecutionProfiles(definition.execution),
         cache: cacheRegistry,
         namedInputs,
         triggers: definition.triggers ?? {},
@@ -260,6 +446,12 @@ export function normalizePipeline(definition) {
 function isDefaultOnlyEnvOptions(value) {
     return typeof value.default === "string";
 }
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEnvVarRef(value) {
+    return isObjectRecord(value) && value.kind === "async-pipeline.env.var";
+}
 function normalizeAgents(definitions = {}) {
     const normalized = {};
     for (const [id, profile] of Object.entries(definitions)) {
@@ -277,11 +469,18 @@ function normalizeSandboxes(definitions = {}) {
     }
     return normalized;
 }
+function normalizeExecutionProfiles(definitions = {}) {
+    const normalized = {};
+    for (const [id, definition] of Object.entries(definitions)) {
+        normalized[id] = cloneExecutionProfile(definition);
+    }
+    return normalized;
+}
 function normalizeCommandPolicy(policy) {
     return command.policy(policy);
 }
 function cloneSandboxDefinition(definition) {
-    if (definition.kind === "docker") {
+    if (definition.kind === "docker" || definition.kind === "container") {
         return {
             ...definition,
             volumes: definition.volumes ? definition.volumes.map((volume) => ({ ...volume })) : undefined
@@ -289,6 +488,19 @@ function cloneSandboxDefinition(definition) {
     }
     return { ...definition };
 }
+function cloneExecutionProfile(definition) {
+    if (definition.kind === "github") {
+        return {
+            ...definition,
+            runsOn: definition.runsOn ? cloneRunsOnEntry(definition.runsOn) : undefined,
+            runsOnMatrix: definition.runsOnMatrix ? definition.runsOnMatrix.map(cloneRunsOnEntry) : undefined
+        };
+    }
+    return { ...definition };
+}
+function cloneRunsOnEntry(entry) {
+    return Array.isArray(entry) ? [...entry] : entry;
+}
 function cloneCommandRule(rule) {
     return {
         exact: rule.exact ? [...rule.exact] : undefined,
@@ -323,7 +535,70 @@ function validateJobRunsOn(jobId, github) {
         }
     }
 }
+function githubConfigFromExecution(profile) {
+    if (!profile || profile.kind !== "github")
+        return undefined;
+    return {
+        runsOn: profile.runsOn ? cloneRunsOnEntry(profile.runsOn) : undefined,
+        runsOnMatrix: profile.runsOnMatrix ? profile.runsOnMatrix.map(cloneRunsOnEntry) : undefined
+    };
+}
+export function githubConfigForJob(pipeline, jobDefinition) {
+    const profileGithub = githubConfigFromExecution(jobDefinition.execution ? pipeline.execution[jobDefinition.execution] : undefined);
+    if (!profileGithub && !jobDefinition.github)
+        return undefined;
+    return {
+        ...profileGithub,
+        ...jobDefinition.github
+    };
+}
+function validateExecutionProfiles(pipeline) {
+    for (const [id, profile] of Object.entries(pipeline.execution)) {
+        if (profile.sandbox !== undefined) {
+            const sandboxDefinition = pipeline.sandboxes[profile.sandbox];
+            if (!sandboxDefinition) {
+                throw pipelineError("ASYNC_PIPELINE_EXECUTION_UNKNOWN_SANDBOX", `Execution profile "${id}" references unknown sandbox "${profile.sandbox}". Declare it under sandboxes.`);
+            }
+            if (profile.provider !== undefined && sandboxDefinition.kind !== "container") {
+                throw pipelineError("ASYNC_PIPELINE_EXECUTION_PROVIDER_MISMATCH", `Execution profile "${id}" sets provider "${profile.provider}", but providers only apply to sandbox.container(...) definitions.`);
+            }
+        }
+        else if (profile.provider !== undefined) {
+            throw pipelineError("ASYNC_PIPELINE_EXECUTION_PROVIDER_MISMATCH", `Execution profile "${id}" sets provider "${profile.provider}" without a sandbox.`);
+        }
+        if (profile.kind === "github") {
+            validateJobRunsOn(`execution:${id}`, githubConfigFromExecution(profile));
+        }
+    }
+}
+function validateJobExecution(pipeline, jobDefinition) {
+    if (!jobDefinition.execution)
+        return;
+    const profile = pipeline.execution[jobDefinition.execution];
+    if (!profile) {
+        throw pipelineError("ASYNC_PIPELINE_EXECUTION_UNKNOWN", `Job "${jobDefinition.id}" references unknown execution profile "${jobDefinition.execution}". Declare it under execution.`);
+    }
+    const effectiveGithub = githubConfigForJob(pipeline, jobDefinition);
+    validateJobRunsOn(jobDefinition.id, effectiveGithub);
+    if (profile.kind === "github" && profile.provider === "apple-container") {
+        validateAppleContainerRunsOn(jobDefinition.id, effectiveGithub);
+    }
+}
+function validateAppleContainerRunsOn(jobId, github) {
+    const entries = github?.runsOnMatrix ?? (github?.runsOn ? [github.runsOn] : []);
+    if (entries.length === 0) {
+        throw pipelineError("ASYNC_PIPELINE_EXECUTION_RUNNER_UNSUPPORTED", `Job "${jobId}" uses provider "apple-container", which requires an explicit self-hosted macOS runner label set.`);
+    }
+    for (const entry of entries) {
+        const labels = Array.isArray(entry) ? entry : [entry];
+        const normalized = labels.map((label) => label.toLowerCase());
+        if (!Array.isArray(entry) || !normalized.includes("self-hosted") || !normalized.includes("macos")) {
+            throw pipelineError("ASYNC_PIPELINE_EXECUTION_RUNNER_UNSUPPORTED", `Job "${jobId}" uses provider "apple-container", which requires a self-hosted macOS runner label set.`);
+        }
+    }
+}
 export function validatePipeline(pipeline) {
+    validateExecutionProfiles(pipeline);
     for (const taskDefinition of Object.values(pipeline.tasks)) {
         for (const dependency of taskDefinition.dependsOn) {
             if (!pipeline.tasks[dependency] && !isKnownExternalTaskRef(pipeline, dependency)) {
@@ -353,7 +628,9 @@ export function validatePipeline(pipeline) {
                 throw new Error(`Job "${jobDefinition.id}" references missing trigger "${triggerId}".`);
             }
         }
-        validateJobRunsOn(jobDefinition.id, jobDefinition.github);
+        validateJobExecution(pipeline, jobDefinition);
+        if (!jobDefinition.execution)
+            validateJobRunsOn(jobDefinition.id, jobDefinition.github);
     }
     validateSyncConfig(pipeline);
     // Fail fast on named-input cycles at definePipeline time instead of
@@ -772,7 +1049,8 @@ function partitionRunItems(items) {
     const steps = [];
     const cacheDirectives = [];
     const dependsOnDirectives = [];
-    for (const item of items) {
+    for (const rawItem of items) {
+        const item = normalizeDeclaredRunItem(rawItem);
         if (isCacheDirective(item)) {
             cacheDirectives.push(item);
             continue;
@@ -788,10 +1066,49 @@ function partitionRunItems(items) {
     }
     return { steps, cacheDirectives, dependsOnDirectives };
 }
+function normalizeDeclaredRunItem(item) {
+    const metadata = assertSupportedDeclaration(item);
+    if (!metadata || !isObjectRecord(item))
+        return item;
+    if (metadata.kind === "shell") {
+        rejectUnknownFields(SHELL_STEP_FIELDS, item, "shell declaration");
+        const command = item.command;
+        if (typeof command !== "string") {
+            throw pipelineError("ASYNC_PIPELINE_DECLARATION_INVALID", "Shell declaration requires a string command.");
+        }
+        return brandDeclaration({ kind: "shell", command }, "shell");
+    }
+    if (metadata.kind === "deferred-shell") {
+        rejectUnknownFields(SHELL_STEP_FIELDS, item, "deferred shell declaration");
+        const command = item.command;
+        if (typeof command !== "function") {
+            throw pipelineError("ASYNC_PIPELINE_DECLARATION_INVALID", "Deferred shell declaration requires a command function.");
+        }
+        return brandDeclaration({ kind: "deferred-shell", command: command }, "deferred-shell");
+    }
+    if (metadata.kind === "agent") {
+        rejectUnknownFields(DECLARED_AGENT_STEP_FIELDS, item, "agent declaration");
+        const use = item.use;
+        const prompt = item.prompt;
+        if ((typeof use !== "string" && !isEnvVarRef(use)) || (typeof use === "string" && use.length === 0)) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent declaration requires "use": a non-empty profile id or env.var(...).');
+        }
+        if (typeof prompt !== "string" || prompt.length === 0) {
+            throw pipelineError("ASYNC_PIPELINE_AGENT_INVALID", 'agent declaration requires a non-empty "prompt" string.');
+        }
+        const step = brandDeclaration({ kind: "agent", use: use, prompt }, "agent");
+        if (item.model !== undefined)
+            step.model = item.model;
+        if (item.stdoutTo !== undefined)
+            step.stdoutTo = item.stdoutTo;
+        return step;
+    }
+    return item;
+}
 function isDependsOnDirective(value) {
     return Boolean(value)
         && typeof value === "object"
-        && value.kind === "async-pipeline.directive.dependsOn";
+        && (value.kind === "async-pipeline.directive.dependsOn" || hasDeclarationKind(value, "directive.dependsOn"));
 }
 function uniqueTaskIds(taskIds) {
     return [...new Set(taskIds)];