zen-fs-config 0.5.4 → 0.5.6

package/DESIGN.md

@@ -748,12 +748,11 @@ The sync engine (`zen-fs-sync`) uses **snapshot-based change detection**. When `
 
 1. Builds a snapshot of the source (IndexedDB) — walks all files, records `path`, `size`, `mtimeMs`
 2. Builds a snapshot of the target (remote backend) — same process
-3. **Merges** both snapshots into one map (`source ∪ target`)
-4. Caches this merged snapshot as `sourceSnapshots`
+3. Caches **separate** snapshots: `prevSrcSnap` (source) and `prevTgtSnap` (target)
 
-On the next `syncAll()`, `syncBidirectional()` compares the current merged snapshot with the cached one. If all paths, sizes, and mtimes match → **"unchanged" → skip sync entirely**.
+On the next `syncAll()`, `syncBidirectional()` compares each side's current snapshot with its own previous snapshot independently. If both sides are unchanged → **"unchanged" → skip sync entirely**.
 
-**The problem**: `buildInitialSnapshots()` only *reads* file metadata — it does NOT copy any files. So if the remote has files that the local doesn't (e.g., duplicate backend descriptors written by another node), the merged snapshot includes them from the remote side. The subsequent sync sees "the merged snapshot already has this file" and skips — the file is never actually copied to local, and local-only dedup logic never runs.
+**The problem**: `buildInitialSnapshots()` only *reads* file metadata — it does NOT copy any files. So if the remote has files that the local doesn't (e.g., duplicate backend descriptors written by another node), the cached snapshots reflect the un-synced state. The subsequent sync sees "snapshots already match this state" and skips — the file is never actually copied to local, and local-only dedup logic never runs.
 
 **The fix**: Always perform a full `syncAll()` **before** `watch()`. With no cached snapshot, `syncBidirectional()` does a complete comparison and copies all missing files. After sync completes, `watch()` builds snapshots from the now-consistent state.
 
@@ -885,8 +884,8 @@ watch() triggers:
   │     → triggers debounced sync (default 300ms)
   │
   ├─ 2. buildInitialSnapshots()
-  │     ├─ BiDirectional: merge source + target snapshots
-  │     └─ OneWay: snapshot source only
+  │     ├─ BiDirectional: cache separate source and target snapshots
+  │     └─ OneWay: cache source snapshot only
   │
   └─ 3. Start poll timers (if backend supports shouldSync)
        ├─ Remote backends poll shouldSync() every pollIntervalMs (default 30min)
@@ -896,12 +895,15 @@ watch() triggers:
 **State guard**: If `unwatch()` is called during `buildInitialSnapshots()` (which is async), the snapshots are discarded — they won't be cached. This prevents stale snapshots from causing sync skips.
 
 **Snapshot comparison** in `syncBidirectional()`:
-1. Build current snapshots of both sides
-2. Merge into `currentMerged = source ∪ target`
-3. Compare with cached `sourceSnapshots`:
-   - If all paths + mtimes + sizes match → "unchanged" → skip
-   - Otherwise → proceed with full diff and file operations
-4. Cache `currentMerged` for next comparison
+1. Build current snapshots of both sides (via `getSnapshot()`)
+2. Compare each side independently against its own previous snapshot:
+   - `srcChanged = !snapshotsEqual(prevSrcSnap, currentSrcSnap)`
+   - `tgtChanged = !snapshotsEqual(prevTgtSnap, currentTgtSnap)`
+   - If neither changed and both previous snapshots exist → skip sync entirely
+3. Cache current snapshots as `prevSrcSnap` and `prevTgtSnap` for next comparison
+4. If either side changed, proceed with full diff and file operations
+
+**Key difference from previous design**: The old approach merged source and target snapshots into a single map (`source ∪ target`), which lost information about which filesystem a file belonged to. The new approach keeps them separate, enabling precise per-side change detection and bidirectional deletion propagation (see §11.10).
 
 ### 11.8 Standalone Data-Sync Group (`createDataSyncGroup`)
 
@@ -995,6 +997,110 @@ interface ConnectResult {
 
 **Offline / zero-parameter mode**: When no `backendInfo` is provided, `connect` defaults to `config-sync` and creates an IndexedDB-only repo (same as `createConfigRepo` with no options).
 
+### 11.10 Snapshot Optimization Design
+
+This section describes three interrelated optimizations to the sync engine's snapshot mechanism.
+
+#### 11.10.1 FS-Provided `createSnapshot()`
+
+The `SyncableFS` interface now includes an optional `createSnapshot()` method:
+
+```typescript
+interface SyncableFS {
+  // ... existing methods ...
+
+  /**
+   * Optional: Build a filesystem snapshot.
+   * Returns a map of relative path → {size, mtimeMs} for all files under root.
+   * Returns null if the filesystem is unreachable.
+   *
+   * Backends that can provide a more efficient snapshot than the generic
+   * walkFiles+stat approach should implement this method.
+   */
+  createSnapshot?(root: string, filter?: SyncFilter): Promise<Map<string, FileSnapshot> | null>;
+}
+```
+
+The sync engine's `getSnapshot()` helper dispatches to the FS-provided method when available, falling back to the generic `buildSnapshot()` (walkFiles + stat) otherwise:
+
+```typescript
+private async getSnapshot(fs: SyncableFS): Promise<Map<string, FileSnapshot> | null> {
+  if (fs.createSnapshot) {
+    return fs.createSnapshot(this.root, this.options.filter);
+  }
+  return buildSnapshot(fs, this.root, this.options.filter);
+}
+```
+
+**Optimization examples**:
+- **Gitee/GitHub**: Use Git tree API to fetch all file metadata in a single request instead of walking files one by one
+- **IndexedDB**: Use `getAll()` for batch querying instead of individual `stat()` calls
+- **InMemory**: Directly iterate the internal Map (no async I/O overhead)
+
+Backends that do not implement `createSnapshot()` are fully supported — the generic fallback produces identical results.
+
+#### 11.10.2 Separate Source and Target Snapshots
+
+**Previous design** (merged snapshots):
+- `buildInitialSnapshots()` merged source and target into a single map: `sourceSnapshots = new Map([...srcSnap, ...tgtSnap])`
+- `syncBidirectional()` compared `currentMerged` with the cached merged snapshot
+- **Problem**: The merged map lost which filesystem a file belonged to. A file present on target but not source could be "new on target" or "deleted from source" — the merged snapshot couldn't distinguish.
+
+**New design** (separate snapshots):
+- `buildInitialSnapshots()` caches two independent maps: `prevSrcSnap` and `prevTgtSnap`
+- `syncBidirectional()` compares each side independently:
+  ```
+  srcChanged = !snapshotsEqual(prevSrcSnap, currentSrcSnap)
+  tgtChanged = !snapshotsEqual(prevTgtSnap, currentTgtSnap)
+  if (!srcChanged && !tgtChanged && prevSrcSnap && prevTgtSnap) → skip sync
+  ```
+- Each side's change is detected independently, preserving file-location information
+
+#### 11.10.3 Bidirectional Deletion Propagation
+
+When a file exists on one side but not the other, the sync engine uses previous snapshots to distinguish "created" from "deleted":
+
+```
+File on target, not on source:
+  ├─ Was it on source in the previous snapshot (prevSrcSnap)?
+  │   ├─ Yes → file was deleted from source → delete from target too (propagate deletion)
+  │   └─ No  → file was created on target → copy to source
+
+File on source, not on target:
+  ├─ Was it on target in the previous snapshot (prevTgtSnap)?
+  │   ├─ Yes → file was deleted from target → delete from source too (propagate deletion)
+  │   └─ No  → file was created on source → copy to target
+```
+
+**Without this mechanism**, deleting a file on one side would cause the sync engine to see "the other side still has it → copy it back", effectively undoing the deletion.
+
+**Relationship with tombstones**: The tombstone mechanism (§11.4) and bidirectional deletion propagation operate at different layers and complement each other:
+
+| Mechanism | Layer | Trigger | How It Works |
+|-----------|-------|---------|--------------|
+| Tombstone | `zen-fs-config` (application) | Application calls `deleteFile()` | Writes a `.meta/.deleted/` marker, physically deletes file on all replicas **before** sync runs |
+| Deletion propagation | `zen-fs-sync` (engine) | Sync detects one-side-only file | Compares with previous snapshot to determine if file was created or deleted |
+
+Tombstones handle application-initiated deletions (the common case). Deletion propagation handles deletions that bypass the tombstone flow — e.g., external modifications on the remote backend, or files removed by other sync mechanisms.
+
+#### 11.10.4 `shouldSync()` vs Snapshot Comparison
+
+These two mechanisms are complementary, not interchangeable:
+
+| Mechanism | Purpose | Cost | When Used |
+|-----------|---------|------|-----------|
+| `shouldSync()` | Fast "has anything changed?" boolean | O(1) for remote (ETag/commit check) | `onRemotePoll()` — decide whether to trigger sync at all |
+| Snapshot comparison | "What exactly changed?" detail | O(n) filesystem traversal | `syncBidirectional()` — decide what to copy/delete |
+
+`shouldSync()` is **not** part of the snapshot comparison because:
+1. `shouldSync()` updates its internal baseline after each call — calling it again during sync would return stale results
+2. `shouldSync()` returning false doesn't guarantee the snapshot is unchanged — it means the FS's own change detection says nothing changed, which could miss edge cases
+3. `shouldSync()` returning true doesn't tell us **which** files changed — snapshots are still needed for that
+
+The two-level optimization works as follows:
+1. **Level 1**: `shouldSync()` in remote poll → if false, skip sync trigger entirely (saves the O(n) snapshot build)
+2. **Level 2**: Separate snapshot comparison in sync → if both sides unchanged, skip file operations (saves I/O)
+
 ## 12. Data Flow
 
 ### Read Path
@@ -1041,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);
     },
@@ -274,6 +277,12 @@ function backendToSyncableFS(backend, name) {
   if (typeof backend.shouldSync === "function") {
     syncable.shouldSync = () => backend.shouldSync();
   }
+  if (typeof backend.createSnapshot === "function") {
+    syncable.createSnapshot = (root, filter) => backend.createSnapshot(root, filter);
+  }
+  if (typeof backend.writeFileWithMtime === "function") {
+    syncable.writeFileWithMtime = (path, data, mtimeMs) => backend.writeFileWithMtime(path, data, mtimeMs);
+  }
   if (typeof backend.checkForUpdates === "function") {
     syncable.checkForUpdates = () => backend.checkForUpdates();
   }
@@ -367,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();
@@ -404,6 +413,12 @@ async function wrapZenFSFileSystem(config) {
   backend.onChange = (callback) => {
     changeCallback = callback;
   };
+  if (typeof isolatedFS.createSnapshot === "function") {
+    backend.createSnapshot = (root, filter) => isolatedFS.createSnapshot(root, filter);
+  }
+  if (typeof isolatedFS.writeFileWithMtime === "function") {
+    backend.writeFileWithMtime = (path, data, mtimeMs) => isolatedFS.writeFileWithMtime(path, data, mtimeMs);
+  }
   return backend;
 }
 var inMemoryCounter = 0;
@@ -442,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;
 }
@@ -478,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,
@@ -489,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 {
@@ -760,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})`);
   }
@@ -796,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}`);
       }
@@ -920,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));
@@ -1021,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}`;
@@ -1065,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 {
     }
@@ -1150,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 {
@@ -1209,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);
@@ -1221,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();
@@ -1254,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);
@@ -1279,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) {
@@ -1289,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)
@@ -1391,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 {
@@ -1490,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;
@@ -1551,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() {
@@ -1752,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);
     },
@@ -217,6 +220,12 @@ function backendToSyncableFS(backend, name) {
   if (typeof backend.shouldSync === "function") {
     syncable.shouldSync = () => backend.shouldSync();
   }
+  if (typeof backend.createSnapshot === "function") {
+    syncable.createSnapshot = (root, filter) => backend.createSnapshot(root, filter);
+  }
+  if (typeof backend.writeFileWithMtime === "function") {
+    syncable.writeFileWithMtime = (path, data, mtimeMs) => backend.writeFileWithMtime(path, data, mtimeMs);
+  }
   if (typeof backend.checkForUpdates === "function") {
     syncable.checkForUpdates = () => backend.checkForUpdates();
   }
@@ -310,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();
@@ -347,6 +356,12 @@ async function wrapZenFSFileSystem(config) {
   backend.onChange = (callback) => {
     changeCallback = callback;
   };
+  if (typeof isolatedFS.createSnapshot === "function") {
+    backend.createSnapshot = (root, filter) => isolatedFS.createSnapshot(root, filter);
+  }
+  if (typeof isolatedFS.writeFileWithMtime === "function") {
+    backend.writeFileWithMtime = (path, data, mtimeMs) => isolatedFS.writeFileWithMtime(path, data, mtimeMs);
+  }
   return backend;
 }
 var inMemoryCounter = 0;
@@ -385,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;
 }
@@ -421,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,
@@ -432,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 {
@@ -703,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})`);
   }
@@ -739,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}`);
       }
@@ -863,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));
@@ -964,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}`;
@@ -1008,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 {
     }
@@ -1093,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 {
@@ -1152,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);
@@ -1164,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();
@@ -1197,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);
@@ -1222,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) {
@@ -1232,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)
@@ -1334,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 {
@@ -1433,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;
@@ -1494,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() {
@@ -1695,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.4",
+  "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",