@lokvis/runtime 0.1.0

package/src/executor.ts

@@ -0,0 +1,303 @@
+/**
+ * Lokvis Workflow Executor
+ *
+ * 第一年只支持 Linear Workflow（线性链）。
+ * 不支持：Branch / Loop / Condition / Parallel。
+ */
+
+import type {
+  Asset,
+  AssetId,
+  ExecutionContext,
+  Workflow,
+  WorkflowEdge,
+  WorkflowNode,
+  WorkflowResult,
+} from '@lokvis/schema';
+import type { EventBus } from '@lokvis/schema';
+import type { AssetStore } from './asset-store.js';
+import type { CapabilityRegistry } from './capability-registry.js';
+
+/** 执行中的工作流状态 */
+interface RunningWorkflow {
+  id: string;
+  workflow: Workflow;
+  status: 'running' | 'paused' | 'cancelled';
+  abortController: AbortController;
+  currentNodeId?: string;
+}
+
+/** Workflow 执行器配置 */
+export interface ExecutorConfig {
+  assetStore: AssetStore;
+  capabilityRegistry: CapabilityRegistry;
+  eventBus: EventBus;
+  enableLog: boolean;
+}
+
+/** 创建执行上下文 */
+function createExecutionContext(
+  workflowId: string,
+  nodeId: string,
+  signal: AbortSignal,
+  onProgress?: (progress: number, message?: string) => void
+): ExecutionContext {
+  return {
+    workflowId,
+    nodeId,
+    signal,
+    onProgress,
+    log: (level, message) => {
+      // 日志输出，可被 Analytics 监听
+      if (level === 'error') {
+        console.error(`[lokvis:${workflowId}:${nodeId}] ${message}`);
+      } else if (level === 'warn') {
+        console.warn(`[lokvis:${workflowId}:${nodeId}] ${message}`);
+      }
+    },
+  };
+}
+
+/** 拓扑排序：将 edges 转换为线性节点序列 */
+function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): WorkflowNode[] {
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+
+  for (const node of nodes) {
+    inDegree.set(node.id, 0);
+    adjacency.set(node.id, []);
+  }
+
+  for (const edge of edges) {
+    inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    adjacency.get(edge.from)?.push(edge.to);
+  }
+
+  const queue: string[] = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+
+  const sorted: WorkflowNode[] = [];
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    const node = nodeMap.get(id);
+    if (node) sorted.push(node);
+
+    for (const next of adjacency.get(id) ?? []) {
+      const newDeg = (inDegree.get(next) ?? 0) - 1;
+      inDegree.set(next, newDeg);
+      if (newDeg === 0) queue.push(next);
+    }
+  }
+
+  if (sorted.length !== nodes.length) {
+    throw new Error('Workflow contains a cycle, cannot execute');
+  }
+
+  return sorted;
+}
+
+/** Workflow 执行器 */
+export class WorkflowExecutor {
+  private config: ExecutorConfig;
+  private running = new Map<string, RunningWorkflow>();
+  /** 暂停时挂起的 resolve:resume/cancel 唤醒之,避免轮询 */
+  private resumeResolvers = new Map<string, () => void>();
+
+  constructor(config: ExecutorConfig) {
+    this.config = config;
+  }
+
+  /** 执行工作流 */
+  async execute(
+    workflow: Workflow,
+    inputs: AssetId[] | Asset[]
+  ): Promise<WorkflowResult> {
+    const workflowId = workflow.id;
+    const abortController = new AbortController();
+    const startTime = Date.now();
+
+    // 解析输入 Asset
+    let currentAssets: Asset[];
+    if (inputs.length === 0 || typeof inputs[0] === 'string') {
+      // AssetId[] - 从 store 加载
+      const ids = inputs as AssetId[];
+      currentAssets = await Promise.all(
+        ids.map(async (id) => {
+          const asset = await this.config.assetStore.get(id);
+          if (!asset) throw new Error(`Asset not found: ${id}`);
+          return asset;
+        })
+      );
+    } else {
+      // Asset[]
+      currentAssets = inputs as Asset[];
+    }
+
+    // 注册运行状态
+    const state: RunningWorkflow = {
+      id: workflowId,
+      workflow,
+      status: 'running',
+      abortController,
+    };
+    this.running.set(workflowId, state);
+
+    this.config.eventBus.emit({
+      type: 'workflow:started',
+      workflowId,
+      workflow,
+    });
+
+    try {
+      // 拓扑排序节点
+      const sortedNodes = topologicalSort(workflow.nodes, workflow.edges);
+
+      // 过滤掉 load 和 export 节点（load 由输入处理，export 由结果处理）
+      const transformNodes = sortedNodes.filter((n) => n.type === 'transform');
+
+      // 依次执行每个 transform 节点
+      for (const node of transformNodes) {
+        // 暂停则挂起,等待 resume/cancel 唤醒(Promise resolver,无轮询)
+        if (state.status === 'paused') {
+          await this.waitForResume(workflowId);
+        }
+        // 唤醒后或每轮起始,若已被取消立即跳出(避免执行多余节点)
+        if (state.status === 'cancelled') {
+          break;
+        }
+
+        state.currentNodeId = node.id;
+        const nodeStart = Date.now();
+
+        this.config.eventBus.emit({
+          type: 'node:started',
+          workflowId,
+          nodeId: node.id,
+          inputs: currentAssets,
+        });
+
+        // 解析能力实现(transform 节点必须有 capability)
+        const capability = node.capability;
+        if (!capability) {
+          throw new Error(`Transform node "${node.id}" has no capability`);
+        }
+        const impl = this.config.capabilityRegistry.resolve(capability);
+        if (!impl) {
+          throw new Error(`No implementation registered for capability "${capability}"`);
+        }
+
+        // 执行能力
+        const ctx = createExecutionContext(
+          workflowId,
+          node.id,
+          abortController.signal
+        );
+        const outputs = await impl.execute(currentAssets, node.params ?? {}, ctx);
+        currentAssets = outputs;
+
+        this.config.eventBus.emit({
+          type: 'node:finished',
+          workflowId,
+          nodeId: node.id,
+          capability,
+          params: node.params ?? {},
+          outputs: currentAssets,
+          duration: Date.now() - nodeStart,
+        });
+      }
+
+      const result: WorkflowResult = {
+        workflowId,
+        outputs: currentAssets.map((a) => a.id),
+        duration: Date.now() - startTime,
+        status: state.status === 'cancelled' ? 'cancelled' : 'completed',
+      };
+
+      this.config.eventBus.emit({
+        type: 'workflow:completed',
+        workflowId,
+        result,
+      });
+
+      return result;
+    } catch (error) {
+      const result: WorkflowResult = {
+        workflowId,
+        outputs: [],
+        duration: Date.now() - startTime,
+        status: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+      };
+
+      this.config.eventBus.emit({
+        type: 'node:failed',
+        workflowId,
+        nodeId: state.currentNodeId ?? 'unknown',
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+
+      this.config.eventBus.emit({
+        type: 'workflow:completed',
+        workflowId,
+        result,
+      });
+
+      return result;
+    } finally {
+      this.running.delete(workflowId);
+      this.resumeResolvers.delete(workflowId);
+    }
+  }
+
+  /** 取消执行 */
+  async cancel(workflowId: string): Promise<void> {
+    const state = this.running.get(workflowId);
+    if (!state) return;
+    state.status = 'cancelled';
+    state.abortController.abort();
+    // 唤醒可能暂停中的执行循环,使其跳出
+    this.resolveResume(workflowId);
+    this.config.eventBus.emit({ type: 'workflow:cancelled', workflowId });
+  }
+
+  /** 暂停执行 */
+  async pause(workflowId: string): Promise<void> {
+    const state = this.running.get(workflowId);
+    if (!state || state.status !== 'running') return;
+    state.status = 'paused';
+    this.config.eventBus.emit({ type: 'workflow:paused', workflowId });
+  }
+
+  /** 恢复执行 */
+  async resume(workflowId: string): Promise<void> {
+    const state = this.running.get(workflowId);
+    if (!state || state.status !== 'paused') return;
+    state.status = 'running';
+    // 唤醒挂起的 waitForResume,无需轮询
+    this.resolveResume(workflowId);
+    this.config.eventBus.emit({ type: 'workflow:resumed', workflowId });
+  }
+
+  /**
+   * 挂起当前执行直到 resume/cancel 唤醒(Promise resolver 模式)。
+   * 相比轮询(setTimeout)无延迟、无 CPU 占用;resume/cancel 通过
+   * resolveResume 触发 resolver。
+   */
+  private waitForResume(workflowId: string): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.resumeResolvers.set(workflowId, resolve);
+    });
+  }
+
+  /** 唤醒挂起的 waitForResume(若存在) */
+  private resolveResume(workflowId: string): void {
+    const resolve = this.resumeResolvers.get(workflowId);
+    if (resolve) {
+      this.resumeResolvers.delete(workflowId);
+      resolve();
+    }
+  }
+}

package/src/history.ts

@@ -0,0 +1,229 @@
+/**
+ * Lokvis History Stack
+ *
+ * 每个工作流拥有独立的 HistoryStack,记录每一步 transform 的 HistoryEntry。
+ * undo/redo 通过 cursor(游标)实现:
+ *   - cursor 指向最后一条已应用的 entry
+ *   - append 新操作时截断 cursor 之后的 redo 分支
+ *   - 超出上限(默认 10 步)时 LRU 淘汰最旧条目并回调 onEvict 通知清理
+ *
+ * 每次变更通过回调通知调用方(由 Runtime 转发为 eventBus 的 history:changed)。
+ *
+ * 对应 PROJECT_PLAN W2 任务 2.1 / 2.2 / 2.4。
+ */
+import type { HistoryEntry } from '@lokvis/schema';
+
+/** HistoryStack 配置 */
+export interface HistoryStackConfig {
+  /** 历史记录上限(默认 10 步) */
+  maxEntries: number;
+  /** 淘汰条目时的回调,用于清理 OPFS 资产 */
+  onEvict?: (entry: HistoryEntry) => void;
+  /** 历史变更时的回调,用于转发为 eventBus 事件 */
+  onChanged?: (workflowId: string, entries: HistoryEntry[]) => void;
+}
+
+/** HistoryStack 状态(供序列化/恢复使用) */
+export interface HistoryStackSnapshot {
+  entries: HistoryEntry[];
+  cursor: number;
+}
+
+export class HistoryStack {
+  private entries: HistoryEntry[] = [];
+  /** 游标:指向最后一条已应用的 entry;-1 表示尚未应用任何条目 */
+  private cursor = -1;
+  private readonly config: Required<Omit<HistoryStackConfig, 'onEvict' | 'onChanged'>> &
+    Pick<HistoryStackConfig, 'onEvict' | 'onChanged'>;
+
+  constructor(
+    private readonly workflowId: string,
+    config: Partial<HistoryStackConfig> = {}
+  ) {
+    this.config = {
+      maxEntries: config.maxEntries ?? 10,
+      onEvict: config.onEvict,
+      onChanged: config.onChanged,
+    };
+  }
+
+  /** 当前可应用的条目数(cursor 之后已截断) */
+  get length(): number {
+    return this.entries.length;
+  }
+
+  /** cursor 位置(指向最后已应用条目,-1 表示空) */
+  get currentIndex(): number {
+    return this.cursor;
+  }
+
+  /** 是否可以 undo */
+  get canUndo(): boolean {
+    return this.cursor >= 0;
+  }
+
+  /** 是否可以 redo */
+  get canRedo(): boolean {
+    return this.cursor < this.entries.length - 1;
+  }
+
+  /** 所有历史条目(只读视图) */
+  list(): HistoryEntry[] {
+    return [...this.entries];
+  }
+
+  /** 仅返回已应用的条目(cursor 及之前) */
+  applied(): HistoryEntry[] {
+    return this.entries.slice(0, this.cursor + 1);
+  }
+
+  /** 仅返回 redo 分支中尚未应用的条目 */
+  redoBranch(): HistoryEntry[] {
+    return this.entries.slice(this.cursor + 1);
+  }
+
+  /**
+   * 追加一条历史记录。
+   * 若当前存在 redo 分支(cursor 之后的条目),则截断之,
+   *   并对被丢弃的条目触发 onEvict(清理其 outputs 资产,避免 OPFS/IDB 泄漏)。
+   * 若超过上限,从最旧端 LRU 淘汰,并触发 onEvict 回调。
+   */
+  append(entry: HistoryEntry): void {
+    if (entry.workflowId !== this.workflowId) {
+      throw new Error(
+        `HistoryEntry.workflowId mismatch: expected "${this.workflowId}", got "${entry.workflowId}"`
+      );
+    }
+
+    // 截断 redo 分支:cursor 之后的条目全部丢弃,并通知清理其 outputs 资产
+    if (this.cursor < this.entries.length - 1) {
+      const dropped = this.entries.slice(this.cursor + 1);
+      this.entries = this.entries.slice(0, this.cursor + 1);
+      this.notifyEvict(dropped);
+    }
+
+    this.entries.push(entry);
+    this.cursor = this.entries.length - 1;
+
+    // LRU 淘汰最旧条目
+    this.evictIfNeeded();
+
+    this.notifyChanged();
+  }
+
+  /**
+   * 撤销一步:cursor 前移,返回当前应应用的 entry(即 undo 后的"当前"输出)。
+   * 返回值含义:
+   *   - 如果 undo 后 cursor >= 0:返回该 entry(调用方应将其 outputs 作为当前状态)
+   *   - 如果 undo 后 cursor < 0(回到初始):返回 null(调用方应恢复初始 inputs)
+   * 如果不能 undo(cursor < 0),返回 undefined 表示无操作。
+   */
+  undo(): HistoryEntry | null | undefined {
+    if (!this.canUndo) return undefined;
+    this.cursor -= 1;
+    this.notifyChanged();
+    return this.cursor >= 0 ? this.entries[this.cursor]! : null;
+  }
+
+  /**
+   * 重做一步:cursor 后移,返回重做后应应用的 entry。
+   * 如果不能 redo,返回 undefined 表示无操作。
+   */
+  redo(): HistoryEntry | undefined {
+    if (!this.canRedo) return undefined;
+    this.cursor += 1;
+    this.notifyChanged();
+    return this.entries[this.cursor]!;
+  }
+
+  /** 跳转到指定条目(按 timestamp 顺序的索引) */
+  jumpTo(index: number): HistoryEntry | null | undefined {
+    if (index < -1 || index >= this.entries.length) return undefined;
+    this.cursor = index;
+    this.notifyChanged();
+    return this.cursor >= 0 ? this.entries[this.cursor]! : null;
+  }
+
+  /** 清空所有历史(不触发 onEvict,用于工作流销毁) */
+  clear(): void {
+    this.entries = [];
+    this.cursor = -1;
+    this.notifyChanged();
+  }
+
+  /**
+   * 重置历史:清空所有条目并对每条触发 onEvict(清理其 outputs 资产)。
+   * 用于工作流重新执行(run)时丢弃上一次(可能失败的)历史,避免资产泄漏。
+   * 与 clear() 的区别:clear() 仅重置内存状态,reset() 同时回收资产。
+   */
+  reset(): void {
+    if (this.entries.length > 0) {
+      this.notifyEvict(this.entries);
+    }
+    this.entries = [];
+    this.cursor = -1;
+    this.notifyChanged();
+  }
+
+  /** 导出快照(用于持久化到 IndexedDB) */
+  snapshot(): HistoryStackSnapshot {
+    return {
+      entries: [...this.entries],
+      cursor: this.cursor,
+    };
+  }
+
+  /** 从快照恢复 */
+  restore(snapshot: HistoryStackSnapshot): void {
+    this.entries = [...snapshot.entries];
+    this.cursor = Math.max(-1, Math.min(snapshot.cursor, this.entries.length - 1));
+    this.notifyChanged();
+  }
+
+  // ─── 内部方法 ──────────────────────────────────────
+
+  /** 对一批被丢弃的条目触发 onEvict(忽略回调抛错) */
+  private notifyEvict(entries: HistoryEntry[]): void {
+    const onEvict = this.config.onEvict;
+    if (!onEvict || entries.length === 0) return;
+    for (const entry of entries) {
+      try {
+        onEvict(entry);
+      } catch {
+        // onEvict 失败不应阻断历史操作,由调用方日志记录
+      }
+    }
+  }
+
+  /** 超过 maxEntries 时从最旧端淘汰,并触发 onEvict 回调 */
+  private evictIfNeeded(): void {
+    // 无 onEvict 回调时仍需维护上限(静默丢弃,调用方无法清理 OPFS,但内存不爆)
+    if (!this.config.onEvict) {
+      while (this.entries.length > this.config.maxEntries) {
+        this.entries.shift();
+        // cursor 跟随左移,但不低于 -1
+        this.cursor = Math.max(-1, this.cursor - 1);
+      }
+      return;
+    }
+
+    const evicted: HistoryEntry[] = [];
+    while (this.entries.length > this.config.maxEntries) {
+      evicted.push(this.entries.shift()!);
+      this.cursor = Math.max(-1, this.cursor - 1);
+    }
+    this.notifyEvict(evicted);
+  }
+
+  private notifyChanged(): void {
+    this.config.onChanged?.(this.workflowId, this.list());
+  }
+}
+
+/** 工厂:创建 HistoryStack */
+export function createHistoryStack(
+  workflowId: string,
+  config?: Partial<HistoryStackConfig>
+): HistoryStack {
+  return new HistoryStack(workflowId, config);
+}

package/src/idb-asset-store.ts

@@ -0,0 +1,121 @@
+/**
+ * IndexedDB Asset Store
+ *
+ * 元数据 + Blob 全部存 IndexedDB(通过 Dexie)。
+ * 当 OPFS 不可用时作为降级方案,数据持久化且支持跨刷新恢复。
+ *
+ * 降级链(W2.8 工厂):OPFS → IndexedDB(本实现) → Memory
+ */
+
+import Dexie, { type Table } from 'dexie';
+import type { Asset, AssetId } from '@lokvis/schema';
+import type { AssetStore } from './asset-store.js';
+import {
+  buildAsset,
+  generateId,
+  parseBlobPath,
+  prepareImport,
+} from './asset-store.js';
+
+/** IndexedDB 不可用时抛出 */
+export class IdbUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'IdbUnavailableError';
+  }
+}
+
+/** IDB 文件存储路径前缀(出现在 BlobHandle.path 中) */
+export const IDB_PATH_PREFIX = 'idb';
+
+/** IDB AssetStore 配置 */
+export interface IdbAssetStoreOptions {
+  /** 数据库名(默认 'lokvis-assets') */
+  dbName?: string;
+  /**
+   * 测试注入:自定义 Dexie 实例。
+   * 默认创建新实例。
+   */
+  dbInstance?: AssetDatabase;
+}
+
+/** IndexedDB 中的资产记录(Asset 元数据 + Blob 数据) */
+export interface AssetRecord {
+  /** 主键 = Asset.id */
+  id: AssetId;
+  /** 资产元数据 */
+  asset: Asset;
+  /** 原始 Blob 数据(结构化克隆存储) */
+  blob: Blob;
+}
+
+/** Dexie 数据库封装 */
+export class AssetDatabase extends Dexie {
+  assets!: Table<AssetRecord, string>;
+
+  constructor(name = 'lokvis-assets') {
+    super(name);
+    this.version(1).stores({
+      // 仅主键 id;按 type 查询由上层过滤 list() 实现,无需二级索引
+      assets: 'id',
+    });
+  }
+}
+
+/** 检测当前环境是否支持 IndexedDB */
+export function isIdbSupported(): boolean {
+  // Dexie 始终可 import,但实际使用需要全局 indexedDB
+  return typeof indexedDB !== 'undefined';
+}
+
+/** 创建 IndexedDB 版 AssetStore */
+export async function createIdbAssetStore(
+  options: IdbAssetStoreOptions = {}
+): Promise<AssetStore> {
+  if (!isIdbSupported() && !options.dbInstance) {
+    throw new IdbUnavailableError(
+      'IndexedDB is not available in this environment'
+    );
+  }
+
+  const db = options.dbInstance ?? new AssetDatabase(options.dbName);
+
+  return {
+    async import(source) {
+      const { id, blob, metadata, type } = prepareImport(source);
+      const asset = buildAsset(id, blob, metadata, type, IDB_PATH_PREFIX);
+      await db.assets.put({ id, asset, blob });
+      return asset;
+    },
+
+    async get(id) {
+      const record = await db.assets.get(id);
+      return record?.asset;
+    },
+
+    async getBlob(handle) {
+      const id = parseBlobPath(handle.path, IDB_PATH_PREFIX);
+      const record = await db.assets.get(id);
+      if (!record) {
+        throw new Error(`Blob not found in IndexedDB for path: ${handle.path}`);
+      }
+      return record.blob;
+    },
+
+    async remove(id) {
+      await db.assets.delete(id);
+    },
+
+    async list() {
+      const records = await db.assets.toArray();
+      return records.map((r) => r.asset);
+    },
+
+    async create(blob, metadata, type) {
+      const id = generateId();
+      const asset = buildAsset(id, blob, metadata, type, IDB_PATH_PREFIX);
+      await db.assets.put({ id, asset, blob });
+      return asset;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @lokvis/runtime
+ *
+ * Lokvis Runtime - Browser-local workflow execution engine.
+ * 所有核心工作流在浏览器执行，Cloudflare 只承担边缘服务。
+ */
+
+export * from './types.js';
+export * from './event-bus.js';
+export * from './asset-store.js';
+export * from './opfs-asset-store.js';
+export * from './idb-asset-store.js';
+export * from './capability-registry.js';
+export * from './executor.js';
+export * from './worker-protocol.js';
+export * from './worker-host.js';
+export * from './history.js';
+export * from './runtime.js';
+
+export { RUNTIME_VERSION } from './runtime.js';