@hoplogic/hopjit 0.1.0

package/dist/engine.d.ts

@@ -0,0 +1,141 @@
+import { VariableStore, type StepStatus } from './ast-runtime.js';
+import { HopLog, type LogLevel } from './hoplog.js';
+import type { PersistenceProvider, HostConfig } from './provider-types.js';
+import type { ExecEvent, FailKind } from './runtime-types.js';
+import type { SpecAST } from './ast-types.js';
+import type { InitResponse, NextResponse, CommandResponse, StatusResponse, VarsResponse, ReplanResponse, ParallelReady, FanoutScheduleResult } from './cli-types.js';
+/** ExecutionEngine 构造/初始化选项——状态目录、持久化、日志、Inputs 实参、call/parallel 子实例参数等。见 [[exec-engine#^anc-struct-exec-engine]] */
+export interface EngineOptions {
+    stateDir?: string;
+    persistence?: PersistenceProvider;
+    logDir?: string;
+    logLevel?: LogLevel;
+    params?: Record<string, unknown>;
+    parentInstanceId?: string;
+    callStepId?: string;
+    traceId?: string;
+    canFanout?: boolean;
+    subtreeRoot?: string;
+    specPath?: string;
+    cliAbsPath?: string;
+    contextMode?: 'full' | 'minimal';
+}
+/** HopJIT 执行状态机——驱动 HopSpec 从初始化到终态，管理步骤状态机/树状变量作用域/retry-adaptive 配额/None 传播。见 [[exec-engine#^anc-struct-exec-engine]] */
+export declare class ExecutionEngine {
+    private instanceId;
+    private spec;
+    private hostConfig;
+    private stepStates;
+    private variables;
+    private loopCounters;
+    private retryCounters;
+    private retryHistory;
+    private replanCounters;
+    private lastReplanChildren;
+    private adaptiveNeededSubtask;
+    private execEvents;
+    private stepFailReasons;
+    private stateDir;
+    private instanceDir;
+    private persistence;
+    private logDir;
+    private hoplog;
+    private canFanout;
+    private subtreeRoot;
+    private specPath;
+    private cliAbsPath;
+    private dispatched;
+    private joinStartedAt;
+    private maxConcurrent;
+    private forEachWorkerIdx;
+    private contextMode;
+    initExecution(specMarkdown: string, hostConfig: HostConfig, options?: EngineOptions): InitResponse;
+    getSpec(): SpecAST | null;
+    getInstanceId(): string;
+    getStepStates(): Map<string, StepStatus>;
+    getVariableStore(): VariableStore;
+    getExecEvents(): ExecEvent[];
+    getLoopCounters(): Map<string, number>;
+    getHopLog(): HopLog | null;
+    setCanFanout(on: boolean): void;
+    getCanFanout(): boolean;
+    getSubtreeRoot(): string | null;
+    setContextMode(mode: 'full' | 'minimal'): void;
+    getContextMode(): 'full' | 'minimal';
+    private isMinimalNonFirst;
+    getInstanceDir(): string | null;
+    getHopLogRunDir(): string | null;
+    /** 顶层步骤是否全部终态（done/failed/skipped）。终态判据单点复用 isTerminalStatus。 */
+    private allTopLevelTerminal;
+    nextStep(): NextResponse;
+    completeStep(stepId: string, outputs?: Record<string, unknown>): CommandResponse;
+    completeAndAdvance(stepId: string, outputs?: Record<string, unknown>): Promise<NextResponse | CommandResponse>;
+    advanceToCaller(): Promise<NextResponse>;
+    nextParallelBatch(): ParallelReady | null;
+    private resolveChildParams;
+    fanoutSchedule(parallelStepId: string): FanoutScheduleResult;
+    private isChildTerminal;
+    private buildWorkerLaunchCommand;
+    private childLogDir;
+    private buildJoinCommand;
+    joinParallel(parallelStepId: string, childResults: Record<string, {
+        vars: Record<string, unknown>;
+        failed: boolean;
+        log?: string;
+    }>): CommandResponse;
+    /** parallel join 两分支（for-each / static）共同尾段：记 parallel 完成 + join 审计 + 落盘 + 返回 ok。 */
+    private finalizeParallelJoin;
+    private isCallerActionPoint;
+    completeCallStep(callStepId: string, childVars: Record<string, unknown>): CommandResponse;
+    failStep(stepId: string, reason: string, failKind?: FailKind): CommandResponse;
+    submitReplan(subtaskId: string, stepsMd: string): ReplanResponse;
+    selectBranch(stepId: string, selectedCaseId: string, reason?: string): CommandResponse;
+    getStatus(): StatusResponse;
+    getVars(): VarsResponse;
+    /** 递归把子树所有步骤置 pending（init 时初始化 / retry 时重置——同一操作，单点定义）。 */
+    private setSubtreePending;
+    private executeSubtreeOnly;
+    private findFirstFailedStep;
+    private propagateAndRecord;
+    getWorkZone(): string;
+    private resolveRawInputs;
+    private deflateValues;
+    private findStepById;
+    private collectOutputs;
+    private assembleBasicContext;
+    private resolveStepDocRefs;
+    private pendingDocRefSources;
+    private flushDocRefMeta;
+    private determineExecutionStatus;
+    private getFailureReason;
+    private handleFailStepRetry;
+    getActiveRetryFeedback(stepId: string): {
+        attempt: number;
+        reason: string;
+    } | undefined;
+    private extractDecision;
+    private mapConfirmOutputs;
+    private mapAskOutputs;
+    private findNearestSubtaskAncestor;
+    private resetSubtaskForRetry;
+    private markSubtaskFailed;
+    private removeChildStates;
+    private reIdSteps;
+    private skipAllDescendants;
+    /** 把步骤节点投影为 StepSummary（step_id/type/summary/输出名）。单点定义——四处（adaptive
+     * original_children、replan 两处、summarizeChildren）复用，字段增减只改这里。 */
+    private toStepSummary;
+    private summarizeChildren;
+    private recordEvent;
+    private recordStepFailure;
+    private persist;
+    private buildStateFile;
+    static load(instanceDir: string): ExecutionEngine;
+    static recover(instanceDir: string): ExecutionEngine;
+    private hasBranchSelection;
+    private validateCheckPreservation;
+    private hasCheckStep;
+    private getCheckFinallySteps;
+    private isReplanDuplicate;
+    private jaccardSimilarity;
+}