@qaick/executor 0.1.0 → 0.2.1

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.1",
   "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",