@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/fileSync.ts

@@ -0,0 +1,351 @@
+import { notifyCallback } from "../core/callbacks";
+import { FileSyncCache, fileSyncScopeKey, type FileSyncScope } from "./fileSyncCache";
+import { FileSyncProcessor } from "./fileSyncProcessor";
+import { createFileWorkQueue } from "./fileSyncQueue";
+
+export const FILE_SYNC_MAX = 100 * 1024 * 1024;
+export interface FileSyncManifest { protocol: 1; namespace: string; revision: string; size: number; hash: string; chunks: { id: string; size: number }[] }
+export interface FileSyncTransport {
+  /** null means 304 after the transport checked the authenticated namespace. */
+  manifest(jobId: string, path: string, options?: { signal?: AbortSignal; revision?: string }): Promise<FileSyncManifest | null>;
+  chunks(jobId: string, input: { path: string; revision: string; ids: string[] }, options?: { signal?: AbortSignal }): Promise<Uint8Array<ArrayBuffer>>;
+}
+export class FileSyncError extends Error {
+  constructor(message: string, readonly status: number, readonly code: string, readonly retryAfterMs?: number) { super(message); this.name = "FileSyncError"; }
+}
+export interface FileSyncProgress { phase: "manifest" | "chunks" | "verify"; loadedBytes: number; totalBytes: number; downloadedBytes: number; reusedBytes: number }
+export interface FileSyncOptions { signal?: AbortSignal; onProgress?: (progress: FileSyncProgress) => void; decode?: boolean; range?: { start?: number; maxBytes: number; tail?: boolean }; pendingTimeoutMs?: number; /** Require a manifest request started after this explicit refresh. */ fresh?: boolean; /** Remember only successfully viewed ranges, never downloads. */ preview?: boolean }
+export interface FilePreviewRefresh { changed: string[]; error?: Error; denied?: Array<{ path: string; message: string }> }
+export interface SyncedFile {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  revision: string; namespace: string; hash: string; size: number; start: number; end: number; truncated: boolean;
+  text?: string; encoding?: string; downloadedBytes: number; reusedBytes: number; cacheMode: "persistent" | "session";
+}
+const hex = /^[a-f0-9]{64}$/;
+export function validateFileSyncManifest(value: unknown): FileSyncManifest {
+  const m = value as FileSyncManifest;
+  if (!m || m.protocol !== 1 || typeof m.namespace !== "string" || !m.namespace || m.namespace.length > 1024 || typeof m.revision !== "string" || typeof m.hash !== "string" || !hex.test(m.revision) || !hex.test(m.hash)
+    || !Number.isSafeInteger(m.size) || m.size < 0 || m.size > FILE_SYNC_MAX || !Array.isArray(m.chunks) || m.chunks.length > 10000) throw new FileSyncError("文件修订清单无效或超过100MiB", 502, "invalid_manifest");
+  let total = 0; const sizes = new Map<string, number>();
+  for (const chunk of m.chunks) {
+    if (!chunk || typeof chunk.id !== "string" || !hex.test(chunk.id) || !Number.isSafeInteger(chunk.size) || chunk.size <= 0 || chunk.size > 256 * 1024 || (sizes.has(chunk.id) && sizes.get(chunk.id) !== chunk.size)) throw new FileSyncError("文件分块清单无效", 502, "invalid_manifest");
+    total += chunk.size; sizes.set(chunk.id, chunk.size);
+  }
+  if (total !== m.size) throw new FileSyncError("文件分块长度与清单不一致", 502, "invalid_manifest");
+  return { protocol: 1, namespace: m.namespace, revision: m.revision, size: m.size, hash: m.hash, chunks: m.chunks.map(chunk => ({ id: chunk.id, size: chunk.size })) };
+}
+const aborted = () => new DOMException("文件同步已取消", "AbortError");
+const check = (signal: AbortSignal) => { if (signal.aborted) throw aborted(); };
+function untilCancelled<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(aborted());
+  return new Promise((resolve, reject) => {
+    const cancel = () => { signal.removeEventListener("abort", cancel); reject(aborted()); };
+    signal.addEventListener("abort", cancel, { once: true });
+    promise.then(value => { signal.removeEventListener("abort", cancel); resolve(value); }, error => { signal.removeEventListener("abort", cancel); reject(error); });
+    if (signal.aborted) cancel();
+  });
+}
+const statusOf = (error: unknown) => error && typeof error === "object" && "status" in error ? Number(error.status) : 0;
+async function retryPending<T>(work: () => Promise<T>, signal: AbortSignal, timeoutMs = 180_000): Promise<T> {
+  const deadline = Date.now() + (Number.isFinite(timeoutMs) && timeoutMs >= 0 ? Math.min(timeoutMs, 180_000) : 180_000);
+  let pending = 0, failures = 0;
+  for (;;) {
+    check(signal);
+    try { return await work(); } catch (error) {
+      check(signal);
+      const status = statusOf(error), code = (error as FileSyncError)?.code;
+      const permanent = error instanceof Error && error.name === "AbortError"
+        || ["client_queue_full", "client_queue_timeout", "integrity", "invalid_manifest", "invalid_response", "response_too_large", "unsupported", "file_sync_unsupported"].includes(code);
+      const retryable = !status || status === 408 || status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+      if (permanent || (status !== 202 && (!retryable || ++failures > 3)) || Date.now() >= deadline) throw error;
+      const backoff = Math.min(8000, 500 * 2 ** (status === 202 ? pending++ : failures - 1));
+      const hint = Number((error as FileSyncError)?.retryAfterMs ?? (status === 202 ? 1000 : 0));
+      // Retry-After is a lower bound. Jitter spreads a burst without retrying before the server is ready.
+      const delay = Math.max(Number.isFinite(hint) && hint > 0 ? hint : 0, backoff) + Math.random() * Math.min(1000, backoff * .25);
+      if (delay > deadline - Date.now()) throw error;
+      await new Promise<void>((resolve, reject) => {
+        const cancel = () => { clearTimeout(timer); reject(aborted()); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", cancel); resolve(); }, delay);
+        signal.addEventListener("abort", cancel, { once: true });
+        if (signal.aborted) cancel();
+      });
+    }
+  }
+}
+type Shared<T> = { controller: AbortController; promise: Promise<T>; consumers: Set<object>; progress: Map<object, (value: FileSyncProgress) => void> };
+function lease<T>(map: Map<string, Shared<T>>, key: string, work: (signal: AbortSignal, notify: (value: FileSyncProgress) => void) => Promise<T>, signal?: AbortSignal, progress?: (value: FileSyncProgress) => void): Promise<T> {
+  if (signal?.aborted) return Promise.reject(aborted());
+  let entry = map.get(key);
+  if (!entry) {
+    const controller = new AbortController();
+    const created = { controller, consumers: new Set<object>(), progress: new Map<object, (value: FileSyncProgress) => void>(), promise: null! as Promise<T> };
+    created.promise = Promise.resolve().then(() => work(controller.signal, value => { for (const callback of [...created.progress.values()]) notifyCallback(callback, value); })).finally(() => { if (map.get(key) === created) map.delete(key); });
+    void created.promise.catch(() => undefined); map.set(key, created); entry = created;
+  }
+  const owned = entry, consumer = {}; owned.consumers.add(consumer); if (progress) owned.progress.set(consumer, progress);
+  return new Promise<T>((resolve, reject) => {
+    let active = true;
+    const release = () => { active = false; signal?.removeEventListener("abort", cancel); owned.consumers.delete(consumer); owned.progress.delete(consumer); };
+    const cancel = () => { if (!active) return; release(); reject(aborted()); if (!owned.consumers.size) { owned.controller.abort(); if (map.get(key) === owned) map.delete(key); } };
+    signal?.addEventListener("abort", cancel, { once: true });
+    owned.promise.then(value => { if (active) { release(); resolve(value); } }, error => { if (active) { release(); reject(error); } });
+    if (signal?.aborted) cancel();
+  });
+}
+
+/** Per-transport coordinator: every caller authorizes a manifest before any cached bytes are read. */
+export function createFileSynchronizer(transport: FileSyncTransport, cache = new FileSyncCache()) {
+  const last = new Map<string, FileSyncManifest>(), manifests = new Map<string, Shared<FileSyncManifest>>(), files = new Map<string, Shared<SyncedFile>>(), chunks = new Map<string, Shared<Uint8Array<ArrayBuffer>>>();
+  type Preview = { namespace: string; revision: string; range?: FileSyncOptions["range"]; stale?: boolean };
+  const previews = new Map<string, Preview>(), previewReads = new Map<string, object>(), previewListeners = new Map<string, Set<() => void>>();
+  const manifestQueue = createFileWorkQueue(3), chunkQueue = createFileWorkQueue(3);
+  const assemblyQueue = createFileWorkQueue(2), refreshQueue = createFileWorkQueue(1);
+  const retireNamespace = (namespace: string) => {
+    for (const entries of [files, chunks]) for (const [key, entry] of entries) if (JSON.parse(JSON.parse(key)[0])[0] === namespace) { entry.controller.abort(); entries.delete(key); }
+  };
+  const retireFile = (scope: FileSyncScope) => {
+    const identity = fileSyncScopeKey(scope);
+    for (const entries of [files, chunks]) for (const [key, entry] of entries) if (JSON.parse(key)[0] === identity) { entry.controller.abort(); entries.delete(key); }
+  };
+  type QueuedChunk = { identity: string; jobId: string; path: string; revision: string; id: string; size: number; signal: AbortSignal; timeout?: number; resolve: (bytes: Uint8Array<ArrayBuffer>) => void; reject: (error: unknown) => void };
+  let queued: QueuedChunk[] = [], flushTimer: ReturnType<typeof setTimeout> | undefined;
+  const flush = () => {
+    flushTimer = undefined; const pending = queued; queued = [];
+    while (pending.length) {
+      const first = pending.shift()!;
+      if (first.signal.aborted) { first.reject(aborted()); continue; }
+      const batch = [first]; let size = first.size;
+      for (let i = 0; i < pending.length;) {
+        const item = pending[i];
+        if (item.identity === first.identity && item.revision === first.revision && size + item.size <= 1024 * 1024) { pending.splice(i, 1); if (item.signal.aborted) item.reject(aborted()); else { batch.push(item); size += item.size; } } else i++;
+      }
+      const controller = new AbortController();
+      const cancel = () => { if (batch.every(item => item.signal.aborted)) controller.abort(); };
+      for (const item of batch) item.signal.addEventListener("abort", cancel);
+      void retryPending(() => chunkQueue.run(() => transport.chunks(first.jobId, { path: first.path, revision: first.revision, ids: batch.map(item => item.id) }, { signal: controller.signal }), controller.signal), controller.signal, first.timeout).then(bytes => {
+        if (bytes.length !== size) throw new FileSyncError("文件块批次长度错误", 502, "integrity");
+        let offset = 0; for (const item of batch) { const data = bytes.slice(offset, offset + item.size); offset += item.size; if (item.signal.aborted) item.reject(aborted()); else item.resolve(data); }
+      }).catch(error => { for (const item of batch) item.reject(error); }).finally(() => { for (const item of batch) item.signal.removeEventListener("abort", cancel); });
+    }
+  };
+  const fetchChunk = (item: Omit<QueuedChunk, "resolve" | "reject">) => new Promise<Uint8Array<ArrayBuffer>>((resolve, reject) => {
+    queued.push({ ...item, resolve, reject }); if (flushTimer === undefined) flushTimer = setTimeout(flush, 12);
+  });
+  const manifestFor = async (jobId: string, path: string, signal?: AbortSignal, timeout?: number, fresh = false) => {
+    const resource = JSON.stringify([jobId, path]);
+    // A round-end check must start after that event. Sharing an older in-flight
+    // check can miss the final edit indefinitely when there is no polling.
+    const earlier = fresh ? manifests.get(resource) : undefined;
+    if (earlier) await untilCancelled(earlier.promise.catch(() => undefined), signal);
+    return lease(manifests, resource, async inner => {
+      const previous = last.get(resource);
+      try {
+        const response = await retryPending(() => manifestQueue.run(() => transport.manifest(jobId, path, { signal: inner, revision: previous?.revision }), inner), inner, timeout); check(inner);
+        const manifest = response ? validateFileSyncManifest(response) : previous;
+        if (!manifest) throw new FileSyncError("没有可复用的授权修订清单", 502, "invalid_manifest");
+        last.delete(resource); last.set(resource, manifest); while (last.size > 40) last.delete(last.keys().next().value!);
+        return manifest;
+      } catch (error) {
+        const status = statusOf(error);
+        if ([401, 403, 404].includes(status)) {
+          last.delete(resource);
+          if (previous) {
+            if (status === 404 || (status === 403 && (error as FileSyncError).code === "file_forbidden")) { const scope = { namespace: previous.namespace, taskId: jobId, path }; retireFile(scope); await cache.purgeFile(scope); }
+            else { retireNamespace(previous.namespace); await cache.purgeNamespace(previous.namespace); }
+          }
+        }
+        throw error;
+      }
+    }, signal);
+  };
+  const read = async (jobId: string, path: string, options: FileSyncOptions = {}, initialManifest?: FileSyncManifest): Promise<SyncedFile> => {
+    if (!path || path.length > 4096 || path.includes("\0")) throw new FileSyncError("文件路径无效", 400, "invalid_path");
+    if (options.range && (!Number.isSafeInteger(options.range.maxBytes) || options.range.maxBytes < 0 || !Number.isSafeInteger(options.range.start ?? 0) || (options.range.start ?? 0) < 0)) throw new FileSyncError("文件读取范围无效", 400, "invalid_range");
+    for (let attempt = 0; ; attempt++) {
+      notifyCallback(options.onProgress, { phase: "manifest", loadedBytes: 0, totalBytes: 0, downloadedBytes: 0, reusedBytes: 0 });
+      const manifest = attempt === 0 && initialManifest ? initialManifest : await manifestFor(jobId, path, options.signal, options.pendingTimeoutMs, options.fresh || attempt > 0);
+      const start = options.range?.tail ? Math.max(0, manifest.size - options.range.maxBytes) : Math.min(manifest.size, options.range?.start ?? 0);
+      const end = options.range ? Math.min(manifest.size, start + options.range.maxBytes) : manifest.size;
+      const scope: FileSyncScope = { namespace: manifest.namespace, taskId: jobId, path };
+      if (options.signal?.aborted) throw aborted();
+      await untilCancelled(cache.authorize(scope, manifest.revision), options.signal);
+      if (options.signal?.aborted) throw aborted();
+      const identity = fileSyncScopeKey(scope), key = JSON.stringify([identity, manifest.revision, start, end, options.decode !== false]);
+      try {
+        return await lease(files, key, (outerSignal, progress) => assemblyQueue.run(async () => {
+          const controller = new AbortController(), cancel = () => controller.abort();
+          outerSignal.addEventListener("abort", cancel, { once: true }); if (outerSignal.aborted) cancel();
+          const signal = controller.signal;
+          const processor = new FileSyncProcessor(signal);
+          let downloadedBytes = 0, reusedBytes = 0, loadedBytes = 0;
+          const report = (phase: FileSyncProgress["phase"]) => progress({ phase, loadedBytes, totalBytes: end - start, downloadedBytes, reusedBytes });
+          let offset = 0;
+          const selected = manifest.chunks.map(chunk => { const value = { ...chunk, offset }; offset += chunk.size; return value; }).filter(chunk => chunk.offset < end && chunk.offset + chunk.size > start);
+          const release = cache.retain(scope, new Set(selected.map(chunk => chunk.id)));
+          const coverStart = selected[0]?.offset ?? start, coverSize = selected.reduce((sum, chunk) => sum + chunk.size, 0);
+          const network = async (chunk: { id: string; size: number }) => {
+            const bytes = await lease(chunks, JSON.stringify([identity, manifest.revision, chunk.id]), inner => fetchChunk({ identity, jobId, path, revision: manifest.revision, id: chunk.id, size: chunk.size, signal: inner, timeout: options.pendingTimeoutMs }), signal);
+            check(signal); if (bytes.byteLength !== chunk.size) throw new FileSyncError("文件块长度错误", 502, "integrity");
+            const verified = await processor.verify(bytes.slice(), chunk.id); check(signal); downloadedBytes += verified.byteLength;
+            await cache.putBlock(scope, chunk.id, verified); check(signal); return verified;
+          };
+          const read = async (chunk: { id: string; size: number }) => {
+            const cached = await cache.getBlock(scope, chunk.id); check(signal);
+            if (cached?.byteLength === chunk.size) return { bytes: cached, cached: true };
+            if (cached) await cache.removeBlock(scope, chunk.id);
+            return { bytes: await network(chunk), cached: false };
+          };
+          const prefetched = new Map<number, ReturnType<typeof read>>();
+          const prefetch = (index: number) => { let bytes = 0; for (let i = index; i < Math.min(selected.length, index + 48); i++) { bytes += selected[i].size; if (bytes > 3 * 1024 * 1024) break; if (!prefetched.has(i)) { const promise = read(selected[i]); void promise.catch(() => undefined); prefetched.set(i, promise); } } };
+          try {
+            await processor.start(coverSize); prefetch(0);
+            for (let index = 0; index < selected.length; index++) {
+              check(signal); const chunk = selected[index]; const data = await prefetched.get(index)!; prefetched.delete(index);
+              try { await processor.append(data.bytes, chunk.id); if (data.cached) reusedBytes += chunk.size; }
+              catch (error) {
+                check(signal); if (!data.cached) throw error;
+                // Several prefetched positions may hold the same old corrupt
+                // block. Reuse a repair already committed by an earlier position.
+                const repaired = await cache.getBlock(scope, chunk.id); check(signal);
+                let reused = false;
+                if (repaired?.byteLength === chunk.size) try { await processor.append(repaired, chunk.id); reused = true; reusedBytes += chunk.size; } catch { check(signal); }
+                if (!reused) { await cache.removeBlock(scope, chunk.id); await processor.append(await network(chunk), chunk.id); }
+              }
+              loadedBytes = Math.min(end - start, chunk.offset + chunk.size - start); report("chunks"); prefetch(index + 1);
+            }
+            report("verify");
+            const complete = start === 0 && end === manifest.size;
+            const assembled = await processor.finish(complete ? manifest.hash : null, options.decode !== false, { start: start - coverStart, length: end - start, fromMiddle: start > 0 });
+            check(signal); const latest = last.get(JSON.stringify([jobId, path]));
+            if (complete && latest?.namespace === manifest.namespace && latest.revision === manifest.revision) await cache.putManifest(scope, manifest); check(signal);
+            return { ...assembled, namespace: manifest.namespace, revision: manifest.revision, hash: manifest.hash, size: manifest.size, start, end, truncated: !complete, downloadedBytes, reusedBytes, cacheMode: cache.mode };
+          } finally { controller.abort(); outerSignal.removeEventListener("abort", cancel); processor.dispose(); release(); }
+        }, outerSignal), options.signal, options.onProgress);
+      } catch (error) {
+        if (statusOf(error) !== 410 || attempt >= 2 || options.signal?.aborted) throw error;
+        last.delete(JSON.stringify([jobId, path]));
+      }
+    }
+  };
+  const sync = async (jobId: string, path: string, options: FileSyncOptions = {}): Promise<SyncedFile> => {
+    const resource = JSON.stringify([jobId, path]), token = {};
+    if (options.preview) previewReads.set(resource, token);
+    try {
+      const result = await read(jobId, path, options);
+      if (options.preview && previewReads.get(resource) === token && !options.signal?.aborted) {
+        const previous = previews.get(resource);
+        const range = options.range ? { start: options.range.start ?? 0, maxBytes: options.range.maxBytes, tail: !!options.range.tail } : undefined;
+        // A preview can finish behind a metadata baseline or a newer background refresh.
+        // Normal revision-only updates must not create a watch -> preview -> watch cycle.
+        const latest = last.get(resource), behindLatest = latest && (latest.namespace !== result.namespace || latest.revision !== result.revision);
+        const alreadyRefreshed = behindLatest && previous?.namespace === latest.namespace && previous.revision === latest.revision && JSON.stringify(previous.range) === JSON.stringify(range);
+        if (alreadyRefreshed) {
+          // Keep the latest verified revision, but request one corrective event
+          // because this caller is about to display an older snapshot.
+          previews.set(resource, { ...previous, stale: true });
+        } else {
+          previews.delete(resource); previews.set(resource, { namespace: result.namespace, revision: result.revision, range });
+          while (previews.size > 40) previews.delete(previews.keys().next().value!);
+        }
+        if (!previous || behindLatest || previous.namespace !== result.namespace || JSON.stringify(previous.range) !== JSON.stringify(range)) {
+          for (const callback of [...previewListeners.get(jobId) ?? []]) notifyCallback(callback, undefined);
+        }
+      }
+      return result;
+    } finally { if (previewReads.get(resource) === token) previewReads.delete(resource); }
+  };
+  const refreshPreviews = (jobId: string, paths: Iterable<string>, signal?: AbortSignal): Promise<FilePreviewRefresh> => {
+    const requested = [...new Set(paths)];
+    // Serialize background assembly across tasks as well: a chunk request limit alone does not
+    // prevent several 100MiB workers allocating full buffers at the same time.
+    const work = async (): Promise<FilePreviewRefresh> => {
+      const changed = new Set<string>(); let error: Error | undefined, hasRecoverableError = false, retryAfterMs = 0;
+      const denied: NonNullable<FilePreviewRefresh["denied"]> = [];
+      for (const path of requested) {
+        if (signal?.aborted) throw aborted();
+        const resource = JSON.stringify([jobId, path]), previous = previews.get(resource);
+        if (!previous) continue; // Restored/unread tabs are still demand-loaded on activation.
+        try {
+          const manifest = await manifestFor(jobId, path, signal, undefined, true);
+          if (manifest.namespace === previous.namespace && manifest.revision === previous.revision && !previous.stale) continue;
+          changed.add(path);
+          const result = await read(jobId, path, { signal, decode: false, range: previous.range }, manifest);
+          const latest = last.get(resource), current = previews.get(resource);
+          if (current?.namespace === previous.namespace && current.revision === previous.revision && JSON.stringify(current.range) === JSON.stringify(previous.range)
+            && latest?.namespace === result.namespace && latest.revision === result.revision) {
+            previews.set(resource, { ...current, namespace: result.namespace, revision: result.revision, stale: false });
+          }
+        } catch (failure) {
+          const status = statusOf(failure);
+          if (signal?.aborted || (failure instanceof Error && failure.name === "AbortError") || status === 401) throw failure;
+          if (status === 403) {
+            if ((failure as FileSyncError).code !== "file_forbidden") throw failure;
+            const scope = { namespace: last.get(resource)?.namespace ?? previous.namespace, taskId: jobId, path };
+            last.delete(resource); previews.delete(resource); retireFile(scope); await cache.purgeFile(scope);
+            changed.delete(path); denied.push({ path, message: failure instanceof Error ? failure.message : String(failure) });
+            continue;
+          }
+          if (status === 404) {
+            changed.add(path);
+            if (previews.get(resource) === previous) {
+              previews.delete(resource);
+              // Deletion may arrive from a chunk request after manifest authorization too.
+              const scope = { namespace: last.get(resource)?.namespace ?? previous.namespace, taskId: jobId, path };
+              last.delete(resource); retireFile(scope); await cache.purgeFile(scope);
+            }
+          } else {
+            const candidate = failure instanceof Error ? failure : new Error(String(failure));
+            const code = (failure as FileSyncError)?.code;
+            // Match event-driven workspace recovery: a permanent failure of one
+            // file must not hide a later file's recoverable failure.
+            const recoverable = !["invalid_manifest", "invalid_response", "integrity", "response_too_large", "client_queue_timeout"].includes(code)
+              && (!status || [408, 429, 500, 502, 503, 504].includes(status));
+            if (!error || (recoverable && !hasRecoverableError)) error = candidate;
+            if (recoverable) {
+              hasRecoverableError = true;
+              const hint = (failure as FileSyncError)?.retryAfterMs;
+              if (typeof hint === "number" && Number.isFinite(hint) && hint >= 0) retryAfterMs = Math.max(retryAfterMs, hint);
+            }
+          }
+        }
+      }
+      // Preserve the original errors: consumers may share them with other reads.
+      const combined = error && hasRecoverableError && retryAfterMs > 0 ? Object.assign(new Error(error.message), error, { name: error.name, retryAfterMs }) : error;
+      return { changed: [...changed], ...(combined ? { error: combined } : {}), ...(denied.length ? { denied } : {}) };
+    };
+    return refreshQueue.run(work, signal);
+  };
+  const onPreviewScope = (jobId: string, callback: () => void) => {
+    let listeners = previewListeners.get(jobId); if (!listeners) { listeners = new Set(); previewListeners.set(jobId, listeners); }
+    listeners.add(callback);
+    return () => { listeners.delete(callback); if (!listeners.size) previewListeners.delete(jobId); };
+  };
+  return { sync, refreshPreviews, onPreviewScope, cache, clearNamespace: (namespace: string) => {
+    for (const entry of manifests.values()) entry.controller.abort(); manifests.clear();
+    retireNamespace(namespace);
+    for (const [key, manifest] of last) if (manifest.namespace === namespace) last.delete(key);
+    for (const [key, preview] of previews) if (preview.namespace === namespace) previews.delete(key);
+    return cache.purgeNamespace(namespace);
+  } };
+}
+const synchronizers = new WeakMap<FileSyncTransport, ReturnType<typeof createFileSynchronizer>>();
+function synchronizerFor(transport: FileSyncTransport) {
+  let sync = synchronizers.get(transport); if (!sync) { sync = createFileSynchronizer(transport); synchronizers.set(transport, sync); }
+  return sync;
+}
+export function syncFile(transport: FileSyncTransport, jobId: string, path: string, options: FileSyncOptions = {}) {
+  return synchronizerFor(transport).sync(jobId, path, options);
+}
+/** Refresh only ranges that were actually previewed, one file at a time. */
+export function refreshFilePreviews(transport: FileSyncTransport, jobId: string, paths: Iterable<string>, signal?: AbortSignal) {
+  return synchronizerFor(transport).refreshPreviews(jobId, paths, signal);
+}
+export function onFilePreviewScope(transport: FileSyncTransport, jobId: string, callback: () => void) {
+  return synchronizerFor(transport).onPreviewScope(jobId, callback);
+}
+/** Hosts can call this on an explicit account logout; a viewer unmount keeps reusable cache. */
+export function clearFileSyncNamespace(transport: FileSyncTransport, namespace: string) {
+  const synchronizer = synchronizers.get(transport);
+  return synchronizer ? synchronizer.clearNamespace(namespace) : new FileSyncCache().purgeNamespace(namespace);
+}

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(); }
+}