@lokvis/runtime 0.2.0-beta.0 → 0.2.0

package/src/runtime.ts

@@ -11,10 +11,12 @@ import type {
   Capability,
   CapabilityParam,
   CapabilityParamType,
+  ExifData,
   HistoryEntry,
   LokvisEvent,
   McpManifest,
   McpToolManifest,
+  MetadataReader,
 } from '@lokvis/schema';
 import type { Workflow, WorkflowResult } from '@lokvis/schema';
 import { validateWorkflow } from '@lokvis/schema';
@@ -34,7 +36,14 @@ import {
 } from './asset-store.js';
 import { CapabilityRegistry } from './capability-registry.js';
 import { WorkflowExecutor } from './executor.js';
+import { MAX_WORKFLOW_STEPS } from './workflow-builder.js';
 import { HistoryStack, type HistoryStackConfig } from './history.js';
+import {
+  createHistoryStore,
+  type HistoryStore,
+} from './history-store.js';
+import { BatchProcessor } from './batch-processor.js';
+import { MemoryGuard, DEFAULT_MEMORY_BUDGET } from './memory-guard.js';
 
 export const RUNTIME_VERSION = '0.1.0';
 
@@ -87,7 +96,18 @@ function estimateSourceSize(source: AssetSource): number {
  * 并发安全:import/create/remove 通过 promise 链串行化,避免 check 与 update
  * 之间的 TOCTOU 窗口导致两个并发操作都基于旧 usage 通过校验或回退。
  */
-function wrapAssetStoreWithQuota(inner: AssetStore, quota: number): AssetStore {
+/**
+ * 配额感知的 AssetStore:在 AssetStore 接口之上扩展 _getQuotaUsage,
+ * 供 runtime.getStorageUsage O(1) 读取内部 usage(下划线表"内部 API")。
+ */
+type QuotaAwareAssetStore = AssetStore & {
+  _getQuotaUsage: () => number;
+};
+
+function wrapAssetStoreWithQuota(
+  inner: AssetStore,
+  quota: number
+): QuotaAwareAssetStore {
   let usage = 0;
   let initialized = false;
   /** 串行化 import/create/remove 的 chain tail,确保 check-update 原子性 */
@@ -148,12 +168,23 @@ function wrapAssetStoreWithQuota(inner: AssetStore, quota: number): AssetStore {
     async create(blob, metadata, type) {
       return runExclusive(async () => {
         await ensureInit();
-        assertQuota(blob.size);
+        // m8 修复:配额预检与累加使用同一口径(metadata.size),
+        // 避免 blob.size 与 metadata.size 漂移导致账面与预检不一致
+        assertQuota(metadata.size);
         const asset = await inner.create(blob, metadata, type);
         usage += asset.metadata.size;
         return asset;
       });
     },
+    /**
+     * m6 优化:暴露配额包装器内部维护的 usage(O(1)),
+     * 供 runtime.getStorageUsage 优先使用,避免每次 O(n) 全量 listAssets。
+     * 下划线前缀表"内部 API",非 AssetStore 接口一部分。
+     * 若 ensureInit 未完成,返回 -1 表示"未就绪",调用方 fallback 到 listAssets。
+     */
+    _getQuotaUsage(): number {
+      return initialized ? usage : -1;
+    },
   };
 }
 
@@ -162,21 +193,73 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
   readonly version = RUNTIME_VERSION;
   readonly eventBus: EventBus;
 
-  private config: Required<Omit<RuntimeConfig, 'assetStore'>>;
+  private config: Required<Omit<RuntimeConfig, 'assetStore' | 'historyStore' | 'historyStoreOptions'>>;
   private _status: RuntimeStatus = 'idle';
-  private assetStore: AssetStore;
+  /**
+   * AssetStore 实例。类型为 QuotaAwareAssetStore —— 由 wrapAssetStoreWithQuota
+   * 返回(在构造函数中无条件包裹,即使是注入的 assetStore 也会被包装以提供配额校验)。
+   * 保留 _getQuotaUsage 内部 API 供 getStorageUsage O(1) 读取 usage。
+   * 注:外部注入的 assetStore 在 wrapAssetStoreWithQuota 中同样被包装,
+   * 因此所有路径下 this.assetStore 都是 QuotaAwareAssetStore。
+   */
+  private assetStore: QuotaAwareAssetStore;
   private capabilityRegistry: CapabilityRegistry;
   private executor: WorkflowExecutor;
+  private memoryGuard: MemoryGuard;
+  private batchProcessor: BatchProcessor;
   /**
    * 每个工作流独立的 HistoryStack。
-   * 注意:历史栈仅在内存中,刷新页面后丢失(资产可能仍存于 OPFS/IDB,
-   * 但因元数据/索引未持久化而无法恢复)—— 跨会话恢复属 W3 范畴。
+   * W7.2 起,栈快照(entries + cursor)连同 initialInputs / currentOutputs
+   * 通过 historyStore 持久化到 IndexedDB,刷新后可恢复。
    */
   private historyStacks = new Map<string, HistoryStack>();
   /** 记录每个工作流的初始输入 AssetId(undo 回到初始时使用) */
   private initialInputsMap = new Map<string, AssetId[]>();
   /** 记录每个工作流当前的输出 AssetId(undo/redo 后切换"当前") */
   private currentOutputsMap = new Map<string, AssetId[]>();
+  /**
+   * 历史持久化存储(W7.2)。undefined 时退化为仅内存历史(刷新后丢失)。
+   * 由 createRuntime 在 enableIndexedDB 时自动创建,或通过 config 注入。
+   */
+  private historyStore: HistoryStore | undefined;
+  /**
+   * 加载持久化历史快照期间的守卫标志。
+   * restore() 会触发 onChanged → persistHistory,此时跳过写回,
+   * 避免把刚读出的数据又重复写入(冗余 IO + 潜在覆盖竞态)。
+   */
+  private isLoadingHistory = false;
+  /**
+   * 加载期间被 onChanged 标记为"dirty"的工作流 ID 集合(W7.2 review 修复)。
+   *
+   * 原实现:isLoadingHistory 期间所有 persistHistory 调用直接 return,
+   * 若加载期间有其他来源(run / undo / 外部事件)触发 onChanged,
+   * 这些变更会被永久丢弃(加载结束后不会重发 persist)。
+   *
+   * 现策略:加载期间被跳过的 persistHistory 把 workflowId 加入此 Set,
+   * loadPersistedHistory 结束后逐个补 persist,确保不丢变更。
+   * (restore() 自身触发的 onChanged 也加入,但其内容与刚读出的相同,
+   *  补 persist 仅多一次等价写回,幂等无害。)
+   */
+  private dirtyDuringLoad = new Set<string>();
+
+  /**
+   * 元数据读取器注册表(W7.3/7.4 长期方案:MetadataReader 依赖反转)。
+   *
+   * Plugin(plugin-image)通过 PluginContext.registerMetadataReader 注册
+   * 查询函数(如 'image.read-exif'),Runtime 持有引用并按名调用。
+   * 解决了 readExif(Blob→ExifData)不符合 Engine 层 Blob↔Blob 纯函数约束、
+   * 也不符合 CapabilityImplementation Asset[]→Asset[] 契约的问题。
+   * UI 经 runtime.readAssetExif 间接调用,不直接依赖 plugin/engine。
+   */
+  private metadataReaders = new Map<string, MetadataReader>();
+
+  /**
+   * 注册元数据读取器(由 PluginContext.registerMetadataReader 转发)。
+   * 下划线前缀表示内部 API,不暴露在 LokvisRuntime 公开接口。
+   */
+  _registerMetadataReader(name: string, reader: MetadataReader): void {
+    this.metadataReaders.set(name, reader);
+  }
 
   constructor(config: RuntimeConfig = {}) {
     this.config = {
@@ -185,14 +268,32 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
       storageQuota: config.storageQuota ?? 1024 * 1024 * 1024, // 1GB
       enableLog: config.enableLog ?? true,
       engineStrategy: config.engineStrategy ?? 'first',
+      isPro: config.isPro ?? false,
+      memoryBudget: config.memoryBudget ?? DEFAULT_MEMORY_BUDGET,
     };
 
     this.eventBus = createEventBus();
 
     // 注入或降级到内存 store;随后用配额校验包裹(W2.9)
+    // M6 修复:enableOpfs/enableIndexedDB 仅在 createLokvis()/createRuntime
+    // 工厂中生效(工厂按 flag 调 createAssetStore 选择 OPFS→IDB→Memory)。
+    // 直接 new LokvisRuntimeImpl 且未传 assetStore 时,无法同步等待 createAssetStore,
+    // 兜底用 Memory store;若用户显式期望持久化,提示其用 createLokvis()。
+    if (!config.assetStore && (this.config.enableOpfs || this.config.enableIndexedDB)) {
+      console.warn(
+        '[lokvis] LokvisRuntimeImpl constructed without assetStore: ' +
+          'enableOpfs/enableIndexedDB flags are ignored. ' +
+          'Use createLokvis() to respect these flags, or pass an assetStore explicitly.'
+      );
+    }
     const rawStore = config.assetStore ?? createMemoryAssetStore();
     this.assetStore = wrapAssetStoreWithQuota(rawStore, this.config.storageQuota);
 
+    // W7.2 历史持久化:优先用注入的 historyStore;否则在 createRuntime 工厂中
+    // 由 createHistoryStore 自动创建并注入。直接 new Impl 时为 undefined,
+    // 历史退化为仅内存模式(与 W2 行为一致)。
+    this.historyStore = config.historyStore;
+
     this.capabilityRegistry = new CapabilityRegistry(this.config.engineStrategy);
 
     this.executor = new WorkflowExecutor({
@@ -202,6 +303,22 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
       enableLog: this.config.enableLog,
     });
 
+    // W3.3 MemoryGuard:追踪中间结果占用,达到 high 阈值时建议 OPFS 溢出。
+    // BatchProcessor 据此动态收缩并发槽位(W6.1)。
+    this.memoryGuard = new MemoryGuard({
+      budget: this.config.memoryBudget,
+      assetStore: this.assetStore,
+    });
+
+    // W6.1 BatchProcessor:把 W5 playground 的并发/进度/重试逻辑下沉到 runtime。
+    // 注入 this(实现 LokvisRuntime 接口),不直接依赖 LokvisRuntimeImpl 避免循环引用。
+    this.batchProcessor = new BatchProcessor({
+      runtime: this,
+      eventBus: this.eventBus,
+      isPro: this.config.isPro,
+      memoryGuard: this.memoryGuard,
+    });
+
     // 监听 node:finished 事件,自动 append 到 HistoryStack
     this.eventBus.on('node:finished', (event) => {
       this.recordHistoryFromNodeEvent(event as Extract<LokvisEvent, { type: 'node:finished' }>);
@@ -212,6 +329,14 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this._status;
   }
 
+  get isPro(): boolean {
+    return this.config.isPro;
+  }
+
+  get batch(): BatchProcessor {
+    return this.batchProcessor;
+  }
+
   // ─── 工作流执行 ──────────────────────────────────────
 
   async run(
@@ -226,7 +351,23 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     // 在入口处暴露，错误信息精准（如 "Edge from __input__ references a
     // reserved sentinel id"），而不是被 executor 拓扑排序误判为含糊的 "cycle"。
     // 三层防御的第 3 层（前两层：executor 防御性校验 + 单元测试覆盖）。
-    const validation = validateWorkflow(workflow);
+    //
+    // W10.2/W10.3 增强:
+    //   - resolveCapability 回调注入 capability 兼容性校验(相邻节点
+    //     outputTypes 与 inputTypes 必须有交集;输入/输出节点类型与
+    //     workflow.inputs/outputs.type 兼容)
+    //   - maxSteps: 5(由 MAX_WORKFLOW_STEPS 常量定义,M1 MVP 约束)
+    const validation = validateWorkflow(workflow, {
+      maxSteps: MAX_WORKFLOW_STEPS,
+      resolveCapability: (name) => {
+        const cap = this.capabilityRegistry.get(name);
+        if (!cap) return undefined;
+        return {
+          inputTypes: cap.inputTypes,
+          outputTypes: cap.outputTypes,
+        };
+      },
+    });
     if (!validation.success) {
       this._status = 'error';
       const error = validation.error.issues
@@ -328,6 +469,15 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this.historyStacks.get(workflowId)?.list() ?? [];
   }
 
+  async getHistoryState(
+    workflowId: string
+  ): Promise<{ entries: HistoryEntry[]; cursor: number }> {
+    const stack = this.historyStacks.get(workflowId);
+    if (!stack) return { entries: [], cursor: -1 };
+    const snap = stack.snapshot();
+    return { entries: snap.entries, cursor: snap.cursor };
+  }
+
   async undo(workflowId: string): Promise<void> {
     const stack = this.getOrCreateHistoryStack(workflowId);
     const result = stack.undo();
@@ -352,6 +502,19 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     // history:changed 事件由 stack 的 onChanged 回调统一发射,避免双发
   }
 
+  async jumpTo(workflowId: string, index: number): Promise<void> {
+    const stack = this.getOrCreateHistoryStack(workflowId);
+    const result = stack.jumpTo(index);
+    if (result === undefined) return; // 越界或游标未变,无操作
+
+    // 同 undo/redo:更新当前输出
+    const newCurrent = result === null
+      ? (this.initialInputsMap.get(workflowId) ?? [])
+      : result.outputs;
+    this.currentOutputsMap.set(workflowId, newCurrent);
+    // history:changed 事件由 stack 的 onChanged 回调统一发射
+  }
+
   // ─── Asset 管理 ──────────────────────────────────────
 
   async importAsset(source: AssetSource): Promise<AssetId> {
@@ -394,13 +557,49 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
   async exportAsset(id: AssetId, format?: string): Promise<Blob> {
     const asset = await this.getAsset(id);
     const blob = await this.assetStore.getBlob(asset.blob);
+    // OPFS 存储后端用 .bin 扩展名存储,读取时 fileHandle.getFile() 返回的
+    // File.type 可能为空字符串或 'application/octet-stream'(浏览器对未知扩展名
+    // 的默认兜底 MIME)。这两种情况都会导致 Object URL 的 Content-Type 退化,
+    // 下载时文件扩展名变成 .octet-stream。
+    // 用 asset metadata 的 mimeType 补全 Blob type(IDB/Memory 后端不受影响)。
+    const OPFS_FALLBACK_MIME = 'application/octet-stream';
+    const mimeType =
+      !blob.type || blob.type === OPFS_FALLBACK_MIME
+        ? asset.metadata.mimeType
+        : blob.type;
+    // 关键:用 arrayBuffer() 显式读取数据到内存,再构造新 Blob。
+    // 不能用 new Blob([blob]) —— 浏览器实现中它可能延迟引用底层 OPFS 文件,
+    // WatermarkBatchTool 在 export 后立即 removeAsset 删除 OPFS 文件,
+    // 导致后续 downloadBlob 读取悬空引用失败("check internet connection")。
+    // arrayBuffer() 立即拉取数据,确保返回的 Blob 完全独立于底层存储。
+    const buffer = await blob.arrayBuffer();
+    const exported = new Blob([buffer], { type: mimeType });
     this.eventBus.emit({
       type: 'export:completed',
       assetId: id,
       format: format ?? asset.metadata.format,
       size: blob.size,
     });
-    return blob;
+    return exported;
+  }
+
+  /**
+   * 读取 image 资产的 EXIF 元数据(W7.3/7.4 长期方案:MetadataReader 依赖反转)。
+   *
+   * Runtime 持有 plugin-image 通过 ctx.registerMetadataReader('image.read-exif', fn)
+   * 注册的 reader 引用,按名调用。reader 内部调 readExifFromBlob(exifr)。
+   * Plugin 未安装时优雅降级返回 null(不抛错)。
+   *
+   * 架构决策:readExif 是 Blob→ExifData 查询,不符合 Engine 层 Blob↔Blob 纯函数
+   * 约束,也不符合 Capability Asset[]→Asset[] 契约,故走 MetadataReader 机制,
+   * 不进 engine-image、不走 Capability execute。
+   */
+  async readAssetExif(id: AssetId): Promise<ExifData | null> {
+    const asset = await this.getAsset(id);
+    if (asset.type !== 'image') return null;
+    const reader = this.metadataReaders.get('image.read-exif');
+    if (!reader) return null; // Plugin 未安装,优雅降级
+    return reader(asset) as Promise<ExifData | null>;
   }
 
   async removeAsset(id: AssetId): Promise<void> {
@@ -412,6 +611,23 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this.assetStore.list();
   }
 
+  async getStorageUsage(): Promise<{ usage: number; quota: number }> {
+    // m6 优化:优先用配额包装器内部维护的 usage(O(1),import/create/remove
+    // 时增量更新),避免每次 O(n) 全量 listAssets 影响 StatusBar 刷新。
+    // 包装器未就绪(ensureInit 未完成)返回 -1 时,fallback 到 listAssets
+    // 实时计算(source of truth,与 W6.4 富元数据一致)。
+    //
+    // 类型说明:assetStore 字段类型为 QuotaAwareAssetStore(含 _getQuotaUsage),
+    // 由 wrapAssetStoreWithQuota 返回。无需重新断言 —— 类型信息未丢失。
+    const cached = this.assetStore._getQuotaUsage();
+    if (cached >= 0) {
+      return { usage: cached, quota: this.config.storageQuota };
+    }
+    const all = await this.assetStore.list();
+    const usage = all.reduce((sum, a) => sum + a.metadata.size, 0);
+    return { usage, quota: this.config.storageQuota };
+  }
+
   // ─── 能力查询 ────────────────────────────────────────
 
   async capabilities(): Promise<Capability[]> {
@@ -486,6 +702,13 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this.capabilityRegistry;
   }
 
+  /**
+   * 获取 MemoryGuard(内部用,供集成测试驱动内存压力验证 BatchProcessor 收缩)。
+   */
+  _getMemoryGuard(): MemoryGuard {
+    return this.memoryGuard;
+  }
+
   /** 获取工作流当前输出 AssetId（undo/redo 后的"当前"状态,内部用） */
   _getCurrentOutputs(workflowId: string): AssetId[] {
     return this.currentOutputsMap.get(workflowId) ?? [];
@@ -543,6 +766,8 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
             entries,
             currentIndex,
           });
+          // W7.2:持久化快照到 IndexedDB(加载期间跳过,避免冗余写回)
+          void this.persistHistory(wfId);
         },
       };
       stack = new HistoryStack(workflowId, stackConfig);
@@ -590,6 +815,107 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     // 更新当前输出为该 node 的 outputs
     this.currentOutputsMap.set(event.workflowId, outputs);
   }
+
+  // ─── 私有:历史持久化(W7.2) ────────────────────────
+
+  /**
+   * 把指定工作流的当前历史状态快照写入 historyStore。
+   *
+   * 时序修复:currentOutputs 从 stack snapshot 派生(cursor === -1 用
+   * initialInputs,否则用 entries[cursor].outputs),而非读 currentOutputsMap。
+   * 原因:onChanged 在 undo/redo/jumpTo/run 内部同步触发时,map 尚未更新,
+   * 会读到旧值(例如 run 后 append 触发 onChanged,但 currentOutputsMap 在
+   * append 返回后才 set)。
+   *
+   * 竞态安全:多个 fire-and-forget save 的 IDB readwrite 事务由 IndexedDB
+   * 引擎按发起顺序串行化(同 object store 不重叠),无需应用层加链。
+   *
+   * - entries 为空时改为 delete,避免残留空记录(reset/clear 后自然清理)
+   * - 加载期间(isLoadingHistory=true)跳过写回,但把 workflowId 加入
+   *   dirtyDuringLoad,loadPersistedHistory 结束后补 persist(避免丢变更)
+   */
+  private async persistHistory(workflowId: string): Promise<void> {
+    if (!this.historyStore) return;
+    if (this.isLoadingHistory) {
+      this.dirtyDuringLoad.add(workflowId);
+      return;
+    }
+    // fire-and-forget 调用方用 `void this.persistHistory(...)`,故内部必须
+    // try/catch,否则 IDB 故障(数据库关闭 / quota exceeded)会变成 unhandled
+    // promise rejection。历史持久化是非关键路径,失败只 warn 不抛。
+    try {
+      const stack = this.historyStacks.get(workflowId);
+      // 栈已从内存移除(disposeWorkflow / enforceHistoryStacksLimit 的 reset+delete
+      // 后异步到达此处)→ 删除持久化记录,避免孤儿数据跨会话残留
+      if (!stack) {
+        await this.historyStore.delete(workflowId);
+        return;
+      }
+      const { entries, cursor } = stack.snapshot();
+      if (entries.length === 0) {
+        await this.historyStore.delete(workflowId);
+        return;
+      }
+      // 从 snapshot 派生 currentOutputs,而非读 currentOutputsMap —— 后者在
+      // onChanged 触发时尚未更新(见方法文档注释)
+      const initialInputs = this.initialInputsMap.get(workflowId) ?? [];
+      const currentOutputs = cursor === -1
+        ? initialInputs
+        : (entries[cursor]?.outputs ?? initialInputs);
+      await this.historyStore.save({
+        workflowId,
+        entries,
+        cursor,
+        initialInputs,
+        currentOutputs,
+        updatedAt: Date.now(),
+      });
+    } catch (err) {
+      console.warn(
+        `[lokvis] persistHistory failed for workflow ${workflowId}:`,
+        err
+      );
+    }
+  }
+
+  /**
+   * 从 historyStore 预加载所有持久化的历史快照,恢复到内存。
+   *
+   * 由 createRuntime 工厂在构造完 impl 后调用一次。加载期间置 isLoadingHistory
+   * 守卫,使 restore() 触发的 onChanged → persistHistory 跳过冗余写回;
+   * 但被跳过的 workflowId 记入 dirtyDuringLoad,加载结束后补 persist,
+   * 避免加载期间其他来源(run / undo / 外部事件)的变更被永久丢弃。
+   *
+   * 注意:restore 会 emit history:changed 事件,但此时 UI 尚未订阅
+   * (runtime-slice.init 在 createRuntime resolve 后才订阅),故无副作用。
+   *
+   * 非 LokvisRuntime 接口的一部分,仅为 impl 的初始化钩子(工厂调用)。
+   */
+  async loadPersistedHistory(): Promise<void> {
+    if (!this.historyStore) return;
+    let records: Awaited<ReturnType<HistoryStore['loadAll']>> = [];
+    this.isLoadingHistory = true;
+    try {
+      records = await this.historyStore.loadAll();
+      for (const record of records) {
+        // 跳过空记录(理论上 save 已删除,双重防御)
+        if (record.entries.length === 0) continue;
+        const stack = this.getOrCreateHistoryStack(record.workflowId);
+        stack.restore({ entries: record.entries, cursor: record.cursor });
+        this.initialInputsMap.set(record.workflowId, record.initialInputs);
+        this.currentOutputsMap.set(record.workflowId, record.currentOutputs);
+      }
+    } finally {
+      this.isLoadingHistory = false;
+      // 加载期间被跳过的 persist 补发:逐个 await 保证顺序
+      // 复制一份避免补 persist 过程中新触发 onChanged → dirtyDuringLoad 死循环
+      const pending = [...this.dirtyDuringLoad];
+      this.dirtyDuringLoad.clear();
+      for (const wfId of pending) {
+        await this.persistHistory(wfId);
+      }
+    }
+  }
 }
 
 /**
@@ -606,7 +932,17 @@ export async function createRuntime(
   const assetStore =
     config?.assetStore ??
     (await createAssetStore({ preferOpfs: config?.enableOpfs ?? true }));
-  return new LokvisRuntimeImpl({ ...config, assetStore });
+  // W7.2:历史持久化 —— 优先用注入的 historyStore;否则在 enableIndexedDB 时
+  // 通过 createHistoryStore 自动创建(IDB 不可用时返回 undefined,退化仅内存)
+  const historyStore =
+    config?.historyStore ??
+    ((config?.enableIndexedDB ?? true)
+      ? createHistoryStore(config?.historyStoreOptions)
+      : undefined);
+  const impl = new LokvisRuntimeImpl({ ...config, assetStore, historyStore });
+  // 预加载持久化的历史快照(跨会话恢复 undo/redo 链)
+  await impl.loadPersistedHistory();
+  return impl;
 }
 
 /**

package/src/types.ts

@@ -11,12 +11,15 @@ import type {
   AssetSource,
   Capability,
   EngineSelectionStrategy,
+  ExifData,
   HistoryEntry,
   McpManifest,
 } from '@lokvis/schema';
 import type { Workflow, WorkflowResult } from '@lokvis/schema';
 import type { EventBus } from '@lokvis/schema';
 import type { AssetStore } from './asset-store.js';
+import type { BatchProcessor } from './batch-processor.js';
+import type { HistoryStore, HistoryStoreOptions } from './history-store.js';
 
 /** Runtime 配置 */
 export interface RuntimeConfig {
@@ -40,6 +43,29 @@ export interface RuntimeConfig {
    * 按 OPFS → IndexedDB → Memory 降级。
    */
   assetStore?: AssetStore;
+  /**
+   * 注入自定义 HistoryStore(W7.2 历史持久化)。
+   * 默认由 createRuntime 在 enableIndexedDB 时通过 createHistoryStore 自动创建;
+   * IndexedDB 不可用时为 undefined,历史退化为仅内存模式。
+   */
+  historyStore?: HistoryStore;
+  /**
+   * HistoryStore 工厂选项(W7.2,仅 historyStore 未注入时生效)。
+   * 测试可注入 dbInstance 或自定义 dbName。
+   */
+  historyStoreOptions?: HistoryStoreOptions;
+  /**
+   * 是否启用 Pro 模式(W6.2 / PROJECT_PLAN 17.4)。
+   * - false(默认):批量上限 10 文件、并发 4、workflow 槽位 5
+   * - true:批量无上限、并发 16、workflow 槽位无限
+   * 由 cloud 侧 createLokvis({ auth }) 注入 session 后置为 true。
+   */
+  isPro?: boolean;
+  /**
+   * 内存预算(字节,W3.3 MemoryGuard)。
+   * 默认 512MB。BatchProcessor 据此在内存压力高时收缩并发槽位。
+   */
+  memoryBudget?: number;
 }
 
 /** Runtime 状态 */
@@ -74,6 +100,10 @@ export interface LokvisRuntime {
   readonly status: RuntimeStatus;
   /** 事件总线 */
   readonly eventBus: EventBus;
+  /** 是否为 Pro 模式(影响批量上限/并发槽位/workflow 数,W6.2) */
+  readonly isPro: boolean;
+  /** 批量处理器(W6.1:并发控制 + 进度 + 失败重试) */
+  readonly batch: BatchProcessor;
 
   // ─── 工作流执行 ──────────────────────────────────────
   /** 运行工作流 */
@@ -104,10 +134,24 @@ export interface LokvisRuntime {
   // ─── 历史与撤销 ──────────────────────────────────────
   /** 获取工作流的执行历史 */
   history(workflowId: string): Promise<HistoryEntry[]>;
+  /**
+   * 获取工作流历史状态(条目 + 当前游标)。
+   * 游标 -1 表示无已应用条目(初始状态);i 表示第 i 条已应用。
+   * 比 history() 多返回 cursor,UI 据此高亮当前步骤。
+   */
+  getHistoryState(
+    workflowId: string
+  ): Promise<{ entries: HistoryEntry[]; cursor: number }>;
   /** 撤销一步 */
   undo(workflowId: string): Promise<void>;
   /** 重做一步 */
   redo(workflowId: string): Promise<void>;
+  /**
+   * 跳转到指定历史条目(按时间顺序的索引,-1 表示回到初始)。
+   * 用于 HistoryPanel 点击条目直接跳转,等价于连续 undo/redo 到目标位置。
+   * 越界或游标未变时为 no-op。
+   */
+  jumpTo(workflowId: string, index: number): Promise<void>;
 
   // ─── Asset 管理 ──────────────────────────────────────
   /** 导入资产 */
@@ -116,10 +160,36 @@ export interface LokvisRuntime {
   getAsset(id: AssetId): Promise<Asset>;
   /** 导出资产为 Blob */
   exportAsset(id: AssetId, format?: string): Promise<Blob>;
+  /**
+   * 读取 image 资产的 EXIF 元数据(W7.3/7.4)。
+   *
+   * 长期方案(MetadataReader 依赖反转):Runtime 持有 plugin-image 通过
+   * `ctx.registerMetadataReader('image.read-exif', fn)` 注册的读取器引用,
+   * 按名调用。Plugin 未安装时优雅降级返回 null。
+   * readExif 实现位于 plugin-image(Capability 层),不进 engine-image
+   * (不符合 Engine 层 Blob↔Blob 纯函数约束)。
+   * UI 通过此方法访问 EXIF,不直接依赖 Engine/Plugin 包(五层架构单向依赖)。
+   *
+   * @param id 资产 ID(须为 image 类型)
+   * @returns ExifData;非 image / 无 EXIF / 解析失败 / reader 未注册返回 null
+   */
+  readAssetExif(id: AssetId): Promise<ExifData | null>;
   /** 删除资产 */
   removeAsset(id: AssetId): Promise<void>;
   /** 列出所有资产 */
   listAssets(): Promise<Asset[]>;
+  /**
+   * 查询存储配额使用情况(W6.7)。
+   *
+   * 返回 `{ usage, quota }`:
+   * - `usage`:当前已用字节数(所有资产 metadata.size 之和)
+   * - `quota`:配置的存储配额上限(RuntimeConfig.storageQuota,默认 1GB)
+   *
+   * UI 据此展示"已用/总额"进度条,接近上限(>=80%)时警告。
+   * 注意:usage 基于 listAssets 实时计算,反映 runtime 实际占用,
+   * 与浏览器 `navigator.storage.estimate()`(origin 整体 OPFS)不同。
+   */
+  getStorageUsage(): Promise<{ usage: number; quota: number }>;
 
   // ─── 能力查询 ────────────────────────────────────────
   /** 列出所有已注册能力 */