@lokvis/runtime 0.1.0 → 0.2.0

package/src/runtime.ts

@@ -11,12 +11,15 @@ 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';
 import type {
   LokvisRuntime,
   RuntimeConfig,
@@ -33,13 +36,32 @@ 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';
 
 /** 默认历史记录上限 */
 const DEFAULT_MAX_HISTORY = 10;
 
+/**
+ * 同时持有的工作流历史栈上限（W2.8 内存治理）。
+ *
+ * 修复 review 报告：原实现 historyStacks 是无限增长 Map，每次 run() 都加入新
+ * workflow.id（ui-react buildLinearWorkflow 用 `wf_${Date.now()}` 每次唯一），
+ * 长会话累积导致 Map 引用的 AssetId 无法回收 → 内存泄漏。
+ *
+ * 32 是经验值：覆盖用户常见使用（多 tab 切换 + undo 范围），超限按 FIFO
+ * 清理最旧 stack（reset 触发 onEvict → assetStore.remove 回收资产）。
+ */
+const MAX_CONCURRENT_WORKFLOW_STACKS = 32;
+
 /** 存储配额超限时抛出(W2.9) */
 export class QuotaExceededError extends Error {
   readonly usage: number;
@@ -74,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 原子性 */
@@ -135,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;
+    },
   };
 }
 
@@ -149,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 = {
@@ -172,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({
@@ -189,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' }>);
@@ -199,27 +329,84 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this._status;
   }
 
+  get isPro(): boolean {
+    return this.config.isPro;
+  }
+
+  get batch(): BatchProcessor {
+    return this.batchProcessor;
+  }
+
   // ─── 工作流执行 ──────────────────────────────────────
 
   async run(
     workflow: Workflow,
-    inputs: AssetId[] | Asset[]
+    inputs: AssetId[] | Asset[],
+    options?: import('./types.js').RunOptions
   ): Promise<WorkflowResult> {
     this._status = 'running';
 
-    // 重新执行同一工作流时,丢弃上一次的历史(含失败后重跑的残留条目),
-    // 并通过 onEvict 回收其 outputs 资产,避免 OPFS/IDB 泄漏。
-    // 初始输入 Asset 不在历史栈中,不受影响。
-    const existingStack = this.historyStacks.get(workflow.id);
-    if (existingStack) {
-      existingStack.reset();
+    // Schema 层校验：在 executor.execute 之前调用 validateWorkflow，
+    // 让结构问题（保留字哨兵 __input__、悬挂 edge、自环、重复 id、真环）
+    // 在入口处暴露，错误信息精准（如 "Edge from __input__ references a
+    // reserved sentinel id"），而不是被 executor 拓扑排序误判为含糊的 "cycle"。
+    // 三层防御的第 3 层（前两层：executor 防御性校验 + 单元测试覆盖）。
+    //
+    // 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
+        .map((i) => i.message)
+        .join('; ');
+      const result: WorkflowResult = {
+        workflowId: workflow.id,
+        outputs: [],
+        duration: 0,
+        status: 'failed',
+        error,
+      };
+      this.eventBus.emit({
+        type: 'workflow:completed',
+        workflowId: workflow.id,
+        result,
+      });
+      return result;
     }
 
-    // 记录初始输入 AssetId(用于 undo 回到初始状态)
+    // 历史栈管理：
+    // - 默认:每次 run() 重置历史(重跑语义),并通过 onEvict 回收旧 outputs 资产
+    // - appendHistory:true:保留已有历史栈,支持跨次 undo/redo 链(如连续滤镜)
     const inputIds = await this.collectInputAssetIds(inputs);
-    this.initialInputsMap.set(workflow.id, inputIds);
-    // 初始当前输出 = 初始输入
-    this.currentOutputsMap.set(workflow.id, inputIds);
+    if (options?.appendHistory && this.historyStacks.has(workflow.id)) {
+      // 追加模式:保留历史栈与 currentOutputs,仅确保初始输入已记录
+      if (!this.initialInputsMap.has(workflow.id)) {
+        this.initialInputsMap.set(workflow.id, inputIds);
+      }
+    } else {
+      // 重置模式(默认):丢弃旧历史,重新初始化
+      const existingStack = this.historyStacks.get(workflow.id);
+      if (existingStack) {
+        existingStack.reset();
+      }
+      this.initialInputsMap.set(workflow.id, inputIds);
+      this.currentOutputsMap.set(workflow.id, inputIds);
+    }
+    this.enforceHistoryStacksLimit();
 
     try {
       const result = await this.executor.execute(workflow, inputs);
@@ -247,6 +434,34 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
     return this.executor.resume(workflowId);
   }
 
+  /**
+   * 销毁指定工作流的运行时状态（W2.8 内存治理）。
+   *
+   * 调用时机：
+   *   - ui-react 卸载 Workspace 组件时
+   *   - 用户主动关闭工作流标签页时
+   *
+   * 行为：
+   *   - 调用 stack.reset() 触发 onEvict → assetStore.remove 回收历史 outputs 资产
+   *   - 从 historyStacks / initialInputsMap / currentOutputsMap 三 Map 中删除 entry
+   *   - 调用 executor.cancel 取消运行中的执行（若有）
+   *
+   * 修复 review 报告：原实现无清理入口,Workflow 组件卸载后 Map 中残留 entry,
+   * 长会话累积导致内存与 OPFS 空间双泄漏。
+   */
+  async disposeWorkflow(workflowId: string): Promise<void> {
+    await this.cancel(workflowId).catch(() => {
+      /* 工作流可能未在运行 */
+    });
+    const stack = this.historyStacks.get(workflowId);
+    if (stack) {
+      stack.reset();
+      this.historyStacks.delete(workflowId);
+    }
+    this.initialInputsMap.delete(workflowId);
+    this.currentOutputsMap.delete(workflowId);
+  }
+
   // ─── 历史与撤销 ──────────────────────────────────────
 
   async history(workflowId: string): Promise<HistoryEntry[]> {
@@ -254,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();
@@ -278,10 +502,44 @@ 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> {
-    const asset = await this.assetStore.import(source);
+    // 修复 review 报告：原实现直接透传 source 给 assetStore.import，
+    // 但 MemoryAssetStore/OpfsAssetStore/IdbAssetStore 的 extractBlobFromSource
+    // 仅支持 file/blob 两种 kind，url/opfs 会抛 "not supported"。
+    // 这里在 runtime 层兜底处理 url（fetch → blob），opfs 暂不支持（OPFS
+    // 路径访问需要 filesystem access permission，未来单独实现）
+    let effectiveSource = source;
+    if (source.kind === 'url') {
+      const resp = await fetch(source.url);
+      if (!resp.ok) {
+        throw new Error(`Failed to fetch asset from ${source.url}: ${resp.status}`);
+      }
+      const blob = await resp.blob();
+      const name = source.url.split('/').pop()?.split('?')[0] ?? 'asset';
+      effectiveSource = { kind: 'blob', blob, name };
+    } else if (source.kind === 'opfs') {
+      throw new Error(
+        "AssetSource kind 'opfs' is not yet supported by importAsset; " +
+          'use the OPFS-aware AssetStore directly or convert to blob first'
+      );
+    }
+
+    const asset = await this.assetStore.import(effectiveSource);
     this.eventBus.emit({
       type: 'asset:imported',
       assetId: asset.id,
@@ -299,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> {
@@ -317,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[]> {
@@ -391,13 +702,49 @@ 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) ?? [];
   }
 
+  /** 获取工作流当前输出 AssetId（公开 API，供 UI / MCP 查询） */
+  async getCurrentOutputs(workflowId: string): Promise<AssetId[]> {
+    return this._getCurrentOutputs(workflowId);
+  }
+
   // ─── 私有：历史栈管理 ──────────────────────────────
 
+  /**
+   * LRU 上限清理：historyStacks 超过 MAX_CONCURRENT_WORKFLOW_STACKS 时
+   * 按 FIFO 删除最旧 stack（reset 触发 onEvict → assetStore.remove 回收资产）。
+   *
+   * Map 的迭代顺序是插入顺序（ES2015+ 规范），所以第一个 entry 即最旧。
+   * 注意：当前 run() 的工作流尚未插入 Map（getOrCreateHistoryStack 才会插入），
+   * 所以这里清理不会误删当前工作流。
+   */
+  private enforceHistoryStacksLimit(): void {
+    while (this.historyStacks.size >= MAX_CONCURRENT_WORKFLOW_STACKS) {
+      // 取最旧 workflowId（Map 第一个 key）
+      const oldestId = this.historyStacks.keys().next().value;
+      if (oldestId === undefined) break;
+      const stack = this.historyStacks.get(oldestId);
+      if (stack) {
+        // reset 触发 onEvict，回收历史 outputs 资产
+        stack.reset();
+      }
+      this.historyStacks.delete(oldestId);
+      this.initialInputsMap.delete(oldestId);
+      this.currentOutputsMap.delete(oldestId);
+    }
+  }
+
   /** 获取或创建工作流对应的 HistoryStack */
   private getOrCreateHistoryStack(workflowId: string): HistoryStack {
     let stack = this.historyStacks.get(workflowId);
@@ -412,12 +759,15 @@ export class LokvisRuntimeImpl implements LokvisRuntime {
             this.assetStore.remove(assetId).catch(() => {});
           }
         },
-        onChanged: (wfId, entries) => {
+        onChanged: (wfId, entries, currentIndex) => {
           this.eventBus.emit({
             type: 'history:changed',
             workflowId: wfId,
             entries,
+            currentIndex,
           });
+          // W7.2:持久化快照到 IndexedDB(加载期间跳过,避免冗余写回)
+          void this.persistHistory(wfId);
         },
       };
       stack = new HistoryStack(workflowId, stackConfig);
@@ -465,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);
+      }
+    }
+  }
 }
 
 /**
@@ -481,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;
 }
 
 /**