zen-fs-config 0.5.5 → 0.5.7

package/DESIGN.md

@@ -1147,6 +1147,67 @@ Application
   → Dispose temporary SyncPair
 ```
 
+### Mtime Preservation During Sync
+
+**Problem**: When the sync engine copies a file from source to target, it calls `writeFile(path, data)`. The target backend sets its own mtime (typically `Date.now()`), losing the source file's original mtime. This causes the next sync cycle to detect a "modified" file (source mtime ≠ target mtime), triggering unnecessary copies on every sync.
+
+**Solution**: An optional `writeFileWithMtime` method on the `SyncableFS` interface, with automatic fallback to `writeFile` when not implemented:
+
+```typescript
+interface SyncableFS {
+  // ... existing methods ...
+
+  /**
+   * Optional: write file with precise mtime.
+   * If implemented, the sync engine uses this instead of writeFile,
+   * passing the source file's mtime so the target can preserve it.
+   * Backends that don't support precise mtime should not implement this —
+   * the sync engine falls back to plain writeFile.
+   */
+  writeFileWithMtime?(path: string, data: string | Uint8Array, mtime: number): Promise<void>;
+}
+```
+
+**Sync engine (`zen-fs-sync`)**: A central helper function handles the fallback:
+
+```javascript
+async function writeFileWithMtimeFallback(fs, path, data, mtimeMs) {
+  if (mtimeMs !== undefined && typeof fs.writeFileWithMtime === "function") {
+    await fs.writeFileWithMtime(path, data, mtimeMs);
+  } else {
+    await fs.writeFile(path, data);
+  }
+}
+```
+
+This helper is used in `copyFile()`, `syncOneWay()`, and `writeFileBoth()`. The source file's mtime is obtained via `stat()` before writing, then passed through to the target.
+
+**Adapters (`zen-fs-config`)**: All three `SyncableFS` adapters implement `writeFileWithMtime`:
+
+| Adapter | Implementation |
+|---|---|
+| `backendToSyncableFS` | Passes `{ mtime }` as options to `backend.writeFile()` — the backend's `writeFile` calls `touch()` with the provided mtime |
+| `zenfsPromisesToSyncableFS` | Calls `promises.writeFile()` then `promises.utimes()` as a fallback (some VFS backends don't support mtime in writeFile) |
+| `cachedFSToSyncableFS` | Passes `{ mtime }` as options to `cached.writeFile()` — mtime flows through to the underlying backend |
+
+**RemoteStorage backend (`zen-fs-remotestoragejs`)**: `writeFileWithMtime` delegates to `writeFile(path, data, { mtime })`, which writes the `.mtime` sidecar file to preserve millisecond-precision mtime (see RemoteStorage DESIGN.md §2 for details).
+
+**Data flow**:
+```
+Source file: /app-a/db.json (mtime=1700000000123)
+  │
+  ├─ sync engine: stat("/app-a/db.json") → mtimeMs=1700000000123
+  ├─ sync engine: readFile("/app-a/db.json") → data
+  ├─ sync engine: writeFileWithMtimeFallback(target, "/app-a/db.json", data, 1700000000123)
+  │   ├─ target has writeFileWithMtime? → YES → target.writeFileWithMtime(path, data, 1700000000123)
+  │   │                                      → backend.writeFile(path, data, { mtime: 1700000000123 })
+  │   │                                      → touch(path, { mtimeMs: 1700000000123 })
+  │   └─ target has writeFileWithMtime? → NO  → target.writeFile(path, data) [fallback]
+  │
+  └─ Target file: /app-a/db.json (mtime=1700000000123) ← preserved!
+     → Next sync: source.mtimeMs === target.mtimeMs → skip (no spurious copy)
+```
+
 ## 13. Peer Dependencies
 
 | Package | Role | Version | Required |

package/dist/index.d.mts

@@ -462,6 +462,8 @@ declare class ConfigRepo implements IConfigRepo {
     private configCache;
     private readonly primaryBackendId;
     private readonly pollIntervalMs?;
+    /** Tombstone cache — avoids redundant reads within a single flush() cycle. */
+    private tombstoneCache;
     constructor(appId: string, nodeId: string, primaryBackendId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>, pollIntervalMs?: number);
     /** Full path to this node's directory on the primary backend. */
     get nodePath(): string;
@@ -484,8 +486,11 @@ declare class ConfigRepo implements IConfigRepo {
     deleteFile(path: string): Promise<void>;
     /**
      * Read all tombstones from the primary backend.
+     * Results are cached within a flush() cycle to avoid redundant reads.
      */
     private readTombstones;
+    /** Invalidate the tombstone cache — call after tombstones are modified. */
+    private invalidateTombstoneCache;
     /**
      * Before sync: for each tombstone, delete the actual file on all replicas.
      * This prevents bi-directional sync from copying the file back.
@@ -522,6 +527,12 @@ declare class ConfigRepo implements IConfigRepo {
     readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     dispose(): Promise<void>;
     setupSync(backends: BackendDescriptor[], primaryBackendId: string, pollIntervalMs?: number): Promise<void>;
+    /** Write version sidecar for a config file (no-op for .version files). */
+    private writeVersionSidecar;
+    /** Delete version sidecar on a backend (no-op for .version files). */
+    private unlinkVersionSidecar;
+    /** Read version sidecar (returns null for .version files). */
+    private readVersionSidecar;
     private persistConfig;
     private reloadConfigCache;
     private handleConflict;
@@ -683,8 +694,11 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
  * /app-a/db.json        → /app-a/.db.json.version
  * /shared/flags.json    → /shared/.flags.json.version
  * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ *
+ * Returns null for files that are already version sidecars (.version files),
+ * to prevent creating version-of-version files (e.g. ..db.json.version.version).
  */
-declare function versionPathFor(configFilePath: string): string;
+declare function versionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.

package/dist/index.d.ts

@@ -462,6 +462,8 @@ declare class ConfigRepo implements IConfigRepo {
     private configCache;
     private readonly primaryBackendId;
     private readonly pollIntervalMs?;
+    /** Tombstone cache — avoids redundant reads within a single flush() cycle. */
+    private tombstoneCache;
     constructor(appId: string, nodeId: string, primaryBackendId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>, pollIntervalMs?: number);
     /** Full path to this node's directory on the primary backend. */
     get nodePath(): string;
@@ -484,8 +486,11 @@ declare class ConfigRepo implements IConfigRepo {
     deleteFile(path: string): Promise<void>;
     /**
      * Read all tombstones from the primary backend.
+     * Results are cached within a flush() cycle to avoid redundant reads.
      */
     private readTombstones;
+    /** Invalidate the tombstone cache — call after tombstones are modified. */
+    private invalidateTombstoneCache;
     /**
      * Before sync: for each tombstone, delete the actual file on all replicas.
      * This prevents bi-directional sync from copying the file back.
@@ -522,6 +527,12 @@ declare class ConfigRepo implements IConfigRepo {
     readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     dispose(): Promise<void>;
     setupSync(backends: BackendDescriptor[], primaryBackendId: string, pollIntervalMs?: number): Promise<void>;
+    /** Write version sidecar for a config file (no-op for .version files). */
+    private writeVersionSidecar;
+    /** Delete version sidecar on a backend (no-op for .version files). */
+    private unlinkVersionSidecar;
+    /** Read version sidecar (returns null for .version files). */
+    private readVersionSidecar;
     private persistConfig;
     private reloadConfigCache;
     private handleConflict;
@@ -683,8 +694,11 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
  * /app-a/db.json        → /app-a/.db.json.version
  * /shared/flags.json    → /shared/.flags.json.version
  * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ *
+ * Returns null for files that are already version sidecars (.version files),
+ * to prevent creating version-of-version files (e.g. ..db.json.version.version).
  */
-declare function versionPathFor(configFilePath: string): string;
+declare function versionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.

package/dist/index.js

@@ -250,6 +250,9 @@ function backendToSyncableFS(backend, name) {
     async writeFile(path, data) {
       return backend.writeFile(path, data);
     },
+    async writeFileWithMtime(path, data, mtime) {
+      return backend.writeFile(path, data, { mtime });
+    },
     async unlink(path) {
       return backend.unlink(path);
     },
@@ -373,7 +376,7 @@ async function wrapZenFSFileSystem(config) {
       }
       await isolatedFS.write(path, bytes, 0);
       try {
-        await isolatedFS.touch(path, { size: bytes.byteLength, mtimeMs: Date.now() });
+        await isolatedFS.touch(path, { size: bytes.byteLength, mtimeMs: _options?.mtime ?? Date.now() });
       } catch {
       }
       notifyChange();
@@ -454,6 +457,9 @@ function versionPathFor(configFilePath) {
   const lastSlash = configFilePath.lastIndexOf("/");
   const dir = lastSlash >= 0 ? configFilePath.slice(0, lastSlash) : "";
   const fileName = lastSlash >= 0 ? configFilePath.slice(lastSlash + 1) : configFilePath;
+  if (fileName.endsWith(".version")) {
+    return null;
+  }
   const versionFileName = `.${fileName}.version`;
   return dir ? `${dir}/${versionFileName}` : versionFileName;
 }
@@ -490,7 +496,7 @@ async function writeVersion(fs, versionFilePath, meta) {
 }
 async function incrementVersion(fs, configFilePath, newContent, author) {
   const vPath = versionPathFor(configFilePath);
-  const prev = await readVersion(fs, vPath);
+  const prev = vPath ? await readVersion(fs, vPath) : null;
   const hash = await sha256(newContent);
   return {
     version: (prev?.version ?? 0) + 1,
@@ -501,6 +507,7 @@ async function incrementVersion(fs, configFilePath, newContent, author) {
 }
 async function verifyOrRepairVersion(fs, configFilePath, author) {
   const vPath = versionPathFor(configFilePath);
+  if (!vPath) return null;
   const existing = await readVersion(fs, vPath);
   if (!existing) return null;
   try {
@@ -579,6 +586,8 @@ var ConfigRepo = class {
   configCache = /* @__PURE__ */ new Map();
   primaryBackendId;
   pollIntervalMs;
+  /** Tombstone cache — avoids redundant reads within a single flush() cycle. */
+  tombstoneCache = null;
   constructor(appId, nodeId, primaryBackendId, cachedFS, serializer, onConflict, pollIntervalMs) {
     this.appId = appId;
     this.nodeId = nodeId;
@@ -739,10 +748,12 @@ var ConfigRepo = class {
     this.assertNotDisposed();
     await this.processTombstones();
     const resultsMap = await this.syncEngine.syncAll();
+    this.invalidateTombstoneCache();
     await this.readAllBackendDescriptors();
     await this.processTombstones();
     await this.updateTombstoneConfirmations();
     await this.gcTombstones();
+    this.invalidateTombstoneCache();
     return Array.from(resultsMap.values());
   }
   // -----------------------------------------------------------------------
@@ -772,16 +783,23 @@ var ConfigRepo = class {
     } catch {
     }
     const versionPath = versionPathFor(normalizedPath);
-    try {
-      await this.cachedFS.unlink(versionPath);
-    } catch {
+    if (versionPath) {
+      try {
+        await this.cachedFS.unlink(versionPath);
+      } catch {
+      }
     }
     console.log(`[ConfigRepo] deleteFile: ${normalizedPath} (tombstone at ${tombstonePath})`);
+    this.invalidateTombstoneCache();
   }
   /**
    * Read all tombstones from the primary backend.
+   * Results are cached within a flush() cycle to avoid redundant reads.
    */
   async readTombstones() {
+    if (this.tombstoneCache !== null) {
+      return this.tombstoneCache;
+    }
     try {
       const entries = await this.cachedFS.readdir(DELETIONS_DIR);
       const tombstones = [];
@@ -794,11 +812,17 @@ var ConfigRepo = class {
         } catch {
         }
       }
+      this.tombstoneCache = tombstones;
       return tombstones;
     } catch {
+      this.tombstoneCache = [];
       return [];
     }
   }
+  /** Invalidate the tombstone cache — call after tombstones are modified. */
+  invalidateTombstoneCache() {
+    this.tombstoneCache = null;
+  }
   /**
    * Before sync: for each tombstone, delete the actual file on all replicas.
    * This prevents bi-directional sync from copying the file back.
@@ -808,22 +832,27 @@ var ConfigRepo = class {
     if (tombstones.length === 0) return;
     console.log(`[ConfigRepo] processTombstones: ${tombstones.length} tombstone(s)`);
     for (const tombstone of tombstones) {
+      const tVersionPath = versionPathFor(tombstone.path);
       try {
         await this.cachedFS.unlink(tombstone.path);
       } catch {
       }
-      try {
-        await this.cachedFS.unlink(versionPathFor(tombstone.path));
-      } catch {
+      if (tVersionPath) {
+        try {
+          await this.cachedFS.unlink(tVersionPath);
+        } catch {
+        }
       }
       for (const [replicaId, replica] of this.replicaBackends) {
         try {
           await replica.instance.unlink(tombstone.path);
         } catch {
         }
-        try {
-          await replica.instance.unlink(versionPathFor(tombstone.path));
-        } catch {
+        if (tVersionPath) {
+          try {
+            await replica.instance.unlink(tVersionPath);
+          } catch {
+          }
         }
         console.log(`[ConfigRepo] tombstone ${tombstone.path}: deleted on ${replicaId}`);
       }
@@ -869,6 +898,7 @@ var ConfigRepo = class {
       }
     }
     console.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
+    this.invalidateTombstoneCache();
   }
   /**
    * GC: remove tombstones where all backends in backends.json have confirmed.
@@ -932,7 +962,7 @@ var ConfigRepo = class {
         bytes,
         author
       );
-      await writeVersion(this.fullFS, versionPathFor(configPath), version);
+      await this.writeVersionSidecar(configPath, version);
       const conflictDir = metaPath.substring(0, metaPath.lastIndexOf("/"));
       const resolvedBackupPath = `${conflictDir}/resolved`;
       const resolvedBytes = typeof mergedContent === "string" ? new TextEncoder().encode(mergedContent) : new TextEncoder().encode(JSON.stringify(mergedContent, null, 2));
@@ -1033,13 +1063,34 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   // Internal — Persistence
   // -----------------------------------------------------------------------
+  /** Write version sidecar for a config file (no-op for .version files). */
+  async writeVersionSidecar(configPath, version) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return;
+    await this.ensureDir(vPath);
+    await writeVersion(this.fullFS, vPath, version);
+  }
+  /** Delete version sidecar on a backend (no-op for .version files). */
+  async unlinkVersionSidecar(fs, configPath) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return;
+    try {
+      await fs.unlink(vPath);
+    } catch {
+    }
+  }
+  /** Read version sidecar (returns null for .version files). */
+  async readVersionSidecar(configPath) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return null;
+    return readVersion(this.fullFS, vPath);
+  }
   async persistConfig(fullPath, bytes) {
     await this.ensureDir(fullPath);
     await this.cachedFS.writeFile(fullPath, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, fullPath, bytes, author);
-    await this.ensureDir(versionPathFor(fullPath));
-    await writeVersion(this.fullFS, versionPathFor(fullPath), version);
+    await this.writeVersionSidecar(fullPath, version);
   }
   async reloadConfigCache() {
     const appDir = `/${this.appId}`;
@@ -1077,7 +1128,7 @@ var ConfigRepo = class {
     );
     let sourceVersion = 0;
     try {
-      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
+      const srcVer = await this.readVersionSidecar(conflict.path);
       if (srcVer) sourceVersion = srcVer.version;
     } catch {
     }
@@ -1162,8 +1213,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(path, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, path, bytes, author);
-    await this.ensureDir(versionPathFor(path));
-    await writeVersion(this.fullFS, versionPathFor(path), version);
+    await this.writeVersionSidecar(path, version);
   }
   async readMetaFile(path) {
     try {
@@ -1221,10 +1271,7 @@ var ConfigRepo = class {
             await replica.instance.unlink(corruptPath);
           } catch {
           }
-          try {
-            await replica.instance.unlink(versionPathFor(corruptPath));
-          } catch {
-          }
+          await this.unlinkVersionSidecar(replica.instance, corruptPath);
         }
         try {
           await this.deleteFile(corruptPath);
@@ -1233,10 +1280,7 @@ var ConfigRepo = class {
             await this.cachedFS.unlink(corruptPath);
           } catch {
           }
-          try {
-            await this.cachedFS.unlink(versionPathFor(corruptPath));
-          } catch {
-          }
+          await this.unlinkVersionSidecar(this.cachedFS, corruptPath);
         }
       }
       const seen = /* @__PURE__ */ new Map();
@@ -1266,10 +1310,7 @@ var ConfigRepo = class {
               await replica.instance.unlink(descPath);
             } catch {
             }
-            try {
-              await replica.instance.unlink(versionPathFor(descPath));
-            } catch {
-            }
+            await this.unlinkVersionSidecar(replica.instance, descPath);
           }
           try {
             await this.deleteFile(descPath);
@@ -1291,8 +1332,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(path, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, path, bytes, author);
-    await this.ensureDir(versionPathFor(path));
-    await writeVersion(this.fullFS, versionPathFor(path), version);
+    await this.writeVersionSidecar(path, version);
   }
   /** Remove a single backend descriptor file + its version sidecar */
   async removeBackendDescriptor(id) {
@@ -1301,10 +1341,7 @@ var ConfigRepo = class {
       await this.cachedFS.unlink(path);
     } catch {
     }
-    try {
-      await this.cachedFS.unlink(versionPathFor(path));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(this.cachedFS, path);
   }
   // -----------------------------------------------------------------------
   // IConfigRepo — Meta file access (no chroot)
@@ -1403,10 +1440,7 @@ var ConfigRepo = class {
       await replica.instance.unlink(descPath);
     } catch {
     }
-    try {
-      await replica.instance.unlink(versionPathFor(descPath));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(replica.instance, descPath);
     try {
       await this.deleteFile(descPath);
     } catch {
@@ -1502,8 +1536,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(descPath, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, descPath, bytes, author);
-    await this.ensureDir(versionPathFor(descPath));
-    await writeVersion(this.fullFS, versionPathFor(descPath), version);
+    await this.writeVersionSidecar(descPath, version);
     this.appDataGroups.set(id, group);
     console.log(`[ConfigRepo] createAppDataGroup: "${id}" created`);
     return group;
@@ -1563,10 +1596,7 @@ var ConfigRepo = class {
       await this.cachedFS.unlink(descPath);
     } catch {
     }
-    try {
-      await this.cachedFS.unlink(versionPathFor(descPath));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(this.cachedFS, descPath);
     console.log(`[ConfigRepo] removeAppDataGroup: "${id}" removed`);
   }
   async listAccountBackends() {
@@ -1764,9 +1794,14 @@ async function createConfigRepo(appId, options = {}) {
       await cachedFS.unlink(BACKENDS_FILE);
     } catch {
     }
-    try {
-      await cachedFS.unlink(versionPathFor(BACKENDS_FILE));
-    } catch {
+    {
+      const vPath = versionPathFor(BACKENDS_FILE);
+      if (vPath) {
+        try {
+          await cachedFS.unlink(vPath);
+        } catch {
+        }
+      }
     }
     console.log(`[createConfigRepo] Migration complete`);
   }

package/dist/index.mjs

@@ -193,6 +193,9 @@ function backendToSyncableFS(backend, name) {
     async writeFile(path, data) {
       return backend.writeFile(path, data);
     },
+    async writeFileWithMtime(path, data, mtime) {
+      return backend.writeFile(path, data, { mtime });
+    },
     async unlink(path) {
       return backend.unlink(path);
     },
@@ -316,7 +319,7 @@ async function wrapZenFSFileSystem(config) {
       }
       await isolatedFS.write(path, bytes, 0);
       try {
-        await isolatedFS.touch(path, { size: bytes.byteLength, mtimeMs: Date.now() });
+        await isolatedFS.touch(path, { size: bytes.byteLength, mtimeMs: _options?.mtime ?? Date.now() });
       } catch {
       }
       notifyChange();
@@ -397,6 +400,9 @@ function versionPathFor(configFilePath) {
   const lastSlash = configFilePath.lastIndexOf("/");
   const dir = lastSlash >= 0 ? configFilePath.slice(0, lastSlash) : "";
   const fileName = lastSlash >= 0 ? configFilePath.slice(lastSlash + 1) : configFilePath;
+  if (fileName.endsWith(".version")) {
+    return null;
+  }
   const versionFileName = `.${fileName}.version`;
   return dir ? `${dir}/${versionFileName}` : versionFileName;
 }
@@ -433,7 +439,7 @@ async function writeVersion(fs, versionFilePath, meta) {
 }
 async function incrementVersion(fs, configFilePath, newContent, author) {
   const vPath = versionPathFor(configFilePath);
-  const prev = await readVersion(fs, vPath);
+  const prev = vPath ? await readVersion(fs, vPath) : null;
   const hash = await sha256(newContent);
   return {
     version: (prev?.version ?? 0) + 1,
@@ -444,6 +450,7 @@ async function incrementVersion(fs, configFilePath, newContent, author) {
 }
 async function verifyOrRepairVersion(fs, configFilePath, author) {
   const vPath = versionPathFor(configFilePath);
+  if (!vPath) return null;
   const existing = await readVersion(fs, vPath);
   if (!existing) return null;
   try {
@@ -522,6 +529,8 @@ var ConfigRepo = class {
   configCache = /* @__PURE__ */ new Map();
   primaryBackendId;
   pollIntervalMs;
+  /** Tombstone cache — avoids redundant reads within a single flush() cycle. */
+  tombstoneCache = null;
   constructor(appId, nodeId, primaryBackendId, cachedFS, serializer, onConflict, pollIntervalMs) {
     this.appId = appId;
     this.nodeId = nodeId;
@@ -682,10 +691,12 @@ var ConfigRepo = class {
     this.assertNotDisposed();
     await this.processTombstones();
     const resultsMap = await this.syncEngine.syncAll();
+    this.invalidateTombstoneCache();
     await this.readAllBackendDescriptors();
     await this.processTombstones();
     await this.updateTombstoneConfirmations();
     await this.gcTombstones();
+    this.invalidateTombstoneCache();
     return Array.from(resultsMap.values());
   }
   // -----------------------------------------------------------------------
@@ -715,16 +726,23 @@ var ConfigRepo = class {
     } catch {
     }
     const versionPath = versionPathFor(normalizedPath);
-    try {
-      await this.cachedFS.unlink(versionPath);
-    } catch {
+    if (versionPath) {
+      try {
+        await this.cachedFS.unlink(versionPath);
+      } catch {
+      }
     }
     console.log(`[ConfigRepo] deleteFile: ${normalizedPath} (tombstone at ${tombstonePath})`);
+    this.invalidateTombstoneCache();
   }
   /**
    * Read all tombstones from the primary backend.
+   * Results are cached within a flush() cycle to avoid redundant reads.
    */
   async readTombstones() {
+    if (this.tombstoneCache !== null) {
+      return this.tombstoneCache;
+    }
     try {
       const entries = await this.cachedFS.readdir(DELETIONS_DIR);
       const tombstones = [];
@@ -737,11 +755,17 @@ var ConfigRepo = class {
         } catch {
         }
       }
+      this.tombstoneCache = tombstones;
       return tombstones;
     } catch {
+      this.tombstoneCache = [];
       return [];
     }
   }
+  /** Invalidate the tombstone cache — call after tombstones are modified. */
+  invalidateTombstoneCache() {
+    this.tombstoneCache = null;
+  }
   /**
    * Before sync: for each tombstone, delete the actual file on all replicas.
    * This prevents bi-directional sync from copying the file back.
@@ -751,22 +775,27 @@ var ConfigRepo = class {
     if (tombstones.length === 0) return;
     console.log(`[ConfigRepo] processTombstones: ${tombstones.length} tombstone(s)`);
     for (const tombstone of tombstones) {
+      const tVersionPath = versionPathFor(tombstone.path);
       try {
         await this.cachedFS.unlink(tombstone.path);
       } catch {
       }
-      try {
-        await this.cachedFS.unlink(versionPathFor(tombstone.path));
-      } catch {
+      if (tVersionPath) {
+        try {
+          await this.cachedFS.unlink(tVersionPath);
+        } catch {
+        }
       }
       for (const [replicaId, replica] of this.replicaBackends) {
         try {
           await replica.instance.unlink(tombstone.path);
         } catch {
         }
-        try {
-          await replica.instance.unlink(versionPathFor(tombstone.path));
-        } catch {
+        if (tVersionPath) {
+          try {
+            await replica.instance.unlink(tVersionPath);
+          } catch {
+          }
         }
         console.log(`[ConfigRepo] tombstone ${tombstone.path}: deleted on ${replicaId}`);
       }
@@ -812,6 +841,7 @@ var ConfigRepo = class {
       }
     }
     console.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
+    this.invalidateTombstoneCache();
   }
   /**
    * GC: remove tombstones where all backends in backends.json have confirmed.
@@ -875,7 +905,7 @@ var ConfigRepo = class {
         bytes,
         author
       );
-      await writeVersion(this.fullFS, versionPathFor(configPath), version);
+      await this.writeVersionSidecar(configPath, version);
       const conflictDir = metaPath.substring(0, metaPath.lastIndexOf("/"));
       const resolvedBackupPath = `${conflictDir}/resolved`;
       const resolvedBytes = typeof mergedContent === "string" ? new TextEncoder().encode(mergedContent) : new TextEncoder().encode(JSON.stringify(mergedContent, null, 2));
@@ -976,13 +1006,34 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   // Internal — Persistence
   // -----------------------------------------------------------------------
+  /** Write version sidecar for a config file (no-op for .version files). */
+  async writeVersionSidecar(configPath, version) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return;
+    await this.ensureDir(vPath);
+    await writeVersion(this.fullFS, vPath, version);
+  }
+  /** Delete version sidecar on a backend (no-op for .version files). */
+  async unlinkVersionSidecar(fs, configPath) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return;
+    try {
+      await fs.unlink(vPath);
+    } catch {
+    }
+  }
+  /** Read version sidecar (returns null for .version files). */
+  async readVersionSidecar(configPath) {
+    const vPath = versionPathFor(configPath);
+    if (!vPath) return null;
+    return readVersion(this.fullFS, vPath);
+  }
   async persistConfig(fullPath, bytes) {
     await this.ensureDir(fullPath);
     await this.cachedFS.writeFile(fullPath, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, fullPath, bytes, author);
-    await this.ensureDir(versionPathFor(fullPath));
-    await writeVersion(this.fullFS, versionPathFor(fullPath), version);
+    await this.writeVersionSidecar(fullPath, version);
   }
   async reloadConfigCache() {
     const appDir = `/${this.appId}`;
@@ -1020,7 +1071,7 @@ var ConfigRepo = class {
     );
     let sourceVersion = 0;
     try {
-      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
+      const srcVer = await this.readVersionSidecar(conflict.path);
       if (srcVer) sourceVersion = srcVer.version;
     } catch {
     }
@@ -1105,8 +1156,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(path, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, path, bytes, author);
-    await this.ensureDir(versionPathFor(path));
-    await writeVersion(this.fullFS, versionPathFor(path), version);
+    await this.writeVersionSidecar(path, version);
   }
   async readMetaFile(path) {
     try {
@@ -1164,10 +1214,7 @@ var ConfigRepo = class {
             await replica.instance.unlink(corruptPath);
           } catch {
           }
-          try {
-            await replica.instance.unlink(versionPathFor(corruptPath));
-          } catch {
-          }
+          await this.unlinkVersionSidecar(replica.instance, corruptPath);
         }
         try {
           await this.deleteFile(corruptPath);
@@ -1176,10 +1223,7 @@ var ConfigRepo = class {
             await this.cachedFS.unlink(corruptPath);
           } catch {
           }
-          try {
-            await this.cachedFS.unlink(versionPathFor(corruptPath));
-          } catch {
-          }
+          await this.unlinkVersionSidecar(this.cachedFS, corruptPath);
         }
       }
       const seen = /* @__PURE__ */ new Map();
@@ -1209,10 +1253,7 @@ var ConfigRepo = class {
               await replica.instance.unlink(descPath);
             } catch {
             }
-            try {
-              await replica.instance.unlink(versionPathFor(descPath));
-            } catch {
-            }
+            await this.unlinkVersionSidecar(replica.instance, descPath);
           }
           try {
             await this.deleteFile(descPath);
@@ -1234,8 +1275,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(path, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, path, bytes, author);
-    await this.ensureDir(versionPathFor(path));
-    await writeVersion(this.fullFS, versionPathFor(path), version);
+    await this.writeVersionSidecar(path, version);
   }
   /** Remove a single backend descriptor file + its version sidecar */
   async removeBackendDescriptor(id) {
@@ -1244,10 +1284,7 @@ var ConfigRepo = class {
       await this.cachedFS.unlink(path);
     } catch {
     }
-    try {
-      await this.cachedFS.unlink(versionPathFor(path));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(this.cachedFS, path);
   }
   // -----------------------------------------------------------------------
   // IConfigRepo — Meta file access (no chroot)
@@ -1346,10 +1383,7 @@ var ConfigRepo = class {
       await replica.instance.unlink(descPath);
     } catch {
     }
-    try {
-      await replica.instance.unlink(versionPathFor(descPath));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(replica.instance, descPath);
     try {
       await this.deleteFile(descPath);
     } catch {
@@ -1445,8 +1479,7 @@ var ConfigRepo = class {
     await this.cachedFS.writeFile(descPath, bytes);
     const author = `${this.appId}/${this.nodeId}`;
     const version = await incrementVersion(this.fullFS, descPath, bytes, author);
-    await this.ensureDir(versionPathFor(descPath));
-    await writeVersion(this.fullFS, versionPathFor(descPath), version);
+    await this.writeVersionSidecar(descPath, version);
     this.appDataGroups.set(id, group);
     console.log(`[ConfigRepo] createAppDataGroup: "${id}" created`);
     return group;
@@ -1506,10 +1539,7 @@ var ConfigRepo = class {
       await this.cachedFS.unlink(descPath);
     } catch {
     }
-    try {
-      await this.cachedFS.unlink(versionPathFor(descPath));
-    } catch {
-    }
+    await this.unlinkVersionSidecar(this.cachedFS, descPath);
     console.log(`[ConfigRepo] removeAppDataGroup: "${id}" removed`);
   }
   async listAccountBackends() {
@@ -1707,9 +1737,14 @@ async function createConfigRepo(appId, options = {}) {
       await cachedFS.unlink(BACKENDS_FILE);
     } catch {
     }
-    try {
-      await cachedFS.unlink(versionPathFor(BACKENDS_FILE));
-    } catch {
+    {
+      const vPath = versionPathFor(BACKENDS_FILE);
+      if (vPath) {
+        try {
+          await cachedFS.unlink(vPath);
+        } catch {
+        }
+      }
     }
     console.log(`[createConfigRepo] Migration complete`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-fs-config",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",