zen-fs-config 0.3.21 → 0.3.23

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
+import { SyncResult, SyncPairStatus, ConflictStrategy, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
 import * as node_fs from 'node:fs';
 
@@ -18,24 +18,6 @@ interface BackendsMeta {
     version: 1;
     backends: BackendDescriptor[];
 }
-/** Sync direction for a path prefix. */
-type SyncDirection = 'one-way' | 'bi-directional' | 'none';
-/** A single sync rule. */
-interface SyncRule {
-    /** Path prefix this rule applies to (e.g., "/app-a/"). */
-    prefix: string;
-    /** Sync direction. */
-    direction: SyncDirection;
-    /** Conflict resolution strategy (only relevant for bi-directional). */
-    conflictStrategy?: ConflictStrategy;
-    /** IDs of replica backends to sync with (from .meta/backends.json). */
-    replicas?: string[];
-}
-/** Content of `.meta/sync-rules.json`. */
-interface SyncRulesMeta {
-    version: 1;
-    rules: SyncRule[];
-}
 /** Content of a sidecar `.version` file. */
 interface VersionMeta {
     /** Monotonically increasing version number. */
@@ -57,18 +39,18 @@ interface ConflictArchive {
     sourceAuthor: string;
     /** Author of the target side. */
     targetAuthor: string;
-    /** Source side content. */
-    sourceContent: unknown;
-    /** Target side content. */
-    targetContent: unknown;
     /** Source side version. */
     sourceVersion: number;
     /** Target side version. */
     targetVersion: number;
     /** Strategy that was used to auto-resolve (if any). */
     resolvedStrategy?: ConflictStrategy;
-    /** The content that was written as the resolved result (if auto-resolved). */
-    resolvedContent?: unknown;
+    /** Path to the source-side backup file. */
+    sourceBackupPath: string;
+    /** Path to the target-side backup file. */
+    targetBackupPath: string;
+    /** Path to the resolved file (present after resolution). */
+    resolvedBackupPath?: string;
 }
 /** Information passed to conflict event handlers. */
 interface ConflictInfo {
@@ -103,11 +85,6 @@ interface CacheOptions {
     /** TTL in milliseconds for cache hits without revalidation. Default: 0 (always revalidate). */
     ttlMs?: number;
 }
-/** Bootstrap data, written to .meta/ only on first initialization. */
-interface BootstrapData {
-    backends: Omit<BackendDescriptor, 'description'>[];
-    syncRules: SyncRule[];
-}
 /** Options for creating a ConfigRepo. */
 interface ConfigRepoOptions {
     /** The backend ID (from .meta/backends.json) to use as this instance's primary. */
@@ -121,8 +98,6 @@ interface ConfigRepoOptions {
     nodeId?: string;
     /** Cache configuration. */
     cache?: CacheOptions;
-    /** Bootstrap data (only used when .meta/backends.json doesn't exist). */
-    bootstrap?: BootstrapData;
     /** Custom serializer. */
     serializer?: ConfigSerializer;
     /** Custom conflict handler. Called before auto-resolution. */
@@ -162,16 +137,17 @@ interface IConfigRepo {
     resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
     /** List all conflict archives. */
     listConflicts(): Promise<ConflictArchive[]>;
+    /** Read the raw content of a conflict backup file (source/target/resolved).
+     *  @param conflictId The meta.json path (e.g., "12345_path.conflict/meta.json")
+     *  @param fileType One of "source", "target", or "resolved"
+     */
+    readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     /** Read .meta/backends.json. */
     getBackends(): Promise<BackendsMeta | null>;
     /** Write .meta/backends.json. */
     updateBackends(meta: BackendsMeta): Promise<void>;
-    /** Read .meta/sync-rules.json. */
-    getSyncRules(): Promise<SyncRulesMeta | null>;
-    /** Write .meta/sync-rules.json. */
-    updateSyncRules(meta: SyncRulesMeta): Promise<void>;
     /**
-     * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+     * Sync .meta/ files (backends.json) to all replica backends.
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
@@ -260,18 +236,21 @@ declare class ConfigRepo implements IConfigRepo {
     peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     flush(): Promise<SyncResult[]>;
     /**
-     * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+     * Sync .meta/ files (backends.json) to all replica backends.
      *
      * This ensures the backend topology is available on every replica, enabling
      * any program that connects to any backend to discover the full topology.
      *
      * Called automatically by createConfigRepo() after setupSync().
-     * Can also be called manually after updateBackends() / updateSyncRules().
      */
     syncMetaToReplicas(): Promise<void>;
+    /** Compare two file contents (handles Uint8Array, ArrayBuffer, string, Buffer). */
+    private bufferEqual;
+    private toUint8Array;
     getSyncStatuses(): Map<string, SyncPairStatus>;
     resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
     listConflicts(): Promise<ConflictArchive[]>;
+    readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     dispose(): Promise<void>;
     setupSync(backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
     private persistConfig;
@@ -279,12 +258,10 @@ declare class ConfigRepo implements IConfigRepo {
     private handleConflict;
     private ensureDir;
     private walkDir;
-    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    writeMetaFile(path: string, data: BackendsMeta): Promise<void>;
     readMetaFile<T>(path: string): Promise<T | null>;
     getBackends(): Promise<BackendsMeta | null>;
     updateBackends(meta: BackendsMeta): Promise<void>;
-    getSyncRules(): Promise<SyncRulesMeta | null>;
-    updateSyncRules(meta: SyncRulesMeta): Promise<void>;
     private tryParse;
     private assertNotDisposed;
 }
@@ -374,4 +351,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
+import { SyncResult, SyncPairStatus, ConflictStrategy, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
 import * as node_fs from 'node:fs';
 
@@ -18,24 +18,6 @@ interface BackendsMeta {
     version: 1;
     backends: BackendDescriptor[];
 }
-/** Sync direction for a path prefix. */
-type SyncDirection = 'one-way' | 'bi-directional' | 'none';
-/** A single sync rule. */
-interface SyncRule {
-    /** Path prefix this rule applies to (e.g., "/app-a/"). */
-    prefix: string;
-    /** Sync direction. */
-    direction: SyncDirection;
-    /** Conflict resolution strategy (only relevant for bi-directional). */
-    conflictStrategy?: ConflictStrategy;
-    /** IDs of replica backends to sync with (from .meta/backends.json). */
-    replicas?: string[];
-}
-/** Content of `.meta/sync-rules.json`. */
-interface SyncRulesMeta {
-    version: 1;
-    rules: SyncRule[];
-}
 /** Content of a sidecar `.version` file. */
 interface VersionMeta {
     /** Monotonically increasing version number. */
@@ -57,18 +39,18 @@ interface ConflictArchive {
     sourceAuthor: string;
     /** Author of the target side. */
     targetAuthor: string;
-    /** Source side content. */
-    sourceContent: unknown;
-    /** Target side content. */
-    targetContent: unknown;
     /** Source side version. */
     sourceVersion: number;
     /** Target side version. */
     targetVersion: number;
     /** Strategy that was used to auto-resolve (if any). */
     resolvedStrategy?: ConflictStrategy;
-    /** The content that was written as the resolved result (if auto-resolved). */
-    resolvedContent?: unknown;
+    /** Path to the source-side backup file. */
+    sourceBackupPath: string;
+    /** Path to the target-side backup file. */
+    targetBackupPath: string;
+    /** Path to the resolved file (present after resolution). */
+    resolvedBackupPath?: string;
 }
 /** Information passed to conflict event handlers. */
 interface ConflictInfo {
@@ -103,11 +85,6 @@ interface CacheOptions {
     /** TTL in milliseconds for cache hits without revalidation. Default: 0 (always revalidate). */
     ttlMs?: number;
 }
-/** Bootstrap data, written to .meta/ only on first initialization. */
-interface BootstrapData {
-    backends: Omit<BackendDescriptor, 'description'>[];
-    syncRules: SyncRule[];
-}
 /** Options for creating a ConfigRepo. */
 interface ConfigRepoOptions {
     /** The backend ID (from .meta/backends.json) to use as this instance's primary. */
@@ -121,8 +98,6 @@ interface ConfigRepoOptions {
     nodeId?: string;
     /** Cache configuration. */
     cache?: CacheOptions;
-    /** Bootstrap data (only used when .meta/backends.json doesn't exist). */
-    bootstrap?: BootstrapData;
     /** Custom serializer. */
     serializer?: ConfigSerializer;
     /** Custom conflict handler. Called before auto-resolution. */
@@ -162,16 +137,17 @@ interface IConfigRepo {
     resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
     /** List all conflict archives. */
     listConflicts(): Promise<ConflictArchive[]>;
+    /** Read the raw content of a conflict backup file (source/target/resolved).
+     *  @param conflictId The meta.json path (e.g., "12345_path.conflict/meta.json")
+     *  @param fileType One of "source", "target", or "resolved"
+     */
+    readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     /** Read .meta/backends.json. */
     getBackends(): Promise<BackendsMeta | null>;
     /** Write .meta/backends.json. */
     updateBackends(meta: BackendsMeta): Promise<void>;
-    /** Read .meta/sync-rules.json. */
-    getSyncRules(): Promise<SyncRulesMeta | null>;
-    /** Write .meta/sync-rules.json. */
-    updateSyncRules(meta: SyncRulesMeta): Promise<void>;
     /**
-     * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+     * Sync .meta/ files (backends.json) to all replica backends.
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
@@ -260,18 +236,21 @@ declare class ConfigRepo implements IConfigRepo {
     peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     flush(): Promise<SyncResult[]>;
     /**
-     * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+     * Sync .meta/ files (backends.json) to all replica backends.
      *
      * This ensures the backend topology is available on every replica, enabling
      * any program that connects to any backend to discover the full topology.
      *
      * Called automatically by createConfigRepo() after setupSync().
-     * Can also be called manually after updateBackends() / updateSyncRules().
      */
     syncMetaToReplicas(): Promise<void>;
+    /** Compare two file contents (handles Uint8Array, ArrayBuffer, string, Buffer). */
+    private bufferEqual;
+    private toUint8Array;
     getSyncStatuses(): Map<string, SyncPairStatus>;
     resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
     listConflicts(): Promise<ConflictArchive[]>;
+    readConflictBackup(conflictId: string, fileType: 'source' | 'target' | 'resolved'): Promise<string>;
     dispose(): Promise<void>;
     setupSync(backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
     private persistConfig;
@@ -279,12 +258,10 @@ declare class ConfigRepo implements IConfigRepo {
     private handleConflict;
     private ensureDir;
     private walkDir;
-    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    writeMetaFile(path: string, data: BackendsMeta): Promise<void>;
     readMetaFile<T>(path: string): Promise<T | null>;
     getBackends(): Promise<BackendsMeta | null>;
     updateBackends(meta: BackendsMeta): Promise<void>;
-    getSyncRules(): Promise<SyncRulesMeta | null>;
-    updateSyncRules(meta: SyncRulesMeta): Promise<void>;
     private tryParse;
     private assertNotDisposed;
 }
@@ -374,4 +351,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.js

@@ -484,10 +484,8 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
 // src/config-repo.ts
 var META_DIR = "/.meta";
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
-var SYNC_RULES_FILE = `${META_DIR}/sync-rules.json`;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
 var NODES_DIR = "/nodes";
-var SHARED_DIR = "/shared";
 var NODE_ID_FILE = `${NODES_DIR}/.node-id`;
 var ConfigRepo = class {
   appId;
@@ -533,12 +531,6 @@ var ConfigRepo = class {
           backends: data.backends
         });
       }
-      if (data.syncRules) {
-        await this.writeMetaFile(SYNC_RULES_FILE, {
-          version: 1,
-          rules: data.syncRules
-        });
-      }
     }
     await this.reloadConfigCache();
   }
@@ -666,33 +658,68 @@ var ConfigRepo = class {
     return Array.from(resultsMap.values());
   }
   /**
-   * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+   * Sync .meta/ files (backends.json) to all replica backends.
    *
    * This ensures the backend topology is available on every replica, enabling
    * any program that connects to any backend to discover the full topology.
    *
    * Called automatically by createConfigRepo() after setupSync().
-   * Can also be called manually after updateBackends() / updateSyncRules().
    */
   async syncMetaToReplicas() {
     this.assertNotDisposed();
-    for (const metaFile of [BACKENDS_FILE, SYNC_RULES_FILE]) {
+    try {
+      const content = await this.cachedFS.readFile(BACKENDS_FILE);
+      const vPath = versionPathFor(BACKENDS_FILE);
+      let vContent;
       try {
-        const content = await this.cachedFS.readFile(metaFile);
-        const vPath = versionPathFor(metaFile);
-        const vContent = await this.cachedFS.readFile(vPath);
-        for (const [id, replica] of this.replicaBackends) {
+        vContent = await this.cachedFS.readFile(vPath);
+      } catch {
+      }
+      for (const [id, replica] of this.replicaBackends) {
+        try {
+          let needWrite = true;
           try {
-            await replica.syncable.writeFile(metaFile, content);
-            await replica.syncable.writeFile(vPath, vContent);
-            console.log(`[ConfigRepo] Synced ${metaFile} + .version to replica ${id}`);
-          } catch (err) {
-            console.error(`[ConfigRepo] Failed to sync ${metaFile} to ${id}:`, err.message);
+            const existing = await replica.syncable.readFile(BACKENDS_FILE);
+            if (this.bufferEqual(content, existing)) {
+              needWrite = false;
+              console.log(`[ConfigRepo] ${BACKENDS_FILE} already up-to-date on ${id}, skipping`);
+            }
+          } catch {
+          }
+          if (needWrite) {
+            await replica.syncable.writeFile(BACKENDS_FILE, content);
+            console.log(`[ConfigRepo] Synced ${BACKENDS_FILE} to replica ${id}`);
           }
+          if (vContent) {
+            try {
+              await replica.syncable.writeFile(vPath, vContent);
+            } catch (err) {
+              console.error(`[ConfigRepo] Failed to sync ${vPath} to ${id}:`, err.message);
+            }
+          }
+        } catch (err) {
+          console.error(`[ConfigRepo] Failed to sync ${BACKENDS_FILE} to ${id}:`, err.message);
         }
-      } catch {
       }
+    } catch {
+    }
+  }
+  /** Compare two file contents (handles Uint8Array, ArrayBuffer, string, Buffer). */
+  bufferEqual(a, b) {
+    const ua = this.toUint8Array(a);
+    const ub = this.toUint8Array(b);
+    if (ua.length !== ub.length) return false;
+    for (let i = 0; i < ua.length; i++) {
+      if (ua[i] !== ub[i]) return false;
     }
+    return true;
+  }
+  toUint8Array(raw) {
+    if (raw instanceof ArrayBuffer) return new Uint8Array(raw);
+    if (raw instanceof Uint8Array) return raw;
+    if (typeof raw === "string") return new TextEncoder().encode(raw);
+    if (Buffer.isBuffer(raw)) return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+    return new Uint8Array(raw);
   }
   getSyncStatuses() {
     this.assertNotDisposed();
@@ -703,9 +730,9 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   async resolveConflict(conflictId, mergedContent) {
     this.assertNotDisposed();
-    const archivePath = `${CONFLICTS_DIR}/${conflictId}`;
+    const metaPath = `${CONFLICTS_DIR}/${conflictId}`;
     try {
-      const raw = await this.cachedFS.readFile(archivePath);
+      const raw = await this.cachedFS.readFile(metaPath);
       const archive = JSON.parse(
         new TextDecoder().decode(toUint8Array(raw))
       );
@@ -720,9 +747,13 @@ var ConfigRepo = class {
         author
       );
       await writeVersion(this.fullFS, versionPathFor(configPath), version);
-      archive.resolvedContent = mergedContent;
+      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));
+      await this.cachedFS.writeFile(resolvedBackupPath, resolvedBytes);
+      archive.resolvedBackupPath = `./resolved`;
       await this.cachedFS.writeFile(
-        archivePath,
+        metaPath,
         new TextEncoder().encode(JSON.stringify(archive, null, 2))
       );
     } catch (err) {
@@ -735,9 +766,9 @@ var ConfigRepo = class {
     try {
       const entries = await this.cachedFS.readdir(CONFLICTS_DIR);
       for (const entry of entries) {
-        if (!entry.endsWith(".json")) continue;
+        const metaPath = `${CONFLICTS_DIR}/${entry}/meta.json`;
         try {
-          const raw = await this.cachedFS.readFile(`${CONFLICTS_DIR}/${entry}`);
+          const raw = await this.cachedFS.readFile(metaPath);
           const archive = JSON.parse(
             new TextDecoder().decode(toUint8Array(raw))
           );
@@ -749,6 +780,13 @@ var ConfigRepo = class {
     }
     return archives.sort((a, b) => a.timestamp - b.timestamp);
   }
+  async readConflictBackup(conflictId, fileType) {
+    this.assertNotDisposed();
+    const conflictDir = `${CONFLICTS_DIR}/${conflictId}`.replace(/\/meta\.json$/, "");
+    const filePath = `${conflictDir}/${fileType}`;
+    const raw = await this.cachedFS.readFile(filePath);
+    return new TextDecoder().decode(toUint8Array(raw));
+  }
   // -----------------------------------------------------------------------
   // IConfigRepo — Lifecycle
   // -----------------------------------------------------------------------
@@ -799,7 +837,7 @@ var ConfigRepo = class {
       );
       console.log(`[ConfigRepo] Sync pair added: pairId=${pair.pairId}, replica=${replicaId}, root=/`);
       const conflictHandler = (event) => {
-        this.handleConflict(event, { prefix: "/", direction: "one-way" });
+        this.handleConflict(event);
       };
       this.syncEngine.on(pair.pairId, "conflict", conflictHandler);
       this.syncEngine.watch(pair.pairId);
@@ -835,45 +873,57 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   // Internal — Conflict Handling
   // -----------------------------------------------------------------------
-  async handleConflict(event, _rule) {
+  async handleConflict(event) {
     const conflict = event.conflict;
     if (!conflict) return;
+    const conflictId = `${event.timestamp}_${conflict.path.replace(/\//g, "_")}`;
+    const conflictDir = `${CONFLICTS_DIR}/${conflictId}`;
+    const sourceBackupPath = `${conflictDir}/source`;
+    const targetBackupPath = `${conflictDir}/target`;
+    await this.ensureDir(conflictDir);
+    await this.cachedFS.writeFile(
+      sourceBackupPath,
+      new TextEncoder().encode(conflict.sourceContent)
+    );
+    await this.cachedFS.writeFile(
+      targetBackupPath,
+      new TextEncoder().encode(conflict.targetContent)
+    );
+    let sourceVersion = 0;
+    try {
+      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
+      if (srcVer) sourceVersion = srcVer.version;
+    } catch {
+    }
     const archive = {
       conflictPath: conflict.path,
       timestamp: event.timestamp,
       sourceAuthor: `${this.appId}/${this.nodeId}`,
       targetAuthor: "unknown",
-      sourceContent: this.tryParse(conflict.sourceContent),
-      targetContent: this.tryParse(conflict.targetContent),
-      sourceVersion: 0,
+      sourceVersion,
       targetVersion: 0,
-      resolvedStrategy: conflict.resolvedWith
+      resolvedStrategy: conflict.resolvedWith,
+      sourceBackupPath: `./source`,
+      targetBackupPath: `./target`
     };
-    try {
-      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
-      if (srcVer) archive.sourceVersion = srcVer.version;
-    } catch {
-    }
-    const archiveFileName = `${event.timestamp}_${conflict.path.replace(/\//g, "_")}.conflict.json`;
-    const archivePath = `${CONFLICTS_DIR}/${archiveFileName}`;
-    await this.ensureDir(archivePath);
+    const metaPath = `${conflictDir}/meta.json`;
     await this.cachedFS.writeFile(
-      archivePath,
+      metaPath,
       new TextEncoder().encode(JSON.stringify(archive, null, 2))
     );
     if (this.onConflictCallback) {
       const info = {
-        conflictId: archiveFileName,
+        conflictId: `${conflictId}/meta.json`,
         path: conflict.path,
         sourceAuthor: archive.sourceAuthor,
         targetAuthor: archive.targetAuthor,
-        sourceContent: archive.sourceContent,
-        targetContent: archive.targetContent
+        sourceContent: this.tryParse(conflict.sourceContent),
+        targetContent: this.tryParse(conflict.targetContent)
       };
       try {
         const customMerge = await this.onConflictCallback(info);
         if (customMerge !== null && customMerge !== void 0) {
-          await this.resolveConflict(archiveFileName, customMerge);
+          await this.resolveConflict(`${conflictId}/meta.json`, customMerge);
         }
       } catch (err) {
         console.error("[zen-fs-config] Conflict handler error:", err);
@@ -958,14 +1008,6 @@ var ConfigRepo = class {
     this.assertNotDisposed();
     await this.writeMetaFile(BACKENDS_FILE, meta);
   }
-  async getSyncRules() {
-    this.assertNotDisposed();
-    return this.readMetaFile(SYNC_RULES_FILE);
-  }
-  async updateSyncRules(meta) {
-    this.assertNotDisposed();
-    await this.writeMetaFile(SYNC_RULES_FILE, meta);
-  }
   tryParse(content) {
     try {
       return JSON.parse(content);
@@ -1026,24 +1068,17 @@ async function createConfigRepo(appId, options) {
   );
   let backendsMeta = await tempRepo.readMetaFile(BACKENDS_FILE);
   if (!backendsMeta) {
-    if (options.bootstrap) {
-      backendsMeta = {
-        version: 1,
-        backends: options.bootstrap.backends
-      };
-      console.log(`[createConfigRepo] First init: using bootstrap backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
-    } else {
-      backendsMeta = {
-        version: 1,
-        backends: [
-          {
-            id: options.primaryBackendId,
-            type: options.backendInfo.type,
-            options: options.backendInfo.options
-          }
-        ]
-      };
-    }
+    backendsMeta = {
+      version: 1,
+      backends: [
+        {
+          id: options.primaryBackendId,
+          type: options.backendInfo.type,
+          options: options.backendInfo.options
+        }
+      ]
+    };
+    console.log(`[createConfigRepo] First init: using bootstrap backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
   } else {
     console.log(`[createConfigRepo] Reconnect: using stored backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
   }
@@ -1058,45 +1093,6 @@ async function createConfigRepo(appId, options) {
     });
   }
   await tempRepo.writeMetaFile(BACKENDS_FILE, backendsMeta);
-  let syncRulesMeta = await tempRepo.readMetaFile(SYNC_RULES_FILE);
-  if (!syncRulesMeta) {
-    if (options.bootstrap) {
-      syncRulesMeta = {
-        version: 1,
-        rules: options.bootstrap.syncRules
-      };
-      console.log(`[createConfigRepo] First init: using bootstrap syncRules: ${syncRulesMeta.rules.length} rules`);
-    } else {
-      syncRulesMeta = {
-        version: 1,
-        rules: [
-          {
-            prefix: `/${appId}/`,
-            direction: "one-way",
-            conflictStrategy: "source-wins",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          },
-          {
-            prefix: `${SHARED_DIR}/`,
-            direction: "bi-directional",
-            conflictStrategy: "merge",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          },
-          { prefix: `${NODES_DIR}/`, direction: "none" },
-          {
-            prefix: `${META_DIR}/`,
-            direction: "one-way",
-            conflictStrategy: "source-wins",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          }
-        ]
-      };
-    }
-  }
-  if (syncRulesMeta) {
-    console.log(`[createConfigRepo] Reconnect: using stored syncRules: ${syncRulesMeta.rules.length} rules`);
-  }
-  await tempRepo.writeMetaFile(SYNC_RULES_FILE, syncRulesMeta);
   let nodeId = options.nodeId;
   if (!nodeId) {
     nodeId = process.env.NODE_ID;

package/dist/index.mjs

@@ -435,10 +435,8 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
 // src/config-repo.ts
 var META_DIR = "/.meta";
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
-var SYNC_RULES_FILE = `${META_DIR}/sync-rules.json`;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
 var NODES_DIR = "/nodes";
-var SHARED_DIR = "/shared";
 var NODE_ID_FILE = `${NODES_DIR}/.node-id`;
 var ConfigRepo = class {
   appId;
@@ -484,12 +482,6 @@ var ConfigRepo = class {
           backends: data.backends
         });
       }
-      if (data.syncRules) {
-        await this.writeMetaFile(SYNC_RULES_FILE, {
-          version: 1,
-          rules: data.syncRules
-        });
-      }
     }
     await this.reloadConfigCache();
   }
@@ -617,33 +609,68 @@ var ConfigRepo = class {
     return Array.from(resultsMap.values());
   }
   /**
-   * Sync .meta/ files (backends.json, sync-rules.json) to all replica backends.
+   * Sync .meta/ files (backends.json) to all replica backends.
    *
    * This ensures the backend topology is available on every replica, enabling
    * any program that connects to any backend to discover the full topology.
    *
    * Called automatically by createConfigRepo() after setupSync().
-   * Can also be called manually after updateBackends() / updateSyncRules().
    */
   async syncMetaToReplicas() {
     this.assertNotDisposed();
-    for (const metaFile of [BACKENDS_FILE, SYNC_RULES_FILE]) {
+    try {
+      const content = await this.cachedFS.readFile(BACKENDS_FILE);
+      const vPath = versionPathFor(BACKENDS_FILE);
+      let vContent;
       try {
-        const content = await this.cachedFS.readFile(metaFile);
-        const vPath = versionPathFor(metaFile);
-        const vContent = await this.cachedFS.readFile(vPath);
-        for (const [id, replica] of this.replicaBackends) {
+        vContent = await this.cachedFS.readFile(vPath);
+      } catch {
+      }
+      for (const [id, replica] of this.replicaBackends) {
+        try {
+          let needWrite = true;
           try {
-            await replica.syncable.writeFile(metaFile, content);
-            await replica.syncable.writeFile(vPath, vContent);
-            console.log(`[ConfigRepo] Synced ${metaFile} + .version to replica ${id}`);
-          } catch (err) {
-            console.error(`[ConfigRepo] Failed to sync ${metaFile} to ${id}:`, err.message);
+            const existing = await replica.syncable.readFile(BACKENDS_FILE);
+            if (this.bufferEqual(content, existing)) {
+              needWrite = false;
+              console.log(`[ConfigRepo] ${BACKENDS_FILE} already up-to-date on ${id}, skipping`);
+            }
+          } catch {
+          }
+          if (needWrite) {
+            await replica.syncable.writeFile(BACKENDS_FILE, content);
+            console.log(`[ConfigRepo] Synced ${BACKENDS_FILE} to replica ${id}`);
           }
+          if (vContent) {
+            try {
+              await replica.syncable.writeFile(vPath, vContent);
+            } catch (err) {
+              console.error(`[ConfigRepo] Failed to sync ${vPath} to ${id}:`, err.message);
+            }
+          }
+        } catch (err) {
+          console.error(`[ConfigRepo] Failed to sync ${BACKENDS_FILE} to ${id}:`, err.message);
         }
-      } catch {
       }
+    } catch {
+    }
+  }
+  /** Compare two file contents (handles Uint8Array, ArrayBuffer, string, Buffer). */
+  bufferEqual(a, b) {
+    const ua = this.toUint8Array(a);
+    const ub = this.toUint8Array(b);
+    if (ua.length !== ub.length) return false;
+    for (let i = 0; i < ua.length; i++) {
+      if (ua[i] !== ub[i]) return false;
     }
+    return true;
+  }
+  toUint8Array(raw) {
+    if (raw instanceof ArrayBuffer) return new Uint8Array(raw);
+    if (raw instanceof Uint8Array) return raw;
+    if (typeof raw === "string") return new TextEncoder().encode(raw);
+    if (Buffer.isBuffer(raw)) return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+    return new Uint8Array(raw);
   }
   getSyncStatuses() {
     this.assertNotDisposed();
@@ -654,9 +681,9 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   async resolveConflict(conflictId, mergedContent) {
     this.assertNotDisposed();
-    const archivePath = `${CONFLICTS_DIR}/${conflictId}`;
+    const metaPath = `${CONFLICTS_DIR}/${conflictId}`;
     try {
-      const raw = await this.cachedFS.readFile(archivePath);
+      const raw = await this.cachedFS.readFile(metaPath);
       const archive = JSON.parse(
         new TextDecoder().decode(toUint8Array(raw))
       );
@@ -671,9 +698,13 @@ var ConfigRepo = class {
         author
       );
       await writeVersion(this.fullFS, versionPathFor(configPath), version);
-      archive.resolvedContent = mergedContent;
+      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));
+      await this.cachedFS.writeFile(resolvedBackupPath, resolvedBytes);
+      archive.resolvedBackupPath = `./resolved`;
       await this.cachedFS.writeFile(
-        archivePath,
+        metaPath,
         new TextEncoder().encode(JSON.stringify(archive, null, 2))
       );
     } catch (err) {
@@ -686,9 +717,9 @@ var ConfigRepo = class {
     try {
       const entries = await this.cachedFS.readdir(CONFLICTS_DIR);
       for (const entry of entries) {
-        if (!entry.endsWith(".json")) continue;
+        const metaPath = `${CONFLICTS_DIR}/${entry}/meta.json`;
         try {
-          const raw = await this.cachedFS.readFile(`${CONFLICTS_DIR}/${entry}`);
+          const raw = await this.cachedFS.readFile(metaPath);
           const archive = JSON.parse(
             new TextDecoder().decode(toUint8Array(raw))
           );
@@ -700,6 +731,13 @@ var ConfigRepo = class {
     }
     return archives.sort((a, b) => a.timestamp - b.timestamp);
   }
+  async readConflictBackup(conflictId, fileType) {
+    this.assertNotDisposed();
+    const conflictDir = `${CONFLICTS_DIR}/${conflictId}`.replace(/\/meta\.json$/, "");
+    const filePath = `${conflictDir}/${fileType}`;
+    const raw = await this.cachedFS.readFile(filePath);
+    return new TextDecoder().decode(toUint8Array(raw));
+  }
   // -----------------------------------------------------------------------
   // IConfigRepo — Lifecycle
   // -----------------------------------------------------------------------
@@ -750,7 +788,7 @@ var ConfigRepo = class {
       );
       console.log(`[ConfigRepo] Sync pair added: pairId=${pair.pairId}, replica=${replicaId}, root=/`);
       const conflictHandler = (event) => {
-        this.handleConflict(event, { prefix: "/", direction: "one-way" });
+        this.handleConflict(event);
       };
       this.syncEngine.on(pair.pairId, "conflict", conflictHandler);
       this.syncEngine.watch(pair.pairId);
@@ -786,45 +824,57 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   // Internal — Conflict Handling
   // -----------------------------------------------------------------------
-  async handleConflict(event, _rule) {
+  async handleConflict(event) {
     const conflict = event.conflict;
     if (!conflict) return;
+    const conflictId = `${event.timestamp}_${conflict.path.replace(/\//g, "_")}`;
+    const conflictDir = `${CONFLICTS_DIR}/${conflictId}`;
+    const sourceBackupPath = `${conflictDir}/source`;
+    const targetBackupPath = `${conflictDir}/target`;
+    await this.ensureDir(conflictDir);
+    await this.cachedFS.writeFile(
+      sourceBackupPath,
+      new TextEncoder().encode(conflict.sourceContent)
+    );
+    await this.cachedFS.writeFile(
+      targetBackupPath,
+      new TextEncoder().encode(conflict.targetContent)
+    );
+    let sourceVersion = 0;
+    try {
+      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
+      if (srcVer) sourceVersion = srcVer.version;
+    } catch {
+    }
     const archive = {
       conflictPath: conflict.path,
       timestamp: event.timestamp,
       sourceAuthor: `${this.appId}/${this.nodeId}`,
       targetAuthor: "unknown",
-      sourceContent: this.tryParse(conflict.sourceContent),
-      targetContent: this.tryParse(conflict.targetContent),
-      sourceVersion: 0,
+      sourceVersion,
       targetVersion: 0,
-      resolvedStrategy: conflict.resolvedWith
+      resolvedStrategy: conflict.resolvedWith,
+      sourceBackupPath: `./source`,
+      targetBackupPath: `./target`
     };
-    try {
-      const srcVer = await readVersion(this.fullFS, versionPathFor(conflict.path));
-      if (srcVer) archive.sourceVersion = srcVer.version;
-    } catch {
-    }
-    const archiveFileName = `${event.timestamp}_${conflict.path.replace(/\//g, "_")}.conflict.json`;
-    const archivePath = `${CONFLICTS_DIR}/${archiveFileName}`;
-    await this.ensureDir(archivePath);
+    const metaPath = `${conflictDir}/meta.json`;
     await this.cachedFS.writeFile(
-      archivePath,
+      metaPath,
       new TextEncoder().encode(JSON.stringify(archive, null, 2))
     );
     if (this.onConflictCallback) {
       const info = {
-        conflictId: archiveFileName,
+        conflictId: `${conflictId}/meta.json`,
         path: conflict.path,
         sourceAuthor: archive.sourceAuthor,
         targetAuthor: archive.targetAuthor,
-        sourceContent: archive.sourceContent,
-        targetContent: archive.targetContent
+        sourceContent: this.tryParse(conflict.sourceContent),
+        targetContent: this.tryParse(conflict.targetContent)
       };
       try {
         const customMerge = await this.onConflictCallback(info);
         if (customMerge !== null && customMerge !== void 0) {
-          await this.resolveConflict(archiveFileName, customMerge);
+          await this.resolveConflict(`${conflictId}/meta.json`, customMerge);
         }
       } catch (err) {
         console.error("[zen-fs-config] Conflict handler error:", err);
@@ -909,14 +959,6 @@ var ConfigRepo = class {
     this.assertNotDisposed();
     await this.writeMetaFile(BACKENDS_FILE, meta);
   }
-  async getSyncRules() {
-    this.assertNotDisposed();
-    return this.readMetaFile(SYNC_RULES_FILE);
-  }
-  async updateSyncRules(meta) {
-    this.assertNotDisposed();
-    await this.writeMetaFile(SYNC_RULES_FILE, meta);
-  }
   tryParse(content) {
     try {
       return JSON.parse(content);
@@ -977,24 +1019,17 @@ async function createConfigRepo(appId, options) {
   );
   let backendsMeta = await tempRepo.readMetaFile(BACKENDS_FILE);
   if (!backendsMeta) {
-    if (options.bootstrap) {
-      backendsMeta = {
-        version: 1,
-        backends: options.bootstrap.backends
-      };
-      console.log(`[createConfigRepo] First init: using bootstrap backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
-    } else {
-      backendsMeta = {
-        version: 1,
-        backends: [
-          {
-            id: options.primaryBackendId,
-            type: options.backendInfo.type,
-            options: options.backendInfo.options
-          }
-        ]
-      };
-    }
+    backendsMeta = {
+      version: 1,
+      backends: [
+        {
+          id: options.primaryBackendId,
+          type: options.backendInfo.type,
+          options: options.backendInfo.options
+        }
+      ]
+    };
+    console.log(`[createConfigRepo] First init: using bootstrap backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
   } else {
     console.log(`[createConfigRepo] Reconnect: using stored backends: ${backendsMeta.backends.map((b) => b.id).join(", ")}`);
   }
@@ -1009,45 +1044,6 @@ async function createConfigRepo(appId, options) {
     });
   }
   await tempRepo.writeMetaFile(BACKENDS_FILE, backendsMeta);
-  let syncRulesMeta = await tempRepo.readMetaFile(SYNC_RULES_FILE);
-  if (!syncRulesMeta) {
-    if (options.bootstrap) {
-      syncRulesMeta = {
-        version: 1,
-        rules: options.bootstrap.syncRules
-      };
-      console.log(`[createConfigRepo] First init: using bootstrap syncRules: ${syncRulesMeta.rules.length} rules`);
-    } else {
-      syncRulesMeta = {
-        version: 1,
-        rules: [
-          {
-            prefix: `/${appId}/`,
-            direction: "one-way",
-            conflictStrategy: "source-wins",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          },
-          {
-            prefix: `${SHARED_DIR}/`,
-            direction: "bi-directional",
-            conflictStrategy: "merge",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          },
-          { prefix: `${NODES_DIR}/`, direction: "none" },
-          {
-            prefix: `${META_DIR}/`,
-            direction: "one-way",
-            conflictStrategy: "source-wins",
-            replicas: backendsMeta.backends.map((b) => b.id)
-          }
-        ]
-      };
-    }
-  }
-  if (syncRulesMeta) {
-    console.log(`[createConfigRepo] Reconnect: using stored syncRules: ${syncRulesMeta.rules.length} rules`);
-  }
-  await tempRepo.writeMetaFile(SYNC_RULES_FILE, syncRulesMeta);
   let nodeId = options.nodeId;
   if (!nodeId) {
     nodeId = process.env.NODE_ID;

package/package.json

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