zen-fs-config 0.5.5 → 0.5.6

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

@@ -522,6 +522,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 +689,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

@@ -522,6 +522,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 +689,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 {
@@ -772,9 +779,11 @@ 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})`);
   }
@@ -808,22 +817,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}`);
       }
@@ -932,7 +946,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 +1047,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 +1112,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 +1197,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 +1255,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 +1264,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 +1294,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 +1316,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 +1325,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 +1424,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 +1520,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 +1580,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 +1778,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 {
@@ -715,9 +722,11 @@ 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})`);
   }
@@ -751,22 +760,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}`);
       }
@@ -875,7 +889,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 +990,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 +1055,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 +1140,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 +1198,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 +1207,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 +1237,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 +1259,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 +1268,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 +1367,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 +1463,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 +1523,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 +1721,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.6",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",