@lokvis/runtime 0.2.2 → 0.4.1

package/src/batch-processor.ts

@@ -1,121 +1,25 @@
 /**
- * BatchProcessor - 批量作业处理器(W6.1 + W6.2 + W6.3)
+ * BatchProcessor - 批量作业处理器 Facade(W4.4 拆分后)
  *
- * 目标:把 W5 在 playground BatchQueue.tsx 里手写的"并发 4 池 + 进度 + 错误"
- * 逻辑下沉到 runtime,统一暴露给 SDK / MCP / UI 消费。
- *
- * 核心能力:
- * - 并发控制:基于槽位池,默认 4(Pro=16),按 MemoryGuard 压力动态收缩
- * - 失败重试:maxRetries(默认 0,与 W5 行为兼容);达到上限才发 batch:item:failed
- * - 批量上限:免费 10 文件(W6.2)、Pro 无限(超额抛 BatchLimitExceededError)
- * - 进度事件:batch:started / batch:item:* / batch:progress / batch:completed / batch:cancelled
- * - 取消:批量级 cancel,逐个取消 in-flight 项,已 pending 的标记 cancelled
- * - 暂停/恢复:挂起 schedule 循环(不取消 in-flight,完成后不再补满)
- *
- * 设计取舍:
- * - 不持久化作业状态(刷新即丢):W6 主要保证 Asset 持久化,批量队列是临时调度
- *   结构,刷新后由 UI 重新发起即可。持久化批量进度属 Phase 2。
- * - 不持有 output Blob:每项执行完即返回 AssetId,Blob 由 AssetStore(OPFS/IDB)托管,
- *   避免 50+ 图批量把 output Blob 全部留在内存导致 OOM。
- * - 单 Job 串行 schedule:同一 BatchProcessor 实例可并发 enqueue 多个 Job,但内部
- *   schedule 逻辑用 per-job lock 防重入(参考 W5 BatchQueue 的 scheduleLock 修复)。
- *
- * @example
- * ```ts
- * const job = runtime.batch.enqueue({
- *   items: files.map((f) => ({ source: { kind: 'file', file: f }, workflow: wf })),
- *   maxRetries: 1,
- * });
- * runtime.batch.onProgress(job.id, (p) => console.log(p.completed, '/', p.total));
- * await runtime.batch.waitForCompletion(job.id);
- * ```
+ * 持有 jobs Map + 协作对象(BatchScheduler / BatchProgressEmitter / ConcurrencyController),
+ * 对外保持原公开 API 不变。调度/重试/进度/并发 委托给协作对象;
+ * Facade 保留 jobs Map 管理、批量上限校验、状态机控制、toJobView。
  */
-import type {
-  AssetId,
-  AssetSource,
-  BatchItemStatus,
-  BatchJobStatus,
-  LokvisEvent,
-  Workflow,
-  WorkflowResult,
-} from '@lokvis/schema';
-import type { EventBus } from '@lokvis/schema';
+import type { BatchItemStatus, EventBus } from '@lokvis/schema';
 import type { LokvisRuntime } from './types.js';
-import { MemoryGuard, type MemoryPressure } from './memory-guard.js';
-
-/** 批量项输入(每个文件一个) */
-export interface BatchItemInput {
-  /**
-   * 资产来源:通常为 { kind: 'file', file }(用户拖入),也可为 blob/url。
-   * BatchProcessor 在执行前调 runtime.importAsset(source) 导入为 AssetId。
-   */
-  source: AssetSource;
-  /** 该项要执行的工作流(每个文件独立 workflow 实例,便于独立 cancel) */
-  workflow: Workflow;
-  /** 该项最大重试次数(覆盖 job 级 maxRetries) */
-  maxRetries?: number;
-}
-
-/** 批量项运行时状态(对外只读视图) */
-export interface BatchItem {
-  /** 项 ID(自动生成,用于事件追踪与 UI 定位) */
-  id: string;
-  /** 在 job 中的序号(0-based,用于事件中的 index 字段) */
-  index: number;
-  status: BatchItemStatus;
-  /** 输入 source(便于失败时 UI 展示文件名) */
-  source: AssetSource;
-  /** 该项执行的工作流 */
-  workflow: Workflow;
-  /** 输出 AssetId(completed 时填) */
-  outputAssetId?: AssetId;
-  /** 失败原因(failed 时填) */
-  error?: Error;
-  /** 已重试次数 */
-  attempts: number;
-  /** 该项最大重试次数 */
-  maxRetries: number;
-  /** 单项执行耗时(ms,completed 时填) */
-  duration?: number;
-}
-
-/** 批量作业运行时状态(对外只读视图) */
-export interface BatchJob {
-  id: string;
-  status: BatchJobStatus;
-  items: BatchItem[];
-  /** 已完成数(completed) */
-  completed: number;
-  /** 失败数(failed) */
-  failed: number;
-  /** 总项数 */
-  total: number;
-  /** job 起始时间(ms) */
-  startedAt: number;
-  /** job 结束时间(ms,完成后填) */
-  endedAt?: number;
-}
-
-/** enqueue 选项 */
-export interface EnqueueOptions {
-  /** 作业项 */
-  items: BatchItemInput[];
-  /** job 级最大重试次数(默认 0,单项可 BatchItemInput.maxRetries 覆盖) */
-  maxRetries?: number;
-  /**
-   * 并发槽位上限(默认按 isPro:free=4,pro=16)。
-   * 实际并发会按 MemoryGuard 压力动态收缩。
-   */
-  concurrency?: number;
-}
-
-/** 进度回调载荷 */
-export interface BatchProgress {
-  jobId: string;
-  completed: number;
-  failed: number;
-  total: number;
-}
+import { MemoryGuard } from './memory-guard.js';
+import {
+  BatchProgressEmitter,
+  type BatchJob,
+  type EnqueueOptions,
+  type BatchProgress,
+} from './batch-progress.js';
+import {
+  FREE_CONCURRENCY,
+  PRO_CONCURRENCY,
+  ConcurrencyController,
+} from './concurrency-controller.js';
+import { BatchScheduler, type BatchJobInternal } from './batch-scheduler.js';
 
 /** 批量上限超限错误(W6.2) */
 export class BatchLimitExceededError extends Error {
@@ -134,29 +38,18 @@ export class BatchLimitExceededError extends Error {
 
 /** 免费版批量上限(W6.2) */
 export const FREE_BATCH_LIMIT = 10;
+/** 终态 job 保留上限(超出按 FIFO 淘汰最旧) */
+export const MAX_RETAINED_JOBS = 10;
+
+export { FREE_CONCURRENCY, PRO_CONCURRENCY } from './concurrency-controller.js';
+export type {
+  BatchProgress,
+  BatchItemInput,
+  BatchItem,
+  BatchJob,
+  EnqueueOptions,
+} from './batch-progress.js';
 
-/** 默认并发槽位 */
-export const FREE_CONCURRENCY = 4;
-export const PRO_CONCURRENCY = 16;
-
-/** 按 MemoryPressure 收缩并发槽位 */
-function shrinkConcurrencyByPressure(
-  base: number,
-  pressure: MemoryPressure
-): number {
-  switch (pressure) {
-    case 'critical':
-      return 1;
-    case 'high':
-      return Math.max(1, Math.floor(base / 2));
-    case 'elevated':
-      return Math.max(2, Math.floor((base * 3) / 4));
-    default:
-      return base;
-  }
-}
-
-/** 生成项 ID */
 function generateItemId(): string {
   if (typeof crypto !== 'undefined' && crypto.randomUUID) {
     return `bi_${crypto.randomUUID()}`;
@@ -164,7 +57,6 @@ function generateItemId(): string {
   return `bi_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
-/** 生成 job ID */
 function generateJobId(): string {
   if (typeof crypto !== 'undefined' && crypto.randomUUID) {
     return `batch_${crypto.randomUUID()}`;
@@ -172,21 +64,14 @@ function generateJobId(): string {
   return `batch_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
-/**
- * BatchProcessor 实现。
- *
- * 不直接依赖 LokvisRuntimeImpl(避免循环引用),通过构造注入 LokvisRuntime 接口。
- * 内部用纯 JS Map 管理作业,无 React state(可被 SDK / MCP / Node 复用)。
- */
+/** BatchProcessor Facade(不依赖 LokvisRuntimeImpl,通过构造注入接口) */
 export class BatchProcessor {
   private readonly runtime: LokvisRuntime;
-  private readonly eventBus: EventBus;
   private readonly isPro: boolean;
-  private readonly memoryGuard?: MemoryGuard;
-  /** jobId → BatchJob 内部可变状态(含 private 字段) */
+  private readonly eventBus: EventBus;
   private readonly jobs = new Map<string, BatchJobInternal>();
-  /** 进度回调订阅 */
-  private readonly progressSubs = new Map<string, Set<(p: BatchProgress) => void>>();
+  private readonly scheduler: BatchScheduler;
+  private readonly progress: BatchProgressEmitter;
 
   constructor(opts: {
     runtime: LokvisRuntime;
@@ -195,35 +80,29 @@ export class BatchProcessor {
     memoryGuard?: MemoryGuard;
   }) {
     this.runtime = opts.runtime;
-    this.eventBus = opts.eventBus;
     this.isPro = opts.isPro;
-    this.memoryGuard = opts.memoryGuard;
+    this.eventBus = opts.eventBus;
+    this.progress = new BatchProgressEmitter(opts.eventBus);
+    const concurrency = new ConcurrencyController({ memoryGuard: opts.memoryGuard });
+    this.scheduler = new BatchScheduler({
+      runtime: opts.runtime,
+      progress: this.progress,
+      concurrency,
+    });
   }
 
-  /**
-   * 入队批量作业。返回 job 视图(只读)。
-   * 超过免费上限时同步抛 BatchLimitExceededError,不创建 job。
-   * 空 items 抛错(避免静默产出 0 项 completed job,遮蔽调用方逻辑错误)。
-   */
   enqueue(options: EnqueueOptions): BatchJob {
     const { items, maxRetries = 0, concurrency } = options;
-
-    // m3: 空数组视为调用方逻辑错误,显式抛错而非静默完成
     if (!Array.isArray(items) || items.length === 0) {
       throw new Error('BatchProcessor.enqueue: items cannot be empty');
     }
-
-    // W6.2 批量上限:免费 10,Pro 无限
     if (!this.isPro && items.length > FREE_BATCH_LIMIT) {
       throw new BatchLimitExceededError(FREE_BATCH_LIMIT, items.length);
     }
-
-    const jobId = generateJobId();
     const baseConcurrency =
       concurrency ?? (this.isPro ? PRO_CONCURRENCY : FREE_CONCURRENCY);
-
     const internal: BatchJobInternal = {
-      id: jobId,
+      id: generateJobId(),
       status: 'queued',
       baseConcurrency,
       maxRetries,
@@ -239,104 +118,104 @@ export class BatchProcessor {
       completed: 0,
       failed: 0,
       startedAt: Date.now(),
-      /** schedule 重入锁(参考 W5 BatchQueue scheduleLock 修复) */
       scheduleLock: false,
-      /** pause 时 schedule 不再补满新项 */
       paused: false,
-      /** cancel 标记:已发起 cancel 后所有 pending → cancelled,schedule 终止 */
       cancelled: false,
     };
-    this.jobs.set(jobId, internal);
-
-    // 异步启动(不阻塞 enqueue 调用方)
-    void this.runJob(internal);
-
+    this.jobs.set(internal.id, internal);
+    void this.scheduler.runJob(internal);
     return this.toJobView(internal);
   }
 
-  /** 列出所有作业(只读视图) */
   list(): BatchJob[] {
     return Array.from(this.jobs.values()).map((j) => this.toJobView(j));
   }
 
-  /** 获取指定 job */
   get(jobId: string): BatchJob | undefined {
     const internal = this.jobs.get(jobId);
     return internal ? this.toJobView(internal) : undefined;
   }
 
-  /** 取消整个 job:逐个取消 in-flight 项,pending 项标记 cancelled */
   async cancel(jobId: string): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) return;
     // m2: failed 也是终态,任何终态 job 不应被改写
-    if (this.isTerminal(job.status)) return;
+    if (this.scheduler.isTerminal(job.status)) return;
 
-    // B1 修复:同步先标记 cancelled,使 in-flight processItem 续跑时读到
-    // cancelled=true 后短路,避免覆盖 cancelled 状态或把被取消的项误标 failed。
+    // B1:同步先标记 cancelled,使 in-flight processItem 续跑时短路
     job.cancelled = true;
     job.paused = false;
     let cancelledCount = 0;
-
-    // 同步把所有 processing/pending 项标记 cancelled(processItem 续跑会读到此状态)
     for (const item of job.items) {
       if (item.status === 'processing' || item.status === 'pending') {
         item.status = 'cancelled';
         cancelledCount++;
       }
     }
-
-    // 异步取消所有 in-flight workflow(此时项状态已是 cancelled,
-    // processItem 续跑会因 job.cancelled 短路,不会回写其他状态)
     for (const item of job.items) {
       if (item.status === 'cancelled') {
-        const wfId = this.itemWorkflowId(job.id, item.id);
+        const wfId = this.scheduler.itemWorkflowId(job.id, item.id);
         try {
           await this.runtime.cancel(wfId);
-        } catch {
-          // 取消失败不阻断,继续取消其他项
+        } catch (err) {
+          // 取消失败不阻断后续项的 cancel,但需记录便于调试
+          console.warn(`[lokvis] BatchProcessor.cancel: cancel(${wfId}) failed:`, err);
         }
       }
     }
-
     job.status = 'cancelled';
     job.endedAt = Date.now();
-    this.emit({ type: 'batch:cancelled', jobId, cancelled: cancelledCount });
-    this.cleanupJobSubs(jobId);
+    this.progress.emitCancelled(jobId, cancelledCount);
+    this.progress.cleanupJobSubs(jobId);
+    this.pruneJobs();
+  }
+
+  /**
+   * 取消所有非终态 job + 清理 progress 订阅(W21.6 runtime.dispose 用)。
+   *
+   * 与单 job cancel 不同:不等待 runtime.cancel(wfId) 完成 —— runtime
+   * 自身的 dispose 会通过 executor.cancelAll 统一取消所有 workflow,
+   * 这里只做 batch 层面的状态标记 + 订阅清理,避免双 await 死锁。
+   */
+  async dispose(): Promise<void> {
+    for (const job of [...this.jobs.values()]) {
+      if (this.scheduler.isTerminal(job.status)) continue;
+      job.cancelled = true;
+      job.paused = false;
+      for (const item of job.items) {
+        if (item.status === 'processing' || item.status === 'pending') {
+          item.status = 'cancelled';
+        }
+      }
+      job.status = 'cancelled';
+      job.endedAt = Date.now();
+      this.progress.cleanupJobSubs(job.id);
+    }
   }
 
-  /** 暂停 job:schedule 不再补满,已 in-flight 项跑完即止 */
   async pause(jobId: string): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) return;
     if (job.status !== 'running' && job.status !== 'queued') return;
     job.paused = true;
     job.status = 'paused';
-    // m1: 发 pause 事件,UI 可订阅无需轮询
-    this.emit({ type: 'batch:paused', jobId });
+    this.progress.emitPaused(jobId);
   }
 
-  /** 恢复 job:解除 pause,schedule 继续补满 */
   async resume(jobId: string): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) return;
     if (job.status !== 'paused') return;
     job.paused = false;
     job.status = 'running';
-    // m1: 发 resumed 事件
-    this.emit({ type: 'batch:resumed', jobId });
-    void this.schedule(job);
+    this.progress.emitResumed(jobId);
+    void this.scheduler.schedule(job);
   }
 
-  /**
-   * 重试 job 中所有 failed 项(仅当 job 已结束)。
-   * 重置 attempts/error/status,pending 重新等待 schedule。
-   */
   async retryFailed(jobId: string): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) return;
     if (job.status !== 'failed' && job.status !== 'completed') return;
-
     for (const item of job.items) {
       if (item.status === 'failed') {
         item.status = 'pending';
@@ -347,319 +226,87 @@ export class BatchProcessor {
     job.failed = 0;
     job.cancelled = false;
     job.status = 'running';
-    void this.schedule(job);
+    void this.scheduler.schedule(job);
   }
 
-  /** 订阅 job 进度(返回取消订阅函数) */
   onProgress(jobId: string, handler: (p: BatchProgress) => void): () => void {
-    let subs = this.progressSubs.get(jobId);
-    if (!subs) {
-      subs = new Set();
-      this.progressSubs.set(jobId, subs);
-    }
-    subs.add(handler);
-    return () => {
-      subs!.delete(handler);
-      if (subs!.size === 0) this.progressSubs.delete(jobId);
-    };
+    return this.progress.onProgress(jobId, handler);
   }
 
   /**
-   * 等待 job 完成(completed/failed/cancelled 任一)。
+   * 等待 job 中至少 count 项进入 processing 状态(TD-2.2 长期方案)。
    *
-   * M5 修复:
-   * - 增加 timeoutMs(默认 5min),超时 reject,避免坏 job 永久挂起泄漏订阅
-   * - batch:completed 事件已涵盖 failed(maybeComplete 对 failed>0 的 job
-   *   同样发 batch:completed),故只需监听 completed + cancelled
-   * - resolve 后立即解绑所有订阅,避免调用方丢弃 promise 时泄漏
-   * - cancel/maybeComplete 进入终态时也会 cleanupJobSubs 兜底
+   * 替代测试中固定 setTimeout 赌注:基于"当前状态快照 + batch:item:started
+   * 事件订阅"双重判定,确定性等待而非时间赌注。
+   *
+   * - 先快照当前 processing 数,若已 >= count 立即 resolve(schedule 循环内
+   *   同步设置 item.status='processing' + 发 batch:item:started,enqueue
+   *   返回时首批项通常已进入 processing)
+   * - 否则订阅 batch:item:started,累计到 count 时 resolve(兜底异步场景)
+   * - 超时(默认 5s)reject,避免坏 job 永久挂起
    */
-  async waitForCompletion(
+  async waitForItemsStarted(
     jobId: string,
-    timeoutMs = 5 * 60 * 1000
-  ): Promise<BatchJob> {
+    count: number,
+    timeoutMs = 5000
+  ): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) throw new Error(`Batch job not found: ${jobId}`);
-    if (this.isTerminal(job.status)) return this.toJobView(job);
-
-    return new Promise<BatchJob>((resolve, reject) => {
+    const current = job.items.filter((i) => i.status === 'processing').length;
+    if (current >= count) return;
+    let seen = current;
+    return new Promise<void>((resolve, reject) => {
       let settled = false;
-      // 声明在前,finish 与各 handler 互相引用
-      let offCompleted: () => void;
-      let offCancelled: () => void;
-      let timer: ReturnType<typeof setTimeout>;
-      const finish = (fn: () => void) => {
+      let off: () => void;
+      const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
-        offCompleted();
-        offCancelled();
-        fn();
-      };
-      offCompleted = this.eventBus.on('batch:completed', (e) => {
-        if (e.jobId !== jobId) return;
-        finish(() => resolve(this.toJobView(this.jobs.get(jobId) ?? job)));
-      });
-      offCancelled = this.eventBus.on('batch:cancelled', (e) => {
-        if (e.jobId !== jobId) return;
-        finish(() => resolve(this.toJobView(this.jobs.get(jobId) ?? job)));
-      });
-      timer = setTimeout(() => {
-        finish(() =>
-          reject(
-            new Error(
-              `BatchProcessor.waitForCompletion timed out after ${timeoutMs}ms (jobId=${jobId})`
-            )
+        off();
+        reject(
+          new Error(
+            `waitForItemsStarted timed out after ${timeoutMs}ms ` +
+              `(jobId=${jobId}, expected=${count}, seen=${seen})`
           )
         );
       }, timeoutMs);
-    });
-  }
-
-  /** 清理 job 的所有进度订阅(终态时调用,避免泄漏) */
-  private cleanupJobSubs(jobId: string): void {
-    this.progressSubs.delete(jobId);
-  }
-
-  // ─── 内部实现 ────────────────────────────────────────
-
-  /** 启动 job:发 batch:started,进入 running,触发首次 schedule */
-  private async runJob(job: BatchJobInternal): Promise<void> {
-    if (job.cancelled) return;
-    job.status = 'running';
-    this.emit({ type: 'batch:started', jobId: job.id, total: job.items.length });
-    await this.schedule(job);
-  }
-
-  /**
-   * 调度循环:把 pending 项填入空闲槽位,直到无可用槽位或无 pending 项。
-   *
-   * 重入保护:用 scheduleLock 防止多个 schedule 调用并发导致超限(参考 W5
-   * BatchQueue.tsx 的 scheduleLock 修复:并发完成时多个 processItem 同时触发
-   * schedule 会读到相同 running 快照,导致并发超限)。
-   */
-  private async schedule(job: BatchJobInternal): Promise<void> {
-    if (job.scheduleLock) return;
-    if (job.cancelled || job.paused) return;
-    if (this.isTerminal(job.status)) return;
-
-    job.scheduleLock = true;
-    try {
-      while (!job.cancelled && !job.paused) {
-        const running = job.items.filter((i) => i.status === 'processing').length;
-        const cap = this.currentConcurrency(job);
-        if (running >= cap) break;
-
-        const next = job.items.find((i) => i.status === 'pending');
-        if (!next) break;
-
-        // 标记 processing 并启动(不 await,让循环继续补满)
-        next.status = 'processing';
-        void this.processItem(job, next);
-      }
-
-      // 循环结束:检查是否所有项都已终结
-      this.maybeComplete(job);
-    } finally {
-      job.scheduleLock = false;
-    }
-  }
-
-  /** 处理单个项:导入 → run workflow → 导出 output AssetId */
-  private async processItem(
-    job: BatchJobInternal,
-    item: BatchItemInternal
-  ): Promise<void> {
-    const start = Date.now();
-    const wfId = this.itemWorkflowId(job.id, item.id);
-
-    this.emit({
-      type: 'batch:item:started',
-      jobId: job.id,
-      itemId: item.id,
-      index: item.index,
-      total: job.items.length,
-    });
-
-    // B1 修复:cancel 已同步把 item 标为 cancelled,此处若发现 cancelled
-    // 直接短路,不发起 import/run,避免与 cancel 竞态
-    if (job.cancelled || item.status === 'cancelled') {
-      return;
-    }
-
-    let inputAssetId: AssetId | undefined;
-    let result: WorkflowResult | undefined;
-    try {
-      // 1. 导入输入资产
-      inputAssetId = await this.runtime.importAsset(item.source);
-
-      // B1 守卫:import 期间可能被 cancel
-      if (job.cancelled) {
-        item.status = 'cancelled';
-        // 清理刚导入的 input,避免孤儿资产(cancel 期间产出的 input 不应残留)
-        void this.runtime.removeAsset(inputAssetId).catch(() => {});
-        return;
-      }
-
-      // 2. 执行工作流(用独立 workflow id,便于 cancel)
-      const wf: Workflow = { ...item.workflow, id: wfId };
-      result = await this.runtime.run(wf, [inputAssetId]);
-
-      // B1 守卫:run 期间可能被 cancel(cancel 已同步标 item=cancelled)
-      if (job.cancelled) {
-        item.status = 'cancelled';
-        return;
-      }
-
-      if (result.status !== 'completed' || result.outputs.length === 0) {
-        throw new Error(result.error || `Workflow ${result.status}`);
-      }
-
-      const outputAssetId = result.outputs[0]!;
-      const duration = Date.now() - start;
-
-      // 成功
-      item.status = 'completed';
-      item.outputAssetId = outputAssetId;
-      item.duration = duration;
-      job.completed++;
-
-      this.emit({
-        type: 'batch:item:finished',
-        jobId: job.id,
-        itemId: item.id,
-        index: item.index,
-        total: job.items.length,
-        outputAssetId,
-        duration,
-      });
-      this.emitProgress(job);
-    } catch (err) {
-      // B1 守卫:被 cancel 的 workflow 抛错不计入 failed(item 已是 cancelled)
-      if (job.cancelled) {
-        item.status = 'cancelled';
-        return;
-      }
-      // 失败:判断是否还可重试
-      item.attempts++;
-      const maxRetries = item.maxRetries;
-      if (item.attempts <= maxRetries) {
-        // 重试:回 pending,schedule 会再次拉起
-        item.status = 'pending';
-        // 注意:不重置 attempts,保留累计重试次数
-        // 清理本次导入的 input asset,避免重试重新 import 时旧 input 成为孤儿
-        // (Blocker 修复:maxRetries=3 全失败原本会累积 3 个孤儿 input)
-        if (inputAssetId !== undefined) {
-          void this.runtime.removeAsset(inputAssetId).catch(() => {});
-        }
-      } else {
-        item.status = 'failed';
-        item.error = err instanceof Error ? err : new Error(String(err));
-        job.failed++;
-        // M4:最终失败时清理已导入的 input asset,避免批量失败累积孤儿资产
-        // 占用 OPFS/IDB 空间并污染 listAssets / StatusBar 配额
-        if (inputAssetId !== undefined) {
-          void this.runtime.removeAsset(inputAssetId).catch(() => {});
+      off = this.eventBus.on('batch:item:started', (e) => {
+        if (e.jobId !== jobId) return;
+        seen++;
+        if (seen >= count) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          off();
+          resolve();
         }
-        this.emit({
-          type: 'batch:item:failed',
-          jobId: job.id,
-          itemId: item.id,
-          index: item.index,
-          total: job.items.length,
-          error: item.error,
-          attempts: item.attempts,
-        });
-        this.emitProgress(job);
-      }
-    } finally {
-      // 触发 schedule 补满(用 ref 打破循环依赖)
-      if (!job.cancelled && !job.paused && !this.isTerminal(job.status)) {
-        void this.schedule(job);
-      }
-    }
-  }
-
-  /** 当前并发槽位(按内存压力动态收缩) */
-  private currentConcurrency(job: BatchJobInternal): number {
-    const pressure = this.memoryGuard?.getPressure() ?? 'low';
-    return shrinkConcurrencyByPressure(job.baseConcurrency, pressure);
-  }
-
-  /** 发出 progress 事件 + 通知订阅者 */
-  private emitProgress(job: BatchJobInternal): void {
-    const payload: BatchProgress = {
-      jobId: job.id,
-      completed: job.completed,
-      failed: job.failed,
-      total: job.items.length,
-    };
-    this.emit({
-      type: 'batch:progress',
-      ...payload,
+      });
     });
-    const subs = this.progressSubs.get(job.id);
-    if (subs) {
-      // M1 修复:遍历副本,防止 handler 内 unsubscribe/subscribe mutate 正在迭代的 Set
-      for (const fn of [...subs]) {
-        try {
-          fn(payload);
-        } catch {
-          // 单个订阅者异常不阻断其他订阅者
-        }
-      }
-    }
   }
 
-  /** 检查 job 是否全部完成,如是则发 batch:completed */
-  private maybeComplete(job: BatchJobInternal): void {
-    if (this.isTerminal(job.status)) return;
-    const pending = job.items.some(
-      (i) => i.status === 'pending' || i.status === 'processing'
-    );
-    if (pending) return;
-
-    job.endedAt = Date.now();
-    job.status = job.failed > 0 ? 'failed' : 'completed';
-    // 注意:无论 job.status 是 'completed' 还是 'failed',都发 batch:completed 事件。
-    // 事件名表示"所有项已终结(含部分失败)",而非"全部成功"。
-    // 消费方应通过 payload.failed 区分;waitForCompletion 依赖此行为(只监听
-    // batch:completed + batch:cancelled 两种终态事件)。
-    this.emit({
-      type: 'batch:completed',
-      jobId: job.id,
-      total: job.items.length,
-      completed: job.completed,
-      failed: job.failed,
-      duration: job.endedAt - job.startedAt,
+  async waitForCompletion(jobId: string, timeoutMs = 5 * 60 * 1000): Promise<BatchJob> {
+    const job = this.jobs.get(jobId);
+    if (!job) throw new Error(`Batch job not found: ${jobId}`);
+    return this.progress.waitForCompletion<BatchJob>(jobId, {
+      timeoutMs,
+      isTerminal: () => this.scheduler.isTerminal(job.status),
+      resolveJob: () => this.toJobView(this.jobs.get(jobId) ?? job),
+      onTimeout: () => this.cancel(jobId),
     });
-    // M5:进入终态清理进度订阅,避免 waitForCompletion 调用方丢弃 promise 后泄漏
-    this.cleanupJobSubs(job.id);
   }
 
-  private isTerminal(status: BatchJobStatus): boolean {
-    return (
-      status === 'completed' ||
-      status === 'cancelled' ||
-      status === 'failed'
-    );
-  }
-
-  /** 派生每项的 workflow id(独立于其他项,便于 cancel) */
-  private itemWorkflowId(jobId: string, itemId: string): string {
-    return `${jobId}__${itemId}`;
-  }
-
-  /** 安全 emit(无 EventBus 时降级为 no-op,便于纯单元测试) */
-  private emit(event: LokvisEvent): void {
-    try {
-      this.eventBus.emit(event);
-    } catch {
-      // EventBus 异常不阻断批量逻辑
+  private pruneJobs(): void {
+    const terminal: BatchJobInternal[] = [];
+    for (const job of this.jobs.values()) {
+      if (this.scheduler.isTerminal(job.status)) terminal.push(job);
+    }
+    if (terminal.length <= MAX_RETAINED_JOBS) return;
+    terminal.sort((a, b) => a.startedAt - b.startedAt);
+    const removeCount = terminal.length - MAX_RETAINED_JOBS;
+    for (let i = 0; i < removeCount; i++) {
+      this.jobs.delete(terminal[i]!.id);
     }
   }
 
-  /** 内部可变状态 → 对外只读视图(浅拷贝 items 数组与每项) */
   private toJobView(job: BatchJobInternal): BatchJob {
     return {
       id: job.id,
@@ -673,27 +320,3 @@ export class BatchProcessor {
     };
   }
 }
-
-/** BatchJob 内部可变状态(BatchProcessor 私有) */
-interface BatchJobInternal {
-  id: string;
-  status: BatchJobStatus;
-  baseConcurrency: number;
-  maxRetries: number;
-  items: BatchItemInternal[];
-  completed: number;
-  failed: number;
-  startedAt: number;
-  endedAt?: number;
-  /** schedule 重入锁 */
-  scheduleLock: boolean;
-  paused: boolean;
-  cancelled: boolean;
-}
-
-/** BatchItem 内部可变状态 */
-interface BatchItemInternal extends Omit<BatchItem, 'outputAssetId' | 'error' | 'duration'> {
-  outputAssetId?: AssetId;
-  error?: Error;
-  duration?: number;
-}