zen-fs-config 0.5.28 → 0.5.30

package/DESIGN.md

@@ -1187,6 +1187,22 @@ Source file: /app-a/db.json (mtime=1700000000123)
      → Next sync: source.mtimeMs === target.mtimeMs → skip (no spurious copy)
 ```
 
+### Backend mtime implementation status
+
+The `writeFileWithMtime` mechanism (above) only preserves mtime if the target
+backend actually persists it. Implementation status per backend:
+
+| Backend | Protocol can set mtime? | Strategy | `write` path writes sidecar? | Status |
+|---|---|---|---|---|
+| RemoteStorage (`zen-fs-remotestoragejs`) | No — server `Last-Modified` is the PUT arrival time, client cannot control it | `.mtime` sidecar | **Yes** — `writeFile` writes the sidecar when `preciseMtime` is enabled (default on) | Working |
+| Gitee (`zen-fs-gitee`) | No — Git has no per-file mtime | `.mtime` sidecar | **Yes** — `write()` / `writeSync()` and `writeFile` / `writeFileSync` persist it; `createSnapshot()` reads it (write fix since 1.2.17, snapshot fix since 1.2.18) | **Fixed in 1.2.18** |
+
+Consequence of the Gitee gap: files pushed through the normal write path have
+no `.mtime` sidecar, so `stat()` falls back to the commit time. That commit
+time never equals the source's real mtime, so the sync engine re-PUTs
+content-identical files every cycle (empty / "no-diff" commits on Gitee). Fix
+tracked in `zen-fs-gitee/DESIGN.md` §5.
+
 ## 13. Peer Dependencies
 
 | Package | Role | Version | Required |

package/dist/index.d.mts

@@ -170,6 +170,12 @@ interface AppDataBackendDescriptor {
     /** Optional: reuse account fields from a config-sync backend. */
     accountBackendId?: string;
     description?: string;
+    /**
+     * Optional creation timestamp (ms). Used when deduplicating backends that
+     * point to the same endpoint — the OLDEST one is kept. Backends without
+     * this field are treated as legacy/oldest (e.g. a fixed `*-primary` id).
+     */
+    createdAt?: number;
 }
 /** Descriptor for a data-sync group referenced by a config-sync group. */
 interface AppDataGroupDescriptor {

package/dist/index.d.ts

@@ -170,6 +170,12 @@ interface AppDataBackendDescriptor {
     /** Optional: reuse account fields from a config-sync backend. */
     accountBackendId?: string;
     description?: string;
+    /**
+     * Optional creation timestamp (ms). Used when deduplicating backends that
+     * point to the same endpoint — the OLDEST one is kept. Backends without
+     * this field are treated as legacy/oldest (e.g. a fixed `*-primary` id).
+     */
+    createdAt?: number;
 }
 /** Descriptor for a data-sync group referenced by a config-sync group. */
 interface AppDataGroupDescriptor {

package/dist/index.js

@@ -1041,6 +1041,31 @@ function sortKeysDeep(obj) {
 function backendDedupKey(desc) {
   return `${desc.type}:${stableOptionsKey(desc.options)}`;
 }
+function backendAgeRank(b) {
+  if (typeof b.createdAt === "number") return b.createdAt;
+  const m = /-(\d{10,})$/.exec(b.id);
+  if (m) return Number(m[1]);
+  return -Infinity;
+}
+function dedupeAppDataBackends(backends) {
+  const byKey = /* @__PURE__ */ new Map();
+  const removed = [];
+  for (const b of backends) {
+    const key = backendDedupKey({ id: b.id, type: b.type, options: b.options });
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, b);
+      continue;
+    }
+    if (backendAgeRank(b) < backendAgeRank(existing)) {
+      removed.push(existing);
+      byKey.set(key, b);
+    } else {
+      removed.push(b);
+    }
+  }
+  return { kept: Array.from(byKey.values()), removed };
+}
 var ConfigRepo = class {
   appId;
   nodeId;
@@ -1471,25 +1496,29 @@ var ConfigRepo = class {
   async updateTombstoneConfirmations() {
     const tombstones = await this.readTombstones();
     if (tombstones.length === 0) return;
-    const backendsMeta = await this.getBackends();
-    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    let modified = 0;
     for (const tombstone of tombstones) {
       const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+      let changed = false;
       for (const replicaId of this.replicaBackends.keys()) {
         if (!tombstone.confirmedBy.includes(replicaId)) {
           tombstone.confirmedBy.push(replicaId);
+          changed = true;
         }
       }
-      try {
-        await this.cachedFS.writeFile(
-          tombstonePath,
-          new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
-        );
-      } catch {
+      if (changed) {
+        try {
+          await this.cachedFS.writeFile(
+            tombstonePath,
+            new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+          );
+          modified++;
+        } catch {
+        }
       }
     }
-    log2.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
-    this.invalidateTombstoneCache();
+    log2.log(`[ConfigRepo] updateTombstoneConfirmations: ${modified} tombstone(s) updated`);
+    if (modified > 0) this.invalidateTombstoneCache();
   }
   /**
    * GC: remove tombstones where all backends in backends.json have confirmed.
@@ -1502,8 +1531,7 @@ var ConfigRepo = class {
   async gcTombstones() {
     const tombstones = await this.readTombstones();
     if (tombstones.length === 0) return;
-    const backendsMeta = await this.getBackends();
-    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    const allBackendIds = [...this.replicaBackends.keys()];
     for (const tombstone of tombstones) {
       const allConfirmed = allBackendIds.every((id) => tombstone.confirmedBy.includes(id));
       if (allConfirmed) {
@@ -2359,6 +2387,13 @@ var AppDataGroupImpl = class {
     }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
+    const { kept, removed } = dedupeAppDataBackends(this._backends);
+    if (removed.length > 0) {
+      log2.warn(
+        `[AppDataGroup:${this.groupId}] dedupe: removing ${removed.length} duplicate backend(s) (${removed.map((b) => b.id).join(", ")}) \u2014 keeping ${kept.map((b) => b.id).join(", ")}`
+      );
+      this._backends = kept;
+    }
     for (const desc of this._backends) {
       try {
         const instance = await createBackend({ type: desc.type, options: desc.options });
@@ -2385,6 +2420,13 @@ var AppDataGroupImpl = class {
       log2.warn(`[AppDataGroup:${this.groupId}] Initial sync failed:`, err);
     }
     this.syncEngine.watchAll();
+    if (removed.length > 0) {
+      try {
+        await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+      } catch (err) {
+        log2.warn(`[AppDataGroup:${this.groupId}] dedupe: failed to persist deduplicated backends:`, err);
+      }
+    }
   }
   getSyncStatuses() {
     return this.syncEngine.getStatusAll();
@@ -2412,7 +2454,7 @@ var AppDataGroupImpl = class {
       },
       "/"
     );
-    const desc = { id, type, options, description };
+    const desc = { id, type, options, description, createdAt: Date.now() };
     this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
     log2.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
     try {

package/dist/index.mjs

@@ -643,6 +643,31 @@ function sortKeysDeep(obj) {
 function backendDedupKey(desc) {
   return `${desc.type}:${stableOptionsKey(desc.options)}`;
 }
+function backendAgeRank(b) {
+  if (typeof b.createdAt === "number") return b.createdAt;
+  const m = /-(\d{10,})$/.exec(b.id);
+  if (m) return Number(m[1]);
+  return -Infinity;
+}
+function dedupeAppDataBackends(backends) {
+  const byKey = /* @__PURE__ */ new Map();
+  const removed = [];
+  for (const b of backends) {
+    const key = backendDedupKey({ id: b.id, type: b.type, options: b.options });
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, b);
+      continue;
+    }
+    if (backendAgeRank(b) < backendAgeRank(existing)) {
+      removed.push(existing);
+      byKey.set(key, b);
+    } else {
+      removed.push(b);
+    }
+  }
+  return { kept: Array.from(byKey.values()), removed };
+}
 var ConfigRepo = class {
   appId;
   nodeId;
@@ -1073,25 +1098,29 @@ var ConfigRepo = class {
   async updateTombstoneConfirmations() {
     const tombstones = await this.readTombstones();
     if (tombstones.length === 0) return;
-    const backendsMeta = await this.getBackends();
-    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    let modified = 0;
     for (const tombstone of tombstones) {
       const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+      let changed = false;
       for (const replicaId of this.replicaBackends.keys()) {
         if (!tombstone.confirmedBy.includes(replicaId)) {
           tombstone.confirmedBy.push(replicaId);
+          changed = true;
         }
       }
-      try {
-        await this.cachedFS.writeFile(
-          tombstonePath,
-          new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
-        );
-      } catch {
+      if (changed) {
+        try {
+          await this.cachedFS.writeFile(
+            tombstonePath,
+            new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+          );
+          modified++;
+        } catch {
+        }
       }
     }
-    log2.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
-    this.invalidateTombstoneCache();
+    log2.log(`[ConfigRepo] updateTombstoneConfirmations: ${modified} tombstone(s) updated`);
+    if (modified > 0) this.invalidateTombstoneCache();
   }
   /**
    * GC: remove tombstones where all backends in backends.json have confirmed.
@@ -1104,8 +1133,7 @@ var ConfigRepo = class {
   async gcTombstones() {
     const tombstones = await this.readTombstones();
     if (tombstones.length === 0) return;
-    const backendsMeta = await this.getBackends();
-    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    const allBackendIds = [...this.replicaBackends.keys()];
     for (const tombstone of tombstones) {
       const allConfirmed = allBackendIds.every((id) => tombstone.confirmedBy.includes(id));
       if (allConfirmed) {
@@ -1961,6 +1989,13 @@ var AppDataGroupImpl = class {
     }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
+    const { kept, removed } = dedupeAppDataBackends(this._backends);
+    if (removed.length > 0) {
+      log2.warn(
+        `[AppDataGroup:${this.groupId}] dedupe: removing ${removed.length} duplicate backend(s) (${removed.map((b) => b.id).join(", ")}) \u2014 keeping ${kept.map((b) => b.id).join(", ")}`
+      );
+      this._backends = kept;
+    }
     for (const desc of this._backends) {
       try {
         const instance = await createBackend({ type: desc.type, options: desc.options });
@@ -1987,6 +2022,13 @@ var AppDataGroupImpl = class {
       log2.warn(`[AppDataGroup:${this.groupId}] Initial sync failed:`, err);
     }
     this.syncEngine.watchAll();
+    if (removed.length > 0) {
+      try {
+        await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+      } catch (err) {
+        log2.warn(`[AppDataGroup:${this.groupId}] dedupe: failed to persist deduplicated backends:`, err);
+      }
+    }
   }
   getSyncStatuses() {
     return this.syncEngine.getStatusAll();
@@ -2014,7 +2056,7 @@ var AppDataGroupImpl = class {
       },
       "/"
     );
-    const desc = { id, type, options, description };
+    const desc = { id, type, options, description, createdAt: Date.now() };
     this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
     log2.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
     try {

package/dist/zen-fs-config.js

@@ -26918,6 +26918,31 @@ var ZenFSConfig = (() => {
   function backendDedupKey(desc) {
     return `${desc.type}:${stableOptionsKey(desc.options)}`;
   }
+  function backendAgeRank(b) {
+    if (typeof b.createdAt === "number") return b.createdAt;
+    const m = /-(\d{10,})$/.exec(b.id);
+    if (m) return Number(m[1]);
+    return -Infinity;
+  }
+  function dedupeAppDataBackends(backends) {
+    const byKey = /* @__PURE__ */ new Map();
+    const removed = [];
+    for (const b of backends) {
+      const key = backendDedupKey({ id: b.id, type: b.type, options: b.options });
+      const existing = byKey.get(key);
+      if (!existing) {
+        byKey.set(key, b);
+        continue;
+      }
+      if (backendAgeRank(b) < backendAgeRank(existing)) {
+        removed.push(existing);
+        byKey.set(key, b);
+      } else {
+        removed.push(b);
+      }
+    }
+    return { kept: Array.from(byKey.values()), removed };
+  }
   var ConfigRepo = class {
     constructor(appId, nodeId, primaryBackendId, cachedFS, serializer, onConflict, pollIntervalMs, cacheOptions) {
       __publicField(this, "appId");
@@ -27348,25 +27373,29 @@ var ZenFSConfig = (() => {
     async updateTombstoneConfirmations() {
       const tombstones = await this.readTombstones();
       if (tombstones.length === 0) return;
-      const backendsMeta = await this.getBackends();
-      const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+      let modified = 0;
       for (const tombstone of tombstones) {
         const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+        let changed = false;
         for (const replicaId of this.replicaBackends.keys()) {
           if (!tombstone.confirmedBy.includes(replicaId)) {
             tombstone.confirmedBy.push(replicaId);
+            changed = true;
           }
         }
-        try {
-          await this.cachedFS.writeFile(
-            tombstonePath,
-            new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
-          );
-        } catch {
+        if (changed) {
+          try {
+            await this.cachedFS.writeFile(
+              tombstonePath,
+              new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+            );
+            modified++;
+          } catch {
+          }
         }
       }
-      log6.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
-      this.invalidateTombstoneCache();
+      log6.log(`[ConfigRepo] updateTombstoneConfirmations: ${modified} tombstone(s) updated`);
+      if (modified > 0) this.invalidateTombstoneCache();
     }
     /**
      * GC: remove tombstones where all backends in backends.json have confirmed.
@@ -27379,8 +27408,7 @@ var ZenFSConfig = (() => {
     async gcTombstones() {
       const tombstones = await this.readTombstones();
       if (tombstones.length === 0) return;
-      const backendsMeta = await this.getBackends();
-      const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+      const allBackendIds = [...this.replicaBackends.keys()];
       for (const tombstone of tombstones) {
         const allConfirmed = allBackendIds.every((id) => tombstone.confirmedBy.includes(id));
         if (allConfirmed) {
@@ -28236,6 +28264,13 @@ var ZenFSConfig = (() => {
       }
       const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
       this.fs = createChrootFS(this.localFS, "/");
+      const { kept, removed } = dedupeAppDataBackends(this._backends);
+      if (removed.length > 0) {
+        log6.warn(
+          `[AppDataGroup:${this.groupId}] dedupe: removing ${removed.length} duplicate backend(s) (${removed.map((b) => b.id).join(", ")}) \u2014 keeping ${kept.map((b) => b.id).join(", ")}`
+        );
+        this._backends = kept;
+      }
       for (const desc of this._backends) {
         try {
           const instance = await createBackend({ type: desc.type, options: desc.options });
@@ -28262,6 +28297,13 @@ var ZenFSConfig = (() => {
         log6.warn(`[AppDataGroup:${this.groupId}] Initial sync failed:`, err2);
       }
       this.syncEngine.watchAll();
+      if (removed.length > 0) {
+        try {
+          await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+        } catch (err2) {
+          log6.warn(`[AppDataGroup:${this.groupId}] dedupe: failed to persist deduplicated backends:`, err2);
+        }
+      }
     }
     getSyncStatuses() {
       return this.syncEngine.getStatusAll();
@@ -28289,7 +28331,7 @@ var ZenFSConfig = (() => {
         },
         "/"
       );
-      const desc = { id, type, options, description };
+      const desc = { id, type, options, description, createdAt: Date.now() };
       this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
       log6.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
       try {

package/package.json

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