@lokvis/runtime 0.1.0 → 0.2.0

package/src/memory-guard.ts

@@ -0,0 +1,202 @@
+/**
+ * 内存阈值监测与 OPFS 溢出(W3.3)
+ *
+ * 目标(对应 whitepaper T1「浏览器内存/性能 ★★★★★」):
+ * 浏览器单 tab 内存有限(桌面典型 2-4GB,移动端更少),大图批量处理
+ * 极易触发 OOM 崩溃(整个 tab 被杀,丢失所有中间结果)。MemoryGuard 通过
+ * 显式追踪中间结果占用 + 周期性压力评估,在逼近预算时把中间 Blob 溢出
+ * 到 OPFS,把"OPFS 当虚拟内存用"——内存里只留当前活跃的一两个 Blob。
+ *
+ * 设计取舍:
+ * - tracked:显式登记的中间分配(decode 结果、canvas 输出等大对象)。
+ *   相比 `performance.memory`(Chrome-only、deprecated、MB 粒度、跨浏览器
+ *   不可用),tracked 是可控、可测、确定性的信号,适合做预算判定主依据。
+ * - budget:512MB(经验值——留出 JS runtime / DOM / 其他 tab 的余量,
+ *   实际由 RuntimeConfig.memoryBudget 传入,默认 512MB)。
+ * - pressure:low(<60%) / elevated(60-80%) / high(80-95%) / critical(≥95%)。
+ * - shouldSpill:pressure >= high 时建议把当前中间结果落 OPFS。
+ * - spill/restore/evict:经由 AssetStore(OPFS-backed when available;
+ *   runtime 已用 wrapAssetStoreWithQuota 包裹,溢出受 storageQuota 约束,
+ *   避免无限溢出把磁盘填满)。
+ *
+ * 集成方式(由 W3.4 degradation 编排):
+ *   const guard = new MemoryGuard({ budget, assetStore });
+ *   const alloc = guard.track(blob.size);          // 登记
+ *   if (guard.shouldSpill()) { const a = await guard.spill(blob); blob = null; }  // 溢出
+ *   ...
+ *   alloc.release();                                // 回退
+ */
+
+import type { Asset, AssetMetadata, AssetType } from '@lokvis/schema';
+import type { AssetStore } from './asset-store.js';
+
+/** 默认内存预算:512MB(见上) */
+export const DEFAULT_MEMORY_BUDGET = 512 * 1024 * 1024;
+
+/** 内存压力等级(降级阶梯 W3.4 据此选择策略) */
+export type MemoryPressure = 'low' | 'elevated' | 'high' | 'critical';
+
+export interface MemoryGuardOptions {
+  /** 总内存预算(字节),超出 high 阈值则建议溢出 */
+  budget?: number;
+  /** elevated 阈值占 budget 比例(默认 0.6) */
+  elevatedRatio?: number;
+  /** high 阈值(默认 0.8):达到则 shouldSpill=true */
+  highRatio?: number;
+  /** critical 阈值(默认 0.95):达到则降级阶梯走 L4 拒绝 */
+  criticalRatio?: number;
+  /** 溢出目标(通常为 OPFS-backed AssetStore);不提供则 shouldSpill 永远 false */
+  assetStore?: AssetStore;
+}
+
+/** track() 返回的分配句柄:丢弃引用时调用 release() 回退计数(幂等) */
+export interface MemoryAllocation {
+  /** 该笔登记的字节数 */
+  readonly bytes: number;
+  /** 回退登记;重复调用幂等(仅首次生效) */
+  release(): void;
+}
+
+/**
+ * 估算解码后位图占用的内存(RGBA,4 字节/像素)。
+ *
+ * 一个 4000×3000 的 JPEG,blob 可能只有 2MB,但 decode 成 ImageBitmap 后
+ * 占 4000*3000*4 ≈ 46MB。追踪中间结果时应以此为准而非 blob.size,
+ * 否则严重低估内存压力。
+ */
+export function estimateDecodedBytes(width: number, height: number): number {
+  return Math.max(0, Math.round(width * height * 4));
+}
+
+/** 估算 Blob 在内存中占用的字节数(对未解码的 Blob,以其 size 为准) */
+export function estimateBlobBytes(blob: Blob): number {
+  return blob.size;
+}
+
+/** 内存守卫:追踪中间结果占用 + 触发 OPFS 溢出 */
+export class MemoryGuard {
+  private tracked = 0;
+  private readonly budget: number;
+  private readonly elevatedRatio: number;
+  private readonly highRatio: number;
+  private readonly criticalRatio: number;
+  private readonly assetStore?: AssetStore;
+
+  constructor(opts: MemoryGuardOptions = {}) {
+    this.budget = opts.budget ?? DEFAULT_MEMORY_BUDGET;
+    this.elevatedRatio = opts.elevatedRatio ?? 0.6;
+    this.highRatio = opts.highRatio ?? 0.8;
+    this.criticalRatio = opts.criticalRatio ?? 0.95;
+    this.assetStore = opts.assetStore;
+
+    // 阈值单调性校验,避免配置错误导致 pressure 永远卡在某一档
+    if (!(this.elevatedRatio <= this.highRatio && this.highRatio <= this.criticalRatio)) {
+      throw new Error(
+        `MemoryGuard thresholds must be non-decreasing: ` +
+          `elevated(${this.elevatedRatio}) <= high(${this.highRatio}) <= critical(${this.criticalRatio})`
+      );
+    }
+  }
+
+  /** 当前已登记的字节数 */
+  get currentUsage(): number {
+    return this.tracked;
+  }
+
+  /** 总预算(字节) */
+  get budgetBytes(): number {
+    return this.budget;
+  }
+
+  /** 当前是否已配置可溢出的 AssetStore */
+  get canSpill(): boolean {
+    return this.assetStore !== undefined;
+  }
+
+  /**
+   * 登记一笔内存占用。返回 release 句柄,丢弃引用时调用以回退计数。
+   * 用于追踪 decode 结果 / canvas 输出等大对象的生命周期。
+   */
+  track(bytes: number): MemoryAllocation {
+    if (bytes < 0) {
+      throw new Error(`MemoryGuard.track: bytes must be non-negative, got ${bytes}`);
+    }
+    this.tracked += bytes;
+    let released = false;
+    return {
+      bytes,
+      release: () => {
+        if (released) return; // 幂等:重复 release 仅首次生效
+        released = true;
+        this.tracked = Math.max(0, this.tracked - bytes);
+      },
+    };
+  }
+
+  /** 当前压力等级(基于 tracked / budget) */
+  getPressure(): MemoryPressure {
+    const ratio = this.tracked / this.budget;
+    if (ratio >= this.criticalRatio) return 'critical';
+    if (ratio >= this.highRatio) return 'high';
+    if (ratio >= this.elevatedRatio) return 'elevated';
+    return 'low';
+  }
+
+  /** 已用比例(0-1+) */
+  getUsageRatio(): number {
+    return this.tracked / this.budget;
+  }
+
+  /**
+   * 是否应溢出(pressure >= high)。无 assetStore 时永远 false(无法溢出,
+   * 交由降级阶梯 L3/L4 处理)。
+   */
+  shouldSpill(): boolean {
+    if (!this.assetStore) return false;
+    const p = this.getPressure();
+    return p === 'high' || p === 'critical';
+  }
+
+  /**
+   * 把一个中间 Blob 溢出到 OPFS(assetStore.create),返回 Asset 句柄。
+   * 调用方应在 spill 后丢弃内存中的 Blob 引用,以真正释放内存。
+   *
+   * @param blob 要溢出的中间结果
+   * @param mimeType Blob 的 MIME(用于元数据);默认取 blob.type
+   * @param assetType 资产类型(默认 'image');video/pdf 管线可传对应类型
+   */
+  async spill(blob: Blob, mimeType?: string, assetType: AssetType = 'image'): Promise<Asset> {
+    if (!this.assetStore) {
+      throw new Error(
+        'MemoryGuard.spill requires an assetStore (OPFS-backed). ' +
+          'Construct MemoryGuard with { assetStore } to enable spilling.'
+      );
+    }
+    const mime = mimeType || blob.type || 'application/octet-stream';
+    const metadata: AssetMetadata = {
+      mimeType: mime,
+      size: blob.size,
+      format: mime.split('/')[1] ?? 'bin',
+    };
+    return this.assetStore.create(blob, metadata, assetType);
+  }
+
+  /** 从 OPFS 读回之前 spill 的中间结果 */
+  async restore(asset: Asset): Promise<Blob> {
+    if (!this.assetStore) {
+      throw new Error('MemoryGuard.restore requires an assetStore');
+    }
+    return this.assetStore.getBlob(asset.blob);
+  }
+
+  /** 丢弃已 spill 的中间结果(处理完成后回收 OPFS 空间) */
+  async evict(asset: Asset): Promise<void> {
+    if (!this.assetStore) return;
+    await this.assetStore.remove(asset.id);
+  }
+
+  /** 重置所有登记(用于工作流结束 / 取消后的清理,tracked 归零) */
+  reset(): void {
+    this.tracked = 0;
+  }
+}

package/src/opfs-asset-store.ts

@@ -1,10 +1,15 @@
 /**
  * OPFS Asset Store
  *
- * 大文件(blob)存 OPFS(Origin Private File System),元数据存内存 Map。
- * OPFS 是浏览器私有文件系统,blob 持久化(刷新后文件仍在),但元数据仅在内存 ——
- * 刷新后 list() 会返回空、get(id) 返回 undefined(除非元数据由上层持久化)。
- * 完整元数据持久化建议叠加 IdbAssetStore 或在 W3 补强。
+ * 大文件(blob)存 OPFS(Origin Private File System),元数据存内存 Map +
+ * IndexedDB(Dexie)持久化。OPFS 是浏览器私有文件系统,blob 持久化(刷新后
+ * 文件仍在);W6.6 起元数据也通过 Dexie 持久化,刷新后 list()/get() 能恢复。
+ *
+ * 持久化策略(W6.6):
+ * - 启动时:db.metadata.toArray() 预加载内存 Map(后续 get/list 零 IO)
+ * - import/create:写 OPFS 文件 + db.metadata.put + 内存 Map.set
+ * - remove:删 OPFS 文件 + db.metadata.delete + 内存 Map.delete
+ * - IndexedDB 不可用时降级为仅内存模式(刷新后丢失,与 W2 行为一致)
  *
  * 注:任务规格提及 FileSystemSyncAccessHandle(Worker 内同步句柄),
  * 但 AssetStore 接口本身为 async,主线程仅可使用 FileSystemFileHandle 异步 API,
@@ -13,6 +18,7 @@
  * 降级链(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 {
@@ -21,6 +27,7 @@ import {
   parseBlobPath,
   prepareImport,
 } from './asset-store.js';
+import { isIdbSupported } from './idb-asset-store.js';
 
 /** OPFS 不可用或初始化失败时抛出 */
 export class OpfsUnavailableError extends Error {
@@ -36,6 +43,31 @@ export const OPFS_PATH_PREFIX = 'opfs';
 /** OPFS 文件名后缀 */
 const OPFS_FILE_SUFFIX = '.bin';
 
+/**
+ * OPFS 元数据持久化数据库(W6.6)。
+ *
+ * 仅存 { id, asset }(不含 blob,blob 在 OPFS 文件里),用于刷新后恢复内存 Map。
+ * 数据库名独立于 IdbAssetStore 的 'lokvis-assets',避免与全持久化 store 冲突。
+ */
+export class OpfsMetadataDatabase extends Dexie {
+  metadata!: Table<OpfsMetadataRecord, AssetId>;
+
+  constructor(name = 'lokvis-opfs-metadata') {
+    super(name);
+    this.version(1).stores({
+      metadata: 'id',
+    });
+  }
+}
+
+/** OPFS 元数据记录 */
+export interface OpfsMetadataRecord {
+  /** 主键 = Asset.id */
+  id: AssetId;
+  /** 资产元数据(blob 在 OPFS 文件,不在此存) */
+  asset: Asset;
+}
+
 /** OPFS AssetStore 配置 */
 export interface OpfsAssetStoreOptions {
   /** OPFS 根目录下的命名空间目录名(默认 'lokvis') */
@@ -47,6 +79,13 @@ export interface OpfsAssetStoreOptions {
    * 默认使用 navigator.storage.getDirectory()。
    */
   rootHandle?: FileSystemDirectoryHandle;
+  /**
+   * 测试注入:自定义元数据库实例(W6.6 持久化)。
+   * 默认在 IndexedDB 可用时自动创建 OpfsMetadataDatabase。
+   */
+  metadataDb?: OpfsMetadataDatabase;
+  /** 元数据库名(默认 'lokvis-opfs-metadata';仅 metadataDb 未注入时生效) */
+  metadataDbName?: string;
 }
 
 /** 检测当前环境是否支持 OPFS */
@@ -98,26 +137,85 @@ async function writeOpfsFile(
   return fileHandle;
 }
 
+/**
+ * 初始化元数据库(W6.6)。
+ *
+ * 优先用 options.metadataDb(测试注入);否则在 IndexedDB 可用时创建新实例。
+ * IndexedDB 不可用时返回 undefined,调用方降级为仅内存模式。
+ */
+function resolveMetadataDb(
+  options: OpfsAssetStoreOptions
+): OpfsMetadataDatabase | undefined {
+  if (options.metadataDb) return options.metadataDb;
+  if (!isIdbSupported()) return undefined;
+  try {
+    return new OpfsMetadataDatabase(options.metadataDbName);
+  } catch (err) {
+    console.warn('[lokvis] OPFS metadata db init failed, falling back to memory-only:', err);
+    return undefined;
+  }
+}
+
+/** 安全写入元数据库(失败仅 warn,不阻断主流程) */
+async function persistMetadata(
+  db: OpfsMetadataDatabase | undefined,
+  id: AssetId,
+  asset: Asset
+): Promise<void> {
+  if (!db) return;
+  try {
+    await db.metadata.put({ id, asset });
+  } catch (err) {
+    console.warn(`[lokvis] OPFS metadata persist failed for ${id}:`, err);
+  }
+}
+
+/** 安全删除元数据(失败仅 warn) */
+async function deleteMetadata(
+  db: OpfsMetadataDatabase | undefined,
+  id: AssetId
+): Promise<void> {
+  if (!db) return;
+  try {
+    await db.metadata.delete(id);
+  } catch (err) {
+    console.warn(`[lokvis] OPFS metadata delete failed for ${id}:`, err);
+  }
+}
+
 /** 创建 OPFS 版 AssetStore */
 export async function createOpfsAssetStore(
   options: OpfsAssetStoreOptions = {}
 ): Promise<AssetStore> {
   const assetsDir = await resolveAssetsDir(options);
-  /** 元数据缓存(内存中;持久化由 IdbAssetStore 负责) */
+  /** 元数据缓存(内存中;W6.6 起启动时从 Dexie 预加载) */
   const assets = new Map<AssetId, Asset>();
-  /** id → 文件句柄(用于 getBlob/remove) */
+  /** id → 文件句柄(用于 getBlob/remove;刷新后丢失,按需重建) */
   const fileHandles = new Map<AssetId, FileSystemFileHandle>();
+  /** 元数据库(W6.6 持久化;undefined 时仅内存模式) */
+  const db = resolveMetadataDb(options);
+
+  // 启动时预加载已持久化的元数据(刷新后恢复 list/get)
+  if (db) {
+    try {
+      const records = await db.metadata.toArray();
+      for (const r of records) assets.set(r.id, r.asset);
+    } catch (err) {
+      console.warn('[lokvis] OPFS metadata preload failed:', err);
+    }
+  }
 
   /** 从 id 派生 OPFS 文件名 */
   const fileName = (id: AssetId) => `${id}${OPFS_FILE_SUFFIX}`;
 
   return {
     async import(source) {
-      const { id, blob, metadata, type } = prepareImport(source);
+      const { id, blob, metadata, type } = await prepareImport(source);
       const handle = await writeOpfsFile(assetsDir, fileName(id), blob);
       fileHandles.set(id, handle);
       const asset = buildAsset(id, blob, metadata, type, OPFS_PATH_PREFIX);
       assets.set(id, asset);
+      await persistMetadata(db, id, asset);
       return asset;
     },
 
@@ -129,7 +227,7 @@ export async function createOpfsAssetStore(
       const id = parseBlobPath(handle.path, OPFS_PATH_PREFIX);
       let fileHandle = fileHandles.get(id);
       if (!fileHandle) {
-        // 可能是进程重启后元数据丢失但句柄仍可恢复
+        // 可能是进程重启后内存句柄丢失,从 OPFS 重新获取
         try {
           fileHandle = await assetsDir.getFileHandle(fileName(id));
           fileHandles.set(id, fileHandle);
@@ -146,9 +244,18 @@ export async function createOpfsAssetStore(
       fileHandles.delete(id);
       try {
         await assetsDir.removeEntry(fileName(id));
-      } catch {
-        // 文件不存在视为已删除,静默忽略
+      } catch (err) {
+        // NotFoundError 是幂等删除的预期场景(文件已不存在),静默忽略;
+        // 其他错误(权限/IO 等)记录 warn,便于排查孤儿 OPFS 文件长期累积
+        // 无论文件删除是否成功,都继续清理 IDB metadata(见下方)
+        if (!(err instanceof DOMException && err.name === 'NotFoundError')) {
+          console.warn(
+            `[lokvis] OPFS removeEntry unexpected failure for asset ${id}:`,
+            err
+          );
+        }
       }
+      await deleteMetadata(db, id);
     },
 
     async list() {
@@ -161,6 +268,7 @@ export async function createOpfsAssetStore(
       fileHandles.set(id, handle);
       const asset = buildAsset(id, blob, metadata, type, OPFS_PATH_PREFIX);
       assets.set(id, asset);
+      await persistMetadata(db, id, asset);
       return asset;
     },
   };