@qaick/executor 0.2.6 → 0.3.0

package/dist/execution-plan.d.ts

@@ -0,0 +1,63 @@
+import type { NormalizedExecutionDocument, ExecutionPackageV7, ExecutableNodeV8, ControlV8, ConditionV8, ContextNode, ExecutionBindingV8, HierarchyAddress, ScopeIteration, IterationSelection, ExecutableInput } from '@qaick/contract';
+export declare const addressKey: (a: HierarchyAddress) => string;
+export type RunIteration = ScopeIteration | IterationSelection;
+export type PlanStep = Omit<ExecutableNodeV8, 'children' | 'control'> & {
+    structuralAddress?: HierarchyAddress;
+    children?: PlanStep[];
+    control?: Omit<ControlV8, 'branches'> & {
+        branches?: Array<{
+            id: string;
+            occurrence: string;
+            condition: boolean | ConditionV8;
+            children: PlanStep[];
+        }>;
+    };
+};
+export type PlanFlow = {
+    id: string;
+    name: string;
+    occurrence: string;
+    steps: PlanStep[];
+    inputDeclarations?: ExecutableInput[];
+    requiredInputs?: string[];
+    outputBindings?: Record<string, ExecutionBindingV8>;
+};
+export type PlanIssue = {
+    code: string;
+    message: string;
+    stepId?: string;
+};
+/** References into the immutable canonical document, not a second executable package. */
+export declare class ExecutionPlan {
+    readonly document: NormalizedExecutionDocument;
+    readonly legacy?: ExecutionPackageV7 | undefined;
+    readonly context: Map<string, ContextNode>;
+    readonly nodes: Map<string, PlanStep>;
+    readonly ordinals: Map<string, string>;
+    readonly inScope: Set<string>;
+    readonly steps: PlanStep[];
+    readonly flows: PlanFlow[];
+    readonly target: {
+        kind: "flow" | "project";
+        id: string;
+        name: string;
+    };
+    readonly packageId: string;
+    readonly inputDeclarations: ExecutableInput[] | undefined;
+    readonly requiredInputs: string[] | undefined;
+    readonly runtimeRequirements: string[] | undefined;
+    readonly project: boolean;
+    constructor(document: NormalizedExecutionDocument, legacy?: ExecutionPackageV7 | undefined);
+    ancestors(key: string): ContextNode[];
+    loops(key: string): string[];
+    dependency(operand: ExecutionBindingV8, consumer: PlanStep, phase: 'entry' | 'completion', actual?: RunIteration[]): PlanIssue[];
+    source(operand: Exclude<ExecutionBindingV8, {
+        type: 'input' | 'unresolved-output';
+    }>): {
+        step: PlanStep;
+        iterations: RunIteration[];
+    };
+    /** Prove unavailable dependencies, never evaluate a future Action's output value. */
+    preflight(inputs: Record<string, unknown>, runtime: Record<string, unknown>, supports: (action: string) => boolean): PlanIssue[];
+}
+export declare function journalKey(step: Pick<PlanStep, 'occurrence' | 'structuralAddress'>, iterations: RunIteration[], version: 7 | 8): string;

package/dist/execution-plan.js

@@ -0,0 +1,235 @@
+import { executionOperandDependencyIssues } from '@qaick/contract';
+import { resolveDeclaredInputs } from './declared-inputs.js';
+export const addressKey = (a) => JSON.stringify([a.scope, a.segments.map(s => s.kind === 'body' ? ['body'] : [s.kind, s.position])]);
+/** References into the immutable canonical document, not a second executable package. */
+export class ExecutionPlan {
+    document;
+    legacy;
+    context;
+    nodes = new Map();
+    ordinals = new Map();
+    inScope = new Set();
+    steps;
+    flows;
+    target;
+    packageId;
+    inputDeclarations;
+    requiredInputs;
+    runtimeRequirements;
+    project;
+    constructor(document, legacy) {
+        this.document = document;
+        this.legacy = legacy;
+        this.context = new Map(document.context.nodes.map(n => [n.key, n]));
+        this.target = document.target;
+        this.packageId = document.packageId;
+        this.runtimeRequirements = document.selection.runtimeRequirements;
+        for (const n of this.context.values())
+            if (n.originalAddress)
+                this.ordinals.set(addressKey(n.originalAddress), n.key);
+        for (const n of document.nodes)
+            this.nodes.set(n.occurrence, { ...n, children: undefined, control: undefined, structuralAddress: this.context.get(n.occurrence)?.originalAddress });
+        const list = (keys) => keys.map(k => this.nodes.get(k));
+        for (const n of document.nodes) {
+            const step = this.nodes.get(n.occurrence);
+            if (n.children)
+                step.children = list(n.children);
+            if (n.control)
+                step.control = { ...n.control, branches: n.control.branches?.map(b => {
+                        const locator = this.context.get(b.occurrence).locator;
+                        const last = locator.kind === 'source' ? locator.path.at(-1) : undefined;
+                        return { ...b, id: last && 'id' in last ? last.id : b.occurrence, children: list(b.children) };
+                    }) };
+        }
+        const flow = (key) => {
+            const f = document.flows.find(f => f.occurrence === key);
+            const c = this.context.get(key);
+            return { ...f, id: c.locator.kind === 'source' ? c.locator.path.at(-1)?.kind === 'flow' ? c.locator.path.at(-1).id : c.locator.root.id : key, name: c.name, steps: list(f.children) };
+        };
+        const root = document.selection.root.kind === 'occurrence' ? document.selection.root.key : document.context.root;
+        const selected = this.context.get(root);
+        const visit = (key) => { this.inScope.add(key); for (const child of this.context.get(key).children)
+            visit(child); };
+        visit(root);
+        const entryPayload = selected.kind === 'flow' ? document.flows.find(f => f.occurrence === root) : document.nodes.find(n => n.occurrence === root);
+        this.inputDeclarations = entryPayload?.inputDeclarations ?? document.selection.inputDeclarations;
+        this.requiredInputs = selected.kind === 'flow' ? [...new Set([...(document.flows.find(f => f.occurrence === root)?.requiredInputs ?? []), ...(document.selection.requiredInputs ?? [])])] : document.selection.requiredInputs;
+        this.project = selected.kind === 'project';
+        this.flows = !document.selection.executable ? [] : this.project ? (selected.sequence ?? []).map(flow) : [];
+        this.steps = !document.selection.executable ? [] : selected.kind === 'flow' ? flow(root).steps : this.project ? [] : [this.nodes.get(root)];
+        if (document.inputVersion === 8) {
+            const freeze = (v) => { if (v && typeof v === 'object') {
+                for (const child of Object.values(v))
+                    freeze(child);
+                Object.freeze(v);
+            } };
+            for (const node of this.nodes.values())
+                freeze(node);
+        }
+        // Only the selected entry is dispatched; full unselected context is retained unchanged.
+    }
+    ancestors(key) {
+        const path = [];
+        for (let n = this.context.get(key); n; n = n.parent === null ? undefined : this.context.get(n.parent))
+            path.unshift(n);
+        return path;
+    }
+    loops(key) { return this.ancestors(key).slice(0, -1).filter(n => this.inScope.has(n.key) && this.nodes.get(n.key)?.control?.type === 'repeat').map(n => n.key); }
+    dependency(operand, consumer, phase, actual) {
+        if (this.document.inputVersion === 7)
+            return executionOperandDependencyIssues(this.legacy, operand, phase === 'entry' ? { phase, address: consumer.structuralAddress } : { phase, address: consumer.structuralAddress, iterations: actual }).map(i => ({ code: i.code, message: i.reason }));
+        const fail = (code, message) => [{ code, message: `${consumer.name}: ${message}`, stepId: consumer.id }];
+        if (operand.type === 'input')
+            return [];
+        if (operand.type === 'unresolved-output')
+            return fail('UNRESOLVED_SCOPE_BINDING', 'The output reference requires repair.');
+        const producer = operand.type === 'occurrence-output' ? operand.producer : this.ordinals.get(addressKey(operand.address));
+        if (!producer || !this.inScope.has(producer))
+            return fail('UNAVAILABLE_SCOPE_DEPENDENCY', 'The required output is outside this execution scope or has no original structural address.');
+        const source = this.nodes.get(producer);
+        if (!source || source.kind !== 'action' || !Object.hasOwn(source.output, operand.outputName))
+            return fail('UNRESOLVED_SCOPE_BINDING', 'The producer does not declare the required Action output.');
+        const a = this.ancestors(producer), b = this.ancestors(consumer.occurrence);
+        const descendant = a.some(n => n.key === consumer.occurrence) && producer !== consumer.occurrence;
+        if (phase === 'completion' && descendant) {
+            const path = a.slice(a.findIndex(n => n.key === consumer.occurrence));
+            if (path.some(n => n.kind === 'branch' || ['condition', 'parallel', 'branch'].includes(this.nodes.get(n.key)?.control?.type ?? '')))
+                return fail('UNAVAILABLE_SCOPE_CONTEXT', 'Conditional or parallel output exposure is not proven.');
+        }
+        else {
+            let i = 0;
+            while (i < a.length && i < b.length && a[i].key === b[i].key)
+                i++;
+            const parent = a[i - 1], left = a[i], right = b[i];
+            if (!parent || !left || !right || left.kind === 'branch' || right.kind === 'branch' || !parent.sequence || parent.sequence.indexOf(left.key) >= parent.sequence.indexOf(right.key))
+                return fail('UNAVAILABLE_SCOPE_DEPENDENCY', 'The producer does not precede this consumer on a proven sequential path.');
+        }
+        const loops = this.loops(producer);
+        const selected = operand.type === 'occurrence-output' ? operand.iterations : operand.iterations.map(i => ({ loop: this.ordinals.get(addressKey(i.loopAddress)) ?? '', iteration: i.iteration }));
+        if (selected.length !== loops.length || loops.some(k => !selected.some(i => i.loop === k)))
+            return fail('UNAVAILABLE_SCOPE_CONTEXT', 'Select every actual in-scope producer loop; enclosing unexecuted loops cannot supply an iteration.');
+        const shared = this.loops(consumer.occurrence).filter(k => loops.includes(k));
+        if (phase === 'entry' && shared.length)
+            return fail('UNAVAILABLE_SCOPE_CONTEXT', 'A fixed iteration cannot precede every consumer iteration.');
+        for (const i of selected) {
+            const count = this.nodes.get(i.loop)?.control?.iterations;
+            if (count !== undefined && i.iteration > count)
+                return fail('UNAVAILABLE_SCOPE_CONTEXT', 'The selected iteration exceeds the configured repeat count.');
+            if (phase === 'completion' && shared.includes(i.loop) && actual && !actual.some(a => 'loop' in a && a.loop === i.loop && a.iteration === i.iteration))
+                return fail('UNAVAILABLE_SCOPE_CONTEXT', 'The selected iteration differs from the completing invocation.');
+        }
+        return [];
+    }
+    source(operand) {
+        const key = operand.type === 'occurrence-output' ? operand.producer : this.ordinals.get(addressKey(operand.address));
+        const step = this.nodes.get(key);
+        if (this.document.inputVersion === 7)
+            return { step, iterations: this.loops(key).map(loop => ({ loopAddress: this.context.get(loop).originalAddress, iteration: operand.iterations.find(i => addressKey(i.loopAddress) === addressKey(this.context.get(loop).originalAddress)).iteration })) };
+        const selected = operand.type === 'occurrence-output' ? operand.iterations : operand.iterations.map(i => ({ loop: this.ordinals.get(addressKey(i.loopAddress)), iteration: i.iteration }));
+        return { step, iterations: this.loops(key).map(loop => ({ loop, iteration: selected.find(i => i.loop === loop).iteration })) };
+    }
+    /** Prove unavailable dependencies, never evaluate a future Action's output value. */
+    preflight(inputs, runtime, supports) {
+        if (this.document.inputVersion === 7)
+            return [];
+        const issues = [];
+        if (!this.document.selection.executable)
+            return this.document.selection.issues.map(issue => ({ code: 'INCOMPLETE_SCOPE', message: `${this.context.get(issue.at)?.name ?? 'Selected scope'}: This content is not ready to run.` }));
+        for (const key of this.inScope) {
+            const step = this.nodes.get(key);
+            if (!step)
+                continue;
+            if (step.kind === 'action' && !supports(step.action))
+                issues.push({ code: 'UNSUPPORTED_SCOPE_CAPABILITY', message: `${step.name}: No Action Executor supports this Action.`, stepId: step.id });
+            // Existing engine intentionally does not implement these completion projections.
+            if (step.control?.mergeBindings)
+                issues.push({ code: 'UNSUPPORTED_SCOPE_CAPABILITY', message: `${step.name}: Parallel output projections are unsupported.`, stepId: step.id });
+        }
+        const rootKey = this.document.selection.root.kind === 'occurrence' ? this.document.selection.root.key : this.document.context.root;
+        const relevantFlows = this.document.flows.filter(f => this.inScope.has(f.occurrence));
+        for (const flow of relevantFlows)
+            if (Object.keys(flow.outputBindings ?? {}).length)
+                issues.push({ code: 'UNSUPPORTED_SCOPE_CAPABILITY', message: `${this.context.get(flow.occurrence).name}: Flow completion exports are unsupported.` });
+        const scopeFrom = (values) => new Map(Object.entries(values).map(([k, value]) => [k, { known: true, value }]));
+        const binding = (op, step, scope, phase) => {
+            issues.push(...this.dependency(op, step, phase));
+            if (op.type !== 'input')
+                return { known: false };
+            let v = scope.get(op.path[0]);
+            if (!v) {
+                issues.push({ code: 'UNAVAILABLE_SCOPE_CONTEXT', message: `${step.name}: Required input ${op.path.join('.')} is unavailable in this scope.`, stepId: step.id });
+                return { known: false };
+            }
+            if (v.known) {
+                let value = v.value;
+                for (const part of op.path.slice(1)) {
+                    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) {
+                        issues.push({ code: 'UNAVAILABLE_SCOPE_CONTEXT', message: `${step.name}: Required input path ${op.path.join('.')} is unavailable.`, stepId: step.id });
+                        return { known: false };
+                    }
+                    value = value[part];
+                }
+                if (value === undefined) {
+                    issues.push({ code: 'UNAVAILABLE_SCOPE_CONTEXT', message: `${step.name}: Required input ${op.path.join('.')} is unavailable.`, stepId: step.id });
+                    return { known: false };
+                }
+                return { known: true, value };
+            }
+            return v;
+        };
+        const condition = (c, s, scope) => { if (c !== undefined && typeof c !== 'boolean')
+            binding(c.binding, s, scope, 'entry'); };
+        const visit = (s, scope) => {
+            const args = scopeFrom(s.occurrence === rootKey ? { ...inputs, ...s.staticInputs } : s.staticInputs ?? {});
+            for (const [name, op] of Object.entries(s.bindings ?? {}))
+                args.set(name, binding(op, s, scope, 'entry'));
+            const child = new Map(scope);
+            if (s.kind === 'operation') {
+                const known = Object.fromEntries([...args].filter(([, v]) => v.known).map(([k, v]) => [k, v.value]));
+                const resolved = resolveDeclaredInputs((s.inputDeclarations ?? []).filter(d => args.get(d.name)?.known !== false), known);
+                issues.push(...resolved.issues.map(i => ({ ...i, message: `${s.name}: ${i.message}`, stepId: s.id })));
+                for (const d of s.inputDeclarations ?? [])
+                    child.delete(d.name);
+                for (const [k, v] of Object.entries(resolved.inputs))
+                    child.set(k, { known: true, value: v });
+                for (const [k, v] of args)
+                    if (!v.known)
+                        child.set(k, v);
+            }
+            else
+                for (const [k, v] of args)
+                    child.set(k, v);
+            condition(s.control?.condition, s, child);
+            for (const branch of s.control?.branches ?? []) {
+                condition(branch.condition, s, child);
+                for (const c of branch.children)
+                    visit(c, child);
+            }
+            if (!s.control?.branches)
+                for (const c of s.children ?? [])
+                    visit(c, child);
+            for (const op of Object.values(s.outputBindings ?? {}))
+                binding(op, s, child, 'completion');
+            for (const op of Object.values(s.control?.mergeBindings ?? {}))
+                binding(op, s, child, 'completion');
+        };
+        if (this.project) {
+            for (const flow of this.flows) {
+                const resolved = resolveDeclaredInputs(flow.inputDeclarations, inputs);
+                issues.push(...resolved.issues);
+                for (const name of flow.requiredInputs ?? [])
+                    if (resolved.inputs[name] === undefined)
+                        issues.push({ code: 'MISSING_INPUT', message: `${flow.name}: Required input ${name} is missing.` });
+                for (const s of flow.steps)
+                    visit(s, scopeFrom(resolved.inputs));
+            }
+        }
+        else
+            for (const s of this.steps)
+                visit(s, scopeFrom(inputs));
+        return issues;
+    }
+}
+export function journalKey(step, iterations, version) {
+    return version === 7 ? JSON.stringify([addressKey(step.structuralAddress), iterations.map(i => [addressKey(i.loopAddress), i.iteration])]) : JSON.stringify([step.occurrence, iterations.map(i => [i.loop, i.iteration])]);
+}

package/dist/executor.d.ts

@@ -1,4 +1,5 @@
-import type { ActReplayTarget, ActReplayHandle, OperationReplayHandle, ActionExecutor, ControlCommand, ExecutionControlState, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun } from './types.js';
+import type { AcceptedExecutorRequest, AcceptedExecutorResult, AcceptedExecutorEvent, ExecutorRequestV8, ExecutorRunV8 } from './types.js';
+import type { ActReplayTarget, ActReplayHandle, OperationReplayHandle, ActionExecutor, ControlCommand, ExecutionControlState, Executor, ExecutorConfiguration, ExecutorRequest, ExecutorRun } from './types.js';
 export declare function createExecutor(configuration?: ExecutorConfiguration): Executor;
 export declare class DefaultExecutor implements Executor {
     private readonly runs;
@@ -7,12 +8,14 @@ export declare class DefaultExecutor implements Executor {
     constructor(configuration?: ExecutorConfiguration);
     registerActionExecutor(executor: ActionExecutor): void;
     execute(request: ExecutorRequest): Promise<ExecutorRun>;
+    execute(request: ExecutorRequestV8): Promise<ExecutorRunV8>;
+    execute(request: AcceptedExecutorRequest): Promise<ExecutorRun | ExecutorRunV8>;
     private startRun;
     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>;
+    events(requestId: string): AsyncIterable<AcceptedExecutorEvent>;
+    result(requestId: string): Promise<AcceptedExecutorResult>;
     private replayTarget;
     retryAction(requestId: string, target: ActReplayTarget): Promise<ActReplayHandle>;
     private replayEvents;
@@ -39,5 +42,6 @@ export declare class DefaultExecutor implements Executor {
     private emitReplayOccurrence;
     private finish;
     private baseResult;
+    private versionedResult;
     private failure;
 }

package/dist/executor.js

@@ -1,3 +1,5 @@
+import { ExecutionPlan, journalKey } from './execution-plan.js';
+import { normalizeV7, normalizeV8, hashCanonicalJson } from '@qaick/contract';
 import { resolveDeclaredInputs } from './declared-inputs.js';
 import { isDeclaredInputNoValue, executionOccurrences, executionOperandDependencyIssues, hierarchyAddressIssues } from '@qaick/contract';
 const addressKey = (address) => JSON.stringify([address.scope, address.segments.map(s => s.kind === 'body' ? ['body'] : [s.kind, s.position])]);
@@ -8,6 +10,11 @@ function freezePlan(value) {
         Object.freeze(value);
     }
 }
+function legacyPackage(run) {
+    if (run.request.executionPackage.schemaVersion !== 7)
+        throw failure('UNSUPPORTED_SCOPE_CAPABILITY', 'Replay of Execution v8 is unsupported.');
+    return run.request.executionPackage;
+}
 const MAX_TIMEOUT_MS = 300_000;
 export function createExecutor(configuration = {}) {
     return new DefaultExecutor(configuration);
@@ -27,26 +34,48 @@ export class DefaultExecutor {
     async startRun(request, debugSeed, debugProvenance) {
         if (this.runs.has(request.requestId))
             throw failure('PREFLIGHT_ERROR', 'Execution request ID already belongs to a Run.');
-        const requestSnapshot = structuredClone(request);
-        const validation = [];
-        let plan = new Map();
-        try {
-            // Shared traversal validates the projection before constructing the immutable plan.
-            plan = new Map(executionOccurrences(requestSnapshot.executionPackage).map(o => [addressKey(o.address), o]));
-            freezePlan(requestSnapshot.executionPackage);
-        }
-        catch (cause) {
-            validation.push({ code: 'invalid-execution-package', message: cause instanceof Error ? cause.message : 'Invalid Execution v7 projection.' });
+        // Register before awaiting native hashing, so concurrent duplicate IDs cannot race admission.
+        // Validate the original v8 JSON boundary before structuredClone could invoke a getter.
+        let preparedV8;
+        if (request.executionPackage.schemaVersion === 8) {
+            try {
+                preparedV8 = normalizeV8(request.executionPackage);
+            }
+            catch (cause) {
+                const issues = cause.issues;
+                throw { code: issues?.[0]?.code ?? 'INVALID_EXECUTION_DOCUMENT', message: 'Execution Document v8 could not be admitted.', ...(issues?.length ? { details: { issues } } : {}) };
+            }
         }
+        const requestSnapshot = structuredClone(request);
+        freezePlan(requestSnapshot.executionPackage);
         let resolve;
-        const result = new Promise(promiseResolve => { resolve = promiseResolve; });
+        const result = new Promise(r => { resolve = r; });
         const run = {
-            debugSeed, debugProvenance, request: requestSnapshot, inputSelections: structuredClone(requestSnapshot.inputs), plan, journal: new Map(), replayCaptures: new Map(), resolve, events: [], listeners: [], abort: new AbortController(), cancelled: false,
+            debugSeed, debugProvenance, request: requestSnapshot, inputSelections: structuredClone(requestSnapshot.inputs), plan: new Map(), journal: new Map(), replayCaptures: new Map(), resolve, events: [], listeners: [], abort: new AbortController(), cancelled: false,
             timedOut: false, controlState: 'idle', pauseRequested: false, stepRequested: false,
-            controlWaiters: [], hitBreakpoints: new Set(), stopAfter: request.debugSession?.stopAfterStepId,
+            controlWaiters: [], hitBreakpoints: new Set(), stopAfter: requestSnapshot.debugSession && ('stopAfter' in requestSnapshot.debugSession ? requestSnapshot.debugSession.stopAfter : ('stopAfterStepId' in requestSnapshot.debugSession ? requestSnapshot.debugSession.stopAfterStepId : undefined)),
             startedMs: Date.now(), pausedDurationMs: 0,
         };
         this.runs.set(request.requestId, run);
+        const validation = [];
+        try {
+            const pkg = requestSnapshot.executionPackage;
+            const document = pkg.schemaVersion === 8 ? preparedV8 : await normalizeV7(pkg);
+            if (pkg.schemaVersion === 8)
+                run.documentHash = await hashCanonicalJson(pkg);
+            run.execution = new ExecutionPlan(document, pkg.schemaVersion === 7 ? pkg : undefined);
+            if (pkg.schemaVersion === 7)
+                run.plan = new Map(executionOccurrences(pkg).map(o => [addressKey(o.address), o]));
+        }
+        catch (cause) {
+            const supplied = cause?.issues;
+            if (requestSnapshot.executionPackage.schemaVersion === 8) {
+                // No accepted v8 Run may pretend to have a hash/source envelope when admission failed.
+                this.runs.delete(request.requestId);
+                throw { code: supplied?.[0]?.code ?? 'INVALID_EXECUTION_DOCUMENT', message: 'Execution Document v8 could not be admitted.', ...(supplied?.length ? { details: { issues: supplied } } : {}) };
+            }
+            validation.push(...(supplied?.length ? supplied : [{ code: 'invalid-execution-package', message: cause instanceof Error ? cause.message : 'Execution admission failed.' }]));
+        }
         void this.run(run, validation);
         return { requestId: request.requestId, result, ...(debugProvenance ? { debugProvenance } : {}) };
     }
@@ -67,6 +96,8 @@ export class DefaultExecutor {
         if (command.type === 'stop')
             return this.cancel(requestId);
         if (command.type === 'stop-after') {
+            if (run.execution?.document.inputVersion === 8 && (!run.execution.inScope.has(command.stepId) || !run.execution.nodes.has(command.stepId)))
+                throw failure('INVALID_SCOPE', 'Stop After target is outside the selected execution scope.');
             run.stopAfter = command.stepId;
             return;
         }
@@ -124,6 +155,7 @@ export class DefaultExecutor {
         if (!parent?.result)
             reject('Act replay requires a terminal original Run.');
         const run = parent;
+        legacyPackage(run);
         if (run.cancelled || run.timedOut)
             reject('Interrupted original Runs cannot be replayed.');
         if (run.activeReplay)
@@ -262,7 +294,7 @@ export class DefaultExecutor {
         // Separate structural state, not a new Run: no registration, root result, resolver,
         // historical journal, controls, captures or original event stream are reused.
         const context = {
-            request: session.request, inputSelections: structuredClone(parent.inputSelections), plan: parent.plan, journal: new Map(), replayCaptures: new Map(),
+            request: session.request, execution: parent.execution, inputSelections: structuredClone(parent.inputSelections), plan: parent.plan, journal: new Map(), replayCaptures: new Map(),
             replay: { session, capture, root: capture.structuralAddress },
             events: [], listeners: [], abort: session.abort,
             get cancelled() { return session.cancelled; }, get timedOut() { return session.timedOut; },
@@ -282,7 +314,7 @@ export class DefaultExecutor {
                     session.abort.abort();
                 }, timeoutMs);
             this.emitReplay(session, 'replay_started', 'running');
-            operation = await this.executeStep(context, step, capture.lexicalScope, [], session.abort.signal, capture.iterations);
+            operation = await this.executeStep(context, parent.execution.nodes.get(parent.execution.ordinals.get(addressKey(step.structuralAddress))), capture.lexicalScope, [], session.abort.signal, capture.iterations);
             this.assertActive(session, session.abort.signal);
             if (operation.state !== 'finished') {
                 state = 'failed';
@@ -315,6 +347,8 @@ export class DefaultExecutor {
     async runFromHere(sourceRequestId, target) {
         const source = this.runs.get(sourceRequestId);
         const reject = (message) => { throw failure('unsupported-execution-context', message); };
+        if (source)
+            legacyPackage(source);
         if (!source?.result || source.cancelled || source.timedOut)
             reject('Run From Here requires a terminal uninterrupted source Run.');
         if (!isRecord(target) || Object.keys(target).some(k => !['structuralAddress', 'iterations'].includes(k))
@@ -327,10 +361,11 @@ export class DefaultExecutor {
         if (!topLevel)
             reject('Nested/control continuation is not supported by Run From Here.');
         const parent = source;
+        legacyPackage(parent);
         const capture = parent.replayCaptures.get(invocationKey(address, []));
         if (!capture || (capture.kind !== 'action' && capture.kind !== 'operation'))
             reject('No eligible private original input capture exists.');
-        const package_ = structuredClone(parent.request.executionPackage);
+        const package_ = structuredClone(legacyPackage(parent));
         const position = segments.at(-1);
         if (position.kind !== 'step')
             throw failure('unsupported-execution-context', 'Expected a top-level step.');
@@ -390,7 +425,7 @@ export class DefaultExecutor {
         freezePlan(seed);
         freezePlan(provenance);
         // Normal Run creation is independent of replay admission and has no external evidence view.
-        return this.startRun({ ...structuredClone(parent.request), requestId: crypto.randomUUID(), executionPackage: package_, inputs: structuredClone(parent.inputSelections) }, seed, provenance);
+        return this.startRun({ ...structuredClone(parent.request), debugSession: parent.request.debugSession, requestId: crypto.randomUUID(), executionPackage: package_, inputs: structuredClone(parent.inputSelections) }, seed, provenance);
     }
     async run(run, validation) {
         const startedAt = new Date().toISOString();
@@ -406,12 +441,15 @@ export class DefaultExecutor {
         let timeout;
         if (timeoutMs !== undefined)
             timeout = setTimeout(() => { if (run.abort.signal.aborted)
-                return; run.timedOut = true; run.abort.abort(); }, timeoutMs);
+                return; run.timedOut = true; run.abort.abort(); if (run.request.executionPackage.schemaVersion === 8)
+                run.controlWaiters.splice(0).forEach(resolve => resolve()); }, timeoutMs);
         this.emit(run, 'run_started', 'created', 'Execution accepted.');
         this.emit(run, 'preflight_started', 'preflighting', 'Validating execution package.');
-        const arguments_ = resolveDeclaredInputs(run.request.executionPackage.inputDeclarations, run.request.inputs);
+        const arguments_ = resolveDeclaredInputs(run.execution.inputDeclarations, run.request.inputs);
         run.request = { ...run.request, inputs: arguments_.inputs };
-        const issues = [...arguments_.issues, ...preflight(run.request.executionPackage, arguments_.inputs, run.request.runtimeValues ?? {})];
+        const debug = run.request.debugSession;
+        const debugIssues = run.execution.document.inputVersion === 8 && debug && [...debug.breakpoints, ...(debug.stopAfter ? [debug.stopAfter] : [])].some(k => !run.execution.inScope.has(k) || !run.execution.nodes.has(k)) ? [{ code: 'INVALID_SCOPE', message: 'Debug target is outside the selected executable scope.' }] : [];
+        const issues = [...debugIssues, ...arguments_.issues, ...preflight(run.execution, arguments_.inputs, run.request.runtimeValues ?? {}), ...run.execution.preflight(arguments_.inputs, run.request.runtimeValues ?? {}, action => this.actionExecutors.some(e => e.supports(action)))];
         if (issues.length > 0 || run.request.options?.dryRun) {
             const result = this.baseResult(run, startedAt, issues.length > 0 ? 'failed' : 'completed', undefined, issues);
             if (timeout)
@@ -419,11 +457,17 @@ export class DefaultExecutor {
             this.finish(run, result);
             return;
         }
+        if (run.cancelled || run.abort.signal.aborted) {
+            if (timeout)
+                clearTimeout(timeout);
+            this.finish(run, this.baseResult(run, startedAt, 'cancelled'));
+            return;
+        }
         run.controlState = 'running';
         try {
-            const result = run.request.executionPackage.target.kind === 'project'
+            const result = run.execution.project
                 ? await this.executeProject(run, startedAt)
-                : await this.executeFlow(run, run.request.executionPackage.steps, run.request.inputs, [], startedAt);
+                : await this.executeFlow(run, run.execution.steps, run.request.inputs, [], startedAt);
             if (timeout)
                 clearTimeout(timeout);
             this.finish(run, result);
@@ -436,7 +480,7 @@ export class DefaultExecutor {
         }
     }
     async executeProject(run, startedAt) {
-        const pkg = run.request.executionPackage;
+        const pkg = run.execution;
         const children = [];
         let inputs = { ...run.request.inputs };
         for (const flow of pkg.flows ?? []) {
@@ -461,18 +505,31 @@ export class DefaultExecutor {
         }
         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, iterations = [], bodyFailurePolicy = 'stop') {
+    async executeFlow(run, steps, initialInputs, path, startedAt, target = run.execution.target, signal = run.abort.signal, iterations = [], bodyFailurePolicy = 'stop') {
         const results = [];
         let state = 'completed';
         let error;
         for (const step of steps) {
-            if (run.cancelled || signal.aborted)
-                throw new Error('Execution cancelled.');
-            await this.boundary(run, step, [...path, step.id], signal, iterations);
-            if (run.cancelled || signal.aborted)
-                throw new Error('Execution cancelled.');
+            try {
+                if (run.cancelled || signal.aborted)
+                    throw new Error('Execution cancelled.');
+                await this.boundary(run, step, [...path, step.id], signal, iterations);
+                if (run.cancelled || signal.aborted)
+                    throw new Error('Execution cancelled.');
+            }
+            catch (cause) {
+                if (run.execution.document.inputVersion === 7)
+                    throw cause;
+                state = run.timedOut ? 'failed' : 'cancelled';
+                error = this.failure(cause, run, signal);
+                break;
+            }
             const result = await this.executeStep(run, step, initialInputs, path, signal, iterations);
             results.push(result);
+            if (run.execution.document.inputVersion === 8 && step.kind !== 'action' && run.stopAfter === step.occurrence) {
+                run.stopAfter = undefined;
+                await this.pauseAtBoundary(run, step, iterations);
+            }
             if (result.state === 'failed' || result.state === 'cancelled') {
                 const interrupted = result.state === 'cancelled' || run.cancelled || run.timedOut || signal.aborted
                     || result.terminalReason === 'timeout' || result.error?.category === 'ACTION_TIMEOUT'
@@ -496,20 +553,25 @@ export class DefaultExecutor {
     async executeStep(run, step, scope, path, signal = run.abort.signal, iterations = []) {
         const startedMs = Date.now();
         const invocationPath = [...path, step.id];
-        const base = { id: step.id, name: step.name, kind: step.kind ?? 'action', inputs: {}, outputs: {}, structuralAddress: structuredClone(step.structuralAddress), iterations: structuredClone(iterations), invocationId: invocationPath.join('/'), invocationPath };
+        const base = { ...(run.execution.document.inputVersion === 8 ? { occurrence: step.occurrence } : {}), id: step.id, name: step.name, kind: step.kind ?? 'action', inputs: {}, outputs: {}, ...(step.structuralAddress ? { structuralAddress: structuredClone(step.structuralAddress) } : {}), iterations: structuredClone(iterations), invocationId: invocationPath.join('/'), invocationPath };
         let inputs = {};
         const attempts = [];
+        let actualChildren;
         this.emit(run, 'step_started', 'running', `${step.name} started.`, step, undefined, iterations);
         try {
             const debugSeed = run.debugSeed && addressKey(run.debugSeed.structuralAddress) === addressKey(step.structuralAddress) ? run.debugSeed : undefined;
             const rootCapture = run.replay && addressKey(run.replay.root) === addressKey(step.structuralAddress) ? run.replay.capture : debugSeed?.kind === 'operation' ? debugSeed : undefined;
-            inputs = debugSeed ? structuredClone(debugSeed.inputs) : rootCapture ? structuredClone(rootCapture.inputs) : { ...structuredClone(step.staticInputs ?? {}), ...this.resolveBindings(run, step.bindings ?? {}, scope, step.structuralAddress) };
+            const selected = run.execution.document.selection.root;
+            const entryInputs = run.execution.document.inputVersion === 8 && (selected.kind === 'occurrence' ? selected.key : run.execution.document.context.root) === step.occurrence ? scope : {};
+            inputs = debugSeed ? structuredClone(debugSeed.inputs) : rootCapture ? structuredClone(rootCapture.inputs) : { ...entryInputs, ...structuredClone(step.staticInputs ?? {}), ...this.resolveBindings(run, step.bindings ?? {}, scope, step) };
             if (step.delayMs) {
                 this.emit(run, 'waiting', 'waiting', `${step.name} is waiting for ${step.delayMs} ms.`, step, undefined, iterations);
                 await delay(step.delayMs, signal);
             }
             if (step.control) {
                 const controlResult = await this.executeControl(run, step, inputs, scope, path, signal, iterations);
+                if (run.execution.document.inputVersion === 8)
+                    this.emit(run, 'step_finished', controlResult.state, `${step.name} ${controlResult.state}.`, step, undefined, iterations);
                 return { ...base, ...controlResult, inputs, durationMs: Date.now() - startedMs };
             }
             if (step.kind === 'operation' && step.children) {
@@ -521,29 +583,30 @@ export class DefaultExecutor {
                 for (const declaration of step.inputDeclarations ?? [])
                     if (!Object.hasOwn(arguments_.inputs, declaration.name))
                         delete childScope[declaration.name];
-                if (!run.replay)
+                if (!run.replay && run.execution.document.inputVersion === 7)
                     this.capture(run, step, iterations, arguments_.inputs, {
                         kind: 'operation', lexicalScope: structuredClone(childScope),
                         externalEvidence: this.captureExternalEvidence(run, step, iterations),
                     });
-                const nested = await this.executeFlow(run, step.children, childScope, [...path, step.id], new Date().toISOString(), run.request.executionPackage.target, signal, iterations);
+                const nested = await this.executeFlow(run, step.children, childScope, [...path, step.id], new Date().toISOString(), run.execution.target, signal, iterations);
+                actualChildren = nested.steps;
                 const outputs = nested.state === 'completed'
-                    ? { ...structuredClone(step.staticOutputs ?? {}), ...this.resolveBindings(run, step.outputBindings ?? {}, childScope, step.structuralAddress, { phase: 'completion', address: step.structuralAddress, iterations }) }
+                    ? { ...structuredClone(step.staticOutputs ?? {}), ...this.resolveBindings(run, step.outputBindings ?? {}, childScope, step, { phase: 'completion', iterations }) }
                     : {};
                 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, undefined, iterations);
                 return result;
             }
-            if (!run.replay)
+            if (!run.replay && run.execution.document.inputVersion === 7)
                 this.capture(run, step, iterations, inputs, { kind: 'action' });
             const actionResult = await this.executeAction(run, step, inputs, attempts, signal, run.replay ? (type, attempt, state) => this.emitReplayOccurrence(run.replay.session, type, state, step, iterations, attempt) : undefined);
             if (signal.aborted || run.cancelled)
                 throw failure(run.timedOut ? 'ACTION_TIMEOUT' : 'ACTION_CANCELLED', 'Execution ended before evidence publication.');
-            run.journal.set(invocationKey(step.structuralAddress, iterations), { outputs: structuredClone(actionResult.outputs), ...(actionResult.evidence ? { evidence: structuredClone(actionResult.evidence) } : {}) });
+            run.journal.set(journalKey(step, iterations, run.execution.document.inputVersion), { outputs: structuredClone(actionResult.outputs), ...(actionResult.evidence ? { evidence: structuredClone(actionResult.evidence) } : {}) });
             freezePlan(attempts);
             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, undefined, iterations);
-            if (run.stopAfter === step.id) {
+            if (run.stopAfter === (run.execution.document.inputVersion === 8 ? step.occurrence : step.id)) {
                 run.stopAfter = undefined;
                 await this.pauseAtBoundary(run, step, iterations);
             }
@@ -553,14 +616,14 @@ export class DefaultExecutor {
             const failure = this.failure(cause, run, signal);
             const state = run.timedOut ? 'failed' : run.cancelled || signal.aborted ? 'cancelled' : 'failed';
             freezePlan(attempts);
-            const result = { ...base, state, inputs, durationMs: Date.now() - startedMs, ...(attempts.length ? { attempts } : {}), terminalReason: run.timedOut ? 'timeout' : state === 'cancelled' ? 'cancelled' : 'failed', error: failure };
+            const result = { ...base, ...(run.execution.document.inputVersion === 8 && actualChildren ? { children: actualChildren } : {}), state, inputs, durationMs: Date.now() - startedMs, ...(attempts.length ? { attempts } : {}), terminalReason: run.timedOut ? 'timeout' : state === 'cancelled' ? 'cancelled' : 'failed', error: failure };
             this.emit(run, 'step_finished', state, `${step.name} ${state}.`, step, undefined, iterations);
             return result;
         }
     }
     async executeControl(run, step, inputs, scope, path, signal = run.abort.signal, iterations = []) {
         const control = step.control;
-        if (control.condition !== undefined && !this.evaluateCondition(run, control.condition, { ...scope, ...inputs }, step.structuralAddress))
+        if (control.condition !== undefined && !this.evaluateCondition(run, control.condition, { ...scope, ...inputs }, step))
             return { state: 'skipped', outputs: {}, terminalReason: 'condition-skipped' };
         if (control.type === 'repeat') {
             const total = Math.max(1, Math.min(control.iterations ?? (control.durationMs !== undefined ? 32 : 1), 32));
@@ -569,8 +632,8 @@ export class DefaultExecutor {
             for (let current = 1; current <= total; current++) {
                 if (control.durationMs !== undefined && Date.now() - loopStarted >= control.durationMs)
                     break;
-                const child = await this.executeFlow(run, step.children ?? [], { ...scope, ...inputs }, [...path, step.id, String(current)], new Date().toISOString(), run.request.executionPackage.target, signal, [...iterations, { loopAddress: step.structuralAddress, iteration: current }]);
-                children.push(...child.steps.map(item => ({ ...item, iteration: { loopId: step.id, current, total } })));
+                const child = await this.executeFlow(run, step.children ?? [], { ...scope, ...inputs }, [...path, step.id, String(current)], new Date().toISOString(), run.execution.target, signal, [...iterations, (run.execution.document.inputVersion === 8 ? { loop: step.occurrence, iteration: current } : { loopAddress: step.structuralAddress, iteration: current })]);
+                children.push(...child.steps.map(item => ({ ...item, iteration: run.execution.document.inputVersion === 8 ? { loop: step.occurrence, current, total } : { 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)
@@ -581,9 +644,9 @@ export class DefaultExecutor {
         if (control.type === 'branch') {
             const children = [];
             for (const branch of control.branches ?? []) {
-                if (!this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step.structuralAddress))
+                if (!this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step))
                     continue;
-                const nested = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.request.executionPackage.target, signal, iterations);
+                const nested = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.execution.target, signal, iterations);
                 children.push(...nested.steps);
                 if (nested.state !== 'completed' && control.onError !== 'continue')
                     return { state: nested.state, outputs: nested.steps.at(-1)?.outputs ?? {}, children, terminalReason: nested.terminalReason, error: nested.error };
@@ -592,7 +655,7 @@ export class DefaultExecutor {
         }
         if (control.type === 'parallel') {
             const branches = control.branches ?? [];
-            const selected = branches.filter(branch => this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step.structuralAddress));
+            const selected = branches.filter(branch => this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step));
             const controllers = selected.map(() => new AbortController());
             const abortBranches = () => controllers.forEach(controller => controller.abort());
             signal.addEventListener('abort', abortBranches, { once: true });
@@ -600,7 +663,7 @@ export class DefaultExecutor {
                 abortBranches();
             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, iterations);
+                    const result = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.execution.target, controllers[index].signal, iterations);
                     return { branch, result };
                 }
                 catch (cause) {
@@ -615,16 +678,16 @@ export class DefaultExecutor {
                 throw failure('unsupported-context', 'Parallel output projections are outside this foundation slice.');
             return { state: failed ? invocationState(failed.result.state) : 'finished', outputs: {}, 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, iterations, control.type === 'sequence' ? control.onError ?? 'stop' : 'stop');
+        const nested = await this.executeFlow(run, step.children ?? [], { ...scope, ...inputs }, [...path, step.id], new Date().toISOString(), run.execution.target, signal, iterations, control.type === 'sequence' ? control.onError ?? 'stop' : 'stop');
         return { state: nested.state === 'completed' ? 'finished' : nested.state, outputs: nested.steps.at(-1)?.outputs ?? {}, children: nested.steps, terminalReason: nested.terminalReason, error: nested.error };
     }
-    resolveBindings(run, bindings, scope, consumer, context = { phase: 'entry', address: consumer }) {
+    resolveBindings(run, bindings, scope, consumer, context = { phase: 'entry' }) {
         return Object.fromEntries(Object.entries(bindings).map(([name, operand]) => [name, this.resolveOperand(run, operand, scope, consumer, context)]));
     }
-    resolveOperand(run, operand, scope, consumer, context = { phase: 'entry', address: consumer }) {
-        const issues = executionOperandDependencyIssues(run.request.executionPackage, operand, context);
+    resolveOperand(run, operand, scope, consumer, context = { phase: 'entry' }) {
+        const issues = run.execution.dependency(operand, consumer, context.phase, context.iterations);
         if (issues.length)
-            throw { code: issues[0].code, message: issues[0].reason, details: { consumer, operand } };
+            throw { code: issues[0].code, message: issues[0].message, ...(run.execution.document.inputVersion === 7 ? { details: { consumer: consumer.structuralAddress, operand } } : {}) };
         if (operand.type === 'input') {
             let value = scope;
             for (const part of operand.path) {
@@ -638,13 +701,11 @@ export class DefaultExecutor {
         }
         if (operand.type === 'unresolved-output')
             throw failure(operand.code, operand.reason);
-        const source = run.plan.get(addressKey(operand.address));
-        const selectors = source.loops.map(loop => ({ loopAddress: loop, iteration: operand.iterations.find(i => addressKey(i.loopAddress) === addressKey(loop)).iteration }));
-        const key = invocationKey(source.address, selectors);
-        const invocation = run.replay && !ownsAddress(run.replay.root, source.address)
-            ? run.replay.capture.externalEvidence.get(key) : run.journal.get(key);
+        const source = run.execution.source(operand);
+        const key = journalKey(source.step, source.iterations, run.execution.document.inputVersion);
+        const invocation = run.replay && !ownsAddress(run.replay.root, source.step.structuralAddress) ? run.replay.capture.externalEvidence.get(key) : run.journal.get(key);
         if (!invocation || !Object.hasOwn(invocation.outputs, operand.outputName) || invocation.outputs[operand.outputName] === undefined)
-            throw { code: 'output-evidence-unavailable', message: run.replay ? 'Required successful Act output is unavailable in this replay evidence view.' : 'Required successful Act output is unavailable in this Run.', details: { missing: invocation ? 'output' : 'invocation', source: operand.address, iterations: selectors, outputName: operand.outputName, consumer } };
+            throw { code: 'output-evidence-unavailable', message: run.execution.document.inputVersion === 7 ? run.replay ? 'Required successful Act output is unavailable in this replay evidence view.' : 'Required successful Act output is unavailable in this Run.' : 'Required successful Action output is unavailable in this Run.', details: { missing: invocation ? 'output' : 'invocation', source: source.step.structuralAddress, iterations: source.iterations, outputName: operand.outputName, consumer: consumer.structuralAddress } };
         return structuredClone(invocation.outputs[operand.outputName]);
     }
     evaluateCondition(run, condition, scope, consumer) {
@@ -673,7 +734,7 @@ export class DefaultExecutor {
                 return;
             // An exact external reference must already be causal at this boundary. No journal scan,
             // legacy ID lookup, or inference of selectors from the current invocation is permitted.
-            if (executionOperandDependencyIssues(run.request.executionPackage, operand, { phase: 'completion', address: operation.structuralAddress, iterations }).length)
+            if (executionOperandDependencyIssues(legacyPackage(run), operand, { phase: 'completion', address: operation.structuralAddress, iterations }).length)
                 return;
             const source = run.plan.get(addressKey(operand.address));
             const selectors = source.loops.map(loop => ({ loopAddress: loop, iteration: operand.iterations.find(i => addressKey(i.loopAddress) === addressKey(loop)).iteration }));
@@ -756,7 +817,7 @@ export class DefaultExecutor {
         }
         const breakpointKey = stepPathForBoundary(step, run, path);
         const breakpoints = run.request.debugSession?.breakpoints ?? [];
-        if (breakpoints.includes(step.id) && !run.hitBreakpoints.has(breakpointKey)) {
+        if (breakpoints.includes(run.execution.document.inputVersion === 8 ? step.occurrence : 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 }, iterations);
@@ -784,7 +845,12 @@ export class DefaultExecutor {
             this.emitReplayOccurrence(run.replay.session, type, state, step, iterations);
             return;
         }
-        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, structuralAddress: structuredClone(step.structuralAddress), iterations: structuredClone(iterations), kind: step.kind ?? 'action' } : {}), ...(control ? { control } : {}) });
+        const base = { requestId: run.request.requestId, sequence: run.events.length + 1, type, state, message, timestamp: new Date().toISOString(), ...(step ? { stepId: step.id, stepName: step.name, ...(step.structuralAddress ? { structuralAddress: structuredClone(step.structuralAddress) } : {}), kind: step.kind ?? 'action' } : {}) };
+        const event = run.request.executionPackage.schemaVersion === 8
+            ? { ...base, eventVersion: 2, ...(step ? { occurrence: step.occurrence, iterations: structuredClone(iterations) } : {}), ...(control ? { control: { type: control.type, ...(step ? { occurrence: step.occurrence } : {}) } } : {}) }
+            : { ...base, ...(step ? { iterations: structuredClone(iterations) } : {}), ...(control ? { control } : {}) };
+        freezePlan(event);
+        run.events.push(event);
         run.listeners.splice(0).forEach(resolve => resolve());
     }
     emitReplayOccurrence(session, type, state, step, iterations, attempt) {
@@ -801,15 +867,21 @@ export class DefaultExecutor {
     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;
+        const evidence = run.request.executionPackage.schemaVersion === 8 ? this.versionedResult(run, finalResult) : finalResult;
+        if (run.request.executionPackage.schemaVersion === 8)
+            freezePlan(evidence);
+        run.result = evidence;
         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.resolve(evidence);
         run.listeners.splice(0).forEach(resolve => resolve());
     }
     baseResult(run, startedAt, state, error, issues, children) {
         return { ...(run.debugProvenance ? { debugProvenance: run.debugProvenance } : {}), 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 } : {}) };
     }
+    versionedResult(run, result) {
+        return { ...result, resultVersion: 2, documentHash: run.documentHash, source: run.execution.document.source, scope: run.execution.document.selection.root, steps: result.steps, ...(result.children ? { children: result.children.map(r => this.versionedResult(run, r)) } : {}) };
+    }
     failure(cause, run, signal = run.abort.signal) {
         if (run.timedOut)
             return failure('ACTION_TIMEOUT', 'Execution exceeded its timeout.');
@@ -827,9 +899,9 @@ function preflight(pkg, inputs, runtimeValues) {
     const issues = [];
     if (!pkg.packageId || !pkg.target?.id)
         issues.push({ code: 'INVALID_PACKAGE', message: 'Execution package identity is incomplete.' });
-    const flowInputNames = new Set(pkg.target.kind === 'project' ? (pkg.flows ?? []).flatMap(flow => Array.isArray(flow.inputDeclarations) ? flow.inputDeclarations.flatMap(input => typeof input?.name === 'string' ? [input.name] : []) : []) : []);
+    const flowInputNames = new Set(pkg.project ? (pkg.flows ?? []).flatMap(flow => Array.isArray(flow.inputDeclarations) ? flow.inputDeclarations.flatMap(input => typeof input?.name === 'string' ? [input.name] : []) : []) : []);
     for (const name of pkg.requiredInputs ?? [])
-        if (inputs[name] === undefined && !flowInputNames.has(name))
+        if ((pkg instanceof ExecutionPlan && pkg.document.inputVersion === 8 ? isDeclaredInputNoValue(inputs[name]) : inputs[name] === undefined) && !flowInputNames.has(name))
             issues.push({ code: 'MISSING_INPUT', message: `Required input '${name}' is missing.` });
     for (const name of pkg.runtimeRequirements ?? [])
         if (runtimeValues[name] === undefined)

package/dist/migrated-executor.d.ts

@@ -1,4 +1,4 @@
-import type { ActReplayTarget, ActReplayHandle, OperationReplayHandle, ActionExecutor, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun, ControlCommand, ExecutionControlState } from './types.js';
+import type { AcceptedExecutorRequest, AcceptedExecutorResult, AcceptedExecutorEvent, ExecutorRequestV8, ExecutorRunV8, ActReplayTarget, ActReplayHandle, OperationReplayHandle, ActionExecutor, Executor, ExecutorConfiguration, ExecutorRequest, ExecutorRun, ControlCommand, ExecutionControlState } from './types.js';
 export declare function createMigratedExecutor(configuration?: ExecutorConfiguration): Executor;
 /**
  * Compatibility facade over the extracted Runner engine. The facade owns the
@@ -13,11 +13,13 @@ export declare class MigratedExecutor implements Executor {
     constructor(configuration?: ExecutorConfiguration);
     registerActionExecutor(executor: ActionExecutor): void;
     execute(request: ExecutorRequest): Promise<ExecutorRun>;
+    execute(request: ExecutorRequestV8): Promise<ExecutorRunV8>;
+    execute(request: AcceptedExecutorRequest): Promise<ExecutorRun | ExecutorRunV8>;
     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>;
+    events(requestId: string): AsyncIterable<AcceptedExecutorEvent>;
+    result(requestId: string): Promise<AcceptedExecutorResult>;
     retryAction(requestId: string, target: ActReplayTarget): Promise<ActReplayHandle>;
     retryOperation(requestId: string, target: ActReplayTarget): Promise<OperationReplayHandle>;
     runFromHere(requestId: string, target: ActReplayTarget): Promise<ExecutorRun>;

package/dist/migrated-executor.js

@@ -21,6 +21,10 @@ export class MigratedExecutor {
     }
     registerActionExecutor(executor) { this.routine.registerActionExecutor(executor); this.adapters.push(toActionAdapter(executor)); }
     async execute(request) {
+        if (request.executionPackage.schemaVersion === 8) {
+            this.routineRuns.add(request.requestId);
+            return this.routine.execute(request);
+        }
         if (request.executionPackage.ordering === 'routine') {
             this.routineRuns.add(request.requestId);
             return this.routine.execute(request);

package/dist/types.d.ts

@@ -223,13 +223,72 @@ export interface ExecutorConfiguration {
 }
 export interface Executor {
     execute(request: ExecutorRequest): Promise<ExecutorRun>;
+    execute(request: ExecutorRequestV8): Promise<ExecutorRunV8>;
+    execute(request: AcceptedExecutorRequest): Promise<ExecutorRun | ExecutorRunV8>;
     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>;
+    events(requestId: string): AsyncIterable<AcceptedExecutorEvent>;
+    result(requestId: string): Promise<AcceptedExecutorResult>;
     retryAction(requestId: string, target: ActReplayTarget): Promise<ActReplayHandle>;
     retryOperation(requestId: string, target: ActReplayTarget): Promise<OperationReplayHandle>;
     runFromHere(requestId: string, target: ActReplayTarget): Promise<ExecutorRun>;
     registerActionExecutor(executor: ActionExecutor): void;
 }
+/** Execution v8 admission shares the existing lifecycle; only identity/evidence is versioned. */
+export interface ExecutorRequestV8 extends Omit<ExecutorRequest, 'executionPackage' | 'debugSession'> {
+    executionPackage: import('@qaick/contract').ExecutionDocumentV8;
+    debugSession?: {
+        breakpoints: string[];
+        stopAfter?: string;
+    };
+}
+export type AcceptedExecutorRequest = ExecutorRequest | ExecutorRequestV8;
+export interface StepResultV8 extends Omit<ExecutorStepResult, 'iterations' | 'children' | 'attempts' | 'iteration'> {
+    occurrence: string;
+    iterations: import('@qaick/contract').ScopeIteration[];
+    children?: StepResultV8[];
+    attempts?: AttemptV8[];
+    iteration?: {
+        loop: string;
+        current: number;
+        total: number;
+    };
+}
+export interface AttemptV8 extends Omit<ExecutionAttempt, 'children'> {
+    children?: StepResultV8[];
+}
+export interface ExecutionResultV8 extends Omit<ExecutorResult, 'steps' | 'children'> {
+    resultVersion: 2;
+    documentHash: string;
+    source: import('@qaick/contract').DocumentSource;
+    scope: import('@qaick/contract').ExecutionRoot;
+    steps: StepResultV8[];
+    children?: ExecutionResultV8[];
+}
+export interface ExecutionEventV8 extends Omit<ExecutorEvent, 'iterations' | 'iteration' | 'parallel' | 'control'> {
+    eventVersion: 2;
+    occurrence?: string;
+    iterations?: import('@qaick/contract').ScopeIteration[];
+    iteration?: {
+        loop: string;
+        current: number;
+        total: number;
+    };
+    parallel?: {
+        group: string;
+        completed: number;
+        total: number;
+        join: 'all' | 'first';
+    };
+    control?: {
+        type: ControlCommand['type'];
+        occurrence?: string;
+    };
+}
+export type AcceptedExecutorResult = ExecutorResult | ExecutionResultV8;
+export type AcceptedExecutorEvent = ExecutorEvent | ExecutionEventV8;
+export interface ExecutorRunV8 {
+    requestId: string;
+    result: Promise<ExecutionResultV8>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaick/executor",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Host-neutral QAick action execution primitives.",
   "files": [
     "dist",
@@ -34,7 +34,7 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
-    "@qaick/contract": "0.5.0"
+    "@qaick/contract": "0.6.1"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",