apcore-js 0.18.0 → 0.20.0

package/dist/pipeline.d.ts

@@ -32,6 +32,43 @@ export interface StepResult {
     confidence?: number | null;
     alternatives?: string[] | null;
 }
+/** Snapshot passed to runUntil predicates after each step completes (§1.4). */
+export interface PipelineState {
+    readonly stepName: string;
+    readonly outputs: Record<string, unknown>;
+    readonly context: PipelineContext;
+}
+/**
+ * Middleware interface for intercepting pipeline step lifecycle (Issue #33 §2.2).
+ *
+ * Each method is optional. The PipelineEngine invokes them in this order
+ * around every step:
+ *
+ *   beforeStep → step.execute → afterStep   (success path)
+ *   beforeStep → step.execute → onStepError (failure path)
+ *
+ * `onStepError` MAY return a non-null recovery value to suppress the error
+ * and continue the pipeline. Returning `null` (or `undefined`) re-raises the
+ * original error after every middleware has been consulted. The first
+ * middleware to return non-null wins; later middlewares are not invoked.
+ *
+ * All methods may be sync or async. The engine awaits any thenable return
+ * value (mirroring Issue #42's middleware fix) so plain functions returning
+ * a Promise are not silently dropped.
+ */
+export interface StepMiddleware {
+    /** Invoked before a step's `execute()` runs. */
+    beforeStep?(stepName: string, state: PipelineState): void | Promise<void>;
+    /** Invoked after a step's `execute()` completes successfully. */
+    afterStep?(stepName: string, state: PipelineState, result: unknown): void | Promise<void>;
+    /**
+     * Invoked when a step's `execute()` throws. Return non-null to recover
+     * (the engine treats the value as the step's output and continues).
+     * Return null/undefined to let the next middleware try, or — if no
+     * middleware recovers — to propagate the original error.
+     */
+    onStepError?(stepName: string, state: PipelineState, error: Error): unknown | null | Promise<unknown | null>;
+}
 /** Holds all state flowing through the pipeline. */
 export interface PipelineContext {
     moduleId: string;
@@ -51,6 +88,8 @@ export interface PipelineContext {
     versionHint?: string | null;
     /** Tracks which middleware ran, enabling on_error recovery chain. */
     executedMiddlewares?: unknown[];
+    /** When set, pipeline halts after the first step where predicate returns true (§1.4). */
+    runUntil?: ((state: PipelineState) => boolean) | null;
 }
 /** Records execution details for a single step. */
 export interface StepTrace {
@@ -77,14 +116,43 @@ export interface StrategyInfo {
     stepNames: string[];
     description: string;
 }
+/**
+ * Optional configuration for {@link ExecutionStrategy}.
+ *
+ * `seedProvides` lists pipeline-context fields that are guaranteed to be
+ * populated by an external caller before the first step runs. They count
+ * as "already provided" during dependency validation (Issue #33 §2.1) so
+ * that legitimate sub-strategies — for example the post-stream strategy
+ * built from {@link Step}s of a parent strategy — do not raise spurious
+ * `PipelineDependencyError`s. Use sparingly; prefer adding the missing
+ * upstream step when possible.
+ */
+export interface ExecutionStrategyOptions {
+    /** Names of pipeline-context fields the caller will pre-populate. */
+    readonly seedProvides?: readonly string[];
+}
 /** An ordered sequence of steps that defines how a module is executed. */
 export declare class ExecutionStrategy {
     readonly name: string;
     private _steps;
-    constructor(name: string, steps: Step[]);
-    /** Warn if any step's requires are not provided by a preceding step. */
+    private _nameToIdx;
+    private readonly _seedProvides;
+    constructor(name: string, steps: Step[], options?: ExecutionStrategyOptions);
+    /** Rebuild the O(1) name→index map. Call after any mutation (§1.5). */
+    private _rebuildIndex;
+    /**
+     * Fail-fast: throw `PipelineDependencyError` if any step's `requires` are not
+     * provided by a preceding step (Issue #33 §2.1).
+     *
+     * Previously this method emitted a `console.warn` and let construction
+     * succeed; that allowed misconfigured strategies to run partway and fail
+     * with a confusing runtime error. Throwing at construction surfaces the
+     * problem immediately and tells the caller which step / field is missing.
+     */
     private _validateDependencies;
     get steps(): readonly Step[];
+    /** Return the index of a step by name, or undefined if not found. O(1). */
+    findStepIndex(name: string): number | undefined;
     /** Insert a step after the named anchor step. */
     insertAfter(anchor: string, step: Step): void;
     /** Insert a step before the named anchor step. */
@@ -93,6 +161,13 @@ export declare class ExecutionStrategy {
     remove(stepName: string): void;
     /** Replace a step by name. Raises if the step is not replaceable. */
     replace(stepName: string, newStep: Step): void;
+    /**
+     * Replace a step by name using replace semantics (§1.2).
+     *
+     * Calling configureStep twice with the same stepName always leaves exactly
+     * one step at that position — idempotent, never duplicates.
+     */
+    configureStep(stepName: string, newStep: Step): void;
     /** Return the ordered list of step names. */
     stepNames(): string[];
     /** Return an AI-introspectable description of this strategy. */
@@ -127,8 +202,54 @@ export declare class StepNameDuplicateError extends ModuleError {
     static readonly DEFAULT_RETRYABLE: boolean | null;
     constructor(message?: string, options?: ErrorOptions);
 }
+/**
+ * Raised when a pipeline step fails (fail-fast, §1.1).
+ *
+ * Wraps the original exception from the failing step. When ignore_errors is
+ * true on the step, this error is NOT raised — execution continues instead.
+ */
+export declare class PipelineStepError extends ModuleError {
+    static readonly DEFAULT_RETRYABLE: boolean | null;
+    readonly stepName: string;
+    readonly pipelineTrace: PipelineTrace | null;
+    constructor(stepName: string, cause?: Error | null, trace?: PipelineTrace | null, options?: ErrorOptions);
+}
+/**
+ * Raised at strategy construction when a step's declared `requires` are not
+ * provided by any preceding step (Issue #33 §2.1).
+ *
+ * This replaces the previous `console.warn` in `_validateDependencies`. The
+ * error names the offending step and the missing fields so the caller can
+ * fix the strategy definition before any step runs.
+ */
+export declare class PipelineDependencyError extends ModuleError {
+    static readonly DEFAULT_RETRYABLE: boolean | null;
+    readonly stepName: string;
+    readonly missingRequires: string[];
+    constructor(stepName: string, missingRequires: string[], options?: ErrorOptions);
+}
+/** Raised when configureStep targets a step name that does not exist. */
+export declare class PipelineStepNotFoundError extends ModuleError {
+    static readonly DEFAULT_RETRYABLE: boolean | null;
+    readonly stepName: string;
+    constructor(stepName?: string, options?: ErrorOptions);
+}
 /** Executes an ExecutionStrategy against a PipelineContext, returning the final output and a complete execution trace. */
 export declare class PipelineEngine {
+    /**
+     * Registered step-lifecycle middlewares (Issue #33 §2.2). Invoked in
+     * registration order around every step's execute() call.
+     */
+    private readonly _stepMiddlewares;
+    /** Read-only view of the registered step middlewares. */
+    get stepMiddlewares(): readonly StepMiddleware[];
+    /**
+     * Register a `StepMiddleware` to intercept every step's lifecycle
+     * (Issue #33 §2.2). beforeStep / afterStep run in registration order;
+     * onStepError is consulted in registration order until one returns a
+     * non-null recovery value.
+     */
+    addStepMiddleware(mw: StepMiddleware): void;
     /** Run every step in the strategy against ctx, respecting flow-control actions (continue, skip_to, abort). */
     run(strategy: ExecutionStrategy, ctx: PipelineContext): Promise<[unknown, PipelineTrace]>;
 }

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js

@@ -3,16 +3,35 @@
  */
 import { ModuleError } from './errors.js';
 import { matchPattern } from './utils/pattern.js';
-// ---------------------------------------------------------------------------
-// ExecutionStrategy
-// ---------------------------------------------------------------------------
+/**
+ * Detect a thenable (Promise-like) without calling `.then`.
+ *
+ * Mirrors the Issue #42 fix in MiddlewareManager: handlers may not be
+ * declared `async` but still return a Promise; treating those values as
+ * sync would silently drop their effects.
+ */
+function _isThenable(value) {
+    return (value != null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+async function _maybeAwait(value) {
+    if (_isThenable(value)) {
+        return await value;
+    }
+    return value;
+}
 /** An ordered sequence of steps that defines how a module is executed. */
 export class ExecutionStrategy {
     name;
     _steps;
-    constructor(name, steps) {
+    _nameToIdx;
+    _seedProvides;
+    constructor(name, steps, options) {
         this.name = name;
         this._steps = [...steps];
+        this._nameToIdx = new Map();
+        this._seedProvides = new Set(options?.seedProvides ?? []);
         // Validate unique step names
         const names = this._steps.map((s) => s.name);
         const seen = new Set();
@@ -26,18 +45,35 @@ export class ExecutionStrategy {
         if (dupes.size > 0) {
             throw new StepNameDuplicateError(`Duplicate step names: ${[...dupes].join(', ')}`);
         }
+        this._rebuildIndex();
         this._validateDependencies();
     }
-    /** Warn if any step's requires are not provided by a preceding step. */
+    /** Rebuild the O(1) name→index map. Call after any mutation (§1.5). */
+    _rebuildIndex() {
+        this._nameToIdx = new Map(this._steps.map((s, i) => [s.name, i]));
+    }
+    /**
+     * Fail-fast: throw `PipelineDependencyError` if any step's `requires` are not
+     * provided by a preceding step (Issue #33 §2.1).
+     *
+     * Previously this method emitted a `console.warn` and let construction
+     * succeed; that allowed misconfigured strategies to run partway and fail
+     * with a confusing runtime error. Throwing at construction surfaces the
+     * problem immediately and tells the caller which step / field is missing.
+     */
     _validateDependencies() {
-        const provided = new Set();
+        const provided = new Set(this._seedProvides);
         for (const step of this._steps) {
             const requires = step.requires ?? [];
+            const missing = [];
             for (const req of requires) {
                 if (!provided.has(req)) {
-                    console.warn(`[apcore:pipeline] Step '${step.name}' requires '${req}', but no preceding step provides it. This may cause runtime errors.`);
+                    missing.push(req);
                 }
             }
+            if (missing.length > 0) {
+                throw new PipelineDependencyError(step.name, missing);
+            }
             for (const p of step.provides ?? []) {
                 provided.add(p);
             }
@@ -46,59 +82,82 @@ export class ExecutionStrategy {
     get steps() {
         return this._steps;
     }
+    /** Return the index of a step by name, or undefined if not found. O(1). */
+    findStepIndex(name) {
+        return this._nameToIdx.get(name);
+    }
     /** Insert a step after the named anchor step. */
     insertAfter(anchor, step) {
-        if (this._steps.some((s) => s.name === step.name)) {
+        if (this._nameToIdx.has(step.name)) {
             throw new StepNameDuplicateError(`Step '${step.name}' already exists`);
         }
-        for (let i = 0; i < this._steps.length; i++) {
-            if (this._steps[i].name === anchor) {
-                this._steps.splice(i + 1, 0, step);
-                this._validateDependencies();
-                return;
-            }
+        const anchorIdx = this._nameToIdx.get(anchor);
+        if (anchorIdx === undefined) {
+            throw new StepNotFoundError(`Anchor step '${anchor}' not found`);
         }
-        throw new StepNotFoundError(`Anchor step '${anchor}' not found`);
+        this._steps.splice(anchorIdx + 1, 0, step);
+        this._rebuildIndex();
+        this._validateDependencies();
     }
     /** Insert a step before the named anchor step. */
     insertBefore(anchor, step) {
-        if (this._steps.some((s) => s.name === step.name)) {
+        if (this._nameToIdx.has(step.name)) {
             throw new StepNameDuplicateError(`Step '${step.name}' already exists`);
         }
-        for (let i = 0; i < this._steps.length; i++) {
-            if (this._steps[i].name === anchor) {
-                this._steps.splice(i, 0, step);
-                this._validateDependencies();
-                return;
-            }
+        const anchorIdx = this._nameToIdx.get(anchor);
+        if (anchorIdx === undefined) {
+            throw new StepNotFoundError(`Anchor step '${anchor}' not found`);
         }
-        throw new StepNotFoundError(`Anchor step '${anchor}' not found`);
+        this._steps.splice(anchorIdx, 0, step);
+        this._rebuildIndex();
+        this._validateDependencies();
     }
     /** Remove a step by name. Raises if the step is not removable. */
     remove(stepName) {
-        for (let i = 0; i < this._steps.length; i++) {
-            if (this._steps[i].name === stepName) {
-                if (!this._steps[i].removable) {
-                    throw new StepNotRemovableError(`Step '${stepName}' is not removable`);
-                }
-                this._steps.splice(i, 1);
-                return;
-            }
+        const idx = this._nameToIdx.get(stepName);
+        if (idx === undefined) {
+            throw new StepNotFoundError(`Step '${stepName}' not found`);
         }
-        throw new StepNotFoundError(`Step '${stepName}' not found`);
+        if (!this._steps[idx].removable) {
+            throw new StepNotRemovableError(`Step '${stepName}' is not removable`);
+        }
+        this._steps.splice(idx, 1);
+        this._rebuildIndex();
     }
     /** Replace a step by name. Raises if the step is not replaceable. */
     replace(stepName, newStep) {
-        for (let i = 0; i < this._steps.length; i++) {
-            if (this._steps[i].name === stepName) {
-                if (!this._steps[i].replaceable) {
-                    throw new StepNotReplaceableError(`Step '${stepName}' is not replaceable`);
-                }
-                this._steps[i] = newStep;
-                return;
-            }
+        const idx = this._nameToIdx.get(stepName);
+        if (idx === undefined) {
+            throw new StepNotFoundError(`Step '${stepName}' not found`);
+        }
+        if (!this._steps[idx].replaceable) {
+            throw new StepNotReplaceableError(`Step '${stepName}' is not replaceable`);
+        }
+        this._steps[idx] = newStep;
+        this._rebuildIndex();
+    }
+    /**
+     * Replace a step by name using replace semantics (§1.2).
+     *
+     * Calling configureStep twice with the same stepName always leaves exactly
+     * one step at that position — idempotent, never duplicates.
+     */
+    configureStep(stepName, newStep) {
+        const idx = this._nameToIdx.get(stepName);
+        if (idx === undefined) {
+            throw new PipelineStepNotFoundError(stepName);
+        }
+        if (!this._steps[idx].replaceable) {
+            throw new StepNotReplaceableError(`Step '${stepName}' is not replaceable`);
         }
-        throw new StepNotFoundError(`Step '${stepName}' not found`);
+        // Guard: reject if newStep.name already exists at a different position.
+        // Allowing it would silently produce duplicate names in _steps and corrupt
+        // _nameToIdx (the second entry for that name would shadow the first).
+        if (newStep.name !== stepName && this._nameToIdx.has(newStep.name)) {
+            throw new StepNameDuplicateError(`Step '${newStep.name}' already exists at a different position`);
+        }
+        this._steps[idx] = newStep;
+        this._rebuildIndex();
     }
     /** Return the ordered list of step names. */
     stepNames() {
@@ -110,7 +169,7 @@ export class ExecutionStrategy {
             name: this.name,
             stepCount: this._steps.length,
             stepNames: this.stepNames(),
-            description: this.stepNames().join(' \u2192 '),
+            description: this.stepNames().join(' → '),
         };
     }
 }
@@ -165,11 +224,76 @@ export class StepNameDuplicateError extends ModuleError {
         this.name = 'StepNameDuplicateError';
     }
 }
+/**
+ * Raised when a pipeline step fails (fail-fast, §1.1).
+ *
+ * Wraps the original exception from the failing step. When ignore_errors is
+ * true on the step, this error is NOT raised — execution continues instead.
+ */
+export class PipelineStepError extends ModuleError {
+    static DEFAULT_RETRYABLE = false;
+    stepName;
+    pipelineTrace;
+    constructor(stepName, cause, trace, options) {
+        const causeMsg = cause?.message ?? 'unknown error';
+        super('PIPELINE_STEP_ERROR', `Pipeline step '${stepName}' failed: ${causeMsg}`, { stepName }, cause ?? undefined, options?.traceId, options?.retryable, options?.aiGuidance, options?.userFixable, options?.suggestion);
+        this.name = 'PipelineStepError';
+        this.stepName = stepName;
+        this.pipelineTrace = trace ?? null;
+    }
+}
+/**
+ * Raised at strategy construction when a step's declared `requires` are not
+ * provided by any preceding step (Issue #33 §2.1).
+ *
+ * This replaces the previous `console.warn` in `_validateDependencies`. The
+ * error names the offending step and the missing fields so the caller can
+ * fix the strategy definition before any step runs.
+ */
+export class PipelineDependencyError extends ModuleError {
+    static DEFAULT_RETRYABLE = false;
+    stepName;
+    missingRequires;
+    constructor(stepName, missingRequires, options) {
+        super('PIPELINE_DEPENDENCY_ERROR', `Pipeline step '${stepName}' requires [${missingRequires.join(', ')}], but no preceding step provides ${missingRequires.length === 1 ? 'it' : 'them'}.`, { stepName, missingRequires: [...missingRequires] }, options?.cause, options?.traceId, options?.retryable, options?.aiGuidance, options?.userFixable, options?.suggestion);
+        this.name = 'PipelineDependencyError';
+        this.stepName = stepName;
+        this.missingRequires = [...missingRequires];
+    }
+}
+/** Raised when configureStep targets a step name that does not exist. */
+export class PipelineStepNotFoundError extends ModuleError {
+    static DEFAULT_RETRYABLE = false;
+    stepName;
+    constructor(stepName = '', options) {
+        super('PIPELINE_STEP_NOT_FOUND', `Pipeline step not found: '${stepName}'`, { stepName }, options?.cause, options?.traceId, options?.retryable, options?.aiGuidance, options?.userFixable, options?.suggestion);
+        this.name = 'PipelineStepNotFoundError';
+        this.stepName = stepName;
+    }
+}
 // ---------------------------------------------------------------------------
 // PipelineEngine
 // ---------------------------------------------------------------------------
 /** Executes an ExecutionStrategy against a PipelineContext, returning the final output and a complete execution trace. */
 export class PipelineEngine {
+    /**
+     * Registered step-lifecycle middlewares (Issue #33 §2.2). Invoked in
+     * registration order around every step's execute() call.
+     */
+    _stepMiddlewares = [];
+    /** Read-only view of the registered step middlewares. */
+    get stepMiddlewares() {
+        return this._stepMiddlewares;
+    }
+    /**
+     * Register a `StepMiddleware` to intercept every step's lifecycle
+     * (Issue #33 §2.2). beforeStep / afterStep run in registration order;
+     * onStepError is consulted in registration order until one returns a
+     * non-null recovery value.
+     */
+    addStepMiddleware(mw) {
+        this._stepMiddlewares.push(mw);
+    }
     /** Run every step in the strategy against ctx, respecting flow-control actions (continue, skip_to, abort). */
     async run(strategy, ctx) {
         const pipelineStart = performance.now();
@@ -182,6 +306,7 @@ export class PipelineEngine {
             success: false,
         };
         ctx.trace = trace;
+        const stepOutputs = {};
         let idx = 0;
         while (idx < steps.length) {
             const step = steps[idx];
@@ -219,8 +344,19 @@ export class PipelineEngine {
                 idx += 1;
                 continue;
             }
-            // ③ Execute with per-step timeout
+            // ③ Execute with per-step timeout, wrapped in StepMiddleware hooks (§2.2)
             const stepStart = performance.now();
+            const stepState = {
+                stepName: step.name,
+                outputs: stepOutputs,
+                context: ctx,
+            };
+            // ③a beforeStep hooks (registration order)
+            for (const mw of this._stepMiddlewares) {
+                if (mw.beforeStep) {
+                    await _maybeAwait(mw.beforeStep(step.name, stepState));
+                }
+            }
             let result;
             try {
                 if (stepTimeoutMs > 0) {
@@ -240,14 +376,55 @@ export class PipelineEngine {
             }
             catch (exc) {
                 const durationMs = performance.now() - stepStart;
+                const cause = exc instanceof Error ? exc : new Error(String(exc));
+                // ③b onStepError hooks: first non-null recovery wins (§2.2)
+                let recovery = null;
+                for (const mw of this._stepMiddlewares) {
+                    if (!mw.onStepError)
+                        continue;
+                    const ret = await _maybeAwait(mw.onStepError(step.name, stepState, cause));
+                    if (ret != null) {
+                        recovery = ret;
+                        break;
+                    }
+                }
+                if (recovery != null) {
+                    // The recovery value is informational — it's surfaced to afterStep
+                    // hooks and recorded in the trace explanation, but NOT auto-merged
+                    // into ctx.output. Middlewares that want to publish recovery state
+                    // into output should mutate ctx.output directly inside onStepError.
+                    const recoveredResult = {
+                        action: 'continue',
+                        explanation: `recovered from: ${cause.message}`,
+                    };
+                    trace.steps.push({
+                        name: step.name,
+                        durationMs,
+                        result: recoveredResult,
+                        skipped: false,
+                        decisionPoint: false,
+                        skipReason: 'error_recovered',
+                    });
+                    // afterStep hooks still fire on recovery — middlewares treat recovery
+                    // as a successful (post-step) outcome and may want to record metrics.
+                    for (const mw of this._stepMiddlewares) {
+                        if (mw.afterStep) {
+                            await _maybeAwait(mw.afterStep(step.name, stepState, recovery));
+                        }
+                    }
+                    stepOutputs[step.name] = ctx.output != null ? { ...ctx.output } : null;
+                    idx += 1;
+                    continue;
+                }
                 // ④ ignore_errors: log and continue
                 if (stepIgnoreErrors) {
+                    console.warn(`[apcore:pipeline] Step '${step.name}' failed (ignored):`, cause.message);
                     trace.steps.push({
                         name: step.name,
                         durationMs,
                         result: {
                             action: 'continue',
-                            explanation: exc instanceof Error ? exc.message : String(exc),
+                            explanation: cause.message,
                         },
                         skipped: false,
                         decisionPoint: false,
@@ -256,21 +433,27 @@ export class PipelineEngine {
                     idx += 1;
                     continue;
                 }
-                // Not ignored: record and raise
+                // Fail-fast (§1.1): wrap in PipelineStepError with step name and cause
                 trace.steps.push({
                     name: step.name,
                     durationMs,
                     result: {
                         action: 'abort',
-                        explanation: exc instanceof Error ? exc.message : String(exc),
+                        explanation: cause.message,
                     },
                     skipped: false,
                     decisionPoint: false,
                 });
                 trace.totalDurationMs = performance.now() - pipelineStart;
-                throw exc;
+                throw new PipelineStepError(step.name, cause, trace);
             }
             const durationMs = performance.now() - stepStart;
+            // ③c afterStep hooks (registration order, success path)
+            for (const mw of this._stepMiddlewares) {
+                if (mw.afterStep) {
+                    await _maybeAwait(mw.afterStep(step.name, stepState, result));
+                }
+            }
             // ⑤ Record trace
             trace.steps.push({
                 name: step.name,
@@ -279,8 +462,23 @@ export class PipelineEngine {
                 skipped: false,
                 decisionPoint: result.confidence != null,
             });
-            // ⑥ Handle abort / skip_to
+            // ⑥ Handle abort / skip_to / continue
             if (result.action === 'continue') {
+                // Snapshot output for run_until predicates (§1.4)
+                stepOutputs[step.name] = ctx.output != null ? { ...ctx.output } : null;
+                // ⑦ run_until: evaluate predicate after each successful continue (§1.4)
+                if (ctx.runUntil != null) {
+                    const state = {
+                        stepName: step.name,
+                        outputs: stepOutputs,
+                        context: ctx,
+                    };
+                    if (ctx.runUntil(state)) {
+                        trace.totalDurationMs = performance.now() - pipelineStart;
+                        trace.success = true;
+                        return [ctx.output ?? null, trace];
+                    }
+                }
                 idx += 1;
             }
             else if (result.action === 'abort') {
@@ -290,8 +488,9 @@ export class PipelineEngine {
             }
             else if (result.action === 'skip_to') {
                 const target = result.skipTo ?? '';
-                const targetIdx = steps.findIndex((s, i) => i > idx && s.name === target);
-                if (targetIdx === -1) {
+                // O(1) step index lookup (§1.5)
+                const targetIdx = strategy.findStepIndex(target);
+                if (targetIdx === undefined || targetIdx <= idx) {
                     throw new StepNotFoundError(`skip_to target '${target}' not found after step '${step.name}'`);
                 }
                 // Mark skipped steps in trace