@qimen-lab/core 0.1.1

package/dist/task/hash-task/hash/HashTaskResources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HashTaskResources.d.ts","sourceRoot":"","sources":["../../../../../src/task/hash-task/hash/HashTaskResources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAIrD;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC,oBAAoB;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAYtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ/B,OAAO,CAAC,YAAY,CAAC,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAC,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;OAKG;gBAEkB,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,UAAU;IAG3C;;;;;;;;;;OAUG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevE;;;;;;;OAOG;YACW,aAAa;IAW3B;;;;;;;OAOG;YACW,aAAa;IAU3B;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B9B;;;;;;;;OAQG;IACH,SAAS,IAAI,YAAY;IAOzB;;;;;;;OAOG;IACH,QAAQ,IAAI,wBAAwB;CAOvC"}

package/dist/task/hash-task/hash/HashTaskResources.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HashTaskResources = void 0;
+const errors_1 = require("../errors");
+const ResourceNotAcquiredError_1 = require("../errors/ResourceNotAcquiredError");
+/**
+ * 哈希任务资源管理类
+ *
+ * 负责管理哈希任务所需的资源，包括内存和Worker。
+ * 这是一个资源管理器，用于在执行哈希任务时获取和释放必要的计算资源。
+ * 设计原则是单一职责，只负责资源的申请和释放，不涉及具体的哈希计算逻辑。
+ *
+ * 设计原则：
+ * - 仅负责资源的申请与释放
+ * - 不涉及具体哈希计算逻辑
+ * - 保证资源操作的原子性
+ * - 提供资源状态快照
+ */
+class HashTaskResources {
+    /**
+     * 构造函数
+     *
+     * @param memoryManager 内存管理器，用于申请和释放内存资源
+     * @param workerPool Worker池，用于获取和归还Worker线程
+     */
+    constructor(memoryManager, workerPool) {
+        this.memoryManager = memoryManager;
+        this.workerPool = workerPool;
+        this.acquired = false; // 标记资源是否已成功获取
+    }
+    /**
+     * 核心：申请计算所需的资源（内存 + 线程）
+     *
+     * 此方法用于为哈希任务申请必要的计算资源。如果资源已经获取，则直接返回。
+     * 方法具有原子性，要么成功获取所有资源，要么在失败时释放已获取的资源。
+     *
+     * @param scriptSource 经过 Builder 转换后的算法源码字符串，将被注入到Worker中
+     * @param memoryBytes 需要锁定的内存预算，以字节为单位
+     * @returns 当资源成功获取后解析的Promise
+     * @throws 当资源申请失败时，会抛出相应的错误，并确保已申请的资源被释放
+     */
+    async acquire(scriptSource, memoryBytes) {
+        if (this.acquired)
+            return; // 防止重复获取资源
+        try {
+            // 按顺序获取内存和Worker资源
+            await this.acquireMemory(memoryBytes);
+            await this.acquireWorker(scriptSource);
+            this.acquired = true; // 标记资源已获取
+        }
+        catch (err) {
+            // 如果获取过程中出现错误，释放已获取的资源
+            await this.release();
+            throw err; // 重新抛出原始错误
+        }
+    }
+    /**
+     * 专用方法：获取内存资源
+     *
+     * 尝试从内存管理器获取指定数量的字节，如果失败则抛出内存资源不可用错误
+     *
+     * @param memoryBytes 需要获取的内存字节数
+     * @throws ResourceUnavailableError 如果内存不足或获取失败
+     */
+    async acquireMemory(memoryBytes) {
+        try {
+            this.memoryTicket = await this.memoryManager.acquire(memoryBytes);
+        }
+        catch (err) {
+            throw new errors_1.ResourceUnavailableError('memory', {
+                requestedBytes: memoryBytes,
+                originalError: err instanceof Error ? err.message : err,
+            });
+        }
+    }
+    /**
+     * 专用方法：获取Worker资源
+     *
+     * 尝试从Worker池获取一个Worker实例，如果失败则抛出Worker资源不可用错误
+     *
+     * @param scriptSource 要注入到Worker中的脚本源码
+     * @throws ResourceUnavailableError 如果Worker池已满或获取失败
+     */
+    async acquireWorker(scriptSource) {
+        try {
+            this.worker = await this.workerPool.acquire(scriptSource);
+        }
+        catch (err) {
+            throw new errors_1.ResourceUnavailableError('worker', {
+                originalError: err instanceof Error ? err.message : err,
+            });
+        }
+    }
+    /**
+     * 释放所有资源（幂等）
+     *
+     * 释放之前通过acquire方法获取的所有资源。此方法是幂等的，
+     * 即可以安全地多次调用而不会产生副作用。
+     * 无论资源是否已经被释放，或者从未被获取，调用此方法都是安全的。
+     *
+     * @returns 当资源成功释放后解析的Promise
+     */
+    async release() {
+        // 释放Worker资源（如果已获取）
+        if (this.worker) {
+            try {
+                this.workerPool.release(this.worker);
+            }
+            catch (error) {
+                // 即使释放worker失败，也要继续释放其他资源
+                console.error('Failed to release worker:', error);
+            }
+            this.worker = undefined;
+        }
+        // 释放内存资源（如果已获取）
+        if (this.memoryTicket) {
+            try {
+                this.memoryTicket.release();
+            }
+            catch (error) {
+                // 即使释放内存失败，也要继续执行
+                console.error('Failed to release memory ticket:', error);
+            }
+            this.memoryTicket = undefined;
+        }
+        // 重置获取状态
+        this.acquired = false;
+    }
+    /**
+     * 访问 worker（只允许 Runner 用）
+     *
+     * 获取当前持有的Worker句柄，供Runner使用来执行实际的哈希计算。
+     * 如果尚未获取Worker或Worker已被释放，则抛出错误。
+     *
+     * @returns Worker句柄，可用于向Worker发送消息和接收结果
+     * @throws 如果Worker尚未获取则抛出错误，确保使用者意识到资源未就绪
+     */
+    getWorker() {
+        if (!this.worker) {
+            throw new ResourceNotAcquiredError_1.ResourceNotAcquiredError();
+        }
+        return this.worker;
+    }
+    /**
+     * 当前资源快照（给 health / debug）
+     *
+     * 获取当前资源使用情况的快照，主要用于健康检查和调试目的。
+     * 返回一个不可变的对象，包含当前内存使用量和Worker状态。
+     *
+     * @returns 资源快照对象，包含内存字节数（如果有）和Worker存在状态
+     */
+    snapshot() {
+        var _a;
+        return {
+            // ✅ 修正：如果有内存票据，返回具体的字节数
+            memoryBytes: (_a = this.memoryTicket) === null || _a === void 0 ? void 0 : _a.bytes,
+            hasWorker: !!this.worker, // 确保返回布尔值
+        };
+    }
+}
+exports.HashTaskResources = HashTaskResources;
+//# sourceMappingURL=HashTaskResources.js.map

package/dist/task/hash-task/hash/HashTaskResources.js.map

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

package/dist/task/hash-task/hash/HashTaskRunner.d.ts

@@ -0,0 +1,122 @@
+import { HashTaskResources } from './HashTaskResources';
+import { HashTaskState } from './HashTaskState';
+import { HashTaskProgress } from './HashTaskProgress';
+import { HashTaskOptions } from './HashTask';
+/**
+ * HashTaskRunner类
+ *
+ * 该类只负责流程控制：
+ * - 驱动任务生命周期
+ * - 串联 State / Progress / Resources
+ * - 把「计算」委托给 worker
+ * - 处理中断（pause / cancel）
+ *
+ * 明确不负责：
+ * - 不分块（ChunkProvider 的事）
+ * - 不实现 hash 算法
+ * - 不处理内存细节
+ * - 不做健康监控
+ * - 不做任务调度
+ */
+export declare class HashTaskRunner {
+    private readonly state;
+    private readonly progress;
+    private readonly resources;
+    private readonly options;
+    private logger;
+    private builder;
+    /**
+     * 构造函数
+     *
+     * @param state 任务状态管理器
+     * @param progress 任务进度管理器
+     * @param resources 任务资源管理器
+     * @param options 哈希任务选项
+     */
+    constructor(state: HashTaskState, progress: HashTaskProgress, resources: HashTaskResources, options: HashTaskOptions);
+    /**
+     * 获取ChunkProvider的辅助属性，让代码更易读
+     */
+    private get chunkProvider();
+    /**
+     * 执行哈希任务
+     *
+     * 该方法负责：
+     * 1. 构建Worker脚本
+     * 2. 计算所需内存
+     * 3. 获取资源（内存和Worker）
+     * 4. 启动健康监控
+     * 5. 执行哈希计算
+     * 6. 最终释放资源
+     *
+     * @returns Promise<ArrayBuffer> 包含哈希结果的Promise
+     */
+    run(): Promise<ArrayBuffer>;
+    /**
+     * 暂停任务：通过状态机实现
+     *
+     * 检查当前状态是否允许暂停，如果允许则更新状态为暂停
+     */
+    pause(): void;
+    /**
+     * 恢复任务：通过状态机实现
+     *
+     * 检查当前状态是否允许恢复，如果允许则更新状态为运行中
+     */
+    resume(): void;
+    /**
+     * 取消任务：直接调用状态机的 cancel
+     * 状态变更为 'cancelled' 后，executeHashing 循环中的 isCancelled() 会检测到并抛出异常
+     *
+     * 检查当前状态是否允许取消，如果允许则更新状态为已取消
+     */
+    cancel(): void;
+    /**
+     * 等待任务恢复（如果处于暂停状态）
+     *
+     * 当任务处于暂停状态时，持续等待直到恢复运行或被取消
+     *
+     * @private
+     */
+    private waitIfPaused;
+    /**
+     * 运行单个数据块的哈希计算
+     *
+     * 该方法向Worker发送数据块进行哈希计算，并等待处理结果
+     *
+     * @param worker Worker句柄
+     * @param chunk 要处理的数据块
+     * @returns Promise<void> 表示处理完成的Promise
+     * @private
+     */
+    private runChunk;
+    /**
+     * 完成哈希计算并获取最终结果
+     *
+     * 该方法向Worker发送完成信号并等待最终的哈希结果
+     *
+     * @param worker Worker句柄
+     * @returns Promise<ArrayBuffer> 包含最终哈希结果的Promise
+     * @private
+     */
+    private finalize;
+    /**
+     * 计算所需内存大小
+     *
+     * 根据数据块大小计算所需的内存，预留额外空间用于处理
+     *
+     * @returns 所需的内存大小（以字节为单位）
+     * @private
+     */
+    private calculateRequiredMemory;
+    /**
+     * 执行哈希计算的主要逻辑
+     *
+     * 主循环：获取数据块 -> 检查暂停/取消 -> 执行哈希 -> 更新进度 -> 继续下一块
+     *
+     * @returns Promise<ArrayBuffer> 包含最终哈希结果的Promise
+     * @private
+     */
+    private executeHashing;
+}
+//# sourceMappingURL=HashTaskRunner.d.ts.map

package/dist/task/hash-task/hash/HashTaskRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HashTaskRunner.d.ts","sourceRoot":"","sources":["../../../../../src/task/hash-task/hash/HashTaskRunner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IAanB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf5B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,OAAO,CAA6B;IAE5C;;;;;;;OAOG;gBAEkB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,eAAe;IAK7C;;OAEG;IACH,OAAO,KAAK,aAAa,GAExB;IAED;;;;;;;;;;;;OAYG;IACG,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC;IAiCjC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAMd;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAMd;;;;;;OAMG;YACW,YAAY;IAO1B;;;;;;;;;OASG;YACW,QAAQ;IA2BtB;;;;;;;;OAQG;YACW,QAAQ;IAgBtB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAQ/B;;;;;;;OAOG;YACW,cAAc;CAiC/B"}

package/dist/task/hash-task/hash/HashTaskRunner.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HashTaskRunner = void 0;
+const logger_1 = require("@qimenjs/logger");
+const worker_1 = require("../worker");
+const HashTaskHealthMonitor_1 = require("./HashTaskHealthMonitor");
+/**
+ * HashTaskRunner类
+ *
+ * 该类只负责流程控制：
+ * - 驱动任务生命周期
+ * - 串联 State / Progress / Resources
+ * - 把「计算」委托给 worker
+ * - 处理中断（pause / cancel）
+ *
+ * 明确不负责：
+ * - 不分块（ChunkProvider 的事）
+ * - 不实现 hash 算法
+ * - 不处理内存细节
+ * - 不做健康监控
+ * - 不做任务调度
+ */
+class HashTaskRunner {
+    /**
+     * 构造函数
+     *
+     * @param state 任务状态管理器
+     * @param progress 任务进度管理器
+     * @param resources 任务资源管理器
+     * @param options 哈希任务选项
+     */
+    constructor(state, progress, resources, options) {
+        this.state = state;
+        this.progress = progress;
+        this.resources = resources;
+        this.options = options;
+        this.builder = new worker_1.WorkerScriptBuilder();
+        this.logger = logger_1.Logger.for('HashTaskRunner');
+    }
+    /**
+     * 获取ChunkProvider的辅助属性，让代码更易读
+     */
+    get chunkProvider() {
+        return this.options.chunkProvider;
+    }
+    /**
+     * 执行哈希任务
+     *
+     * 该方法负责：
+     * 1. 构建Worker脚本
+     * 2. 计算所需内存
+     * 3. 获取资源（内存和Worker）
+     * 4. 启动健康监控
+     * 5. 执行哈希计算
+     * 6. 最终释放资源
+     *
+     * @returns Promise<ArrayBuffer> 包含哈希结果的Promise
+     */
+    async run() {
+        this.logger.debug(`Starting hash task with algorithm: ${this.options.algorithm}`);
+        const scriptSource = this.builder.build(this.options.algorithm);
+        // 使用新定义的辅助属性计算内存
+        const memoryRequired = this.calculateRequiredMemory();
+        this.logger.debug(`Acquiring resources: memory=${(memoryRequired / 1024 / 1024).toFixed(2)}MB`);
+        await this.resources.acquire(scriptSource, memoryRequired);
+        const monitor = new HashTaskHealthMonitor_1.HashTaskHealthMonitor(this.state, this.progress, this.resources);
+        monitor.start();
+        try {
+            // 注意：此时 State 的迁移需要符合你上传的 HashTaskState.ts 逻辑
+            if (this.state.canStart()) {
+                this.state.start();
+            }
+            return await this.executeHashing();
+        }
+        catch (err) {
+            // 如果 state 有 fail 方法，在这里调用
+            // this.state.fail(err);
+            this.logger.error('Task failed:', err);
+            throw err;
+        }
+        finally {
+            this.logger.debug('Releasing resources and stopping monitor.');
+            monitor.stop();
+            await this.resources.release();
+        }
+    }
+    /**
+     * 暂停任务：通过状态机实现
+     *
+     * 检查当前状态是否允许暂停，如果允许则更新状态为暂停
+     */
+    pause() {
+        if (this.state.canPause()) {
+            this.state.pause();
+        }
+    }
+    /**
+     * 恢复任务：通过状态机实现
+     *
+     * 检查当前状态是否允许恢复，如果允许则更新状态为运行中
+     */
+    resume() {
+        if (this.state.canResume()) {
+            this.state.resume();
+        }
+    }
+    /**
+     * 取消任务：直接调用状态机的 cancel
+     * 状态变更为 'cancelled' 后，executeHashing 循环中的 isCancelled() 会检测到并抛出异常
+     *
+     * 检查当前状态是否允许取消，如果允许则更新状态为已取消
+     */
+    cancel() {
+        if (this.state.canCancel()) {
+            this.state.cancel();
+        }
+    }
+    /**
+     * 等待任务恢复（如果处于暂停状态）
+     *
+     * 当任务处于暂停状态时，持续等待直到恢复运行或被取消
+     *
+     * @private
+     */
+    async waitIfPaused() {
+        // ✅ 统一使用 state 判定，不再需要私有变量
+        while (this.state.value === 'paused' && !this.state.isCancelled()) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+        }
+    }
+    /**
+     * 运行单个数据块的哈希计算
+     *
+     * 该方法向Worker发送数据块进行哈希计算，并等待处理结果
+     *
+     * @param worker Worker句柄
+     * @param chunk 要处理的数据块
+     * @returns Promise<void> 表示处理完成的Promise
+     * @private
+     */
+    async runChunk(worker, chunk) {
+        return new Promise((resolve, reject) => {
+            let unsubscribe;
+            // 1. 定义处理器
+            const handler = (msg) => {
+                // 只响应当前 chunk 的确认消息
+                if (msg.type === 'ack' && msg.chunkId === chunk.id) {
+                    if (unsubscribe)
+                        unsubscribe(); // ✨ 执行清理！
+                    resolve();
+                }
+                else if (msg.type === 'error') {
+                    if (unsubscribe)
+                        unsubscribe(); // ✨ 出错也要清理！
+                    reject(new Error(msg.message));
+                }
+            };
+            // 2. 订阅消息
+            unsubscribe = worker.onMessage(handler);
+            // 3. 发送数据
+            worker.post({ type: 'update', chunkId: chunk.id, data: chunk.data }, [chunk.data] // 零拷贝转移
+            );
+        });
+    }
+    /**
+     * 完成哈希计算并获取最终结果
+     *
+     * 该方法向Worker发送完成信号并等待最终的哈希结果
+     *
+     * @param worker Worker句柄
+     * @returns Promise<ArrayBuffer> 包含最终哈希结果的Promise
+     * @private
+     */
+    async finalize(worker) {
+        return new Promise((resolve, reject) => {
+            let unsubscribe;
+            const onMessage = (msg) => {
+                if (msg.type === 'digest') {
+                    if (unsubscribe)
+                        unsubscribe(); // ✨ 清理
+                    resolve(msg.result);
+                }
+            };
+            unsubscribe = worker.onMessage(onMessage);
+            worker.post({ type: 'final' });
+        });
+    }
+    /**
+     * 计算所需内存大小
+     *
+     * 根据数据块大小计算所需的内存，预留额外空间用于处理
+     *
+     * @returns 所需的内存大小（以字节为单位）
+     * @private
+     */
+    calculateRequiredMemory() {
+        // 所有的 Provider 现在都有这个方法了
+        const chunkSize = this.chunkProvider.getChunkSize();
+        // 预留 2 个分片 + 1MB 冗余
+        return chunkSize * 2 + 1024 * 1024;
+    }
+    /**
+     * 执行哈希计算的主要逻辑
+     *
+     * 主循环：获取数据块 -> 检查暂停/取消 -> 执行哈希 -> 更新进度 -> 继续下一块
+     *
+     * @returns Promise<ArrayBuffer> 包含最终哈希结果的Promise
+     * @private
+     */
+    async executeHashing() {
+        const worker = this.resources.getWorker();
+        const provider = this.chunkProvider;
+        while (provider.hasNext()) {
+            // 1. 检查暂停
+            await this.waitIfPaused();
+            // 2. 检查取消
+            if (this.state.isCancelled()) {
+                throw new Error('Task cancelled');
+            }
+            const chunk = await provider.next();
+            if (!chunk)
+                break;
+            // 3. 执行哈希
+            await this.runChunk(worker, chunk);
+            // 4. 更新进度
+            this.progress.onChunk(chunk);
+        }
+        const result = await this.finalize(worker);
+        // ✨ 完成后同步状态机
+        if (this.state.canPause()) {
+            // 此时状态通常是 running
+            this.state.complete();
+        }
+        return result;
+    }
+}
+exports.HashTaskRunner = HashTaskRunner;
+//# sourceMappingURL=HashTaskRunner.js.map

package/dist/task/hash-task/hash/HashTaskRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HashTaskRunner.js","sourceRoot":"","sources":["../../../../../src/task/hash-task/hash/HashTaskRunner.ts"],"names":[],"mappings":";;;AAAA,4CAAkD;AAKlD,sCAA8D;AAE9D,mEAAgE;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,MAAa,cAAc;IAIvB;;;;;;;OAOG;IACH,YACqB,KAAoB,EACpB,QAA0B,EAC1B,SAA4B,EAC5B,OAAwB;QAHxB,UAAK,GAAL,KAAK,CAAe;QACpB,aAAQ,GAAR,QAAQ,CAAkB;QAC1B,cAAS,GAAT,SAAS,CAAmB;QAC5B,YAAO,GAAP,OAAO,CAAiB;QAdrC,YAAO,GAAG,IAAI,4BAAmB,EAAE,CAAC;QAgBxC,IAAI,CAAC,MAAM,GAAG,eAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,IAAY,aAAa;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,GAAG;QACL,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QAClF,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhE,iBAAiB;QACjB,MAAM,cAAc,GAAG,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAEtD,IAAI,CAAC,MAAM,CAAC,KAAK,CACb,+BAA+B,CAAC,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAC/E,CAAC;QACF,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,IAAI,6CAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrF,OAAO,CAAC,KAAK,EAAE,CAAC;QAEhB,IAAI,CAAC;YACD,8CAA8C;YAC9C,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;YAED,OAAO,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,2BAA2B;YAC3B,wBAAwB;YACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YACvC,MAAM,GAAG,CAAC;QACd,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC/D,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QACnC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM;QACF,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM;QACF,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,YAAY;QACtB,2BAA2B;QAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YAChE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3D,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACK,KAAK,CAAC,QAAQ,CAAC,MAAoB,EAAE,KAAY;QACrD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,WAAuB,CAAC;YAE5B,WAAW;YACX,MAAM,OAAO,GAAG,CAAC,GAAQ,EAAE,EAAE;gBACzB,oBAAoB;gBACpB,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC,EAAE,EAAE,CAAC;oBACjD,IAAI,WAAW;wBAAE,WAAW,EAAE,CAAC,CAAC,UAAU;oBAC1C,OAAO,EAAE,CAAC;gBACd,CAAC;qBAAM,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBAC9B,IAAI,WAAW;wBAAE,WAAW,EAAE,CAAC,CAAC,YAAY;oBAC5C,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;gBACnC,CAAC;YACL,CAAC,CAAC;YAEF,UAAU;YACV,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAExC,UAAU;YACV,MAAM,CAAC,IAAI,CACP,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EACvD,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ;aACxB,CAAC;QACN,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,QAAQ,CAAC,MAAoB;QACvC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,WAAuB,CAAC;YAE5B,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAE,EAAE;gBAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACxB,IAAI,WAAW;wBAAE,WAAW,EAAE,CAAC,CAAC,OAAO;oBACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACxB,CAAC;YACL,CAAC,CAAC;YAEF,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACK,uBAAuB;QAC3B,yBAAyB;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC;QAEpD,oBAAoB;QACpB,OAAO,SAAS,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,cAAc;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC;QAEpC,OAAO,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACxB,UAAU;YACV,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YAE1B,UAAU;YACV,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;YACtC,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,MAAM;YAElB,UAAU;YACV,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAEnC,UAAU;YACV,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE3C,aAAa;QACb,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;YACxB,kBAAkB;YAClB,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;QAED,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AAjPD,wCAiPC"}

package/dist/task/hash-task/hash/HashTaskState.d.ts

@@ -0,0 +1,143 @@
+import { TaskStatus } from '../types';
+/**
+ * HashTaskState 只做 3 件事：
+ * - 维护任务状态机
+ * - 校验状态迁移是否合法
+ * - 提供只读快照
+ *
+ * 明确不负责：
+ * - 不处理异步操作
+ * - 不操作资源
+ * - 不记录日志
+ * - 不抛出原始Error（只抛出语义化Error）
+ */
+/**
+ * 任务状态快照接口
+ *
+ * 定义了任务状态的快照信息
+ */
+export interface TaskStateSnapshot {
+    /** 当前任务状态 */
+    status: TaskStatus;
+    /** 开始时间戳（可选） */
+    startedAt?: number;
+    /** 完成时间戳（可选） */
+    finishedAt?: number;
+    /** 暂停时间戳（可选） */
+    pausedAt?: number;
+}
+/**
+ * 哈希任务状态管理类
+ *
+ * 管理哈希任务的整个生命周期状态，包括状态迁移验证和状态查询
+ */
+export declare class HashTaskState {
+    private status;
+    private startedAt?;
+    private finishedAt?;
+    private pausedAt?;
+    /**
+     * 获取当前任务状态
+     */
+    get value(): TaskStatus;
+    /**
+     * 检查是否可以开始任务
+     *
+     * @returns 如果当前状态为 'idle' 则返回 true，否则返回 false
+     */
+    canStart(): boolean;
+    /**
+     * 检查是否可以暂停任务
+     *
+     * @returns 如果当前状态为 'running' 则返回 true，否则返回 false
+     */
+    canPause(): boolean;
+    /**
+     * 检查是否可以恢复任务
+     *
+     * @returns 如果当前状态为 'paused' 则返回 true，否则返回 false
+     */
+    canResume(): boolean;
+    /**
+     * 检查是否可以取消任务
+     *
+     * @returns 如果当前状态为 'running' 或 'paused' 则返回 true，否则返回 false
+     */
+    canCancel(): boolean;
+    /**
+     * 检查任务是否已完成
+     *
+     * @returns 如果当前状态为 'completed'、'failed' 或 'cancelled' 则返回 true，否则返回 false
+     */
+    isFinished(): boolean;
+    /**
+     * 适配 Runner 的检查逻辑
+     * 判断任务是否因为用户操作而进入了取消状态
+     *
+     * @returns 如果当前状态为 'cancelled' 则返回 true，否则返回 false
+     */
+    isCancelled(): boolean;
+    /**
+     * 开始任务
+     *
+     * 将任务状态从 'idle' 迁移到 'running'，并记录开始时间
+     *
+     * @throws TaskStateError 如果当前状态不允许开始操作
+     */
+    start(): void;
+    /**
+     * 暂停任务
+     *
+     * 将任务状态从 'running' 迁移到 'paused'，并记录暂停时间
+     *
+     * @throws TaskStateError 如果当前状态不允许暂停操作
+     */
+    pause(): void;
+    /**
+     * 恢复任务
+     *
+     * 将任务状态从 'paused' 迁移到 'running'，并清除暂停时间
+     *
+     * @throws TaskStateError 如果当前状态不允许恢复操作
+     */
+    resume(): void;
+    /**
+     * 完成任务
+     *
+     * 将任务状态从 'running' 迁移到 'completed'，并记录完成时间
+     *
+     * @throws TaskStateError 如果当前状态不允许完成操作
+     */
+    complete(): void;
+    /**
+     * 标记任务失败
+     *
+     * 将任务状态迁移到 'failed'，并记录完成时间
+     *
+     * @param error 失败的错误对象
+     * @throws TaskStateError 如果当前状态不允许失败操作
+     */
+    fail(error: Error): void;
+    /**
+     * 取消任务
+     *
+     * 将任务状态迁移到 'cancelled'，并记录完成时间
+     *
+     * @throws TaskStateError 如果当前状态不允许取消操作
+     */
+    cancel(): void;
+    /**
+     * 生成当前状态的快照
+     *
+     * @returns 任务状态快照
+     */
+    snapshot(): TaskStateSnapshot;
+    /**
+     * 适配 Runner 的状态更新逻辑
+     * 将状态迁移封装一层，方便 Runner 调用
+     *
+     * @param newStatus 新的任务状态
+     */
+    updateStatus(newStatus: TaskStatus): void;
+}
+//# sourceMappingURL=HashTaskState.d.ts.map