@spzxg/cli-ui 0.6.6 → 0.6.7

package/src/board/fileSyncCache.ts

@@ -0,0 +1,250 @@
+import type { FileSyncManifest } from "./fileSync";
+
+export interface FileSyncScope { namespace: string; taskId: string; path: string }
+export const fileSyncScopeKey = (scope: FileSyncScope) => JSON.stringify([scope.namespace, scope.taskId, scope.path]);
+type CachedFile = { key: string; namespace: string; bytes: number; touched: number; manifest?: FileSyncManifest; authorizedRevision?: string };
+type CachedBlock = { key: string; scope: string; id: string; bytes: ArrayBuffer; size: number; touched: number };
+export interface FileSyncCacheOptions { indexedDB?: IDBFactory | null; name?: string; maxBytes?: number }
+const CACHE_TIMEOUT_MS = 5000;
+const unavailable = new WeakSet<IDBDatabase>(), expired = new WeakSet<IDBTransaction>();
+const cacheTimeout = () => new Error("本地文件缓存响应超时");
+function abandon(tx: IDBTransaction | null) {
+  if (!tx) return;
+  expired.add(tx); unavailable.add(tx.db);
+  try { tx.abort(); } catch { /* A completed transaction cannot be aborted. */ }
+  tx.db.close();
+}
+const request = <T>(value: IDBRequest<T>) => new Promise<T>((resolve, reject) => {
+  const finish = (error?: unknown) => { clearTimeout(timer); value.onsuccess = value.onerror = null; if (error) reject(error); else resolve(value.result); };
+  const timer = setTimeout(() => { abandon(value.transaction); finish(cacheTimeout()); }, CACHE_TIMEOUT_MS);
+  value.onsuccess = () => finish(value.transaction && expired.has(value.transaction) ? cacheTimeout() : undefined);
+  value.onerror = () => finish(value.error ?? new Error("文件缓存读取失败"));
+});
+const completed = (tx: IDBTransaction) => {
+  const done = new Promise<void>((resolve, reject) => {
+    const finish = (error?: unknown) => { clearTimeout(timer); tx.oncomplete = tx.onabort = tx.onerror = null; if (error) reject(error); else resolve(); };
+    const timer = setTimeout(() => { abandon(tx); finish(cacheTimeout()); }, CACHE_TIMEOUT_MS);
+    tx.oncomplete = () => finish(); tx.onabort = tx.onerror = () => finish(tx.error ?? new Error("文件缓存事务失败"));
+  });
+  void done.catch(() => undefined); return done;
+};
+function visitCursor(cursor: IDBRequest<IDBCursor | null>, visit: (item: IDBCursor) => boolean | void) {
+  return new Promise<void>((resolve, reject) => {
+    const finish = (error?: unknown) => { clearTimeout(timer); cursor.onsuccess = cursor.onerror = null; if (error) reject(error); else resolve(); };
+    const timer = setTimeout(() => { abandon(cursor.transaction); finish(cacheTimeout()); }, CACHE_TIMEOUT_MS);
+    cursor.onerror = () => finish(cursor.error ?? new Error("文件缓存索引读取失败"));
+    cursor.onsuccess = () => {
+      try {
+        if (cursor.transaction && expired.has(cursor.transaction)) throw cacheTimeout();
+        const item = cursor.result;
+        if (!item || visit(item) === false) finish(); else item.continue();
+      } catch (error) { finish(error); }
+    };
+  });
+}
+const blockKey = (scope: string, id: string) => JSON.stringify([scope, id]);
+const isBuffer = (value: unknown): value is ArrayBuffer => Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+
+/** Only authenticated namespaces reach this cache. A cache miss never substitutes another scope. */
+export class FileSyncCache {
+  private database: Promise<IDBDatabase | null>;
+  private writes: Promise<unknown> = Promise.resolve();
+  private memory = new Map<string, CachedBlock>();
+  private files = new Map<string, CachedFile>();
+  private leases = new Map<string, number>();
+  private protectedBlocks = new Map<string, Map<string, number>>();
+  private touches = new Map<string, number>();
+  private budget: number;
+  private fallback = false;
+  private estimate: { at: number; available: number } | null = null;
+  constructor(options: FileSyncCacheOptions = {}) {
+    this.budget = Math.max(0, options.maxBytes ?? 256 * 1024 * 1024);
+    const factory = options.indexedDB === undefined ? globalThis.indexedDB : options.indexedDB;
+    this.database = !factory ? Promise.resolve(null) : new Promise(resolve => {
+      let abandoned = false;
+      let opened: IDBOpenDBRequest;
+      try { opened = factory.open(options.name ?? "cli-ui-file-sync-v1", 2); } catch { resolve(null); return; }
+      const timer = setTimeout(() => { abandoned = true; try { opened.transaction?.abort(); } catch { /* The open can complete later. */ } resolve(null); }, CACHE_TIMEOUT_MS);
+      opened.onupgradeneeded = event => {
+        if (abandoned) { opened.transaction?.abort(); return; }
+        const db = opened.result;
+        if (!db.objectStoreNames.contains("files")) db.createObjectStore("files", { keyPath: "key" });
+        const blocks = db.objectStoreNames.contains("blocks") ? opened.transaction!.objectStore("blocks") : db.createObjectStore("blocks", { keyPath: "key" });
+        if (!blocks.indexNames.contains("scope")) blocks.createIndex("scope", "scope");
+        if (!blocks.indexNames.contains("lru")) blocks.createIndex("lru", ["touched", "size"]);
+        if (event.oldVersion === 1) { const cursor = blocks.openCursor(); cursor.onsuccess = () => { if (abandoned) return; const item = cursor.result; if (item) { item.update({ ...item.value, size: item.value.bytes.byteLength, touched: item.value.touched ?? 0 }); item.continue(); } }; }
+      };
+      opened.onerror = opened.onblocked = () => { abandoned = true; clearTimeout(timer); resolve(null); };
+      opened.onsuccess = () => {
+        clearTimeout(timer);
+        const db = opened.result;
+        if (abandoned) { db.close(); return; }
+        db.onversionchange = () => { db.close(); unavailable.add(db); this.fallback = true; };
+        db.onclose = () => { unavailable.add(db); this.fallback = true; };
+        resolve(db);
+      };
+    });
+  }
+  get mode(): "persistent" | "session" { return this.fallback ? "session" : this.persistent ? "persistent" : "session"; }
+  private persistent = false;
+  private async db() {
+    const db = await this.database;
+    if (db && unavailable.has(db)) { this.fallback = true; return null; }
+    this.persistent = !!db;
+    return db;
+  }
+  retain(scope: FileSyncScope, ids: ReadonlySet<string> = new Set()) {
+    const key = fileSyncScopeKey(scope); this.leases.set(key, (this.leases.get(key) ?? 0) + 1);
+    const protectedIds = this.protectedBlocks.get(key) ?? new Map<string, number>(); for (const id of ids) protectedIds.set(id, (protectedIds.get(id) ?? 0) + 1); this.protectedBlocks.set(key, protectedIds);
+    let active = true;
+    return () => { if (!active) return; active = false; const count = (this.leases.get(key) ?? 1) - 1; if (count) this.leases.set(key, count); else this.leases.delete(key); for (const id of ids) { const uses = (protectedIds.get(id) ?? 1) - 1; if (uses) protectedIds.set(id, uses); else protectedIds.delete(id); } if (!protectedIds.size) this.protectedBlocks.delete(key); };
+  }
+  private serialize<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.writes.then(work, work); this.writes = next.catch(() => undefined); return next;
+  }
+  private touch(key: string) {
+    const now = Date.now(); if (this.touches.has(key) && now - this.touches.get(key)! < 5000) return;
+    this.touches.set(key, now); const file = this.files.get(key); if (file) file.touched = now;
+    void this.serialize(async () => {
+      const db = await this.db(); if (!db || this.fallback) return;
+      try { const tx = db.transaction("files", "readwrite"), done = completed(tx); const files = tx.objectStore("files"), file = await request(files.get(key)) as CachedFile | undefined; if (file) files.put({ ...file, touched: now }); await done; } catch { /* LRU hints are not required for reading verified bytes. */ }
+    });
+  }
+  async getBlock(scope: FileSyncScope, id: string): Promise<Uint8Array<ArrayBuffer> | null> {
+    const scopeKey = fileSyncScopeKey(scope), key = blockKey(scopeKey, id), hot = this.memory.get(key);
+    if (hot) { this.touch(scopeKey); return new Uint8Array(hot.bytes.slice(0)); }
+    const db = await this.db(); if (!db) return null;
+    try { const tx = db.transaction("blocks", "readonly"); const item = await request(tx.objectStore("blocks").get(key)) as CachedBlock | undefined; if (item && (!isBuffer(item.bytes) || item.scope !== scopeKey || item.id !== id)) { await this.removeBlock(scope, id); return null; } if (item) this.touch(scopeKey); return item ? new Uint8Array(item.bytes) : null; }
+    catch { this.fallback = true; return null; }
+  }
+  private async deleteDiskFile(tx: IDBTransaction, key: string) {
+    const blocks = tx.objectStore("blocks"), index = blocks.index("scope");
+    await visitCursor(index.openKeyCursor(IDBKeyRange.only(key)), item => { blocks.delete(item.primaryKey); });
+    tx.objectStore("files").delete(key);
+  }
+  private memoryPut(scope: FileSyncScope, id: string, bytes: Uint8Array<ArrayBuffer>) {
+    const key = fileSyncScopeKey(scope), entryKey = blockKey(key, id);
+    let used = [...this.memory.values()].reduce((n, block) => n + block.bytes.byteLength, 0);
+    const replaced = this.memory.get(entryKey)?.bytes.byteLength ?? 0; used -= replaced;
+    for (const file of [...this.files.values()].sort((a, b) => a.touched - b.touched)) {
+      if (used + bytes.byteLength <= this.budget) break;
+      if (this.leases.has(file.key)) continue;
+      for (const [oldKey, block] of this.memory) if (block.scope === file.key) { used -= block.bytes.byteLength; this.memory.delete(oldKey); }
+      this.files.delete(file.key);
+    }
+    for (const [oldKey, block] of [...this.memory].sort((a, b) => a[1].touched - b[1].touched)) {
+      if (used + bytes.byteLength <= this.budget) break;
+      if (oldKey === entryKey || this.protectedBlocks.get(block.scope)?.has(block.id)) continue;
+      used -= block.bytes.byteLength; this.memory.delete(oldKey); const file = this.files.get(block.scope); if (file) file.bytes -= block.bytes.byteLength;
+    }
+    if (used + bytes.byteLength > this.budget) return false;
+    this.memory.set(entryKey, { key: entryKey, scope: key, id, bytes: bytes.slice().buffer, size: bytes.byteLength, touched: Date.now() });
+    const previous = this.files.get(key); this.files.set(key, { ...previous, key, namespace: scope.namespace, bytes: (previous?.bytes ?? 0) + bytes.byteLength - replaced, touched: Date.now() });
+    return true;
+  }
+  putBlock(scope: FileSyncScope, id: string, bytes: Uint8Array<ArrayBuffer>): Promise<boolean> {
+    return this.serialize(async () => {
+      const db = await this.db();
+      if (!db || this.fallback) { this.fallback = true; return this.memoryPut(scope, id, bytes); }
+      const key = fileSyncScopeKey(scope), entryKey = blockKey(key, id);
+      let transaction: IDBTransaction | undefined;
+      try {
+        if (!this.estimate || Date.now() - this.estimate.at > 5000) {
+          const values = await request(db.transaction("files", "readonly").objectStore("files").getAll()) as CachedFile[];
+          if (values.some(file => !Number.isSafeInteger(file.bytes) || file.bytes < 0)) throw new Error("文件缓存计账已损坏");
+          const owned = values.reduce((sum, file) => sum + file.bytes, 0);
+          let available = this.budget;
+          let estimateTimer: ReturnType<typeof setTimeout> | undefined;
+          try {
+            const estimate = await Promise.race([navigator.storage?.estimate(), new Promise<undefined>(resolve => { estimateTimer = setTimeout(() => resolve(undefined), 1000); })]);
+            if (estimate?.quota !== undefined && estimate.usage !== undefined) available = Math.min(available, Math.max(0, estimate.quota - estimate.usage + owned));
+          } catch { /* Best-effort estimates cannot disable viewing. */ }
+          finally { if (estimateTimer !== undefined) clearTimeout(estimateTimer); }
+          this.estimate = { at: Date.now(), available };
+        }
+        const available = this.estimate.available;
+        // Read accounting and mutate it under the same IndexedDB write lock,
+        // including writers in other tabs or cache instances.
+        const update = transaction = db.transaction(["blocks", "files"], "readwrite"), committed = completed(update);
+        const existing = await request(update.objectStore("blocks").get(entryKey)) as CachedBlock | undefined;
+        const all = await request(update.objectStore("files").getAll()) as CachedFile[];
+        if (all.some(file => !Number.isSafeInteger(file.bytes) || file.bytes < 0)) throw new Error("文件缓存计账已损坏");
+        let used = all.reduce((sum, file) => sum + file.bytes, 0);
+        const added = bytes.byteLength - (isBuffer(existing?.bytes) ? existing!.bytes.byteLength : 0);
+        for (const file of all.sort((a, b) => a.touched - b.touched)) {
+          if (used + added <= available) break;
+          if (this.leases.has(file.key) || file.key === key) continue;
+          await this.deleteDiskFile(update, file.key); used -= file.bytes;
+        }
+        if (used + added > available) await visitCursor(update.objectStore("blocks").index("lru").openKeyCursor(), item => {
+          if (used + added <= available) return false;
+          const [scopeKey, id] = JSON.parse(String(item.primaryKey)) as [string, string];
+          if (String(item.primaryKey) !== entryKey && !this.protectedBlocks.get(scopeKey)?.has(id)) {
+            const size = Number((item.key as number[])[1]); if (!Number.isSafeInteger(size) || size < 0) throw new Error("文件缓存计账已损坏");
+            used -= size; update.objectStore("blocks").delete(item.primaryKey);
+            const file = all.find(value => value.key === scopeKey); if (file) { file.bytes = Math.max(0, file.bytes - size); update.objectStore("files").put(file); }
+          }
+        });
+        if (used + added > available) { await committed; return false; }
+        const previous = all.find(file => file.key === key);
+        update.objectStore("blocks").put({ key: entryKey, scope: key, id, bytes: bytes.slice().buffer, size: bytes.byteLength, touched: Date.now() } satisfies CachedBlock);
+        update.objectStore("files").put({ ...previous, key, namespace: scope.namespace, bytes: Math.max(0, (previous?.bytes ?? 0) + added), touched: Date.now() } satisfies CachedFile);
+        await committed; return true;
+      } catch { try { transaction?.abort(); } catch { /* A failed request may already have aborted it. */ } this.fallback = true; return this.memoryPut(scope, id, bytes); }
+    });
+  }
+  removeBlock(scope: FileSyncScope, id: string) {
+    return this.serialize(async () => {
+      const key = fileSyncScopeKey(scope), entryKey = blockKey(key, id), previous = this.memory.get(entryKey); this.memory.delete(entryKey);
+      const memoryFile = this.files.get(key); if (memoryFile && previous) memoryFile.bytes = Math.max(0, memoryFile.bytes - previous.bytes.byteLength);
+      const db = await this.db(); if (!db) return;
+      try {
+        const tx = db.transaction(["blocks", "files"], "readwrite"), done = completed(tx);
+        const block = await request(tx.objectStore("blocks").get(entryKey)) as CachedBlock | undefined;
+        const file = await request(tx.objectStore("files").get(key)) as CachedFile | undefined;
+        tx.objectStore("blocks").delete(entryKey);
+        if (file && block) tx.objectStore("files").put({ ...file, bytes: Math.max(0, file.bytes - (isBuffer(block.bytes) ? block.bytes.byteLength : Number(block.size) || 0)) });
+        await done;
+      } catch { this.fallback = true; }
+    });
+  }
+  authorize(scope: FileSyncScope, revision: string) {
+    return this.serialize(async () => {
+      const key = fileSyncScopeKey(scope), db = await this.db();
+      const remember = () => { const old = this.files.get(key); this.files.set(key, { ...old, key, namespace: scope.namespace, bytes: old?.bytes ?? 0, touched: Date.now(), authorizedRevision: revision }); };
+      if (!db || this.fallback) { remember(); return; }
+      try { const tx = db.transaction("files", "readwrite"), done = completed(tx), files = tx.objectStore("files"); const old = await request(files.get(key)) as CachedFile | undefined; files.put({ ...old, key, namespace: scope.namespace, bytes: old?.bytes ?? 0, touched: Date.now(), authorizedRevision: revision }); await done; }
+      catch { this.fallback = true; remember(); }
+    });
+  }
+  putManifest(scope: FileSyncScope, manifest: FileSyncManifest) {
+    return this.serialize(async () => {
+      const key = fileSyncScopeKey(scope), db = await this.db();
+      if (!db || this.fallback) { const previous = this.files.get(key); if (previous?.authorizedRevision && previous.authorizedRevision !== manifest.revision) return; this.files.set(key, { ...previous, key, namespace: scope.namespace, bytes: previous?.bytes ?? 0, touched: Date.now(), manifest }); return; }
+      try { const tx = db.transaction("files", "readwrite"), done = completed(tx); const previous = await request(tx.objectStore("files").get(key)) as CachedFile | undefined; if (!previous?.authorizedRevision || previous.authorizedRevision === manifest.revision) tx.objectStore("files").put({ ...previous, key, namespace: scope.namespace, bytes: previous?.bytes ?? 0, touched: Date.now(), manifest }); await done; }
+      catch { this.fallback = true; }
+    });
+  }
+  async getManifest(scope: FileSyncScope): Promise<FileSyncManifest | null> {
+    const key = fileSyncScopeKey(scope); if (this.files.get(key)?.manifest) return this.files.get(key)!.manifest!;
+    const db = await this.db(); if (!db) return null;
+    try { const tx = db.transaction("files", "readonly"); return ((await request(tx.objectStore("files").get(key))) as CachedFile | undefined)?.manifest ?? null; } catch { return null; }
+  }
+  purgeFile(scope: FileSyncScope) {
+    return this.serialize(async () => {
+      const key = fileSyncScopeKey(scope); this.files.delete(key); this.touches.delete(key);
+      for (const [id, block] of this.memory) if (block.scope === key) this.memory.delete(id);
+      const db = await this.db(); if (!db) return;
+      try { const tx = db.transaction(["blocks", "files"], "readwrite"), done = completed(tx); await this.deleteDiskFile(tx, key); await done; }
+      catch { this.fallback = true; }
+    });
+  }
+  purgeNamespace(namespace: string) {
+    return this.serialize(async () => {
+      for (const [key, file] of this.files) if (file.namespace === namespace) { this.files.delete(key); for (const [id, block] of this.memory) if (block.scope === key) this.memory.delete(id); }
+      const db = await this.db(); if (!db) return;
+      try { const tx = db.transaction(["blocks", "files"], "readwrite"), done = completed(tx); const files = await request(tx.objectStore("files").getAll()) as CachedFile[]; for (const file of files) if (file.namespace === namespace) await this.deleteDiskFile(tx, file.key); await done; } catch { this.fallback = true; }
+    });
+  }
+  async close() { await this.writes; (await this.database)?.close(); }
+}

package/src/board/fileSyncProcessor.ts

@@ -0,0 +1,71 @@
+import { decodeText } from "../core/textDecode";
+
+const aborted = () => new DOMException("文件同步已取消", "AbortError");
+const integrity = (message: string) => Object.assign(new Error(message), { status: 422, code: "integrity" });
+const digest = async (bytes: Uint8Array<ArrayBuffer>) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map(byte => byte.toString(16).padStart(2, "0")).join("");
+type Processed = { bytes: Uint8Array<ArrayBuffer>; text?: string; encoding?: string };
+
+/** One worker owns the assembled buffer; chunks are transferred, not copied into a second main-thread file. */
+export class FileSyncProcessor {
+  private worker: Worker | null = null;
+  private url: string | null = null;
+  private sequence = 0;
+  private pending = new Map<number, { resolve: (value: any) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private output: Uint8Array<ArrayBuffer> | null = null;
+  private offset = 0;
+  private size = 0;
+  private stopped = false;
+  private failed: Error | null = null;
+  constructor(private signal: AbortSignal) {
+    if (typeof Worker !== "undefined" && typeof URL.createObjectURL === "function") try {
+      const script = `const decode=${decodeText.toString()};let output=null,offset=0;
+const hash=async b=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',b)),v=>v.toString(16).padStart(2,'0')).join('');
+onmessage=async({data:m})=>{try{let value;
+if(m.op==='start'){output=new Uint8Array(m.size);offset=0;value=true;}
+if(m.op==='verify'){if(await hash(m.bytes)!==m.hash)throw Error('文件块校验失败');value={bytes:m.bytes};}
+if(m.op==='append'){if(!output||offset+m.bytes.byteLength>output.length||await hash(m.bytes)!==m.hash)throw Error('文件块校验失败');output.set(new Uint8Array(m.bytes),offset);offset+=m.bytes.byteLength;value=true;}
+if(m.op==='finish'){if(!output||offset!==output.length||(m.hash&&await hash(output)!==m.hash))throw Error('完整文件校验失败');const bytes=m.start===0&&m.length===output.length?output:output.slice(m.start,m.start+m.length);const decoded=m.decode?decode(bytes,{fromMiddle:m.fromMiddle}):{};value={bytes:bytes.buffer,...decoded};output=null;}
+postMessage({id:m.id,value},value&&value.bytes?[value.bytes]:[]);}catch(error){postMessage({id:m.id,error:error.message});}};`;
+      this.url = URL.createObjectURL(new Blob([script], { type: "text/javascript" }));
+      this.worker = new Worker(this.url);
+      this.worker.onmessage = event => { const item = this.pending.get(event.data.id); if (!item) return; this.pending.delete(event.data.id); clearTimeout(item.timer); if (event.data.error) item.reject(integrity(event.data.error)); else item.resolve(event.data.value); };
+      this.worker.onerror = () => this.fail(new Error("文件校验 Worker 不可用"));
+    } catch { this.worker?.terminate(); this.worker = null; }
+    signal.addEventListener("abort", this.cancel, { once: true });
+  }
+  private fail(error: Error) { this.failed = error; this.worker?.terminate(); this.worker = null; for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(error); } this.pending.clear(); }
+  private cancel = () => { this.stopped = true; this.worker?.terminate(); for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(aborted()); } this.pending.clear(); this.output = null; };
+  private check() { if (this.stopped || this.signal.aborted) throw aborted(); if (this.failed) throw this.failed; }
+  private rpc(op: string, data: Record<string, unknown>, transfers: Transferable[] = []) {
+    this.check();
+    return new Promise<any>((resolve, reject) => { const id = ++this.sequence, timer = setTimeout(() => this.fail(new Error("文件校验 Worker 超时")), op === "start" ? 5000 : 120_000); this.pending.set(id, { resolve, reject, timer }); try { this.worker!.postMessage({ id, op, ...data }, transfers); } catch (error) { this.pending.delete(id); clearTimeout(timer); reject(error); } });
+  }
+  async start(size: number) {
+    this.check();
+    this.size = size;
+    if (this.worker) {
+      try { await this.rpc("start", { size }); return; }
+      catch (error) { if (this.signal.aborted || this.stopped) throw aborted(); this.worker?.terminate(); this.worker = null; this.failed = null; if (error instanceof DOMException && error.name === "AbortError") throw error; }
+    }
+    this.output = new Uint8Array(size); this.offset = 0;
+  }
+  async verify(bytes: Uint8Array<ArrayBuffer>, hash: string): Promise<Uint8Array<ArrayBuffer>> {
+    this.check();
+    if (this.worker) { const result = await this.rpc("verify", { bytes: bytes.buffer, hash }, [bytes.buffer]); this.check(); return new Uint8Array(result.bytes); }
+    if (await digest(bytes) !== hash) throw integrity("文件块校验失败"); this.check(); return bytes;
+  }
+  async append(bytes: Uint8Array<ArrayBuffer>, hash: string) {
+    this.check();
+    if (this.worker) { await this.rpc("append", { bytes: bytes.buffer, hash }, [bytes.buffer]); this.check(); return; }
+    if (!this.output || this.offset + bytes.length > this.output.length || await digest(bytes) !== hash) throw integrity("文件块校验失败");
+    this.check(); this.output.set(bytes, this.offset); this.offset += bytes.length;
+  }
+  async finish(hash: string | null, decode: boolean, range = { start: 0, length: this.size, fromMiddle: false }): Promise<Processed> {
+    this.check();
+    if (this.worker) { const result = await this.rpc("finish", { hash, decode, ...range }); this.check(); return { ...result, bytes: new Uint8Array(result.bytes) }; }
+    if (!this.output || this.offset !== this.output.length || (hash && await digest(this.output) !== hash)) throw integrity("完整文件校验失败");
+    this.check(); const bytes = range.start === 0 && range.length === this.output.length ? this.output : this.output.slice(range.start, range.start + range.length);
+    return { bytes, ...(decode ? decodeText(bytes, { fromMiddle: range.fromMiddle }) : {}) };
+  }
+  dispose() { this.signal.removeEventListener("abort", this.cancel); this.cancel(); if (this.url) URL.revokeObjectURL(this.url); }
+}

package/src/board/fileSyncQueue.ts

@@ -0,0 +1,56 @@
+/** A finite FIFO for one transport. Waiting work never owns a buffer or request. */
+export function createFileWorkQueue(concurrency: number, maxQueued = 128, waitMs = 180_000) {
+  let active = 0;
+  type Waiting = { start: () => void; cancel: () => void };
+  const waiting: Waiting[] = [];
+  const drain = () => { while (active < concurrency && waiting.length) waiting.shift()!.start(); };
+  return {
+    run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        const abort = () => new DOMException("文件同步已取消", "AbortError");
+        if (signal?.aborted) { reject(abort()); return; }
+        if (active >= concurrency && waiting.length >= maxQueued) {
+          reject(Object.assign(new Error("文件同步队列繁忙，请稍后重试"), { status: 429, code: "client_queue_full", retryAfterMs: 1000 })); return;
+        }
+        let started = false, running = false, settled = false, released = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const settle = (ok: boolean, result: unknown) => {
+          if (settled) return;
+          settled = true; signal?.removeEventListener("abort", item.cancel);
+          if (timer !== undefined) clearTimeout(timer);
+          if (ok) resolve(result as T); else reject(result);
+        };
+        const release = () => {
+          if (released) return;
+          released = true;
+          if (started) active--;
+          else { const index = waiting.indexOf(item); if (index !== -1) waiting.splice(index, 1); }
+          drain();
+        };
+        const finish = (ok: boolean, result: unknown) => { settle(ok, result); release(); };
+        const item: Waiting = {
+          start: () => {
+            if (settled) return;
+            if (timer !== undefined) clearTimeout(timer);
+            started = true; active++;
+            // A caller can cancel before this microtask starts; do not execute retired work.
+            void Promise.resolve().then(() => { if (settled) throw abort(); running = true; return work(); }).then(value => finish(true, value), error => finish(false, error));
+          },
+          cancel: () => {
+            settle(false, abort());
+            // Uncooperative legacy hosts may ignore cancellation. Keep their actual
+            // request/buffer counted until work settles, while rejecting the caller now.
+            if (!running) release();
+          },
+        };
+        signal?.addEventListener("abort", item.cancel, { once: true });
+        if (active < concurrency) item.start();
+        else {
+          waiting.push(item);
+          timer = setTimeout(() => finish(false, Object.assign(new Error("文件同步等待超时，请稍后重试"), { status: 429, code: "client_queue_timeout", retryAfterMs: 1000 })), waitMs);
+        }
+        if (signal?.aborted) item.cancel();
+      });
+    },
+  };
+}

package/src/board/fileSyncTransport.ts

@@ -0,0 +1,85 @@
+import { FileSyncError, validateFileSyncManifest, type FileSyncManifest, type FileSyncTransport } from "./fileSync";
+
+const MANIFEST_MAX = 2 * 1024 * 1024;
+const BATCH_MAX = 1024 * 1024;
+const abortError = () => new DOMException("文件同步已取消", "AbortError");
+
+/** Short, bounded requests only; a 304 is reusable only in the same authenticated namespace. */
+export function createFileSyncTransport(fetcher: typeof fetch, pathBuilder: (jobId: string, operation: "manifest" | "chunks") => string,
+  headers: () => Record<string, string> = () => ({}), options: { requestTimeoutMs?: number } = {}): FileSyncTransport {
+  const namespaces = new Map<string, string>();
+  const call = async (url: string, init: RequestInit, limit: number, signal?: AbortSignal) => {
+    if (signal?.aborted) throw abortError();
+    const controller = new AbortController(); let timedOut = false;
+    const cancel = () => controller.abort(); signal?.addEventListener("abort", cancel, { once: true });
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, options.requestTimeoutMs ?? 30_000);
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    const stopped = new Promise<never>((_resolve, reject) => controller.signal.addEventListener("abort", () => reject(signal?.aborted ? abortError() : new FileSyncError("文件同步请求超时", 0, "timeout")), { once: true }));
+    try {
+      const fetching = fetcher(url, { ...init, headers: { ...headers(), ...init.headers }, signal: controller.signal, cache: "no-store" });
+      void fetching.then(response => { if (controller.signal.aborted) void response.body?.cancel().catch(() => undefined); }, () => undefined);
+      const response = await Promise.race([fetching, stopped]);
+      if (response.status === 304) { void response.body?.cancel().catch(() => undefined); return { response, bytes: new Uint8Array(0) }; }
+      const maximum = response.ok && response.status !== 202 ? limit : 8192;
+      const declared = Number(response.headers.get("Content-Length") ?? 0);
+      if (declared > maximum) { void response.body?.cancel().catch(() => undefined); throw new FileSyncError("文件同步响应超过协议上限", response.status, "response_too_large"); }
+      reader = response.body?.getReader();
+      const parts: Uint8Array[] = []; let size = 0;
+      if (reader) {
+        while (true) {
+          const next = await Promise.race([reader.read(), stopped]);
+          if (next.done) break;
+          size += next.value.byteLength;
+          if (size > maximum) throw new FileSyncError("文件同步响应超过协议上限", response.status, "response_too_large");
+          parts.push(next.value);
+        }
+      }
+      const bytes = new Uint8Array(size); let offset = 0;
+      for (const part of parts) { bytes.set(part, offset); offset += part.byteLength; }
+      if (!response.ok || response.status === 202) {
+        let error: { error?: string; detail?: string } = {};
+        try { error = JSON.parse(new TextDecoder().decode(bytes)); } catch { /* Status remains authoritative. */ }
+        const retry = response.headers.get("Retry-After");
+        const retryAfterMs = retry ? (/^\d+(\.\d+)?$/.test(retry) ? Number(retry) * 1000 : Math.max(0, Date.parse(retry) - Date.now())) : undefined;
+        const missingRoute = response.status === 501 || (response.status === 404 && !["file_not_found", "task_not_found", "job_not_found"].includes(error.error ?? ""));
+        const code = missingRoute ? "unsupported" : error.error ?? "http_error";
+        const common: Record<string, string> = { node_unreachable: "执行节点暂时连不上，请稍后重试", unsupported: "服务端尚未支持大文件增量同步，请升级节点和中枢", file_sync_unsupported: "服务端尚未支持大文件增量同步，请升级节点和中枢", file_not_found: "文件不存在（可能已删除或改名）", file_forbidden: "文件访问权限失效，请重新登录或确认权限", file_sync_busy: "文件服务繁忙，请稍后重试", too_many_snapshot_builds: "文件服务繁忙，请稍后重试", too_many_uploads: "上传任务较多，请稍后重试", file_sync_queue_timeout: "文件处理排队超时，请稍后重试", file_sync_timeout: "文件服务响应超时，请重试", snapshot_cache_full: "文件缓存空间不足，请稍后重试", upload_storage_full: "文件上传空间不足，请稍后重试" };
+        const message = common[code] ?? ([401, 403].includes(response.status) ? "文件访问权限失效，请重新登录或确认权限" : error.detail ?? `文件同步失败（HTTP ${response.status})`);
+        throw new FileSyncError(message, response.status, code, retryAfterMs);
+      }
+      return { response, bytes };
+    } catch (error) {
+      if (signal?.aborted) throw abortError();
+      if (timedOut) throw new FileSyncError("文件同步请求超时", 0, "timeout");
+      throw error;
+    } finally {
+      clearTimeout(timer); signal?.removeEventListener("abort", cancel);
+      if (reader) { void reader.cancel().catch(() => undefined); try { reader.releaseLock(); } catch { /* A cancelled read can still be retiring. */ } }
+    }
+  };
+  return {
+    async manifest(jobId, path, settings = {}) {
+      const key = JSON.stringify([jobId, path]);
+      const read = async (revision?: string): Promise<FileSyncManifest | null> => {
+        const endpoint = pathBuilder(jobId, "manifest"), url = `${endpoint}${endpoint.includes("?") ? "&" : "?"}path=${encodeURIComponent(path)}`;
+        const { response, bytes } = await call(url, { headers: revision ? { "If-None-Match": `"${revision}"` } : {} }, MANIFEST_MAX, settings.signal);
+        if (response.status === 304) {
+          const namespace = response.headers.get("X-File-Sync-Namespace");
+          if (revision && namespace && namespace === namespaces.get(key)) return null;
+          if (revision) return read();
+          throw new FileSyncError("文件修订清单缺失", 502, "invalid_manifest");
+        }
+        let manifest: FileSyncManifest;
+        try { manifest = validateFileSyncManifest(JSON.parse(new TextDecoder().decode(bytes))); }
+        catch (error) { throw error instanceof FileSyncError ? error : new FileSyncError("文件修订清单格式错误", 502, "invalid_manifest"); }
+        namespaces.set(key, manifest.namespace); return manifest;
+      };
+      return read(settings.revision);
+    },
+    async chunks(jobId, input, settings = {}) {
+      if (!input.ids.length) return new Uint8Array(0);
+      const { bytes } = await call(pathBuilder(jobId, "chunks"), { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input) }, BATCH_MAX, settings.signal);
+      return bytes;
+    },
+  };
+}