@lokvis/runtime 0.2.2 → 0.4.1

package/dist/runtime.d.ts

@@ -1,238 +1,15 @@
 /**
- * Lokvis Runtime Implementation
+ * Lokvis Runtime 入口(Facade,W1.7)
  *
- * Runtime 是整个系统的"浏览器操作系统"，唯一职责：Input → Run → Output。
- */
-import type { Asset, AssetId, AssetSource, Capability, ExifData, HistoryEntry, McpManifest, MetadataReader } from '@lokvis/schema';
-import type { Workflow, WorkflowResult } from '@lokvis/schema';
-import type { LokvisRuntime, PluginInstallEntry, RuntimeConfig, RuntimeStatus, ToMcpManifestOptions } from './types.js';
-import type { EventBus } from '@lokvis/schema';
-import { type AssetStore } from './asset-store.js';
-import { CapabilityRegistry } from './capability-registry.js';
-import { BatchProcessor } from './batch-processor.js';
-import { MemoryGuard } from './memory-guard.js';
-export declare const RUNTIME_VERSION = "0.1.0";
-/** 存储配额超限时抛出(W2.9) */
-export declare class QuotaExceededError extends Error {
-    readonly usage: number;
-    readonly delta: number;
-    readonly quota: number;
-    constructor(usage: number, delta: number, quota: number);
-}
-/** Runtime 实现类 */
-export declare class LokvisRuntimeImpl implements LokvisRuntime {
-    readonly version = "0.1.0";
-    readonly eventBus: EventBus;
-    private config;
-    private _status;
-    /**
-     * AssetStore 实例。类型为 QuotaAwareAssetStore —— 由 wrapAssetStoreWithQuota
-     * 返回(在构造函数中无条件包裹,即使是注入的 assetStore 也会被包装以提供配额校验)。
-     * 保留 _getQuotaUsage 内部 API 供 getStorageUsage O(1) 读取 usage。
-     * 注:外部注入的 assetStore 在 wrapAssetStoreWithQuota 中同样被包装,
-     * 因此所有路径下 this.assetStore 都是 QuotaAwareAssetStore。
-     */
-    private assetStore;
-    private capabilityRegistry;
-    private executor;
-    private memoryGuard;
-    private batchProcessor;
-    /**
-     * 每个工作流独立的 HistoryStack。
-     * W7.2 起,栈快照(entries + cursor)连同 initialInputs / currentOutputs
-     * 通过 historyStore 持久化到 IndexedDB,刷新后可恢复。
-     */
-    private historyStacks;
-    /** 记录每个工作流的初始输入 AssetId(undo 回到初始时使用) */
-    private initialInputsMap;
-    /** 记录每个工作流当前的输出 AssetId(undo/redo 后切换"当前") */
-    private currentOutputsMap;
-    /**
-     * 历史持久化存储(W7.2)。undefined 时退化为仅内存历史(刷新后丢失)。
-     * 由 createRuntime 在 enableIndexedDB 时自动创建,或通过 config 注入。
-     */
-    private historyStore;
-    /**
-     * 加载持久化历史快照期间的守卫标志。
-     * restore() 会触发 onChanged → persistHistory,此时跳过写回,
-     * 避免把刚读出的数据又重复写入(冗余 IO + 潜在覆盖竞态)。
-     */
-    private isLoadingHistory;
-    /**
-     * 加载期间被 onChanged 标记为"dirty"的工作流 ID 集合(W7.2 review 修复)。
-     *
-     * 原实现:isLoadingHistory 期间所有 persistHistory 调用直接 return,
-     * 若加载期间有其他来源(run / undo / 外部事件)触发 onChanged,
-     * 这些变更会被永久丢弃(加载结束后不会重发 persist)。
-     *
-     * 现策略:加载期间被跳过的 persistHistory 把 workflowId 加入此 Set,
-     * loadPersistedHistory 结束后逐个补 persist,确保不丢变更。
-     * (restore() 自身触发的 onChanged 也加入,但其内容与刚读出的相同,
-     *  补 persist 仅多一次等价写回,幂等无害。)
-     */
-    private dirtyDuringLoad;
-    /**
-     * 元数据读取器注册表(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;
-    /**
-     * 注册元数据读取器(由 PluginContext.registerMetadataReader 转发)。
-     * 下划线前缀表示内部 API,不暴露在 LokvisRuntime 公开接口。
-     */
-    _registerMetadataReader(name: string, reader: MetadataReader): void;
-    constructor(config?: RuntimeConfig);
-    get status(): RuntimeStatus;
-    get isPro(): boolean;
-    get batch(): BatchProcessor;
-    run(workflow: Workflow, inputs: AssetId[] | Asset[], options?: import('./types.js').RunOptions): Promise<WorkflowResult>;
-    cancel(workflowId: string): Promise<void>;
-    pause(workflowId: string): Promise<void>;
-    resume(workflowId: string): Promise<void>;
-    /**
-     * 销毁指定工作流的运行时状态（W2.8 内存治理）。
-     *
-     * 调用时机：
-     *   - ui-react 卸载 Workspace 组件时
-     *   - 用户主动关闭工作流标签页时
-     *
-     * 行为：
-     *   - 调用 stack.reset() 触发 onEvict → assetStore.remove 回收历史 outputs 资产
-     *   - 从 historyStacks / initialInputsMap / currentOutputsMap 三 Map 中删除 entry
-     *   - 调用 executor.cancel 取消运行中的执行（若有）
-     *
-     * 修复 review 报告：原实现无清理入口,Workflow 组件卸载后 Map 中残留 entry,
-     * 长会话累积导致内存与 OPFS 空间双泄漏。
-     */
-    disposeWorkflow(workflowId: string): Promise<void>;
-    history(workflowId: string): Promise<HistoryEntry[]>;
-    getHistoryState(workflowId: string): Promise<{
-        entries: HistoryEntry[];
-        cursor: number;
-    }>;
-    undo(workflowId: string): Promise<void>;
-    redo(workflowId: string): Promise<void>;
-    jumpTo(workflowId: string, index: number): Promise<void>;
-    importAsset(source: AssetSource): Promise<AssetId>;
-    getAsset(id: AssetId): Promise<Asset>;
-    exportAsset(id: AssetId, format?: string): Promise<Blob>;
-    /**
-     * 读取 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。
-     */
-    readAssetExif(id: AssetId): Promise<ExifData | null>;
-    removeAsset(id: AssetId): Promise<void>;
-    listAssets(): Promise<Asset[]>;
-    getStorageUsage(): Promise<{
-        usage: number;
-        quota: number;
-    }>;
-    capabilities(): Promise<Capability[]>;
-    hasCapability(name: string): Promise<boolean>;
-    /**
-     * 生成 MCP server manifest(不启动 server,仅描述当前可被 MCP 暴露的能力)。
-     * - `mcpExposure='private'`:任何模式都不暴露
-     * - `mcpExposure='batch-only'`:仅在 `options.batchMode=true` 时暴露
-     *   (避免单文件误用)
-     * - 其余(默认 'public'):总是暴露
-     * - tool 名取 capability.mcpToolName 或 `lokvis_${name.replace(/\./g, '_')}`
-     * - resource 固定为 capabilities 与 workflows 两个清单
-     */
-    toMcpManifest(options?: ToMcpManifestOptions): McpManifest;
-    /**
-     * 在本 Runtime 上安装一个插件(实现 LokvisRuntime.installPlugin 接口)。
-     *
-     * 步骤:
-     * 1. 注册能力声明(plugin.config.capabilities → CapabilityRegistry)
-     * 2. 构造受限 PluginContext(只暴露受限 Runtime API + 注册器 + 日志)
-     * 3. 调用 plugin.install(ctx),让插件注册 CapabilityImplementation
-     * 4. 发射 `plugin:loaded` 事件
-     *
-     * 不吞错:plugin.install 抛出的错误原样上抛,由 SDK 包成 PluginLoadError。
-     *
-     * 此前 SDK 通过 `instanceof LokvisRuntimeImpl` + `_getAssetStore()` /
-     * `_getCapabilityRegistry()` 反向访问内部依赖,现改为公共接口调用,
-     * SDK 不再依赖具体实现类。
-     */
-    installPlugin(plugin: PluginInstallEntry): Promise<void>;
-    /** 获取 AssetStore(仅测试用,SDK 通过 installPlugin 间接访问) */
-    _getAssetStore(): AssetStore;
-    /** 获取 CapabilityRegistry(仅测试用,SDK 通过 installPlugin 间接访问) */
-    _getCapabilityRegistry(): CapabilityRegistry;
-    /**
-     * 获取 MemoryGuard(内部用,供集成测试驱动内存压力验证 BatchProcessor 收缩)。
-     */
-    _getMemoryGuard(): MemoryGuard;
-    /** 获取工作流当前输出 AssetId（undo/redo 后的"当前"状态,内部用） */
-    _getCurrentOutputs(workflowId: string): AssetId[];
-    /** 获取工作流当前输出 AssetId（公开 API，供 UI / MCP 查询） */
-    getCurrentOutputs(workflowId: string): Promise<AssetId[]>;
-    /**
-     * LRU 上限清理：historyStacks 超过 MAX_CONCURRENT_WORKFLOW_STACKS 时
-     * 按 FIFO 删除最旧 stack（reset 触发 onEvict → assetStore.remove 回收资产）。
-     *
-     * Map 的迭代顺序是插入顺序（ES2015+ 规范），所以第一个 entry 即最旧。
-     * 注意：当前 run() 的工作流尚未插入 Map（getOrCreateHistoryStack 才会插入），
-     * 所以这里清理不会误删当前工作流。
-     */
-    private enforceHistoryStacksLimit;
-    /** 获取或创建工作流对应的 HistoryStack */
-    private getOrCreateHistoryStack;
-    /** 将输入归一化为 AssetId[]（run() 入参可为 AssetId[] 或 Asset[]） */
-    private collectInputAssetIds;
-    /** 监听 node:finished 事件,自动 append 到对应工作流的 HistoryStack */
-    private recordHistoryFromNodeEvent;
-    /**
-     * 把指定工作流的当前历史状态快照写入 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 persistHistory;
-    /**
-     * 从 historyStore 预加载所有持久化的历史快照,恢复到内存。
-     *
-     * 由 createRuntime 工厂在构造完 impl 后调用一次。加载期间置 isLoadingHistory
-     * 守卫,使 restore() 触发的 onChanged → persistHistory 跳过冗余写回;
-     * 但被跳过的 workflowId 记入 dirtyDuringLoad,加载结束后补 persist,
-     * 避免加载期间其他来源(run / undo / 外部事件)的变更被永久丢弃。
-     *
-     * 注意:restore 会 emit history:changed 事件,但此时 UI 尚未订阅
-     * (runtime-slice.init 在 createRuntime resolve 后才订阅),故无副作用。
-     *
-     * 非 LokvisRuntime 接口的一部分,仅为 impl 的初始化钩子(工厂调用)。
-     */
-    loadPersistedHistory(): Promise<void>;
-}
-/**
- * 创建 Runtime 实例(W2.8 + W2.9)。
- *
- * 默认通过 createAssetStore 工厂按 OPFS → IndexedDB → Memory 降级创建 AssetStore,
- * 并用配额校验包裹。也可通过 config.assetStore 注入自定义 store。
+ * 本文件仅 re-export runtime-impl.ts 的实现类与工厂,保持外部导入路径
+ * (`@lokvis/runtime` / `'../runtime.js'`)不变。实现细节见 runtime-impl.ts。
  *
- * 注:此函数为 async(工厂需异步探测环境)。SDK 的 createLokvis 已是 async。
+ * Re-export 列表:
+ * - `LokvisRuntimeImpl` — Runtime 实现类(测试 / SDK 通过此名构造)
+ * - `createRuntime`     — 异步工厂(按 OPFS → IDB → Memory 降级创建 store)
+ * - `RUNTIME_VERSION`   — 版本常量(写入 manifest.version)
+ * - `QuotaExceededError` — 配额超限错误类型(SDK / 集成代码从此入口导入)
  */
-export declare function createRuntime(config?: RuntimeConfig): Promise<LokvisRuntime>;
+export { LokvisRuntimeImpl, createRuntime, RUNTIME_VERSION, } from './runtime-impl.js';
+export { QuotaExceededError } from './managers/quota-manager.js';
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC"}