@qaick/executor 0.1.0 → 0.2.0

package/dist/executor.d.ts

@@ -1,4 +1,4 @@
-import type { ActionExecutor, ControlCommand, ExecutionControlState, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun } from './types.js';
+import type { ActReplayTarget, ActReplayHandle, OperationReplayHandle, 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;
@@ -7,23 +7,36 @@ export declare class DefaultExecutor implements Executor {
     constructor(configuration?: ExecutorConfiguration);
     registerActionExecutor(executor: ActionExecutor): void;
     execute(request: ExecutorRequest): Promise<ExecutorRun>;
+    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>;
-    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 replayTarget;
+    retryAction(requestId: string, target: ActReplayTarget): Promise<ActReplayHandle>;
+    private replayEvents;
+    private emitReplay;
+    private replayAct;
+    retryOperation(requestId: string, target: ActReplayTarget): Promise<OperationReplayHandle>;
+    private replayOperation;
+    runFromHere(sourceRequestId: string, target: ActReplayTarget): Promise<ExecutorRun>;
     private run;
     private executeProject;
     private executeFlow;
     private executeStep;
     private executeControl;
+    private resolveBindings;
+    private resolveOperand;
+    private evaluateCondition;
+    private capture;
+    private captureExternalEvidence;
+    private assertActive;
     private executeAction;
     private boundary;
     private pauseAtBoundary;
     private emit;
+    private emitReplayOccurrence;
     private finish;
     private baseResult;
     private failure;

package/dist/executor.js

@@ -1,4 +1,13 @@
 import { resolveDeclaredInputs } from './declared-inputs.js';
+import { 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])]);
+const invocationKey = (address, iterations) => JSON.stringify([addressKey(address), iterations.map(i => [addressKey(i.loopAddress), i.iteration])]);
+function freezePlan(value) {
+    if (value && typeof value === 'object') {
+        Object.values(value).forEach(freezePlan);
+        Object.freeze(value);
+    }
+}
 const MAX_TIMEOUT_MS = 300_000;
 export function createExecutor(configuration = {}) {
     return new DefaultExecutor(configuration);
@@ -13,21 +22,37 @@ export class DefaultExecutor {
     }
     registerActionExecutor(executor) { this.actionExecutors.push(executor); }
     async execute(request) {
+        return this.startRun(request);
+    }
+    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.' });
+        }
         let resolve;
         const result = new Promise(promiseResolve => { resolve = promiseResolve; });
         const run = {
-            request, resolve, events: [], listeners: [], abort: new AbortController(), cancelled: false,
+            debugSeed, debugProvenance, request: requestSnapshot, plan, 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,
             startedMs: Date.now(), pausedDurationMs: 0,
         };
         this.runs.set(request.requestId, run);
-        void this.run(run);
-        return { requestId: request.requestId, result };
+        void this.run(run, validation);
+        return { requestId: request.requestId, result, ...(debugProvenance ? { debugProvenance } : {}) };
     }
     async cancel(requestId) {
         const run = this.runs.get(requestId);
-        if (!run || run.result)
+        if (!run || run.result || run.abort.signal.aborted)
             return;
         run.cancelled = true;
         run.controlState = 'stopped';
@@ -92,92 +117,287 @@ export class DefaultExecutor {
             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 });
+    // Terminal Act replay targets only private original structural captures.
+    replayTarget(requestId, target, kind) {
+        const parent = this.runs.get(requestId);
+        const reject = (message) => { throw failure('unsupported-execution-context', message); };
+        if (!parent?.result)
+            reject('Act replay requires a terminal original Run.');
+        const run = parent;
+        if (run.cancelled || run.timedOut)
+            reject('Interrupted original Runs cannot be replayed.');
+        if (run.activeReplay)
+            reject('An interactive replay session is already active for this Run.');
+        if (!isRecord(target) || Object.keys(target).some(key => !['structuralAddress', 'iterations'].includes(key)) || hierarchyAddressIssues(target.structuralAddress).length || !Array.isArray(target.iterations))
+            reject('Malformed structural replay target.');
+        const occurrence = run.plan.get(addressKey(target.structuralAddress));
+        if (!occurrence)
+            reject('Replay structural target does not exist in the original plan.');
+        const selections = target.iterations;
+        if (selections.length !== occurrence.loops.length || selections.some(selection => !isRecord(selection) || Object.keys(selection).some(key => !['loopAddress', 'iteration'].includes(key))
+            || hierarchyAddressIssues(selection.loopAddress).length || !Number.isSafeInteger(selection.iteration) || selection.iteration < 1)
+            || new Set(selections.map(selection => addressKey(selection.loopAddress))).size !== selections.length
+            || occurrence.loops.some(loop => !selections.some(selection => addressKey(selection.loopAddress) === addressKey(loop))))
+            reject('Replay requires the complete explicit actual loop vector.');
+        const iterations = occurrence.loops.map(loop => ({ loopAddress: loop, iteration: selections.find(selection => addressKey(selection.loopAddress) === addressKey(loop)).iteration }));
+        const capture = run.replayCaptures.get(invocationKey(target.structuralAddress, iterations));
+        if (!capture || capture.kind !== kind)
+            reject('No original matching input capture exists for that structural invocation.');
+        return { run, occurrence: occurrence, capture: capture };
+    }
+    async retryAction(requestId, target) {
+        const { run, occurrence, capture } = this.replayTarget(requestId, target, 'action');
+        const snapshot = structuredClone({ structuralAddress: capture.structuralAddress, iterations: capture.iterations });
+        freezePlan(snapshot);
+        const session = {
+            parentRequestId: requestId, sessionId: crypto.randomUUID(), target: snapshot,
+            request: structuredClone(run.request), abort: new AbortController(), cancelled: false, timedOut: false,
+            kind: 'action', events: [], listeners: [],
+        };
+        run.activeReplay = session;
+        const result = this.replayAct(run, session, occurrence.step, capture.inputs);
+        const handle = {
+            parentRequestId: requestId, sessionId: session.sessionId, target: snapshot, result,
+            events: () => this.replayEvents(session),
+            cancel: async () => {
+                if (session.result || session.abort.signal.aborted)
+                    return;
+                session.cancelled = true;
+                session.abort.abort();
+            },
+        };
+        return Object.freeze(handle);
+    }
+    async *replayEvents(session) {
+        let index = 0;
+        while (true) {
+            while (index < session.events.length)
+                yield session.events[index++];
+            if (session.result)
+                return;
+            await new Promise(resolve => session.listeners.push(resolve));
+        }
+    }
+    emitReplay(session, type, state, attempt, terminalReason) {
+        const event = {
+            parentRequestId: session.parentRequestId, sessionId: session.sessionId,
+            sequence: session.events.length + 1, timestamp: new Date().toISOString(),
+            ...structuredClone(session.target), kind: session.kind, type, state,
+            ...(attempt === undefined ? {} : { attempt }), ...(terminalReason ? { terminalReason } : {}),
+        };
+        freezePlan(event);
+        session.events.push(event);
+        session.listeners.splice(0).forEach(resolve => resolve());
+    }
+    async replayAct(parent, session, step, inputs) {
+        const startedMs = Date.now(), startedAt = new Date().toISOString();
+        const attempts = [];
+        let timer;
+        let outputs = {}, evidence, error;
+        let state = 'completed';
         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);
+            // The approved session deadline is fresh and covers all attempts and retry delays.
+            const timeoutMs = session.request.options?.timeoutMs;
+            if (timeoutMs !== undefined)
+                timer = setTimeout(() => {
+                    if (session.abort.signal.aborted)
+                        return;
+                    session.timedOut = true;
+                    session.abort.abort();
+                }, timeoutMs);
+            this.emitReplay(session, 'replay_started', 'running');
+            const result = await this.executeAction(session, step, inputs, attempts, session.abort.signal, (type, attempt, attemptState) => this.emitReplay(session, type, attemptState, attempt));
+            this.assertActive(session, session.abort.signal);
+            outputs = structuredClone(result.outputs);
+            evidence = structuredClone(result.evidence);
         }
         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);
+            error = structuredClone(this.failure(cause, session));
+            state = session.timedOut ? 'failed' : session.cancelled ? 'cancelled' : 'failed';
         }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // One admitted session owns this lock and releases it on every terminal path.
+            parent.activeReplay = undefined;
+        }
+        const terminalReason = session.timedOut ? 'timeout' : state === 'cancelled' ? 'cancelled' : state === 'failed' ? 'failed' : 'completed';
+        const result = {
+            parentRequestId: session.parentRequestId, sessionId: session.sessionId, target: structuredClone(session.target), kind: 'action',
+            state, terminalReason, startedAt, finishedAt: new Date().toISOString(), durationMs: Date.now() - startedMs,
+            inputs: structuredClone(inputs), outputs, ...(evidence ? { evidence } : {}), attempts,
+            ...(error ? { error } : {}),
+        };
+        freezePlan(result);
+        session.result = result;
+        this.emitReplay(session, 'replay_finished', state, undefined, terminalReason);
+        return result;
     }
-    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 arguments_ = resolveDeclaredInputs(definition.inputDeclarations, located.inputs);
-        if (arguments_.issues.length)
-            return;
-        const childScope = { ...run.request.inputs, ...arguments_.inputs };
-        const nested = await this.executeFlow(run, definition.children, childScope, [...(located.invocationPath ?? []).slice(0, -1), definition.id], new Date().toISOString());
-        const outputs = definition.outputBindings && nested.state === 'completed'
-            ? { ...definition.staticOutputs, ...resolveBindings(definition.outputBindings, childScope, new Map(nested.steps.map(child => [child.id, child.outputs]))) }
-            : nested.steps.at(-1)?.outputs ?? {};
-        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, durationMs: nested.steps.reduce((sum, child) => sum + child.durationMs, 0), children: nested.steps, ...(nested.error ? { error: nested.error } : {}) }];
-        located.children = nested.steps;
-        located.outputs = 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 retryOperation(requestId, target) {
+        const { run, occurrence, capture } = this.replayTarget(requestId, target, 'operation');
+        if (capture.kind !== 'operation')
+            throw failure('unsupported-execution-context', 'Operation capture required.');
+        const snapshot = structuredClone({ structuralAddress: capture.structuralAddress, iterations: capture.iterations });
+        freezePlan(snapshot);
+        const session = {
+            parentRequestId: requestId, sessionId: crypto.randomUUID(), target: snapshot, kind: 'operation',
+            request: structuredClone(run.request), abort: new AbortController(), cancelled: false, timedOut: false,
+            events: [], listeners: [],
+        };
+        run.activeReplay = session;
+        const result = this.replayOperation(run, session, occurrence.step, capture);
+        return Object.freeze({
+            parentRequestId: requestId, sessionId: session.sessionId, target: snapshot, result,
+            events: () => this.replayEvents(session),
+            cancel: async () => {
+                if (session.result || session.abort.signal.aborted)
+                    return;
+                session.cancelled = true;
+                session.abort.abort();
+            },
         });
     }
-    async run(run) {
+    async replayOperation(parent, session, step, capture) {
+        const startedMs = Date.now(), startedAt = new Date().toISOString();
+        // 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, 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; },
+            controlState: 'running', pauseRequested: false, stepRequested: false,
+            controlWaiters: [], hitBreakpoints: new Set(), startedMs, pausedDurationMs: 0,
+        };
+        let timer;
+        let operation, error;
+        let state = 'completed';
+        try {
+            const timeoutMs = session.request.options?.timeoutMs;
+            if (timeoutMs !== undefined)
+                timer = setTimeout(() => {
+                    if (session.abort.signal.aborted)
+                        return;
+                    session.timedOut = true;
+                    session.abort.abort();
+                }, timeoutMs);
+            this.emitReplay(session, 'replay_started', 'running');
+            operation = await this.executeStep(context, step, capture.lexicalScope, [], session.abort.signal, capture.iterations);
+            this.assertActive(session, session.abort.signal);
+            if (operation.state !== 'finished') {
+                state = 'failed';
+                error = operation.error;
+            }
+        }
+        catch (cause) {
+            error = structuredClone(this.failure(cause, session));
+            state = session.timedOut ? 'failed' : session.cancelled ? 'cancelled' : 'failed';
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            parent.activeReplay = undefined;
+        }
+        const terminalReason = session.timedOut ? 'timeout' : state === 'cancelled' ? 'cancelled' : state === 'failed' ? 'failed' : 'completed';
+        const result = {
+            parentRequestId: session.parentRequestId, sessionId: session.sessionId,
+            target: structuredClone(session.target), kind: 'operation', state, terminalReason,
+            startedAt, finishedAt: new Date().toISOString(), durationMs: Date.now() - startedMs,
+            inputs: structuredClone(capture.inputs), lexicalScope: structuredClone(capture.lexicalScope),
+            children: structuredClone(operation?.children ?? []), outputs: state === 'completed' ? structuredClone(operation?.outputs ?? {}) : {},
+            ...(error ? { error: structuredClone(error) } : {}),
+        };
+        freezePlan(result);
+        session.result = result;
+        this.emitReplay(session, 'replay_finished', state, undefined, terminalReason);
+        return result;
+    }
+    async runFromHere(sourceRequestId, target) {
+        const source = this.runs.get(sourceRequestId);
+        const reject = (message) => { throw failure('unsupported-execution-context', message); };
+        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))
+            || hierarchyAddressIssues(target.structuralAddress).length || !Array.isArray(target.iterations) || target.iterations.length)
+            reject('Run From Here requires a top-level target with an empty iteration vector.');
+        const address = target.structuralAddress, segments = address.segments;
+        const topLevel = address.scope === 'routine'
+            ? segments.length === 2 && segments[0].kind === 'flow' && segments[1].kind === 'step'
+            : segments.length === 1 && segments[0].kind === 'step';
+        if (!topLevel)
+            reject('Nested/control continuation is not supported by Run From Here.');
+        const parent = source;
+        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 position = segments.at(-1);
+        if (position.kind !== 'step')
+            throw failure('unsupported-execution-context', 'Expected a top-level step.');
+        const stepPosition = position.position;
+        const omitted = [];
+        if (package_.executionContext.mode === 'routine') {
+            const first = segments[0];
+            if (first.kind !== 'flow')
+                throw failure('unsupported-execution-context', 'Routine selection requires an original Flow ordinal.');
+            const flowPosition = first.position;
+            const omittedFlowInputs = new Set((package_.flows ?? []).filter(f => f.structuralPosition < flowPosition).flatMap(f => (f.inputDeclarations ?? []).map(d => d.name)));
+            package_.flows = (package_.flows ?? []).filter(flow => {
+                if (flow.structuralPosition < flowPosition) {
+                    omitted.push(...flow.steps.map(s => s.structuralAddress));
+                    return false;
+                }
+                if (flow.structuralPosition === flowPosition)
+                    flow.steps = flow.steps.filter(step => {
+                        const last = step.structuralAddress.segments.at(-1);
+                        if (last.kind === 'step' && last.position < stepPosition) {
+                            omitted.push(step.structuralAddress);
+                            return false;
+                        }
+                        return true;
+                    });
+                return true;
+            });
+            const retainedRequirements = new Set([...(package_.inputDeclarations ?? []).map(d => d.name), ...(package_.flows ?? []).flatMap(f => [...(f.requiredInputs ?? []), ...(f.inputDeclarations ?? []).map(d => d.name)])]);
+            if (package_.requiredInputs)
+                package_.requiredInputs = package_.requiredInputs.filter(name => !omittedFlowInputs.has(name) || retainedRequirements.has(name));
+        }
+        else {
+            package_.steps = package_.steps.filter(step => {
+                const last = step.structuralAddress.segments.at(-1);
+                if (last.kind === 'step' && last.position < stepPosition) {
+                    omitted.push(step.structuralAddress);
+                    return false;
+                }
+                return true;
+            });
+        }
+        // Keep existing omissions and original parent/Flow ordinals; never lift or renumber.
+        const omissions = new Map((package_.omittedOccurrences ?? []).map(o => [addressKey(o.address), o]));
+        for (const omittedAddress of omitted)
+            omissions.set(addressKey(omittedAddress), { address: omittedAddress, reason: 'Run From Here predecessor omitted.' });
+        package_.omittedOccurrences = [...omissions.values()];
+        const seed = {
+            structuralAddress: structuredClone(capture.structuralAddress), inputs: structuredClone(capture.inputs),
+            ...(capture.kind === 'operation' ? { kind: 'operation', lexicalScope: structuredClone(capture.lexicalScope) } : { kind: 'action' }),
+        };
+        const provenance = {
+            kind: 'run-from-here', sourceRequestId, selection: structuredClone(target),
+            inputSeed: { kind: 'captured-inputs', inputs: structuredClone(capture.inputs),
+                ...(capture.kind === 'operation' ? { lexicalScope: structuredClone(capture.lexicalScope) } : {}) },
+            omittedOccurrences: package_.omittedOccurrences.map(o => structuredClone(o.address)),
+        };
+        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_ }, seed, provenance);
+    }
+    async run(run, validation) {
         const startedAt = new Date().toISOString();
+        if (validation.length) {
+            this.finish(run, this.baseResult(run, startedAt, 'failed', undefined, validation));
+            return;
+        }
         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.` }));
@@ -185,7 +405,8 @@ export class DefaultExecutor {
         }
         let timeout;
         if (timeoutMs !== undefined)
-            timeout = setTimeout(() => { run.timedOut = true; run.abort.abort(); }, timeoutMs);
+            timeout = setTimeout(() => { if (run.abort.signal.aborted)
+                return; 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 arguments_ = resolveDeclaredInputs(run.request.executionPackage.inputDeclarations, run.request.inputs);
@@ -211,7 +432,7 @@ export class DefaultExecutor {
             if (timeout)
                 clearTimeout(timeout);
             const error = this.failure(cause, run);
-            this.finish(run, this.baseResult(run, startedAt, run.timedOut ? 'failed' : 'cancelled', error));
+            this.finish(run, this.baseResult(run, startedAt, run.cancelled || run.abort.signal.aborted && !run.timedOut ? 'cancelled' : 'failed', error));
         }
     }
     async executeProject(run, startedAt) {
@@ -229,33 +450,34 @@ export class DefaultExecutor {
             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 };
+            if (flow.outputBindings && Object.keys(flow.outputBindings).length)
+                throw failure('unsupported-context', 'Flow completion exports are outside this foundation slice.');
         }
         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();
+    async executeFlow(run, steps, initialInputs, path, startedAt, target = run.request.executionPackage.target, signal = run.abort.signal, iterations = [], bodyFailurePolicy = 'stop') {
         const results = [];
         let state = 'completed';
         let error;
-        for (const step of run.request.executionPackage.ordering === 'routine' ? steps : orderSteps(steps)) {
+        for (const step of 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);
+            await this.boundary(run, step, [...path, step.id], signal, iterations);
+            if (run.cancelled || signal.aborted)
+                throw new Error('Execution cancelled.');
+            const result = await this.executeStep(run, step, initialInputs, path, signal, iterations);
             results.push(result);
-            outputsById.set(step.id, result.outputs);
             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'
+                    || result.error?.code === 'ACTION_TIMEOUT' || result.error?.code === 'HTTP_TIMEOUT';
+                // Only this explicitly configured body's ordinary failures are tolerated.
+                // Its child failures remain recorded; policies never leak into nested bodies.
+                if (bodyFailurePolicy === 'continue' && !interrupted)
+                    continue;
                 state = result.state === 'cancelled' ? 'cancelled' : 'failed';
                 error = result.error;
-                if (step.control?.onError !== 'continue')
+                if (interrupted || step.control?.onError !== 'continue')
                     break;
             }
         }
@@ -265,68 +487,82 @@ export class DefaultExecutor {
             steps: results,
         };
     }
-    async executeStep(run, step, scope, outputsById, path, signal = run.abort.signal) {
+    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: {}, 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);
+        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 };
+        let inputs = {};
+        const attempts = [];
+        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) };
             if (step.delayMs) {
-                this.emit(run, 'waiting', 'waiting', `${step.name} is waiting for ${step.delayMs} ms.`, step);
+                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, outputsById, path, signal);
+                const controlResult = await this.executeControl(run, step, inputs, scope, path, signal, iterations);
                 return { ...base, ...controlResult, inputs, durationMs: Date.now() - startedMs };
             }
             if (step.kind === 'operation' && step.children) {
-                const arguments_ = resolveDeclaredInputs(step.inputDeclarations, inputs);
+                const arguments_ = rootCapture ? { inputs: structuredClone(rootCapture.inputs), issues: [] } : resolveDeclaredInputs(step.inputDeclarations, inputs);
                 if (arguments_.issues.length)
                     throw failure('BINDING_RESOLUTION_ERROR', arguments_.issues.map(issue => issue.message).join(' '));
-                const childScope = { ...scope, ...arguments_.inputs };
+                const childScope = rootCapture ? structuredClone(rootCapture.lexicalScope) : { ...scope, ...arguments_.inputs };
                 for (const declaration of step.inputDeclarations ?? [])
                     if (!Object.hasOwn(arguments_.inputs, declaration.name))
                         delete childScope[declaration.name];
-                const nested = await this.executeFlow(run, step.children, childScope, [...path, step.id], new Date().toISOString(), run.request.executionPackage.target, signal);
-                const outputs = step.outputBindings && nested.state === 'completed'
-                    ? { ...step.staticOutputs, ...resolveBindings(step.outputBindings, childScope, new Map(nested.steps.map(child => [child.id, child.outputs]))) }
-                    : nested.steps.at(-1)?.outputs ?? {};
+                if (!run.replay)
+                    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 outputs = nested.state === 'completed'
+                    ? { ...structuredClone(step.staticOutputs ?? {}), ...this.resolveBindings(run, step.outputBindings ?? {}, childScope, step.structuralAddress, { phase: 'completion', address: step.structuralAddress, 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);
+                this.emit(run, 'step_finished', result.state, `${step.name} ${result.state}.`, step, undefined, iterations);
                 return result;
             }
-            const actionResult = await this.executeAction(run, step, inputs, signal);
+            if (!run.replay)
+                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) } : {}) });
+            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);
+            this.emit(run, 'step_finished', 'finished', `${step.name} finished.`, step, undefined, iterations);
             if (run.stopAfter === step.id) {
                 run.stopAfter = undefined;
-                await this.pauseAtBoundary(run, step);
+                await this.pauseAtBoundary(run, step, iterations);
             }
             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);
+            freezePlan(attempts);
+            const result = { ...base, 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, outputs, path, signal = run.abort.signal) {
+    async executeControl(run, step, inputs, scope, path, signal = run.abort.signal, iterations = []) {
         const control = step.control;
-        if (control.condition !== undefined && !evaluateCondition(control.condition, { ...scope, ...inputs }, outputs))
+        if (control.condition !== undefined && !this.evaluateCondition(run, control.condition, { ...scope, ...inputs }, step.structuralAddress))
             return { state: 'skipped', outputs: {}, terminalReason: 'condition-skipped' };
         if (control.type === 'repeat') {
-            const total = run.request.executionPackage.ordering === 'routine' ? Math.max(1, Math.min(control.iterations ?? (control.durationMs !== undefined ? 32 : 1), 32)) : control.iterations ?? 1;
+            const total = Math.max(1, Math.min(control.iterations ?? (control.durationMs !== undefined ? 32 : 1), 32));
             const loopStarted = Date.now();
             const children = [];
             for (let current = 1; current <= total; current++) {
-                if (run.request.executionPackage.ordering === 'routine' && control.durationMs !== undefined && Date.now() - loopStarted >= control.durationMs)
+                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);
+                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 } })));
                 if (child.state !== 'completed' && control.onError !== 'continue')
                     return { state: child.state, outputs: child.steps.at(-1)?.outputs ?? {}, children, terminalReason: child.terminalReason, error: child.error };
@@ -335,43 +571,29 @@ export class DefaultExecutor {
             }
             return { state: 'finished', outputs: children.at(-1)?.outputs ?? {}, children, terminalReason: 'completed' };
         }
-        if (control.type === 'branch' && run.request.executionPackage.ordering === 'routine') {
+        if (control.type === 'branch') {
             const children = [];
             for (const branch of control.branches ?? []) {
-                if (!evaluateCondition(branch.condition, { ...scope, ...inputs }, outputs))
+                if (!this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step.structuralAddress))
                     continue;
-                const nested = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.request.executionPackage.target, signal);
+                const nested = await this.executeFlow(run, branch.children, { ...scope, ...inputs }, [...path, step.id, branch.id], new Date().toISOString(), run.request.executionPackage.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 };
             }
             return { state: children.length ? 'finished' : 'skipped', outputs: children.at(-1)?.outputs ?? {}, children, terminalReason: children.length ? 'completed' : 'branch-skipped' };
         }
-        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 join = run.request.executionPackage.ordering === 'routine' ? 'all' : control.join;
-            const selected = branches.filter(branch => evaluateCondition(branch.condition, { ...scope, ...inputs }, outputs));
+            const selected = branches.filter(branch => this.evaluateCondition(run, branch.condition, { ...scope, ...inputs }, step.structuralAddress));
             const controllers = selected.map(() => new AbortController());
             const abortBranches = () => controllers.forEach(controller => controller.abort());
             signal.addEventListener('abort', abortBranches, { once: true });
             if (signal.aborted)
                 abortBranches();
-            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 (join === 'first' && result.state === 'completed' && winnerIndex === undefined) {
-                        winnerIndex = index;
-                        controllers.forEach((controller, candidate) => { if (candidate !== index)
-                            controller.abort(); });
-                    }
+                    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);
                     return { branch, result };
                 }
                 catch (cause) {
@@ -381,61 +603,166 @@ export class DefaultExecutor {
             signal.removeEventListener('abort', abortBranches);
             const nested = branchRuns.map(item => item.result);
             const children = nested.flatMap(item => item.steps);
-            const considered = 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 ?? (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 failed = branchRuns.find(item => item.result.state !== 'completed');
+            if (control.mergeBindings)
+                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);
+        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');
         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) {
+    resolveBindings(run, bindings, scope, consumer, context = { phase: 'entry', address: consumer }) {
+        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);
+        if (issues.length)
+            throw { code: issues[0].code, message: issues[0].reason, details: { consumer, operand } };
+        if (operand.type === 'input') {
+            let value = scope;
+            for (const part of operand.path) {
+                if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part))
+                    throw failure('BINDING_RESOLUTION_ERROR', `Required lexical input ${JSON.stringify(operand.path)} is absent.`);
+                value = value[part];
+            }
+            if (value === undefined)
+                throw failure('BINDING_RESOLUTION_ERROR', 'Required lexical input value is undefined.');
+            return structuredClone(value);
+        }
+        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);
+        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 } };
+        return structuredClone(invocation.outputs[operand.outputName]);
+    }
+    evaluateCondition(run, condition, scope, consumer) {
+        if (typeof condition === 'boolean')
+            return condition;
+        const value = this.resolveOperand(run, condition.binding, scope, consumer);
+        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);
+    }
+    capture(run, step, iterations, inputs, extra) {
+        const capture = { structuralAddress: structuredClone(step.structuralAddress), iterations: structuredClone(iterations), inputs: structuredClone(inputs), ...extra };
+        freezePlan(capture);
+        run.replayCaptures.set(invocationKey(step.structuralAddress, iterations), capture);
+    }
+    captureExternalEvidence(run, operation, iterations) {
+        const evidence = new Map();
+        const owns = (address) => address.scope === operation.structuralAddress.scope
+            && operation.structuralAddress.segments.every((segment, index) => JSON.stringify(segment) === JSON.stringify(address.segments[index]));
+        const captureOperand = (operand) => {
+            if (operand.type !== 'hierarchy-output' || owns(operand.address))
+                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)
+                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 }));
+            const key = invocationKey(source.address, selectors);
+            const successful = run.journal.get(key);
+            if (!successful || !Object.hasOwn(successful.outputs, operand.outputName) || successful.outputs[operand.outputName] === undefined)
+                return;
+            const snapshot = structuredClone(successful);
+            freezePlan(snapshot);
+            evidence.set(key, snapshot);
+        };
+        const condition = (value) => { if (value && typeof value !== 'boolean')
+            captureOperand(value.binding); };
+        // Shared traversal has already assigned each occurrence exactly one structural identity,
+        // including branch children that also appear in a container's presentation children.
+        for (const occurrence of run.plan.values()) {
+            if (!owns(occurrence.address))
+                continue;
+            const step = occurrence.step;
+            Object.values(step.bindings ?? {}).forEach(captureOperand);
+            Object.values(step.outputBindings ?? {}).forEach(captureOperand);
+            condition(step.control?.condition);
+            for (const branch of step.control?.branches ?? [])
+                condition(branch.condition);
+        }
+        return evidence;
+    }
+    assertActive(run, signal) {
+        if (run.timedOut)
+            throw failure('ACTION_TIMEOUT', 'Execution exceeded its timeout.');
+        if (run.cancelled || signal.aborted)
+            throw failure('ACTION_CANCELLED', 'Execution was cancelled.');
+    }
+    async executeAction(run, step, inputs, attempts, signal = run.abort.signal, onAttempt) {
         if (run.request.options?.dryRun)
-            return { outputs: {}, attempts: [] };
+            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 originalInputs = structuredClone(inputs);
+        freezePlan(originalInputs);
         const maxAttempts = Math.max(1, step.retry?.maxAttempts ?? 1);
-        const attempts = [];
         let lastFailure;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const context = { action: step.action, inputs: structuredClone(originalInputs), environment: run.request.environment, runtimeValues: run.request.runtimeValues ?? {}, step, signal };
+            this.assertActive(run, signal);
             const startedAt = new Date().toISOString();
             const startedMs = Date.now();
+            onAttempt?.('attempt_started', attempt, 'running');
             try {
-                const context = { action: step.action, inputs, environment: run.request.environment, runtimeValues: run.request.runtimeValues ?? {}, step, signal };
                 const raw = await executor.execute(context);
+                this.assertActive(run, signal);
                 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 });
+                const history = { attempt, kind: 'automatic', state: 'finished', startedAt, finishedAt: new Date().toISOString(), inputs: structuredClone(originalInputs), outputs: structuredClone(normalized.outputs), durationMs: Date.now() - startedMs, evidence: structuredClone(normalized.evidence) };
+                freezePlan(history);
+                attempts.push(history);
+                onAttempt?.('attempt_finished', attempt, history.state);
                 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)
+                const history = { attempt, kind: 'automatic', state: run.timedOut ? 'failed' : run.cancelled || signal.aborted ? 'cancelled' : 'failed', startedAt, finishedAt: new Date().toISOString(), inputs: structuredClone(originalInputs), outputs: {}, durationMs: Date.now() - startedMs, error: structuredClone(lastFailure) };
+                freezePlan(history);
+                attempts.push(history);
+                onAttempt?.('attempt_finished', attempt, history.state);
+                this.assertActive(run, signal);
+                if (attempt < maxAttempts && step.retry?.delayMs) {
+                    this.assertActive(run, signal);
                     await delay(step.retry.delayMs, signal);
+                    this.assertActive(run, signal);
+                }
             }
         }
         throw lastFailure ?? failure('ACTION_FAILED', `Action ${step.action} failed.`);
     }
-    async boundary(run, step, path, signal = run.abort.signal) {
+    async boundary(run, step, path, signal = run.abort.signal, iterations = []) {
+        if (run.replay) {
+            this.assertActive(run, signal);
+            return;
+        }
         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 });
+            this.emit(run, 'waiting', 'waiting', `Breakpoint reached before ${step.name}.`, step, { type: 'pause', stepId: step.id }, iterations);
         }
         if (run.pauseRequested || run.controlState === 'pause-requested')
-            await this.pauseAtBoundary(run, step);
+            await this.pauseAtBoundary(run, step, iterations);
         if (run.cancelled || signal.aborted)
             throw new Error('Execution cancelled.');
     }
-    async pauseAtBoundary(run, step) {
+    async pauseAtBoundary(run, step, iterations) {
         run.controlState = 'paused';
         run.pausedStartedMs = Date.now();
-        this.emit(run, 'waiting', 'waiting', `Paused before ${step.name}.`, step, { type: 'pause', stepId: step.id });
+        this.emit(run, 'waiting', 'waiting', `Paused before ${step.name}.`, step, { type: 'pause', stepId: step.id }, iterations);
         await new Promise(resolve => run.controlWaiters.push(resolve));
         run.pausedDurationMs += Date.now() - (run.pausedStartedMs ?? Date.now());
         run.pausedStartedMs = undefined;
@@ -445,10 +772,25 @@ export class DefaultExecutor {
             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 } : {}) });
+    emit(run, type, state, message, step, control, iterations = []) {
+        if (run.replay && step) {
+            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 } : {}) });
         run.listeners.splice(0).forEach(resolve => resolve());
     }
+    emitReplayOccurrence(session, type, state, step, iterations, attempt) {
+        const event = {
+            parentRequestId: session.parentRequestId, sessionId: session.sessionId,
+            sequence: session.events.length + 1, timestamp: new Date().toISOString(),
+            structuralAddress: structuredClone(step.structuralAddress), iterations: structuredClone(iterations),
+            kind: step.kind ?? 'action', type, state, ...(attempt === undefined ? {} : { attempt }),
+        };
+        freezePlan(event);
+        session.events.push(event);
+        session.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 } };
@@ -459,15 +801,15 @@ export class DefaultExecutor {
         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 } : {}) };
+        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 } : {}) };
     }
     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.');
+        if (isFailure(cause))
+            return cause;
         return failure('ACTION_FAILED', cause instanceof Error ? cause.message : 'Action execution failed.');
     }
 }
@@ -487,104 +829,9 @@ function preflight(pkg, inputs, runtimeValues) {
             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) {
@@ -599,3 +846,7 @@ 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); }
+function ownsAddress(root, address) {
+    return root.segments.length <= address.segments.length
+        && addressKey(root) === addressKey({ scope: address.scope, segments: address.segments.slice(0, root.segments.length) });
+}

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

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

package/dist/migrated-executor.d.ts

@@ -1,4 +1,4 @@
-import type { ActionExecutor, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun, ControlCommand, ExecutionControlState } from './types.js';
+import type { ActReplayTarget, ActReplayHandle, OperationReplayHandle, ActionExecutor, Executor, ExecutorConfiguration, ExecutorEvent, ExecutorRequest, ExecutorResult, ExecutorRun, ControlCommand, ExecutionControlState } from './types.js';
 export declare function createMigratedExecutor(configuration?: ExecutorConfiguration): Executor;
 /**
  * Compatibility facade over the extracted Runner engine. The facade owns the
@@ -18,7 +18,7 @@ export declare class MigratedExecutor implements Executor {
     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>;
+    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

@@ -48,17 +48,22 @@ export class MigratedExecutor {
     controlState(requestId) { return this.routineRuns.has(requestId) ? this.routine.controlState(requestId) : this.engine.controlState(requestId); }
     async *events(requestId) { yield* (this.routineRuns.has(requestId) ? this.routine.events(requestId) : this.engine.events(requestId)); }
     async result(requestId) { return (this.routineRuns.has(requestId) ? this.routine.result(requestId) : this.engine.result(requestId)); }
-    async retryAction(requestId, stepId, invocationPath) { await (this.routineRuns.has(requestId) ? this.routine.retryAction(requestId, stepId, invocationPath) : this.engine.retryAction(requestId, stepId, invocationPath)); }
-    async retryOperation(requestId, stepId, invocationPath) { await (this.routineRuns.has(requestId) ? this.routine.retryOperation(requestId, stepId, invocationPath) : this.engine.retryOperation(requestId, stepId, invocationPath)); }
-    async runFromHere(requestId, stepId, invocationPath) {
-        if (this.routineRuns.has(requestId)) {
-            const targeted = await this.routine.runFromHere(requestId, stepId, invocationPath);
-            if (targeted)
-                this.routineRuns.add(targeted.requestId);
-            return targeted;
-        }
-        const accepted = await this.engine.runFromHere(requestId, stepId, invocationPath);
-        return accepted ? { requestId: accepted.requestId, result: this.result(accepted.requestId) } : undefined;
+    async retryAction(requestId, target) {
+        if (this.routineRuns.has(requestId))
+            return this.routine.retryAction(requestId, target);
+        throw { code: 'unsupported-execution-context', message: 'Structural Act replay requires the canonical execution path.' };
+    }
+    async retryOperation(requestId, target) {
+        if (this.routineRuns.has(requestId))
+            return this.routine.retryOperation(requestId, target);
+        throw { code: 'unsupported-execution-context', message: 'Structural Operation replay requires the canonical execution path.' };
+    }
+    async runFromHere(requestId, target) {
+        if (!this.routineRuns.has(requestId))
+            throw { code: 'unsupported-execution-context', message: 'Structural Run From Here requires the canonical execution path.' };
+        const started = await this.routine.runFromHere(requestId, target);
+        this.routineRuns.add(started.requestId);
+        return started;
     }
 }
 function toActionAdapter(executor) {

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { ExecutionPackage, ExecutionStep, ExecutionState, InvocationState, TerminalReason } from '@qaick/contract';
-export type { ExecutionPackage, ExecutionStep, ExecutionState, InvocationState, TerminalReason } from '@qaick/contract';
+import type { ExecutionPackageV7 as ExecutionPackage, ExecutionStepV7 as ExecutionStep, ExecutionState, InvocationState, TerminalReason } from '@qaick/contract';
+export type { ExecutionPackageV7 as ExecutionPackage, ExecutionStepV7 as ExecutionStep, ExecutionState, InvocationState, TerminalReason } from '@qaick/contract';
 export type ActionFailureCode = 'ACTION_FAILED' | 'ACTION_TIMEOUT' | 'ACTION_CANCELLED' | 'UNSUPPORTED_ACTION' | 'BINDING_RESOLUTION_ERROR' | 'CONTROL_BLOCK_ERROR' | 'PREFLIGHT_ERROR' | 'INTERNAL_EXECUTION_ERROR';
 export interface ActionFailure {
     code: string;
@@ -12,7 +12,7 @@ export interface ActionExecutionContext {
     inputs: Record<string, unknown>;
     environment: string;
     runtimeValues: Record<string, unknown>;
-    step: ExecutionStep;
+    step: Pick<ExecutionStep, 'id' | 'name' | 'action' | 'output' | 'adapterConfig'>;
     signal: AbortSignal;
 }
 export interface ActionExecutionResult {
@@ -63,6 +63,8 @@ export interface ExecutorStepResult {
     inputs: Record<string, unknown>;
     outputs: Record<string, unknown>;
     durationMs: number;
+    structuralAddress?: import('@qaick/contract').HierarchyAddress;
+    iterations?: import('@qaick/contract').IterationSelection[];
     invocationId?: string;
     invocationPath?: string[];
     kind?: 'action' | 'operation' | 'control-block';
@@ -78,6 +80,7 @@ export interface ExecutorStepResult {
     error?: ActionFailure;
 }
 export interface ExecutorResult {
+    readonly debugProvenance?: RunFromHereProvenance;
     requestId: string;
     state: Exclude<ExecutionState, 'created' | 'preflighting' | 'running'>;
     target: ExecutionPackage['target'];
@@ -100,6 +103,9 @@ export interface ExecutorResult {
     };
 }
 export interface ExecutorEvent {
+    structuralAddress?: import('@qaick/contract').HierarchyAddress;
+    iterations?: import('@qaick/contract').IterationSelection[];
+    kind?: 'action' | 'operation' | 'control-block';
     requestId: string;
     sequence: number;
     type: 'run_started' | 'preflight_started' | 'step_started' | 'waiting' | 'step_finished' | 'run_finished';
@@ -138,9 +144,79 @@ export type ControlCommand = {
 };
 export type ExecutionControlState = 'idle' | 'running' | 'pause-requested' | 'paused' | 'resuming' | 'stopped' | 'failed' | 'completed';
 export interface ExecutorRun {
+    readonly debugProvenance?: RunFromHereProvenance;
     requestId: string;
     result: Promise<ExecutorResult>;
 }
+/** Runtime diagnostic target; never serialized into an Execution v7 package. */
+export interface ActReplayTarget {
+    structuralAddress: import('@qaick/contract').HierarchyAddress;
+    iterations: import('@qaick/contract').IterationSelection[];
+}
+/** Descriptive runtime provenance, not an execution operand or persisted package field. */
+export interface RunFromHereProvenance {
+    readonly kind: 'run-from-here';
+    readonly sourceRequestId: string;
+    readonly selection: Readonly<ActReplayTarget>;
+    readonly inputSeed: {
+        readonly kind: 'captured-inputs';
+        readonly inputs: Readonly<Record<string, unknown>>;
+        readonly lexicalScope?: Readonly<Record<string, unknown>>;
+    };
+    readonly omittedOccurrences: readonly import('@qaick/contract').HierarchyAddress[];
+}
+export interface ActReplayResult {
+    readonly parentRequestId: string;
+    readonly sessionId: string;
+    readonly target: Readonly<ActReplayTarget>;
+    readonly kind: 'action';
+    readonly state: 'completed' | 'failed' | 'cancelled';
+    readonly terminalReason: 'completed' | 'failed' | 'cancelled' | 'timeout';
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly durationMs: number;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly outputs: Readonly<Record<string, unknown>>;
+    readonly evidence?: Readonly<Record<string, unknown>>;
+    readonly attempts: readonly ExecutionAttempt[];
+    readonly error?: Readonly<ActionFailure>;
+}
+export interface ActReplayEvent {
+    readonly parentRequestId: string;
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly timestamp: string;
+    readonly structuralAddress: import('@qaick/contract').HierarchyAddress;
+    readonly iterations: import('@qaick/contract').IterationSelection[];
+    readonly kind: 'action';
+    readonly type: 'replay_started' | 'attempt_started' | 'attempt_finished' | 'replay_finished';
+    readonly state: 'running' | 'finished' | 'completed' | 'failed' | 'cancelled';
+    readonly attempt?: number;
+    readonly terminalReason?: ActReplayResult['terminalReason'];
+}
+/** A replay is associated with a historical Run; this is not a new ExecutorRun. */
+export interface ActReplayHandle {
+    readonly parentRequestId: string;
+    readonly sessionId: string;
+    readonly target: Readonly<ActReplayTarget>;
+    readonly result: Promise<ActReplayResult>;
+    events(): AsyncIterable<ActReplayEvent>;
+    cancel(): Promise<void>;
+}
+export interface OperationReplayResult extends Omit<ActReplayResult, 'kind' | 'attempts' | 'evidence'> {
+    readonly kind: 'operation';
+    readonly lexicalScope: Readonly<Record<string, unknown>>;
+    readonly children: readonly ExecutorStepResult[];
+}
+export interface OperationReplayEvent extends Omit<ActReplayEvent, 'kind' | 'type' | 'state'> {
+    readonly kind: 'action' | 'operation' | 'control-block';
+    readonly type: ActReplayEvent['type'] | 'step_started' | 'step_finished' | 'waiting';
+    readonly state: ActReplayEvent['state'] | 'waiting' | 'skipped';
+}
+export interface OperationReplayHandle extends Omit<ActReplayHandle, 'result' | 'events'> {
+    readonly result: Promise<OperationReplayResult>;
+    events(): AsyncIterable<OperationReplayEvent>;
+}
 export interface ExecutorConfiguration {
     actionExecutors?: ActionExecutor[];
     maxTimeoutMs?: number;
@@ -152,8 +228,8 @@ export interface Executor {
     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>;
+    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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaick/executor",
-  "version": "0.1.0",
+  "version": "0.2.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.2.13"
+    "@qaick/contract": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",