@lokvis/runtime 0.2.2 → 0.4.2

package/src/concurrency-controller.ts

@@ -0,0 +1,52 @@
+/**
+ * ConcurrencyController - 批量作业并发槽位控制(W4.4 拆分)
+ *
+ * 职责:
+ * - 提供免费/Pro 默认并发上限常量
+ * - 按 MemoryGuard 压力动态收缩并发槽位
+ *
+ * 设计原则:
+ * - 无状态:仅依赖注入的 memoryGuard
+ * - 纯函数:current() 基于 baseConcurrency + 当前 pressure 计算
+ */
+import type { MemoryGuard, MemoryPressure } from './memory-guard.js';
+
+/** 默认并发槽位 */
+export const FREE_CONCURRENCY = 4;
+export const PRO_CONCURRENCY = 16;
+
+/** 按 MemoryPressure 收缩并发槽位 */
+export 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;
+  }
+}
+
+/**
+ * 并发控制器:基于 MemoryGuard 压力动态收缩槽位。
+ *
+ * 不持有 baseConcurrency(每 job 独立),current() 接收 base 并返回当前实际可用槽位。
+ */
+export class ConcurrencyController {
+  private readonly memoryGuard?: MemoryGuard;
+
+  constructor(opts: { memoryGuard?: MemoryGuard }) {
+    this.memoryGuard = opts.memoryGuard;
+  }
+
+  /** 当前并发槽位(按内存压力动态收缩) */
+  current(baseConcurrency: number): number {
+    const pressure = this.memoryGuard?.getPressure() ?? 'low';
+    return shrinkConcurrencyByPressure(baseConcurrency, pressure);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime 类型化错误类(T10:消除 SDK message 模式匹配)
+ *
+ * 这些错误类供 runtime 各模块在对应场景抛出,替代原先的 `throw new Error(...)`。
+ * SDK 的 `fromLokvisError()` 通过 `instanceof` 检测这些类,包装为对应的 SDK
+ * 错误类(LokvisError 子类),无需再依赖 message 字符串模式匹配。
+ *
+ * 命名与 SDK 错误类对应(如 runtime `AssetNotFoundError` → SDK `AssetNotFoundError`),
+ * 但 runtime 侧继承 `Error`(不依赖 SDK 的 `LokvisError`),符合五层架构
+ * (Runtime 不依赖 SDK)。SDK import 时加 `Runtime` 前缀别名避免命名冲突
+ * (与 QuotaExceededError / Worker*Error 等现有模式一致)。
+ *
+ * super message 与原 `throw new Error(...)` 的 message 完全一致,保证:
+ * - 日志/堆栈输出不变
+ * - 依赖 message 文案的测试不破
+ */
+
+/** 资产未找到(assetStore.get 返回空) */
+export class AssetNotFoundError extends Error {
+  readonly assetId: string;
+  constructor(assetId: string) {
+    super(`Asset not found: ${assetId}`);
+    this.name = 'AssetNotFoundError';
+    this.assetId = assetId;
+  }
+}
+
+/** 资产 Blob 未找到(getBlob 在 store 中找不到对应 blob) */
+export class AssetBlobNotFoundError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'AssetBlobNotFoundError';
+  }
+}
+
+/** 工作流结构校验失败(节点 ID 重复 / edge 引用未知节点 / 自环等) */
+export class WorkflowInvalidError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkflowInvalidError';
+  }
+}
+
+/** 工作流包含环(拓扑排序后 sorted.length !== nodes.length) */
+export class WorkflowCycleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkflowCycleError';
+  }
+}
+
+/** 工作流节点执行失败(transform 节点缺 capability 字段) */
+export class WorkflowNodeError extends Error {
+  readonly nodeId: string;
+  constructor(nodeId: string, message: string) {
+    super(message);
+    this.name = 'WorkflowNodeError';
+    this.nodeId = nodeId;
+  }
+}
+
+/** 能力未注册(capabilityRegistry.resolve 返回空且非 stub-only) */
+export class CapabilityNotRegisteredError extends Error {
+  readonly capability: string;
+  constructor(capability: string) {
+    super(`No implementation registered for capability "${capability}"`);
+    this.name = 'CapabilityNotRegisteredError';
+    this.capability = capability;
+  }
+}
+
+/** 能力仅有 stub 实现(需安装真实 engine 插件) */
+export class CapabilityStubOnlyError extends Error {
+  readonly capability: string;
+  constructor(capability: string) {
+    super(
+      `Capability "${capability}" is not yet available (only stub engine registered). Install a real engine plugin to use this capability.`
+    );
+    this.name = 'CapabilityStubOnlyError';
+    this.capability = capability;
+  }
+}

package/src/executor.ts

@@ -17,6 +17,14 @@ import type {
 import type { EventBus } from '@lokvis/schema';
 import type { AssetStore } from './asset-store.js';
 import type { CapabilityRegistry } from './capability-registry.js';
+import {
+  AssetNotFoundError,
+  WorkflowInvalidError,
+  WorkflowCycleError,
+  WorkflowNodeError,
+  CapabilityNotRegisteredError,
+  CapabilityStubOnlyError,
+} from './errors.js';
 
 /** 执行中的工作流状态 */
 interface RunningWorkflow {
@@ -75,7 +83,7 @@ function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): Workflow
     const seen = new Set<string>();
     for (const n of nodes) {
       if (seen.has(n.id)) {
-        throw new Error(`Workflow contains duplicate node id: ${n.id}`);
+        throw new WorkflowInvalidError(`Workflow contains duplicate node id: ${n.id}`);
       }
       seen.add(n.id);
     }
@@ -90,7 +98,7 @@ function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): Workflow
   // 被静默吞掉，进而导致下游节点入度无法归零 → 误判为环）
   for (const edge of edges) {
     if (!nodeMap.has(edge.from)) {
-      throw new Error(
+      throw new WorkflowInvalidError(
         `Workflow edge references unknown source node: "${edge.from}". ` +
           `Edge endpoints must reference existing nodes; ` +
           `reserved sentinel nodes (e.g. "__input__") are not supported ` +
@@ -99,13 +107,13 @@ function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): Workflow
       );
     }
     if (!nodeMap.has(edge.to)) {
-      throw new Error(
+      throw new WorkflowInvalidError(
         `Workflow edge references unknown target node: "${edge.to}". ` +
           `Edge endpoints must reference existing nodes.`
       );
     }
     if (edge.from === edge.to) {
-      throw new Error(
+      throw new WorkflowInvalidError(
         `Workflow contains self-loop on node: "${edge.from}". ` +
           `Self-loops create cycles and are not allowed.`
       );
@@ -133,7 +141,7 @@ function topologicalSort(nodes: WorkflowNode[], edges: WorkflowEdge[]): Workflow
   }
 
   if (sorted.length !== nodes.length) {
-    throw new Error('Workflow contains a cycle, cannot execute');
+    throw new WorkflowCycleError('Workflow contains a cycle, cannot execute');
   }
 
   return sorted;
@@ -167,7 +175,7 @@ export class WorkflowExecutor {
       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}`);
+          if (!asset) throw new AssetNotFoundError(id);
           return asset;
         })
       );
@@ -198,65 +206,109 @@ export class WorkflowExecutor {
       // 过滤掉 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;
-        }
+      // E1: 多 target 机制
+      // targets 存在且非空时,为每个 target 独立执行一次 transform 链,
+      // target.params 浅合并到每个节点的 params（target 优先）。
+      // 无 targets 时等价于单次执行（targetParams = undefined）。
+      const targets = workflow.outputs.targets;
+      const targetParamSets: (Record<string, unknown> | undefined)[] =
+        targets && targets.length > 0
+          ? targets.map((t) => t.params)
+          : [undefined];
+
+      // 保存原始输入资产,每个 target 执行前重置
+      const inputAssets = [...currentAssets];
+      const allOutputs: Asset[] = [];
+      /**
+       * 各 transform 节点的输出 AssetId(按 node.id 索引)。
+       * 仅单 target 场景填充(多 target 同一节点会有多份输出,
+       * 索引歧义,留空让调用方走事件总线监听 node:finished)。
+       */
+      const stepOutputs: Record<string, AssetId[]> = {};
+      const isSingleTarget = targetParamSets.length === 1;
+
+      for (const targetParams of targetParamSets) {
+        // 每个 target 开始前重置为原始输入
+        currentAssets = [...inputAssets];
+
+        // 依次执行每个 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();
+          state.currentNodeId = node.id;
+          const nodeStart = Date.now();
 
-        this.config.eventBus.emit({
-          type: 'node:started',
-          workflowId,
-          nodeId: node.id,
-          inputs: currentAssets,
-        });
+          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) {
-          if (this.config.capabilityRegistry.isStubOnly(capability)) {
-            throw new Error(
-              `Capability "${capability}" is not yet available (only stub engine registered). Install a real engine plugin to use this capability.`
-            );
+          // 解析能力实现(transform 节点必须有 capability)
+          const capability = node.capability;
+          if (!capability) {
+            throw new WorkflowNodeError(node.id, `Transform node "${node.id}" has no capability`);
+          }
+          const impl = this.config.capabilityRegistry.resolve(capability);
+          if (!impl) {
+            if (this.config.capabilityRegistry.isStubOnly(capability)) {
+              throw new CapabilityStubOnlyError(capability);
+            }
+            throw new CapabilityNotRegisteredError(capability);
+          }
+
+          // E1: target params 覆盖 node params（浅合并,target 优先）
+          // 注：展开 undefined 是 no-op,无需 ?? {} fallback（oxlint no-empty-fallback-in-spread）
+          const mergedParams = targetParams
+            ? { ...node.params, ...targetParams }
+            : (node.params ?? {});
+
+          // 执行能力
+          const ctx = createExecutionContext(
+            workflowId,
+            node.id,
+            abortController.signal
+          );
+          const outputs = await impl.execute(currentAssets, mergedParams, ctx);
+          currentAssets = outputs;
+
+          // 单 target 时记录该节点输出,供调用方读取中间结果
+          // (多 target 场景跳过,避免 last-write-wins 语义歧义)
+          if (isSingleTarget) {
+            stepOutputs[node.id] = currentAssets.map((a) => a.id);
           }
-          throw new Error(`No implementation registered for capability "${capability}"`);
+
+          this.config.eventBus.emit({
+            type: 'node:finished',
+            workflowId,
+            nodeId: node.id,
+            capability,
+            params: mergedParams,
+            outputs: currentAssets,
+            duration: Date.now() - nodeStart,
+          });
         }
 
-        // 执行能力
-        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,
-        });
+        // 收集当前 target 的输出（cancelled 时也保留已完成的节点输出）
+        allOutputs.push(...currentAssets);
+
+        if (state.status === 'cancelled') break;
       }
 
       const result: WorkflowResult = {
         workflowId,
-        outputs: currentAssets.map((a) => a.id),
+        outputs: allOutputs.map((a) => a.id),
+        // 单 target 且非取消时暴露中间步骤输出;其他场景保持 undefined,
+        // 调用方需要中间结果时应改用 eventBus 监听 node:finished 事件
+        stepOutputs: isSingleTarget && state.status !== 'cancelled' ? stepOutputs : undefined,
         duration: Date.now() - startTime,
         status: state.status === 'cancelled' ? 'cancelled' : 'completed',
       };
@@ -308,6 +360,21 @@ export class WorkflowExecutor {
     this.config.eventBus.emit({ type: 'workflow:cancelled', workflowId });
   }
 
+  /**
+   * 取消所有运行中的工作流(W21.6 runtime.dispose 用)。
+   *
+   * 遍历 running Map,对每个 state 执行 cancel 的同步部分
+   * (status = cancelled + abort + 唤醒 resume resolver + emit event)。
+   * 不等待 executor.execute 内部循环跳出 —— abort 后循环在下个 await
+   * 点自然抛 AbortError,资源随 Promise reject 释放。
+   */
+  cancelAll(): void {
+    // 复制一份避免 cancel 内 emit 触发的 listener 回调 mutate 原集合
+    for (const workflowId of [...this.running.keys()]) {
+      void this.cancel(workflowId);
+    }
+  }
+
   /** 暂停执行 */
   async pause(workflowId: string): Promise<void> {
     const state = this.running.get(workflowId);

package/src/history.ts

@@ -189,8 +189,9 @@ export class HistoryStack {
     for (const entry of entries) {
       try {
         onEvict(entry);
-      } catch {
-        // onEvict 失败不应阻断历史操作,由调用方日志记录
+      } catch (err) {
+        // onEvict 失败不应阻断历史操作,但需记录便于调试
+        console.warn(`[lokvis] history onEvict threw for entry ${entry.id}:`, err);
       }
     }
   }

package/src/idb-asset-store.ts

@@ -16,6 +16,7 @@ import {
   parseBlobPath,
   prepareImport,
 } from './asset-store.js';
+import { AssetBlobNotFoundError } from './errors.js';
 
 /** IndexedDB 不可用时抛出 */
 export class IdbUnavailableError extends Error {
@@ -97,7 +98,7 @@ export async function createIdbAssetStore(
       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}`);
+        throw new AssetBlobNotFoundError(`Blob not found in IndexedDB for path: ${handle.path}`);
       }
       return record.blob;
     },
@@ -117,5 +118,10 @@ export async function createIdbAssetStore(
       await db.assets.put({ id, asset, blob });
       return asset;
     },
+
+    // W21.6: 关闭 Dexie 连接(IDB 数据不删除,下次创建 store 时可恢复)。
+    async dispose() {
+      db.close();
+    },
   };
 }

package/src/index.ts

@@ -3,23 +3,58 @@
  *
  * Lokvis Runtime - Browser-local workflow execution engine.
  * 所有核心工作流在浏览器执行，Cloudflare 只承担边缘服务。
+ *
+ * 公共 API 收敛策略(O-3):
+ * - 4 个模块全量透传:types / errors / browser-detect / runtime(仅 4 个符号)
+ * - 7 个模块仅命名导出被外部消费的符号(AssetStore / 错误类 / BatchProcessor 等)
+ * - 8 个纯内部模块(event-bus / capability-registry / executor / worker-protocol /
+ *   history / memory-guard / plugin-permissions / plugin-context)不从公共入口透传,
+ *   runtime 内部代码与测试通过相对路径 import。
  */
 
+// ─── 全量透传(公共 API) ──────────────────────────────────────────
 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 './history-store.js';
-export * from './memory-guard.js';
-export * from './degradation.js';
-export * from './batch-processor.js';
-export * from './workflow-builder.js';
+export * from './errors.js';
+export * from './browser-detect.js';
 export * from './runtime.js';
 
-export { RUNTIME_VERSION } from './runtime.js';
+// ─── 命名导出(仅被外部消费的符号) ────────────────────────────────
+
+// asset-store:mcp-server 的 NodeAssetStore 实现此接口
+export type { AssetStore } from './asset-store.js';
+
+// opfs-asset-store:仅错误类被 SDK errors 引用
+export { OpfsUnavailableError } from './opfs-asset-store.js';
+
+// idb-asset-store:仅错误类被 SDK errors 引用
+export { IdbUnavailableError } from './idb-asset-store.js';
+
+// degradation:仅错误类被 SDK errors 引用
+export { DegradationRejectedError } from './degradation.js';
+
+// worker-host:6 个错误类被 SDK errors 引用
+export {
+  WorkerCrashedError,
+  WorkerRestartingError,
+  WorkerDeadError,
+  WorkerRequestTimeoutError,
+  WorkerHandshakeError,
+  WorkerRequestAbortedError,
+} from './worker-host.js';
+
+// batch-processor:BatchProcessor 类型 + 错误类 + 常量被 SDK 引用
+export {
+  BatchProcessor,
+  BatchLimitExceededError,
+  FREE_BATCH_LIMIT,
+} from './batch-processor.js';
+export type {
+  BatchJob,
+  BatchItem,
+  BatchItemInput,
+  EnqueueOptions,
+  BatchProgress,
+} from './batch-processor.js';
+
+// history-store:HistoryStore / HistoryStoreOptions 是 RuntimeConfig 字段类型契约
+export type { HistoryStore, HistoryStoreOptions } from './history-store.js';