@qaick/executor 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,15 @@
+# QAick Executor
+
+`@qaick/executor` is the host-neutral execution domain for QAick Flow and Project artifacts. It owns orchestration, bindings, control blocks, Action Executor dispatch, lifecycle events, cancellation, retries, timing, and live execution results.
+
+Host integration and transport implementations remain outside this package. Register host-provided Action Executors through the public API:
+
+```ts
+import { createMigratedExecutor } from '@qaick/executor';
+
+const executor = createMigratedExecutor({ actionExecutors: [actionExecutor] });
+const run = await executor.execute(request);
+const result = await run.result;
+```
+
+The package requires Node 20 or newer and depends on the published `@qaick/contract` package. Build with `npm run build`, run tests with `npm test`, and inspect publication contents with `npm pack --dry-run`.

package/dist/executor.d.ts

@@ -0,0 +1,30 @@
+import type { ActionExecutor, ControlCommand, ExecutionControlState, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun } from './types.js';
+export declare function createExecutor(configuration?: ExecutorConfiguration): Executor;
+export declare class DefaultExecutor implements Executor {
+    private readonly runs;
+    private readonly actionExecutors;
+    private readonly maxTimeoutMs;
+    constructor(configuration?: ExecutorConfiguration);
+    registerActionExecutor(executor: ActionExecutor): void;
+    execute(request: ExecutorRequest): Promise<ExecutorRun>;
+    cancel(requestId: string): Promise<void>;
+    control(requestId: string, command: ControlCommand): Promise<void>;
+    controlState(requestId: string): ExecutionControlState | undefined;
+    events(requestId: string): AsyncIterable<ExecutorEvent>;
+    result(requestId: string): Promise<ExecutorResult>;
+    retryAction(requestId: string, stepId: string, invocationPath?: string[]): Promise<void>;
+    retryOperation(requestId: string, stepId: string, invocationPath?: string[]): Promise<void>;
+    runFromHere(requestId: string, stepId: string, invocationPath?: string[]): Promise<ExecutorRun | undefined>;
+    private run;
+    private executeProject;
+    private executeFlow;
+    private executeStep;
+    private executeControl;
+    private executeAction;
+    private boundary;
+    private pauseAtBoundary;
+    private emit;
+    private finish;
+    private baseResult;
+    private failure;
+}

package/dist/executor.js

@@ -0,0 +1,556 @@
+const MAX_TIMEOUT_MS = 300_000;
+export function createExecutor(configuration = {}) {
+    return new DefaultExecutor(configuration);
+}
+export class DefaultExecutor {
+    runs = new Map();
+    actionExecutors;
+    maxTimeoutMs;
+    constructor(configuration = {}) {
+        this.actionExecutors = [...(configuration.actionExecutors ?? [])];
+        this.maxTimeoutMs = configuration.maxTimeoutMs ?? MAX_TIMEOUT_MS;
+    }
+    registerActionExecutor(executor) { this.actionExecutors.push(executor); }
+    async execute(request) {
+        let resolve;
+        const result = new Promise(promiseResolve => { resolve = promiseResolve; });
+        const run = {
+            request, resolve, events: [], listeners: [], abort: new AbortController(), cancelled: false,
+            timedOut: false, controlState: 'idle', pauseRequested: false, stepRequested: false,
+            controlWaiters: [], hitBreakpoints: new Set(), stopAfter: request.debugSession?.stopAfterStepId,
+            startedMs: Date.now(), pausedDurationMs: 0,
+        };
+        this.runs.set(request.requestId, run);
+        void this.run(run);
+        return { requestId: request.requestId, result };
+    }
+    async cancel(requestId) {
+        const run = this.runs.get(requestId);
+        if (!run || run.result)
+            return;
+        run.cancelled = true;
+        run.controlState = 'stopped';
+        run.abort.abort();
+        run.controlWaiters.splice(0).forEach(resolve => resolve());
+        run.listeners.splice(0).forEach(resolve => resolve());
+    }
+    async control(requestId, command) {
+        const run = this.runs.get(requestId);
+        if (!run || run.result)
+            return;
+        if (command.type === 'stop')
+            return this.cancel(requestId);
+        if (command.type === 'stop-after') {
+            run.stopAfter = command.stepId;
+            return;
+        }
+        if (command.type === 'pause') {
+            if (run.controlState !== 'paused' && run.controlState !== 'pause-requested') {
+                run.pauseRequested = true;
+                run.controlState = 'pause-requested';
+                this.emit(run, 'waiting', 'waiting', 'Pause requested.', undefined, { type: 'pause', });
+            }
+            return;
+        }
+        if (command.type === 'resume') {
+            run.pauseRequested = false;
+            run.stepRequested = false;
+            run.controlState = 'resuming';
+            run.controlWaiters.splice(0).forEach(resolve => resolve());
+            return;
+        }
+        if (command.type === 'step' && run.controlState === 'paused') {
+            run.pauseRequested = false;
+            run.stepRequested = true;
+            run.controlState = 'resuming';
+            run.controlWaiters.splice(0).forEach(resolve => resolve());
+        }
+    }
+    controlState(requestId) { return this.runs.get(requestId)?.controlState; }
+    async *events(requestId) {
+        const run = this.runs.get(requestId);
+        if (!run)
+            return;
+        let index = 0;
+        while (true) {
+            while (index < run.events.length)
+                yield run.events[index++];
+            if (run.result)
+                return;
+            await new Promise(resolve => run.listeners.push(resolve));
+        }
+    }
+    async result(requestId) {
+        const run = this.runs.get(requestId);
+        if (!run)
+            throw new Error(`Unknown execution ${requestId}.`);
+        if (run.result)
+            return run.result;
+        return new Promise(resolve => {
+            const previous = run.resolve;
+            run.resolve = value => { previous(value); resolve(value); };
+        });
+    }
+    async retryAction(requestId, stepId, invocationPath) {
+        const run = this.runs.get(requestId);
+        if (!run?.result || run.cancelled || run.abort.signal.aborted)
+            return;
+        const located = findStep(run.result.steps, stepId, invocationPath);
+        const definition = findDefinition(run.request.executionPackage.steps, stepId, invocationPath);
+        if (!located || !definition || definition.kind === 'operation' || definition.control || located.state === 'skipped')
+            return;
+        this.emit(run, 'waiting', 'waiting', `Interactive retry requested for ${located.name}.`, definition, { type: 'step', stepId });
+        try {
+            const action = await this.executeAction(run, definition, located.inputs);
+            const previous = located.attempts ?? [];
+            located.attempts = [...previous, ...action.attempts.map(attempt => ({ ...attempt, kind: 'interactive' }))];
+            located.outputs = action.outputs;
+            located.evidence = action.evidence;
+            located.state = 'finished';
+            located.terminalReason = 'completed';
+            delete located.error;
+            if (run.result.state === 'failed') {
+                run.result.state = 'completed';
+                run.result.terminalReason = 'completed';
+                delete run.result.error;
+            }
+            this.emit(run, 'step_finished', 'finished', `${located.name} interactive retry completed.`, definition);
+        }
+        catch (cause) {
+            located.state = 'failed';
+            located.terminalReason = 'failed';
+            located.error = this.failure(cause, run);
+            this.emit(run, 'step_finished', 'failed', `${located.name} interactive retry failed.`, definition);
+        }
+    }
+    async retryOperation(requestId, stepId, invocationPath) {
+        const run = this.runs.get(requestId);
+        if (!run?.result || run.cancelled || run.abort.signal.aborted)
+            return;
+        const located = findStep(run.result.steps, stepId, invocationPath);
+        const definition = findDefinition(run.request.executionPackage.steps, stepId, invocationPath);
+        if (!located || !definition?.children?.length || definition.control || definition.kind !== 'operation')
+            return;
+        const nested = await this.executeFlow(run, definition.children, located.inputs, [...(located.invocationPath ?? []).slice(0, -1), definition.id], new Date().toISOString());
+        const previous = located.attempts ?? [];
+        located.attempts = [...previous, { attempt: previous.length + 1, kind: 'interactive', state: nested.state === 'completed' ? 'finished' : 'failed', startedAt: nested.startedAt, finishedAt: nested.finishedAt, inputs: located.inputs, outputs: nested.steps.at(-1)?.outputs ?? {}, durationMs: nested.steps.reduce((sum, child) => sum + child.durationMs, 0), children: nested.steps, ...(nested.error ? { error: nested.error } : {}) }];
+        located.children = nested.steps;
+        located.outputs = nested.steps.at(-1)?.outputs ?? {};
+        located.state = nested.state === 'completed' ? 'finished' : nested.state === 'cancelled' ? 'cancelled' : 'failed';
+        located.terminalReason = nested.terminalReason ?? (located.state === 'finished' ? 'completed' : 'failed');
+        located.error = nested.error;
+        if (located.state === 'finished' && run.result.state === 'failed') {
+            run.result.state = 'completed';
+            run.result.terminalReason = 'completed';
+            delete run.result.error;
+        }
+    }
+    async runFromHere(requestId, stepId, invocationPath) {
+        const run = this.runs.get(requestId);
+        if (!run)
+            return undefined;
+        if (invocationPath?.length)
+            return undefined;
+        const index = run.request.executionPackage.steps.findIndex(step => step.id === stepId);
+        if (index < 0)
+            return undefined;
+        const selected = findStep(run.result?.steps ?? [], stepId, invocationPath);
+        if (!selected)
+            return undefined;
+        const requestIdForRun = `${requestId}:from:${stepId}`;
+        const remainingSteps = run.request.executionPackage.steps.slice(index).map((step, offset) => offset === 0
+            ? { ...step, bindings: undefined, staticInputs: { ...(step.staticInputs ?? {}), ...selected.inputs } }
+            : step);
+        return this.execute({
+            ...run.request,
+            requestId: requestIdForRun,
+            executionPackage: { ...run.request.executionPackage, steps: remainingSteps, target: { kind: 'flow', id: run.request.executionPackage.target.id, name: run.request.executionPackage.target.name } },
+            inputs: selected.inputs,
+        });
+    }
+    async run(run) {
+        const startedAt = new Date().toISOString();
+        const timeoutMs = run.request.options?.timeoutMs;
+        if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > this.maxTimeoutMs)) {
+            this.finish(run, this.baseResult(run, startedAt, 'failed', { code: 'PREFLIGHT_ERROR', message: `Timeout must be between 0 and ${this.maxTimeoutMs} ms.` }));
+            return;
+        }
+        let timeout;
+        if (timeoutMs !== undefined)
+            timeout = setTimeout(() => { run.timedOut = true; run.abort.abort(); }, timeoutMs);
+        this.emit(run, 'run_started', 'created', 'Execution accepted.');
+        this.emit(run, 'preflight_started', 'preflighting', 'Validating execution package.');
+        const issues = preflight(run.request.executionPackage, run.request.inputs, run.request.runtimeValues ?? {});
+        if (issues.length > 0 || run.request.options?.dryRun) {
+            const result = this.baseResult(run, startedAt, issues.length > 0 ? 'failed' : 'completed', undefined, issues);
+            if (timeout)
+                clearTimeout(timeout);
+            this.finish(run, result);
+            return;
+        }
+        run.controlState = 'running';
+        try {
+            const result = run.request.executionPackage.target.kind === 'project'
+                ? await this.executeProject(run, startedAt)
+                : await this.executeFlow(run, run.request.executionPackage.steps, run.request.inputs, [], startedAt);
+            if (timeout)
+                clearTimeout(timeout);
+            this.finish(run, result);
+        }
+        catch (cause) {
+            if (timeout)
+                clearTimeout(timeout);
+            const error = this.failure(cause, run);
+            this.finish(run, this.baseResult(run, startedAt, run.timedOut ? 'failed' : 'cancelled', error));
+        }
+    }
+    async executeProject(run, startedAt) {
+        const pkg = run.request.executionPackage;
+        const children = [];
+        let inputs = { ...run.request.inputs };
+        for (const flow of pkg.flows ?? []) {
+            if (run.cancelled || run.abort.signal.aborted)
+                throw new Error('Execution cancelled.');
+            const child = await this.executeFlow(run, flow.steps, inputs, [flow.id], startedAt, { kind: 'flow', id: flow.id, name: flow.name });
+            children.push(child);
+            if (child.state !== 'completed')
+                return this.baseResult(run, startedAt, child.state, child.error, undefined, children);
+            const last = child.steps.at(-1)?.outputs ?? {};
+            const mapped = flow.outputBindings
+                ? Object.fromEntries(Object.entries(flow.outputBindings).flatMap(([name, ref]) => {
+                    const match = /^\$outputs\.(.+)$/.exec(ref);
+                    return match && last[match[1]] !== undefined ? [[name, last[match[1]]]] : [];
+                }))
+                : last;
+            inputs = { ...inputs, ...mapped };
+        }
+        return this.baseResult(run, startedAt, 'completed', undefined, undefined, children);
+    }
+    async executeFlow(run, steps, initialInputs, path, startedAt, target = run.request.executionPackage.target, signal = run.abort.signal) {
+        const outputsById = new Map();
+        const results = [];
+        let state = 'completed';
+        let error;
+        for (const step of orderSteps(steps)) {
+            if (run.cancelled || signal.aborted)
+                throw new Error('Execution cancelled.');
+            await this.boundary(run, step, [...path, step.id], signal);
+            const result = await this.executeStep(run, step, initialInputs, outputsById, path, signal);
+            results.push(result);
+            outputsById.set(step.id, result.outputs);
+            if (result.state === 'failed' || result.state === 'cancelled') {
+                state = result.state === 'cancelled' ? 'cancelled' : 'failed';
+                error = result.error;
+                if (step.control?.onError !== 'continue')
+                    break;
+            }
+        }
+        return {
+            ...this.baseResult(run, startedAt, state, error),
+            target,
+            steps: results,
+        };
+    }
+    async executeStep(run, step, scope, outputsById, path, signal = run.abort.signal) {
+        const startedMs = Date.now();
+        const invocationPath = [...path, step.id];
+        const base = { id: step.id, name: step.name, kind: step.kind ?? 'action', inputs: {}, outputs: {}, invocationId: invocationPath.join('/'), invocationPath };
+        if (step.dependsOn?.some(id => !outputsById.has(id)))
+            return { ...base, state: 'skipped', durationMs: 0, terminalReason: 'dependency-skipped' };
+        const inputs = { ...(step.staticInputs ?? {}), ...(step.bindings ? resolveBindings(step.bindings, scope, outputsById) : {}) };
+        this.emit(run, 'step_started', 'running', `${step.name} started.`, step);
+        try {
+            if (step.delayMs) {
+                this.emit(run, 'waiting', 'waiting', `${step.name} is waiting for ${step.delayMs} ms.`, step);
+                await delay(step.delayMs, signal);
+            }
+            if (step.control) {
+                const controlResult = await this.executeControl(run, step, inputs, scope, outputsById, path, signal);
+                return { ...base, ...controlResult, inputs, durationMs: Date.now() - startedMs };
+            }
+            if (step.kind === 'operation' && step.children) {
+                const nested = await this.executeFlow(run, step.children, { ...scope, ...inputs }, [...path, step.id], new Date().toISOString(), run.request.executionPackage.target, signal);
+                const outputs = nested.steps.at(-1)?.outputs ?? {};
+                const result = { ...base, state: nested.state === 'completed' ? 'finished' : nested.state, inputs, outputs, durationMs: Date.now() - startedMs, children: nested.steps, terminalReason: nested.terminalReason ?? (nested.state === 'completed' ? 'completed' : 'failed'), error: nested.error };
+                this.emit(run, 'step_finished', result.state, `${step.name} ${result.state}.`, step);
+                return result;
+            }
+            const actionResult = await this.executeAction(run, step, inputs, signal);
+            const result = { ...base, state: 'finished', inputs, outputs: actionResult.outputs, durationMs: Date.now() - startedMs, terminalReason: 'completed', attempts: actionResult.attempts, evidence: actionResult.evidence };
+            this.emit(run, 'step_finished', 'finished', `${step.name} finished.`, step);
+            if (run.stopAfter === step.id) {
+                run.stopAfter = undefined;
+                await this.pauseAtBoundary(run, step);
+            }
+            return result;
+        }
+        catch (cause) {
+            const failure = this.failure(cause, run, signal);
+            const state = run.timedOut ? 'failed' : run.cancelled || signal.aborted ? 'cancelled' : 'failed';
+            const result = { ...base, state, inputs, durationMs: Date.now() - startedMs, terminalReason: run.timedOut ? 'timeout' : state === 'cancelled' ? 'cancelled' : 'failed', error: failure };
+            this.emit(run, 'step_finished', state, `${step.name} ${state}.`, step);
+            return result;
+        }
+    }
+    async executeControl(run, step, inputs, scope, outputs, path, signal = run.abort.signal) {
+        const control = step.control;
+        if (control.condition !== undefined && !evaluateCondition(control.condition, { ...scope, ...inputs }, outputs))
+            return { state: 'skipped', outputs: {}, terminalReason: 'condition-skipped' };
+        if (control.type === 'repeat') {
+            const total = control.iterations ?? 1;
+            const children = [];
+            for (let current = 1; current <= total; current++) {
+                const child = await this.executeFlow(run, step.children ?? [], { ...scope, ...inputs }, [...path, step.id, String(current)], new Date().toISOString(), run.request.executionPackage.target, signal);
+                children.push(...child.steps.map(item => ({ ...item, iteration: { loopId: step.id, current, total } })));
+                if (child.state !== 'completed' && control.onError !== 'continue')
+                    return { state: child.state, outputs: child.steps.at(-1)?.outputs ?? {}, children, terminalReason: child.terminalReason, error: child.error };
+                if (control.iterationDelayMs)
+                    await delay(control.iterationDelayMs, signal);
+            }
+            return { state: 'finished', outputs: children.at(-1)?.outputs ?? {}, children, terminalReason: 'completed' };
+        }
+        if (control.type === 'branch') {
+            const branch = control.branches?.find(candidate => evaluateCondition(candidate.condition, { ...scope, ...inputs }, outputs));
+            if (!branch)
+                return { state: 'skipped', outputs: {}, terminalReason: 'branch-skipped' };
+            const nested = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.request.executionPackage.target, signal);
+            return { state: nested.state === 'completed' ? 'finished' : nested.state, outputs: nested.steps.at(-1)?.outputs ?? {}, children: nested.steps, terminalReason: nested.terminalReason, error: nested.error };
+        }
+        if (control.type === 'parallel') {
+            const branches = control.branches ?? [];
+            const selected = branches.filter(branch => evaluateCondition(branch.condition, { ...scope, ...inputs }, outputs));
+            const controllers = selected.map(() => new AbortController());
+            let winnerIndex;
+            const branchRuns = await Promise.all(selected.map(async (branch, index) => {
+                try {
+                    const result = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.request.executionPackage.target, controllers[index].signal);
+                    if (control.join === 'first' && result.state === 'completed' && winnerIndex === undefined) {
+                        winnerIndex = index;
+                        controllers.forEach((controller, candidate) => { if (candidate !== index)
+                            controller.abort(); });
+                    }
+                    return { branch, result };
+                }
+                catch (cause) {
+                    return { branch, result: this.baseResult(run, new Date().toISOString(), controllers[index].signal.aborted ? 'cancelled' : 'failed', this.failure(cause, run, controllers[index].signal)) };
+                }
+            }));
+            const nested = branchRuns.map(item => item.result);
+            const children = nested.flatMap(item => item.steps);
+            const considered = control.join === 'first' && winnerIndex !== undefined ? [branchRuns[winnerIndex]] : branchRuns;
+            const failed = considered.find(item => item.result.state !== 'completed');
+            const branchOutputs = considered.map(({ branch, result }) => ({ id: branch.id, outputs: result.steps.at(-1)?.outputs ?? {} }));
+            const mergedOutputs = mergeBranchOutputs(branchOutputs, control.mergeBindings, control.merge ?? (control.join === 'first' ? 'first' : 'collect'));
+            return { state: failed ? invocationState(failed.result.state) : 'finished', outputs: mergedOutputs, children, terminalReason: failed?.result.terminalReason ?? 'parallel-joined', error: failed?.result.error };
+        }
+        const nested = await this.executeFlow(run, step.children ?? [], { ...scope, ...inputs }, [...path, step.id], new Date().toISOString(), run.request.executionPackage.target, signal);
+        return { state: nested.state === 'completed' ? 'finished' : nested.state, outputs: nested.steps.at(-1)?.outputs ?? {}, children: nested.steps, terminalReason: nested.terminalReason, error: nested.error };
+    }
+    async executeAction(run, step, inputs, signal = run.abort.signal) {
+        if (run.request.options?.dryRun)
+            return { outputs: {}, attempts: [] };
+        const executor = this.actionExecutors.find(candidate => candidate.supports(step.action));
+        if (!executor)
+            throw failure('UNSUPPORTED_ACTION', `No Action Executor is registered for ${step.action}.`);
+        const maxAttempts = Math.max(1, step.retry?.maxAttempts ?? 1);
+        const attempts = [];
+        let lastFailure;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const startedAt = new Date().toISOString();
+            const startedMs = Date.now();
+            try {
+                const context = { action: step.action, inputs, environment: run.request.environment, runtimeValues: run.request.runtimeValues ?? {}, step, signal };
+                const raw = await executor.execute(context);
+                const normalized = isActionResult(raw) ? raw : { outputs: raw };
+                const finishedAt = new Date().toISOString();
+                attempts.push({ attempt, state: 'finished', startedAt, finishedAt, inputs, outputs: normalized.outputs, durationMs: Date.now() - startedMs, evidence: normalized.evidence });
+                return { outputs: normalized.outputs, evidence: normalized.evidence, attempts };
+            }
+            catch (cause) {
+                lastFailure = this.failure(cause, run, signal);
+                attempts.push({ attempt, state: run.timedOut ? 'failed' : run.cancelled || signal.aborted ? 'cancelled' : 'failed', startedAt, finishedAt: new Date().toISOString(), inputs, outputs: {}, durationMs: Date.now() - startedMs, error: lastFailure });
+                if (attempt < maxAttempts && step.retry?.delayMs)
+                    await delay(step.retry.delayMs, signal);
+            }
+        }
+        throw lastFailure ?? failure('ACTION_FAILED', `Action ${step.action} failed.`);
+    }
+    async boundary(run, step, path, signal = run.abort.signal) {
+        const breakpointKey = stepPathForBoundary(step, run, path);
+        const breakpoints = run.request.debugSession?.breakpoints ?? [];
+        if (breakpoints.includes(step.id) && !run.hitBreakpoints.has(breakpointKey)) {
+            run.hitBreakpoints.add(breakpointKey);
+            run.pauseRequested = true;
+            this.emit(run, 'waiting', 'waiting', `Breakpoint reached before ${step.name}.`, step, { type: 'pause', stepId: step.id });
+        }
+        if (run.pauseRequested || run.controlState === 'pause-requested')
+            await this.pauseAtBoundary(run, step);
+        if (run.cancelled || signal.aborted)
+            throw new Error('Execution cancelled.');
+    }
+    async pauseAtBoundary(run, step) {
+        run.controlState = 'paused';
+        run.pausedStartedMs = Date.now();
+        this.emit(run, 'waiting', 'waiting', `Paused before ${step.name}.`, step, { type: 'pause', stepId: step.id });
+        await new Promise(resolve => run.controlWaiters.push(resolve));
+        run.pausedDurationMs += Date.now() - (run.pausedStartedMs ?? Date.now());
+        run.pausedStartedMs = undefined;
+        run.controlState = 'running';
+        if (run.stepRequested) {
+            run.stepRequested = false;
+            run.pauseRequested = true;
+        }
+    }
+    emit(run, type, state, message, step, control) {
+        run.events.push({ requestId: run.request.requestId, sequence: run.events.length + 1, type, state, message, timestamp: new Date().toISOString(), ...(step ? { stepId: step.id, stepName: step.name } : {}), ...(control ? { control } : {}) });
+        run.listeners.splice(0).forEach(resolve => resolve());
+    }
+    finish(run, result) {
+        const finishedAt = new Date().toISOString();
+        const finalResult = { ...result, finishedAt, executionTiming: { wallDurationMs: Date.now() - run.startedMs, activeDurationMs: Date.now() - run.startedMs - run.pausedDurationMs, pausedDurationMs: run.pausedDurationMs } };
+        run.result = finalResult;
+        run.controlState = finalResult.state === 'completed' ? 'completed' : finalResult.state === 'cancelled' ? 'stopped' : 'failed';
+        this.emit(run, 'run_finished', finalResult.state, finalResult.error?.message ?? `Execution ${finalResult.state}.`);
+        run.resolve(finalResult);
+        run.listeners.splice(0).forEach(resolve => resolve());
+    }
+    baseResult(run, startedAt, state, error, issues, children) {
+        return { requestId: run.request.requestId, state, target: run.request.executionPackage.target, environment: run.request.environment, startedAt, finishedAt: new Date().toISOString(), steps: [], ...(children ? { children } : {}), ...(error ? { error } : {}), ...(issues ? { issues } : {}) };
+    }
+    failure(cause, run, signal = run.abort.signal) {
+        if (isFailure(cause))
+            return cause;
+        if (run.timedOut)
+            return failure('ACTION_TIMEOUT', 'Execution exceeded its timeout.');
+        if (run.cancelled || signal.aborted)
+            return failure('ACTION_CANCELLED', 'Execution was cancelled.');
+        return failure('ACTION_FAILED', cause instanceof Error ? cause.message : 'Action execution failed.');
+    }
+}
+function stepPathForBoundary(step, run, path) {
+    return `${run.request.requestId}:${path.join('.')}:${step.id}`;
+}
+function preflight(pkg, inputs, runtimeValues) {
+    const issues = [];
+    if (!pkg.packageId || !pkg.target?.id)
+        issues.push({ code: 'INVALID_PACKAGE', message: 'Execution package identity is incomplete.' });
+    for (const name of pkg.requiredInputs ?? [])
+        if (inputs[name] === undefined)
+            issues.push({ code: 'MISSING_INPUT', message: `Required input '${name}' is missing.` });
+    for (const name of pkg.runtimeRequirements ?? [])
+        if (runtimeValues[name] === undefined)
+            issues.push({ code: 'MISSING_RUNTIME_VALUE', message: `Runtime value '${name}' is missing.` });
+    return issues;
+}
+function orderSteps(steps) {
+    const byId = new Map();
+    for (const step of steps) {
+        if (byId.has(step.id))
+            throw failure('PREFLIGHT_ERROR', `Graph contains duplicate step id ${step.id}.`);
+        byId.set(step.id, step);
+    }
+    const remaining = [...steps];
+    const ordered = [];
+    while (remaining.length) {
+        const index = remaining.findIndex(step => (step.dependsOn ?? []).every(dependency => byId.has(dependency) && ordered.some(done => done.id === dependency)));
+        if (index < 0) {
+            const missing = remaining.flatMap(step => step.dependsOn ?? []).find(dependency => !byId.has(dependency));
+            throw failure('PREFLIGHT_ERROR', missing ? `Graph dependency ${missing} is missing.` : 'Graph contains a dependency cycle.');
+        }
+        ordered.push(remaining.splice(index, 1)[0]);
+    }
+    return ordered;
+}
+function findStep(results, stepId, invocationPath) {
+    for (const result of results) {
+        if (result.id === stepId && (!invocationPath || result.invocationPath?.join('.') === invocationPath.join('.')))
+            return result;
+        const nested = result.children && findStep(result.children, stepId, invocationPath);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+function findDefinition(steps, stepId, invocationPath) {
+    for (const step of steps) {
+        if (step.id === stepId && (!invocationPath || invocationPath.at(-1) === stepId))
+            return step;
+        const nested = step.children && findDefinition(step.children, stepId, invocationPath);
+        if (nested)
+            return nested;
+        for (const branch of step.control?.branches ?? []) {
+            const branchNested = findDefinition(branch.children, stepId, invocationPath);
+            if (branchNested)
+                return branchNested;
+        }
+    }
+    return undefined;
+}
+function invocationState(state) {
+    return state === 'cancelled' ? 'cancelled' : state === 'failed' ? 'failed' : 'skipped';
+}
+function mergeBranchOutputs(branches, bindings, policy) {
+    if (bindings)
+        return Object.fromEntries(Object.entries(bindings).flatMap(([name, source]) => {
+            const match = /^([^.]+)\.(.+)$/.exec(source);
+            const branch = match ? branches.find(item => item.id === match[1]) : undefined;
+            return branch && match && Object.prototype.hasOwnProperty.call(branch.outputs, match[2]) ? [[name, branch.outputs[match[2]]]] : [];
+        }));
+    if (policy === 'first')
+        return { ...(branches[0]?.outputs ?? {}) };
+    if (policy === 'last')
+        return { ...(branches.at(-1)?.outputs ?? {}) };
+    return Object.fromEntries(branches.flatMap(branch => Object.entries(branch.outputs).map(([name, value]) => [`${branch.id}.${name}`, value])));
+}
+function resolveBindings(bindings, scope, outputs) {
+    return Object.fromEntries(Object.entries(bindings).map(([name, reference]) => [name, resolveReference(reference, scope, outputs)]));
+}
+function resolveReference(reference, scope, outputs) {
+    const input = /^\$inputs\.(.+)$/.exec(reference);
+    if (input)
+        return readPath(scope, input[1]);
+    const step = /^\$steps\.([^.]+)\.(.+)$/.exec(reference);
+    if (step)
+        return readPath(outputs.get(step[1]) ?? {}, step[2]);
+    if (reference.startsWith('$'))
+        throw failure('BINDING_RESOLUTION_ERROR', `Binding '${reference}' could not be resolved.`);
+    return reference;
+}
+function readPath(value, path) {
+    const result = path.split('.').reduce((current, segment) => isRecord(current) ? current[segment] : undefined, value);
+    if (result === undefined)
+        throw failure('BINDING_RESOLUTION_ERROR', `Binding path '${path}' could not be resolved.`);
+    return result;
+}
+function evaluateCondition(condition, scope, outputs) {
+    if (typeof condition === 'boolean')
+        return condition;
+    let value;
+    try {
+        value = resolveReference(condition.binding, scope, outputs);
+    }
+    catch {
+        value = undefined;
+    }
+    if (condition.exists !== undefined)
+        return condition.exists === (value !== undefined);
+    if ('equals' in condition)
+        return value === condition.equals;
+    if ('notEquals' in condition)
+        return value !== condition.notEquals;
+    return Boolean(value);
+}
+function delay(durationMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error('Execution cancelled.'));
+            return;
+        }
+        const timer = setTimeout(resolve, durationMs);
+        signal.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('Execution cancelled.')); }, { once: true });
+    });
+}
+function failure(code, message) { return { code, message, category: code }; }
+function isFailure(value) { return isRecord(value) && typeof value.code === 'string' && typeof value.message === 'string'; }
+function isActionResult(value) { return isRecord(value) && isRecord(value.outputs); }
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }

package/dist/in-memory-action-executor.d.ts

@@ -0,0 +1,5 @@
+import type { ActionExecutionContext, ActionExecutionResult, ActionExecutor } from './types.js';
+export declare class InMemoryActionExecutor implements ActionExecutor {
+    supports(action: string): boolean;
+    execute(context: ActionExecutionContext): Promise<ActionExecutionResult>;
+}

package/dist/in-memory-action-executor.js

@@ -0,0 +1,6 @@
+export class InMemoryActionExecutor {
+    supports(action) { return action.startsWith('in-memory.') || action.startsWith('studio:'); }
+    async execute(context) {
+        return { outputs: context.step.output };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './executor.js';
+export * from './in-memory-action-executor.js';
+export * from './migrated-executor.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './executor.js';
+export * from './in-memory-action-executor.js';
+export * from './migrated-executor.js';

package/dist/migrated-adapter.d.ts

@@ -0,0 +1,5 @@
+import type { ActionAdapter, ActionContext } from './migrated-types.js';
+export declare class InMemoryActionAdapter implements ActionAdapter {
+    supports(action: string): boolean;
+    execute(context: ActionContext): Promise<Record<string, unknown>>;
+}

package/dist/migrated-adapter.js

@@ -0,0 +1,4 @@
+export class InMemoryActionAdapter {
+    supports(action) { return action.startsWith('in-memory.') || action.startsWith('studio:'); }
+    async execute(context) { return context.step.output; }
+}

package/dist/migrated-artifact-hash.d.ts

@@ -0,0 +1,3 @@
+import type { ExecutionPackage } from './types';
+/** Stable, dependency-free content identity for the normalized execution package. */
+export declare function hashExecutionPackage(pack: ExecutionPackage): string;