@hoplogic/hopjit 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+export declare enum ErrorCode {
+    INVALID_STEP_ID = "INVALID_STEP_ID",
+    INVALID_STATE = "INVALID_STATE",
+    SCHEMA_MISMATCH = "SCHEMA_MISMATCH",
+    DEPTH_EXCEEDED = "DEPTH_EXCEEDED",
+    CYCLE_DETECTED = "CYCLE_DETECTED",
+    AUTH_FAILURE = "AUTH_FAILURE",
+    CONTEXT_OVERFLOW = "CONTEXT_OVERFLOW",
+    MISSING_INPUT = "MISSING_INPUT",
+    MAX_TOOL_ITERATIONS = "MAX_TOOL_ITERATIONS",
+    BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    COMMIT_REQUIRED = "COMMIT_REQUIRED",
+    STEP_TIMEOUT = "STEP_TIMEOUT",
+    CORRUPT_STATE_FILE = "CORRUPT_STATE_FILE",// 状态文件损坏/版本不符（join 读子实例时校验）// @a: anc-exec-parallel-join-preconditions
+    REPLAN_LIMIT_EXCEEDED = "REPLAN_LIMIT_EXCEEDED",
+    REPLAN_DUPLICATE = "REPLAN_DUPLICATE",
+    PARSE_ERROR = "PARSE_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    IO_ERROR = "IO_ERROR",
+    RATE_LIMITED = "RATE_LIMITED",
+    API_TIMEOUT = "API_TIMEOUT",
+    API_NETWORK_ERROR = "API_NETWORK_ERROR",
+    API_SERVER_ERROR = "API_SERVER_ERROR",
+    TOOL_TIMEOUT = "TOOL_TIMEOUT",
+    TOOL_EXEC_ERROR = "TOOL_EXEC_ERROR",
+    ALREADY_DONE = "ALREADY_DONE",
+    ALREADY_FAILED = "ALREADY_FAILED"
+}
+/** Spec 错误联合类型——parser/validator 产出，覆盖解析与校验两类失败。见 [[shared-errors#^anc-error-spec-error]]。 */
+export type SpecError = ParseError | ValidationError;
+/** 解析错误——parser 在 markdown → AST 阶段产出，带行号定位。见 [[shared-errors#^anc-error-spec-error]]。 */
+export interface ParseError {
+    kind: 'parse';
+    line: number;
+    message: string;
+}
+/** 校验违规严重度——error 阻塞执行、warn 仅建议修复。见 [[shared-errors#^anc-error-types]]。 */
+export type ValidationSeverity = 'error' | 'warn';
+/** 校验错误——validator 产出、engine 消费，带规则 ID 与严重度定位违规。见 [[shared-errors#^anc-error-spec-error]]。 */
+export interface ValidationError {
+    kind: 'validate';
+    rule: string;
+    severity: ValidationSeverity;
+    step_id?: string;
+    line?: number;
+    message: string;
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+// @module: shared-errors ^anc-error-error-code — 错误码与错误类型契约。中稳：新增错误码向后兼容，删/改语义破坏。
+// 拆自原 types.ts（见 design/spec-ast.md ^anc-struct-spec-ast 拆分表）。
+export var ErrorCode;
+(function (ErrorCode) {
+    // Fatal (non-retryable)
+    ErrorCode["INVALID_STEP_ID"] = "INVALID_STEP_ID";
+    ErrorCode["INVALID_STATE"] = "INVALID_STATE";
+    ErrorCode["SCHEMA_MISMATCH"] = "SCHEMA_MISMATCH";
+    ErrorCode["DEPTH_EXCEEDED"] = "DEPTH_EXCEEDED";
+    ErrorCode["CYCLE_DETECTED"] = "CYCLE_DETECTED";
+    ErrorCode["AUTH_FAILURE"] = "AUTH_FAILURE";
+    ErrorCode["CONTEXT_OVERFLOW"] = "CONTEXT_OVERFLOW";
+    ErrorCode["MISSING_INPUT"] = "MISSING_INPUT";
+    ErrorCode["MAX_TOOL_ITERATIONS"] = "MAX_TOOL_ITERATIONS";
+    ErrorCode["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+    ErrorCode["COMMIT_REQUIRED"] = "COMMIT_REQUIRED";
+    ErrorCode["STEP_TIMEOUT"] = "STEP_TIMEOUT";
+    ErrorCode["CORRUPT_STATE_FILE"] = "CORRUPT_STATE_FILE";
+    ErrorCode["REPLAN_LIMIT_EXCEEDED"] = "REPLAN_LIMIT_EXCEEDED";
+    ErrorCode["REPLAN_DUPLICATE"] = "REPLAN_DUPLICATE";
+    // Retryable
+    ErrorCode["PARSE_ERROR"] = "PARSE_ERROR";
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ErrorCode["IO_ERROR"] = "IO_ERROR";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["API_TIMEOUT"] = "API_TIMEOUT";
+    ErrorCode["API_NETWORK_ERROR"] = "API_NETWORK_ERROR";
+    ErrorCode["API_SERVER_ERROR"] = "API_SERVER_ERROR";
+    ErrorCode["TOOL_TIMEOUT"] = "TOOL_TIMEOUT";
+    ErrorCode["TOOL_EXEC_ERROR"] = "TOOL_EXEC_ERROR";
+    // Idempotent hits
+    ErrorCode["ALREADY_DONE"] = "ALREADY_DONE";
+    ErrorCode["ALREADY_FAILED"] = "ALREADY_FAILED";
+})(ErrorCode || (ErrorCode = {}));

package/dist/hoplog.d.ts

@@ -0,0 +1,120 @@
+export type LogLevel = 'debug' | 'info' | 'warn';
+export interface ToolCallRecord {
+    name: string;
+    result: 'success' | 'failure';
+    at: string;
+}
+/** commit 步骤的审计字段：不可逆操作的目标、授权来源、结果、时间——审计性字段，无视日志级别始终记录。见 [[spec-observability#^anc-obs-audit]] */
+export interface CommitAuditRecord {
+    target?: string;
+    authorized_by: 'human' | 'caller' | 'policy' | 'none';
+    result: 'success' | 'failure';
+    at: string;
+}
+/** confirm 步骤的 HITL 记录：人的决策、决策者、结构化选项——审计性字段，任何级别都写入。见 [[spec-observability#^anc-obs-hitl-record]] */
+export interface HitlRecord {
+    response?: string;
+    responder?: 'human' | 'caller';
+    options?: string[];
+    at?: string;
+}
+export interface ReplanAuditRecord {
+    spec_id: string;
+    step_id: string;
+    error_reason: string;
+    generated_children: Array<{
+        step_id: string;
+        step_type: string;
+        summary: string;
+        outputs: string[];
+    }>;
+    base: 'scratch' | 'fallback';
+    at: string;
+}
+export interface StepMeta {
+    tool?: ToolCallRecord[];
+    commit_audit?: CommitAuditRecord;
+    hitl?: HitlRecord;
+    callee_spec_id?: string;
+    knowledge?: Array<{
+        source_id: string;
+        at: string;
+    }>;
+    doc_refs?: Array<{
+        source_id: string;
+        at: string;
+    }>;
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    taken?: string;
+    condition?: string;
+    llm?: {
+        model?: string;
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+    tokens_used?: number;
+}
+/** HopLog 构造选项：spec_id、日志目录、最低记录级别等——决定 run 目录命名与级别裁剪深度。见 [[spec-observability#^anc-obs-file-layout]] */
+export interface HopLogOptions {
+    specId: string;
+    logDir: string;
+    level?: LogLevel;
+    title: string;
+    goal: string;
+    inputs?: Record<string, unknown>;
+    traceId?: string;
+}
+/**
+ * HopLog 执行轨迹日志——唯一信息源是 main.yaml 文件本身。
+ * 每个 record* 方法实时 appendFileSync，无内存镜像（查询已记录内容请读文件）。
+ */
+export declare class HopLog {
+    private level;
+    private runDir;
+    private filePath;
+    private startedSteps;
+    private pendingResume;
+    private iterCounts;
+    private doneSteps;
+    private resumedWritten;
+    constructor(options: HopLogOptions);
+    static resume(runDir: string, level?: LogLevel): HopLog;
+    private flushTopLevelResume;
+    private stepDepth;
+    private ind;
+    private hoplogKey;
+    private blockHeader;
+    recordStepStart(stepId: string, type: string, summary: string, inputs?: Record<string, unknown>, promptText?: string): void;
+    private emitResumed;
+    private guardOrphan;
+    recordStepDone(stepId: string, outputs?: Record<string, unknown>): void;
+    recordStepFailed(stepId: string, reason: string, failKind?: string): void;
+    /**
+     * 记录步骤特有字段。审计性字段（tool/commit_audit/hitl/callee_spec_id）
+     * 无视日志级别始终写入；流控轨迹字段（knowledge/retry/taken/condition/llm/tokens_used）info 级写入。
+     */
+    recordStepMeta(stepId: string, meta: StepMeta): void;
+    recordWarn(stepId: string, message: string): void;
+    recordParallelFanout(parallelStepId: string, childIds: string[], maxConcurrent: number): void;
+    recordParallelDispatch(parallelStepId: string, childId: string, logDir: string): void;
+    recordParallelJoin(parallelStepId: string, childResults: Record<string, {
+        failed: boolean;
+        log?: string;
+    }>, startedAt?: string): void;
+    recordReplanAudit(audit: ReplanAuditRecord): void;
+    close(status: 'completed' | 'failed' | 'cancelled'): void;
+    getRunDir(): string;
+    getFilePath(): string;
+    flush(): void;
+    private append;
+    private shouldRecord;
+    private filterValues;
+}
+/** 日志脱敏 helper：抹除 API key 类敏感 pattern 并截断超长文本，保证密钥不落 HopLog。见 [[spec-observability#^anc-obs-log-levels]] */
+export declare function sanitize(text: string): string;
+export declare function timestamp(): string;
+/** 把日志条目对象序列化为 block-style YAML 文本，供 record* 方法实时 appendFileSync 写入 main.yaml。见 [[spec-observability#^anc-obs-hoplog-flush]] */
+export declare function toYaml(obj: unknown, indent?: number): string;