fix(desktop): atomic writes for all filesystem-backed stores

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Atomic writes for desktop filesystem storage.** Every `services/fs/*Store.ts` writer
+  (project, active-project marker, settings, API keys, snapshots, Codex, RAG vectors, binder
+  assets, images) previously wrote directly to its final path — a crash or power loss mid-write
+  could leave the file truncated/corrupted with no recovery path. New `writeTextFileAtomic`/
+  `writeFileAtomic` helpers (`services/fs/fsCore.ts`) write to a temp sibling first, then
+  atomically rename over the final path, so a reader only ever sees the old complete file or the
+  new complete file, never a partial one. Also fixes a latent capability gap: `fs:allow-read-file`/
+  `fs:allow-write-file`/`fs:allow-rename` were never declared in
+  `src-tauri/capabilities/default.json`, even though `assetFsStore.ts` already called the binary
+  `readFile`/`writeFile` commands they gate. **Review-loop follow-up fixes to the same change:** a
+  failed temp-file write (not just a failed rename) now also cleans up its orphaned temp file;
+  same-path writes now serialize in call order via a per-path queue, closing a race where two
+  overlapping saves could have an older write's rename land after a newer one and silently roll
+  the file back; `crypto.randomUUID()` now has a `getRandomValues()`-based fallback for WebKit
+  versions that predate it, matching the existing pattern in
+  `encryptionMigrationOrchestrator.ts#createMigrationOperationId`. A new startup sweep
+  (`cleanupOrphanedTempFiles`, run once per session, fire-and-forget) recursively removes
+  `.tmp-*` siblings left behind by a write interrupted by an actual process kill (crash/power
+  loss) rather than a caught JS error — neither `atomicRename`'s nor the temp-write failure
+  handler's in-session cleanup can ever see that case, since execution stops before either runs.
+  **Second round of review-loop follow-up fixes:** the startup sweep being fire-and-forget meant a
+  save started immediately after `initialize()` could create a brand-new (legitimate, not
+  orphaned) temp file that the still-running sweep would then delete out from under it — a
+  module-level `activeTempPaths` set, populated for the duration of each write, now tells the
+  sweep to skip any temp file currently being written rather than delaying every session's
+  startup by awaiting the sweep. The per-path write queue also didn't coalesce: a burst of
+  same-path writes arriving faster than disk I/O completes (e.g. rapid autosave retries on a slow
+  or temporarily locked disk) appended every call to a growing promise chain, writing every stale
+  intermediate version to disk instead of just the latest one. The queue now keeps at most the
+  currently-running write and a single latest-queued write per path — a write arriving while
+  another is already queued (not yet started) supersedes it in place instead of appending another
+  link, bounding both memory and wasted I/O regardless of how many same-path writes arrive in a
+  burst.
+
 ## [1.27.0] — 2026-08-13
 
 ### Added

services/fs/assetFsStore.ts

@@ -6,9 +6,28 @@
 
 import { logger } from '../logger';
 import type { BinderAssetMeta, BinderAssetPayload } from '../storageBackend';
-import { retryFs, sanitizePathSegment } from './fsCore';
+import { retryFs, sanitizePathSegment, writeFileAtomic, writeTextFileAtomic } from './fsCore';
 import { FsSnapshotStore } from './snapshotFsStore';
 
+interface BinderAssetManifest {
+  version: 1;
+  dataFile: string;
+  meta: BinderAssetMeta;
+}
+
+function createBinderRevision(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+function isBinderAssetManifest(value: unknown): value is BinderAssetManifest {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<BinderAssetManifest>;
+  return candidate.version === 1 && typeof candidate.dataFile === 'string' && !!candidate.meta;
+}
+
 export class FsAssetStore extends FsSnapshotStore {
   // --- Image Store Methods ---
 
@@ -22,8 +41,8 @@ export class FsAssetStore extends FsSnapshotStore {
     }
 
     const imageFile = await apis.join(imagesPath, `${sanitizePathSegment(id, 'image')}.png`);
-    const cleanBase64 = base64Data.replace(/^data:image\/png;base64,/, '');
-    await retryFs(() => apis.writeTextFile(imageFile, cleanBase64));
+    // QNBS-v3: preserve the original data URL so JPEG/WebP uploads keep their MIME type; legacy raw base64 remains readable below.
+    await writeTextFileAtomic(apis, imageFile, base64Data);
   }
 
   async getImage(id: string): Promise<string | null> {
@@ -41,7 +60,9 @@ export class FsAssetStore extends FsSnapshotStore {
       }
 
       const base64Data = await retryFs(() => apis.readTextFile(imageFile));
-      return `data:image/png;base64,${base64Data}`;
+      return base64Data.startsWith('data:image/')
+        ? base64Data
+        : `data:image/png;base64,${base64Data}`;
     } catch (error) {
       logger.error('Failed to load image:', error);
       return null;
@@ -75,7 +96,29 @@ export class FsAssetStore extends FsSnapshotStore {
     const dir = await apis.join(appDataPath, 'projects', safeId, 'binder');
     const binFile = await apis.join(dir, `${safeAsset}.bin`);
     const metaFile = await apis.join(dir, `${safeAsset}.meta.json`);
-    return { apis, dir, binFile, metaFile };
+    return { apis, dir, binFile, metaFile, safeAsset };
+  }
+
+  private async readBinderManifest(
+    apis: Awaited<ReturnType<FsAssetStore['binderAssetPaths']>>['apis'],
+    metaFile: string,
+    safeAsset: string,
+  ): Promise<BinderAssetManifest | null> {
+    try {
+      const parsed = JSON.parse(await retryFs(() => apis.readTextFile(metaFile))) as unknown;
+      if (!isBinderAssetManifest(parsed)) return null;
+      if (
+        !parsed.dataFile.startsWith(`${safeAsset}.`) ||
+        !parsed.dataFile.endsWith('.bin') ||
+        parsed.dataFile.includes('/') ||
+        parsed.dataFile.includes('\\')
+      ) {
+        throw new Error('Binder asset manifest references an invalid data file');
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
   }
 
   async saveBinderAsset(
@@ -85,23 +128,53 @@ export class FsAssetStore extends FsSnapshotStore {
     meta: BinderAssetMeta,
   ): Promise<void> {
     const apis = await this.getApis();
-    const { dir, binFile, metaFile } = await this.binderAssetPaths(projectId, assetId);
+    const { dir, binFile, metaFile, safeAsset } = await this.binderAssetPaths(projectId, assetId);
     if (!(await apis.exists(dir))) await apis.mkdir(dir, { recursive: true });
     const metaOut: BinderAssetMeta = { ...meta, byteSize: data.byteLength };
-    await retryFs(() => apis.writeFile(binFile, new Uint8Array(data)));
-    await retryFs(() => apis.writeTextFile(metaFile, JSON.stringify(metaOut)));
+    const prior = await this.readBinderManifest(apis, metaFile, safeAsset);
+    const dataFileName = `${safeAsset}.${createBinderRevision()}.bin`;
+    const dataFile = await apis.join(dir, dataFileName);
+    await writeFileAtomic(apis, dataFile, new Uint8Array(data));
+    // QNBS-v3: publishing this manifest is the binder pair's commit point, so readers never combine new bytes with stale metadata.
+    try {
+      await writeTextFileAtomic(
+        apis,
+        metaFile,
+        JSON.stringify({ version: 1, dataFile: dataFileName, meta: metaOut }),
+      );
+    } catch (error) {
+      // QNBS-v3: the revision is unreachable until its manifest commits, so failed publication must not leak a new binary on every retry.
+      await retryFs(() => apis.remove(dataFile)).catch((cleanupError) => {
+        logger.warn('Failed to remove unpublished binder asset revision:', cleanupError);
+      });
+      throw error;
+    }
+    if (prior) {
+      const priorFile = await apis.join(dir, prior.dataFile);
+      if (priorFile !== dataFile && (await apis.exists(priorFile))) {
+        await retryFs(() => apis.remove(priorFile)).catch((error) => {
+          logger.warn('Failed to remove superseded binder asset revision:', error);
+        });
+      }
+    } else if (await apis.exists(binFile)) {
+      await retryFs(() => apis.remove(binFile)).catch((error) => {
+        logger.warn('Failed to remove superseded legacy binder asset:', error);
+      });
+    }
   }
 
   async getBinderAsset(projectId: string, assetId: string): Promise<BinderAssetPayload | null> {
     try {
       const apis = await this.getApis();
-      const { binFile, metaFile } = await this.binderAssetPaths(projectId, assetId);
-      if (!(await apis.exists(binFile)) || !(await apis.exists(metaFile))) return null;
-      const [bytes, metaRaw] = await Promise.all([
-        retryFs(() => apis.readFile(binFile)),
-        retryFs(() => apis.readTextFile(metaFile)),
-      ]);
-      const meta = JSON.parse(metaRaw) as BinderAssetMeta;
+      const { binFile, metaFile, dir, safeAsset } = await this.binderAssetPaths(projectId, assetId);
+      if (!(await apis.exists(metaFile))) return null;
+      const manifest = await this.readBinderManifest(apis, metaFile, safeAsset);
+      const dataFile = manifest ? await apis.join(dir, manifest.dataFile) : binFile;
+      if (!(await apis.exists(dataFile))) return null;
+      const bytes = await retryFs(() => apis.readFile(dataFile));
+      const meta = manifest
+        ? manifest.meta
+        : (JSON.parse(await retryFs(() => apis.readTextFile(metaFile))) as BinderAssetMeta);
       const copy = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
       return { data: copy, meta };
     } catch (error) {
@@ -113,8 +186,12 @@ export class FsAssetStore extends FsSnapshotStore {
   async deleteBinderAsset(projectId: string, assetId: string): Promise<void> {
     try {
       const apis = await this.getApis();
-      const { binFile, metaFile } = await this.binderAssetPaths(projectId, assetId);
-      if (await apis.exists(binFile)) await retryFs(() => apis.remove(binFile));
+      const { binFile, metaFile, dir, safeAsset } = await this.binderAssetPaths(projectId, assetId);
+      const manifest = await this.readBinderManifest(apis, metaFile, safeAsset);
+      const dataFile = manifest ? await apis.join(dir, manifest.dataFile) : binFile;
+      if (await apis.exists(dataFile)) await retryFs(() => apis.remove(dataFile));
+      if (dataFile !== binFile && (await apis.exists(binFile)))
+        await retryFs(() => apis.remove(binFile));
       if (await apis.exists(metaFile)) await retryFs(() => apis.remove(metaFile));
     } catch (error) {
       logger.warn('deleteBinderAsset failed:', error);

services/fs/codexFsStore.ts

@@ -6,7 +6,13 @@
 
 import type { StoryCodex } from '../../types';
 import { logger } from '../logger';
-import { compressData, decompressData, retryFs, sanitizePathSegment } from './fsCore';
+import {
+  compressData,
+  decompressData,
+  retryFs,
+  sanitizePathSegment,
+  writeTextFileAtomic,
+} from './fsCore';
 import { FsSettingsStore } from './settingsFsStore';
 
 export class FsCodexStore extends FsSettingsStore {
@@ -19,7 +25,8 @@ export class FsCodexStore extends FsSettingsStore {
     const codexDir = await apis.join(appDataPath, 'projects', safeId, 'codex');
     if (!(await apis.exists(codexDir))) await apis.mkdir(codexDir, { recursive: true });
     const codexFile = await apis.join(codexDir, 'codex.snap');
-    await retryFs(() => apis.writeTextFile(codexFile, compressData(codex)));
+    // QNBS-v3: atomic write — a crash/power-loss mid-write must never leave codex.snap truncated.
+    await writeTextFileAtomic(apis, codexFile, compressData(codex));
   }
 
   async getStoryCodex(projectId: string): Promise<StoryCodex | null> {
@@ -58,7 +65,8 @@ export class FsCodexStore extends FsSettingsStore {
     const codexDir = await apis.join(appDataPath, 'projects', safeId, 'codex');
     if (!(await apis.exists(codexDir))) await apis.mkdir(codexDir, { recursive: true });
     const vectorsFile = await apis.join(codexDir, 'vectors.snap');
-    await retryFs(() => apis.writeTextFile(vectorsFile, compressData(vectors)));
+    // QNBS-v3: atomic write — same crash-safety rationale as saveStoryCodex above.
+    await writeTextFileAtomic(apis, vectorsFile, compressData(vectors));
   }
 
   async getRagVectors(projectId: string): Promise<unknown[]> {