@rljson/fs-agent 0.0.3 → 0.0.4

package/README.architecture.md

@@ -447,3 +447,50 @@ This peer-to-peer pattern with server coordination enables:
 ✅ **Real-world deployment**: Works across networks, not just in-memory mocks
 
 **This is why clients must NEVER access server Io/Bs directly** - it would bypass the entire peer-to-peer mechanism and make the system only work in single-process scenarios.
+
+## Bounce-Back Prevention
+
+Bidirectional sync creates a potential infinite loop:
+
+```
+Client A writes file → syncToDb stores tree → broadcasts ref →
+Client B receives ref → syncFromDb restores file → fs watcher fires →
+syncToDb stores tree → broadcasts ref → Client A receives ref → ...
+```
+
+FsAgent uses three layers of deduplication to break the loop:
+
+1. **Ref-level dedup**: After `syncToDb` stores a tree, it compares the
+   resulting ref against `_lastSentRef`. If identical, no broadcast occurs.
+
+2. **Content-key dedup**: Even when refs differ (e.g. different mtimes produce
+   different hashes), `syncToDb` computes a content key from file paths +
+   blobIds. If the content key matches `_lastSentContentKey`, the broadcast
+   is skipped.
+
+3. **Content comparison before restore**: In `syncFromDb`, before restoring
+   an incoming tree, FsAgent compares its file content map against the current
+   filesystem. If they are equivalent, the restore is skipped entirely,
+   preventing the filesystem watcher from firing.
+
+Additionally, all sync callbacks are **debounced** (default 300ms) to coalesce
+rapid filesystem events (e.g. multi-file saves, editor autosave) into a single
+sync operation.
+
+## Known Constraints
+
+### macOS Finder Paste and Rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS). This works
+reliably for programmatic file operations (Node.js `writeFile`/`copyFile`,
+terminal commands, editor saves) but **not** for macOS Finder's paste-and-rename
+workflow.
+
+Finder generates rapid, non-atomic, multi-step event sequences (create temp →
+write → rename → delete temp) that FSEvents may coalesce, reorder, or split
+unpredictably. This causes intermediate filesystem states to be scanned and
+broadcast before the operation completes, leading to sync conflicts.
+
+**This is a known limitation and is not supported.** Use programmatic operations
+or terminal commands instead of Finder drag-and-drop or paste-and-rename for
+files in synced folders.

package/README.public.md

@@ -21,9 +21,11 @@ found in the LICENSE file in the root of this package.
 - 💾 **Smart Storage**: Content-addressed blob storage eliminates duplicate file content
 - 📜 **Version History**: Every change is tracked with complete insert history
 - 🔁 **Bidirectional Sync**: Changes in either direction are automatically propagated
-- 🛡️ **Loop Prevention**: Intelligent pause/resume mechanism prevents infinite sync loops
+- 🛡️ **Loop Prevention**: Content-based dedup, ref tracking, and debounce prevent infinite sync loops
+- ⏱️ **Timeout Guards**: Every async operation is bounded to prevent silent hangs
+- 🎯 **Debounce**: Rapid filesystem events are coalesced into a single sync cycle
 - ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🧪 **Battle-Tested**: 100% test coverage with 139 tests
+- 🧪 **Battle-Tested**: 100% test coverage with 204 tests (SocketMock + Socket.IO)
 - 🧹 **Target Cleanup**: Optional `cleanTarget` restore prunes stale files and directories
 
 ## Installation
@@ -700,6 +702,36 @@ try {
 }
 ```
 
+## Timeout & Debounce Configuration
+
+Every async operation in FsAgent is guarded by a timeout to prevent silent hangs.
+Rapid filesystem events are debounced to coalesce into a single sync cycle.
+
+```typescript
+const agent = new FsAgent('./my-project', bs, {
+  timeouts: {
+    dbQuery: 10_000,      // Single db.get() query (default: 10s)
+    fetchTree: 20_000,    // Fetching an entire tree from the DB (default: 20s)
+    extract: 15_000,      // Filesystem extract/scan (default: 15s)
+    restore: 15_000,      // Filesystem restore (default: 15s)
+    syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
+    debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+  },
+});
+```
+
+## Bounce-Back Prevention
+
+Bidirectional sync can cause infinite loops when both clients detect each
+other's restores as changes. FsAgent prevents this with three layers:
+
+1. **Ref tracking** (`_lastSentRef`): Skips re-broadcast if the stored tree
+   produces the same ref as the last one we sent.
+2. **Content-key dedup** (`_lastSentContentKey`): Compares file paths + blobIds
+   (ignoring mtimes) to detect identical content with different tree hashes.
+3. **Content comparison before restore**: `syncFromDb` compares the incoming
+   tree's content with the current filesystem and skips restore if identical.
+
 ## Performance
 
 - **Efficient Scanning**: Only scans changed directories
@@ -707,6 +739,8 @@ try {
 - **Content-Addressed**: Fast lookups via hashes
 - **Optimized Watching**: Uses native filesystem events
 - **Smart Sync**: Only syncs when changes detected
+- **Debounced Events**: Rapid changes coalesced into single operations
+- **Bounded Operations**: All async operations time out to prevent hangs
 
 ## Troubleshooting
 
@@ -763,6 +797,29 @@ ignore: ['*'];
 ignore: ['node_modules', '*.log'];
 ```
 
+## Known Constraints
+
+### macOS Finder paste and rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS) to detect
+filesystem changes. This works reliably for **programmatic** file operations:
+
+- ✅ `writeFile`, `copyFile`, `rename` from Node.js or shell commands
+- ✅ Editor saves (VS Code, Vim, etc.)
+- ✅ Terminal commands (`echo`, `cp`, `mv`, `touch`, etc.)
+- ✅ Application-generated file changes
+
+However, **macOS Finder's paste-and-rename workflow** generates rapid,
+non-atomic, multi-step event sequences (create temporary file → write → rename →
+delete temporary) that FSEvents may coalesce, reorder, or split unpredictably.
+This can cause intermediate states to be scanned and broadcast before the
+operation completes, leading to sync conflicts.
+
+**This is a known limitation of filesystem watching on macOS and is not
+supported.** If you need to add or rename files in synced folders, use
+programmatic operations or terminal commands instead of Finder drag-and-drop or
+paste-and-rename.
+
 ## Related Packages
 
 - `@rljson/db` - RLJSON database

package/dist/README.architecture.md

@@ -447,3 +447,50 @@ This peer-to-peer pattern with server coordination enables:
 ✅ **Real-world deployment**: Works across networks, not just in-memory mocks
 
 **This is why clients must NEVER access server Io/Bs directly** - it would bypass the entire peer-to-peer mechanism and make the system only work in single-process scenarios.
+
+## Bounce-Back Prevention
+
+Bidirectional sync creates a potential infinite loop:
+
+```
+Client A writes file → syncToDb stores tree → broadcasts ref →
+Client B receives ref → syncFromDb restores file → fs watcher fires →
+syncToDb stores tree → broadcasts ref → Client A receives ref → ...
+```
+
+FsAgent uses three layers of deduplication to break the loop:
+
+1. **Ref-level dedup**: After `syncToDb` stores a tree, it compares the
+   resulting ref against `_lastSentRef`. If identical, no broadcast occurs.
+
+2. **Content-key dedup**: Even when refs differ (e.g. different mtimes produce
+   different hashes), `syncToDb` computes a content key from file paths +
+   blobIds. If the content key matches `_lastSentContentKey`, the broadcast
+   is skipped.
+
+3. **Content comparison before restore**: In `syncFromDb`, before restoring
+   an incoming tree, FsAgent compares its file content map against the current
+   filesystem. If they are equivalent, the restore is skipped entirely,
+   preventing the filesystem watcher from firing.
+
+Additionally, all sync callbacks are **debounced** (default 300ms) to coalesce
+rapid filesystem events (e.g. multi-file saves, editor autosave) into a single
+sync operation.
+
+## Known Constraints
+
+### macOS Finder Paste and Rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS). This works
+reliably for programmatic file operations (Node.js `writeFile`/`copyFile`,
+terminal commands, editor saves) but **not** for macOS Finder's paste-and-rename
+workflow.
+
+Finder generates rapid, non-atomic, multi-step event sequences (create temp →
+write → rename → delete temp) that FSEvents may coalesce, reorder, or split
+unpredictably. This causes intermediate filesystem states to be scanned and
+broadcast before the operation completes, leading to sync conflicts.
+
+**This is a known limitation and is not supported.** Use programmatic operations
+or terminal commands instead of Finder drag-and-drop or paste-and-rename for
+files in synced folders.

package/dist/README.public.md

@@ -21,9 +21,11 @@ found in the LICENSE file in the root of this package.
 - 💾 **Smart Storage**: Content-addressed blob storage eliminates duplicate file content
 - 📜 **Version History**: Every change is tracked with complete insert history
 - 🔁 **Bidirectional Sync**: Changes in either direction are automatically propagated
-- 🛡️ **Loop Prevention**: Intelligent pause/resume mechanism prevents infinite sync loops
+- 🛡️ **Loop Prevention**: Content-based dedup, ref tracking, and debounce prevent infinite sync loops
+- ⏱️ **Timeout Guards**: Every async operation is bounded to prevent silent hangs
+- 🎯 **Debounce**: Rapid filesystem events are coalesced into a single sync cycle
 - ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🧪 **Battle-Tested**: 100% test coverage with 139 tests
+- 🧪 **Battle-Tested**: 100% test coverage with 204 tests (SocketMock + Socket.IO)
 - 🧹 **Target Cleanup**: Optional `cleanTarget` restore prunes stale files and directories
 
 ## Installation
@@ -700,6 +702,36 @@ try {
 }
 ```
 
+## Timeout & Debounce Configuration
+
+Every async operation in FsAgent is guarded by a timeout to prevent silent hangs.
+Rapid filesystem events are debounced to coalesce into a single sync cycle.
+
+```typescript
+const agent = new FsAgent('./my-project', bs, {
+  timeouts: {
+    dbQuery: 10_000,      // Single db.get() query (default: 10s)
+    fetchTree: 20_000,    // Fetching an entire tree from the DB (default: 20s)
+    extract: 15_000,      // Filesystem extract/scan (default: 15s)
+    restore: 15_000,      // Filesystem restore (default: 15s)
+    syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
+    debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+  },
+});
+```
+
+## Bounce-Back Prevention
+
+Bidirectional sync can cause infinite loops when both clients detect each
+other's restores as changes. FsAgent prevents this with three layers:
+
+1. **Ref tracking** (`_lastSentRef`): Skips re-broadcast if the stored tree
+   produces the same ref as the last one we sent.
+2. **Content-key dedup** (`_lastSentContentKey`): Compares file paths + blobIds
+   (ignoring mtimes) to detect identical content with different tree hashes.
+3. **Content comparison before restore**: `syncFromDb` compares the incoming
+   tree's content with the current filesystem and skips restore if identical.
+
 ## Performance
 
 - **Efficient Scanning**: Only scans changed directories
@@ -707,6 +739,8 @@ try {
 - **Content-Addressed**: Fast lookups via hashes
 - **Optimized Watching**: Uses native filesystem events
 - **Smart Sync**: Only syncs when changes detected
+- **Debounced Events**: Rapid changes coalesced into single operations
+- **Bounded Operations**: All async operations time out to prevent hangs
 
 ## Troubleshooting
 
@@ -763,6 +797,29 @@ ignore: ['*'];
 ignore: ['node_modules', '*.log'];
 ```
 
+## Known Constraints
+
+### macOS Finder paste and rename
+
+Bidirectional sync relies on Node.js `fs.watch` (FSEvents on macOS) to detect
+filesystem changes. This works reliably for **programmatic** file operations:
+
+- ✅ `writeFile`, `copyFile`, `rename` from Node.js or shell commands
+- ✅ Editor saves (VS Code, Vim, etc.)
+- ✅ Terminal commands (`echo`, `cp`, `mv`, `touch`, etc.)
+- ✅ Application-generated file changes
+
+However, **macOS Finder's paste-and-rename workflow** generates rapid,
+non-atomic, multi-step event sequences (create temporary file → write → rename →
+delete temporary) that FSEvents may coalesce, reorder, or split unpredictably.
+This can cause intermediate states to be scanned and broadcast before the
+operation completes, leading to sync conflicts.
+
+**This is a known limitation of filesystem watching on macOS and is not
+supported.** If you need to add or rename files in synced folders, use
+programmatic operations or terminal commands instead of Finder drag-and-drop or
+paste-and-rename.
+
 ## Related Packages
 
 - `@rljson/db` - RLJSON database

package/dist/fs-agent.d.ts

@@ -1,4 +1,5 @@
 import { Bs } from '@rljson/bs';
+import { ClientId, SyncConfig } from '@rljson/rljson';
 import { FsBlobAdapter } from './fs-blob-adapter.ts';
 import { StoreFsTreeOptions } from './fs-db-adapter.ts';
 import { FsScanner, FsTree } from './fs-scanner.ts';
@@ -23,12 +24,56 @@ export interface FsAgentOptions {
     bidirectional?: boolean;
     /** Restore options applied when syncing from DB */
     restoreOptions?: RestoreOptions;
+    /** Timeout configuration for async operations */
+    timeouts?: TimeoutConfig;
+    /**
+     * Centralized sync protocol configuration.
+     * When provided, this SyncConfig is forwarded to every Connector
+     * created by {@link FsAgent.fromClient}, and governs whether
+     * `sendWithAck()` (when `requireAck` is true) or `send()` is used
+     * in {@link FsAgent.syncToDb}.
+     *
+     * The same SyncConfig should also be passed to the Server and Client
+     * constructors so that every layer uses the same protocol settings.
+     */
+    syncConfig?: SyncConfig;
+    /**
+     * Stable client identity. When provided, it is forwarded to every
+     * Connector created by {@link FsAgent.fromClient}. When omitted but
+     * `syncConfig.includeClientIdentity` is true, each Connector
+     * auto-generates its own identity.
+     */
+    clientIdentity?: ClientId;
 }
 /** Restore options */
 export interface RestoreOptions {
     /** Remove files/dirs on target that are not present in the tree */
     cleanTarget?: boolean;
 }
+/**
+ * Timeout configuration for async operations (milliseconds).
+ * Every async operation in FsAgent is guarded by a timeout to prevent
+ * silent hangs in socket communication, filesystem I/O, or database queries.
+ */
+export interface TimeoutConfig {
+    /** Timeout for a single db.get() query. Default: 10 000 ms */
+    dbQuery?: number;
+    /** Timeout for fetching an entire tree from the DB. Default: 20 000 ms */
+    fetchTree?: number;
+    /** Timeout for a filesystem extract / scan. Default: 15 000 ms */
+    extract?: number;
+    /** Timeout for a filesystem restore. Default: 15 000 ms */
+    restore?: number;
+    /** Timeout for the overall syncFromDb callback. Default: 25 000 ms */
+    syncCallback?: number;
+    /**
+     * Debounce delay for sync callbacks (milliseconds). Default: 300 ms.
+     * Rapid filesystem events (e.g. macOS Finder "Keep Both" copy+rename)
+     * are coalesced into a single sync operation after this quiet period.
+     * Also applies to incoming database refs in syncFromDb.
+     */
+    debounceMs?: number;
+}
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -42,6 +87,9 @@ export declare class FsAgent {
     private _stopSync?;
     private _stopSyncFromDb?;
     private _lastSentRef?;
+    /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
+    private _lastSentContentKey?;
+    private _timeouts;
     constructor(rootPath: string, bs?: Bs, options?: FsAgentOptions);
     /**
      * Gets the root path
@@ -59,6 +107,27 @@ export declare class FsAgent {
      * Gets the adapter instance
      */
     get adapter(): FsBlobAdapter;
+    /**
+     * Gets the current timeout configuration
+     */
+    get timeouts(): Required<TimeoutConfig>;
+    /**
+     * Wraps a promise with a timeout.
+     * Rejects with a descriptive error if the promise does not settle
+     * within the given number of milliseconds.
+     * @param promise - The promise to guard
+     * @param ms - Maximum allowed time in milliseconds
+     * @param label - Human-readable label included in the error message
+     */
+    private static _withTimeout;
+    /**
+     * Sends a ref through the connector.
+     * Uses `sendWithAck()` when the connector has `requireAck` enabled,
+     * otherwise falls back to fire-and-forget `send()`.
+     * @param connector - The Connector to send through
+     * @param ref - The ref to broadcast
+     */
+    private _sendRef;
     /**
      * Starts automatic syncing to database
      * Note: Auto-sync requires Connector which is not available in constructor.
@@ -130,6 +199,15 @@ export declare class FsAgent {
      * @returns Array of all tree nodes in the tree
      */
     private _fetchTreeRecursively;
+    /**
+     * Fetches tree from database without restoring to filesystem.
+     * Separated from loadFromDb to allow content comparison before restore.
+     * @param db - Database instance
+     * @param treeKey - Tree table key
+     * @param rootRef - Root tree reference (hash)
+     * @returns FsTree structure ready for restore
+     */
+    private _fetchTreeFromDb;
     /**
      * Loads tree from database and restores to filesystem
      * Writes to filesystem from DB trees and Bs blobs
@@ -159,10 +237,37 @@ export declare class FsAgent {
      * @param db - Database instance
      * @param connector - Connector instance for socket-based sync
      * @param treeKey - Tree table key
-     * @param options - Storage options (e.g., notify)
+     * @param options - Storage options (e.g., skipNotification)
      * @returns Function to stop watching
      */
     syncToDb(db: Db, connector: Connector, treeKey: string, options?: StoreFsTreeOptions): Promise<() => void>;
+    /**
+     * Builds a map of relativePath → blobId for all files in a tree.
+     * Used to compare trees by content rather than by hash (which includes mtime).
+     * @param tree - Tree structure to extract file content map from
+     */
+    private _getFileContentMap;
+    /**
+     * Derives a deterministic string key from a content map so that two trees
+     * with identical file paths + blobIds produce the same key regardless of
+     * mtime differences.
+     * @param map - Content map (relativePath → blobId)
+     */
+    private _contentKeyFromMap;
+    /**
+     * Derives a deterministic content key from an FsTree.
+     * @param tree - Tree structure to derive content key from
+     */
+    private _contentKeyFromTree;
+    /**
+     * Compares two trees by file content (relativePath + blobId).
+     * Ignores mtime differences — trees are equivalent if they have the same
+     * files with the same content. This prevents bounce-back restores from
+     * destroying locally-created files during bidirectional sync.
+     * @param a - First tree to compare
+     * @param b - Second tree to compare
+     */
+    private _treesHaveEquivalentContent;
     /**
      * Watches database for tree changes and syncs to filesystem
      * Uses Connector for socket-based notifications
@@ -181,16 +286,21 @@ export declare class FsAgent {
      * @param treeKey - Tree table key (route will be `/${treeKey}`)
      * @param client - Client instance with io and bs properties
      * @param socket - Socket instance for connector communication
-     * @param options - Optional FsAgent options (db and treeKey are set automatically)
+     * @param options - Optional FsAgent options (db and treeKey are set automatically).
+     *   `syncConfig` and `clientIdentity` from these options are forwarded to
+     *   the Connector so that a single config origin governs all layers.
      * @returns Configured FsAgent instance with simplified sync API
      * @example
      * ```typescript
-     * const agent = await FsAgent.fromClient('./my-folder', 'sharedTree', client, socket);
+     * const syncConfig: SyncConfig = { requireAck: true, maxDedupSetSize: 5000 };
+     * const agent = await FsAgent.fromClient(
+     *   './my-folder', 'sharedTree', client, socket, { syncConfig },
+     * );
      * // Simplified sync methods - no db/connector/treeKey needed
-     * await agent.syncToDbSimple({ notify: true });
+     * await agent.syncToDbSimple();
      * await agent.syncFromDbSimple({ cleanTarget: true });
      * // Original methods still work
-     * await agent.syncToDb(db, connector, treeKey, { notify: true });
+     * await agent.syncToDb(db, connector, treeKey);
      * ```
      */
     static fromClient(filePath: string, treeKey: string, client: any, // Client type from \@rljson/server

package/dist/fs-agent.js

@@ -1,5 +1,5 @@
 import { BsMem } from "@rljson/bs";
-import { timeId, Route, createTreesTableCfg } from "@rljson/rljson";
+import { Route, createTreesTableCfg } from "@rljson/rljson";
 import { stat, readFile, mkdir, writeFile, readdir, utimes, rm } from "fs/promises";
 import { dirname, join, sep } from "path";
 import { hip } from "@rljson/hash";
@@ -124,7 +124,6 @@ class FsDbAdapter {
    * @returns The root tree reference
    */
   async storeFsTree(fsTree, options = {}) {
-    const { notify = false } = options;
     if (!fsTree) {
       throw new Error("fsTree cannot be null or undefined");
     }
@@ -153,37 +152,10 @@ class FsDbAdapter {
       (tree) => tree._hash !== fsTree.rootHash
     );
     trees.push(rootTree);
-    const treeTable = {
-      _type: "trees",
-      _data: trees
-    };
-    try {
-      await this.db.core.import({
-        [this.treeKey]: treeTable
-      });
-    } catch (error) {
-      throw new Error(
-        `Failed to import tree data into database: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-    const treeRootRef = trees[trees.length - 1]._hash;
-    const historyRow = {
-      timeId: timeId(),
-      route: `/${this.treeKey}/${treeRootRef}`,
-      [`${this.treeKey}Ref`]: treeRootRef
-    };
-    const historyTable = {
-      _type: "insertHistory",
-      _data: [historyRow]
-    };
-    await this.db.core.import({
-      [`${this.treeKey}InsertHistory`]: historyTable
+    const results = await this.db.insertTrees(this.treeKey, trees, {
+      skipNotification: options.skipNotification
     });
-    if (notify) {
-      const treeKeyRoute = Route.fromFlat(`/${this.treeKey}`);
-      this.db.notify.notify(treeKeyRoute, historyRow);
-    }
-    return treeRootRef;
+    return results[0][`${this.treeKey}Ref`];
   }
   /**
    * Get the tree table key
@@ -499,6 +471,14 @@ class FsScanner {
     });
   }
 }
+const DEFAULT_TIMEOUTS = {
+  dbQuery: 1e4,
+  fetchTree: 2e4,
+  extract: 15e3,
+  restore: 15e3,
+  syncCallback: 25e3,
+  debounceMs: 300
+};
 class FsAgent {
   _scanner;
   _adapter;
@@ -509,11 +489,15 @@ class FsAgent {
   _stopSync;
   _stopSyncFromDb;
   _lastSentRef;
+  /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
+  _lastSentContentKey;
+  _timeouts;
   constructor(rootPath, bs, options = {}) {
     this._rootPath = rootPath;
     this._bs = bs || new BsMem();
     this._db = options.db;
     this._treeKey = options.treeKey;
+    this._timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
     this._scanner = new FsScanner(rootPath, { ...options, bs: this._bs });
     this._adapter = new FsBlobAdapter(this._bs);
     if (this._db && this._treeKey) {
@@ -547,6 +531,51 @@ class FsAgent {
   get adapter() {
     return this._adapter;
   }
+  /**
+   * Gets the current timeout configuration
+   */
+  get timeouts() {
+    return this._timeouts;
+  }
+  /**
+   * Wraps a promise with a timeout.
+   * Rejects with a descriptive error if the promise does not settle
+   * within the given number of milliseconds.
+   * @param promise - The promise to guard
+   * @param ms - Maximum allowed time in milliseconds
+   * @param label - Human-readable label included in the error message
+   */
+  static _withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Timeout after ${ms}ms: ${label}`));
+      }, ms);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  /**
+   * Sends a ref through the connector.
+   * Uses `sendWithAck()` when the connector has `requireAck` enabled,
+   * otherwise falls back to fire-and-forget `send()`.
+   * @param connector - The Connector to send through
+   * @param ref - The ref to broadcast
+   */
+  async _sendRef(connector, ref) {
+    if (connector.syncConfig?.requireAck) {
+      await connector.sendWithAck(ref);
+    } else {
+      connector.send(ref);
+    }
+  }
   /**
    * Starts automatic syncing to database
    * Note: Auto-sync requires Connector which is not available in constructor.
@@ -727,8 +756,15 @@ class FsAgent {
       processed.add(currentHash);
       let result;
       try {
-        result = await db.get(route, { _hash: currentHash });
-      } catch {
+        result = await FsAgent._withTimeout(
+          db.get(route, { _hash: currentHash }),
+          this._timeouts.dbQuery,
+          `db.get(${treeKey}, _hash=${currentHash.slice(0, 8)}…)`
+        );
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Timeout")) {
+          throw error;
+        }
         continue;
       }
       const treeData = result?.rljson?.[treeKey];
@@ -751,24 +787,22 @@ class FsAgent {
     return Array.from(fetchedNodes.values());
   }
   /**
-   * Loads tree from database and restores to filesystem
-   * Writes to filesystem from DB trees and Bs blobs
+   * Fetches tree from database without restoring to filesystem.
+   * Separated from loadFromDb to allow content comparison before restore.
    * @param db - Database instance
    * @param treeKey - Tree table key
    * @param rootRef - Root tree reference (hash)
-   * @param targetPath - Optional target path (defaults to rootPath)
-   * @param options - Restore options
+   * @returns FsTree structure ready for restore
    */
-  async loadFromDb(db, treeKey, rootRef, targetPath, options) {
+  async _fetchTreeFromDb(db, treeKey, rootRef) {
     if (!rootRef || rootRef.trim() === "") {
       throw new Error("rootRef cannot be empty");
     }
     const route = Route.fromFlat(treeKey);
-    const allNodes = await this._fetchTreeRecursively(
-      db,
-      route,
-      treeKey,
-      rootRef
+    const allNodes = await FsAgent._withTimeout(
+      this._fetchTreeRecursively(db, route, treeKey, rootRef),
+      this._timeouts.fetchTree,
+      `fetchTree(${treeKey}@${rootRef.slice(0, 8)}…)`
     );
     if (allNodes.length === 0) {
       throw new Error(
@@ -786,10 +820,19 @@ class FsAgent {
         `Root tree node "${rootRef}" not found in tree data. Available hashes: ${Array.from(trees.keys()).slice(0, 5).join(", ")}${trees.size > 5 ? "..." : ""}`
       );
     }
-    const fsTree = {
-      rootHash: rootRef,
-      trees
-    };
+    return { rootHash: rootRef, trees };
+  }
+  /**
+   * Loads tree from database and restores to filesystem
+   * Writes to filesystem from DB trees and Bs blobs
+   * @param db - Database instance
+   * @param treeKey - Tree table key
+   * @param rootRef - Root tree reference (hash)
+   * @param targetPath - Optional target path (defaults to rootPath)
+   * @param options - Restore options
+   */
+  async loadFromDb(db, treeKey, rootRef, targetPath, options) {
+    const fsTree = await this._fetchTreeFromDb(db, treeKey, rootRef);
     await this.restore(fsTree, targetPath, options);
   }
   /**
@@ -845,33 +888,115 @@ class FsAgent {
    * @param db - Database instance
    * @param connector - Connector instance for socket-based sync
    * @param treeKey - Tree table key
-   * @param options - Storage options (e.g., notify)
+   * @param options - Storage options (e.g., skipNotification)
    * @returns Function to stop watching
    */
   async syncToDb(db, connector, treeKey, options) {
-    const initialRef = await this.storeInDb(db, treeKey, options);
+    const initialRef = await FsAgent._withTimeout(
+      this.storeInDb(db, treeKey, options),
+      this._timeouts.fetchTree,
+      `syncToDb → initial storeInDb(${treeKey})`
+    );
     if (initialRef) {
       this._lastSentRef = initialRef;
-      connector.send(initialRef);
+      const currentTree = this._scanner.tree;
+      if (currentTree) {
+        this._lastSentContentKey = this._contentKeyFromTree(currentTree);
+      }
+      await this._sendRef(connector, initialRef);
     }
-    const syncCallback = async () => {
-      const tree = this._scanner.tree;
-      if (tree) {
-        const dbAdapter = new FsDbAdapter(db, treeKey);
-        const ref = await dbAdapter.storeFsTree(tree, options);
-        this._lastSentRef = ref;
-        if (ref) {
-          connector.send(ref);
+    let debounceTimer = null;
+    const debouncedSync = () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        debounceTimer = null;
+        const tree = this._scanner.tree;
+        if (tree) {
+          try {
+            const contentKey = this._contentKeyFromTree(tree);
+            if (contentKey === this._lastSentContentKey) {
+              return;
+            }
+            const dbAdapter = new FsDbAdapter(db, treeKey);
+            const ref = await FsAgent._withTimeout(
+              dbAdapter.storeFsTree(tree, options),
+              this._timeouts.fetchTree,
+              `syncToDb → storeFsTree(${treeKey})`
+            );
+            if (ref === this._lastSentRef) {
+              return;
+            }
+            this._lastSentRef = ref;
+            this._lastSentContentKey = contentKey;
+            if (ref) {
+              await this._sendRef(connector, ref);
+            }
+          } catch {
+          }
         }
-      }
+      }, this._timeouts.debounceMs);
     };
-    this._scanner.onChange(syncCallback);
+    this._scanner.onChange(debouncedSync);
     await this._scanner.watch();
     return () => {
-      this._scanner.offChange(syncCallback);
+      if (debounceTimer) clearTimeout(debounceTimer);
+      this._scanner.offChange(debouncedSync);
       this._scanner.stopWatch();
     };
   }
+  /**
+   * Builds a map of relativePath → blobId for all files in a tree.
+   * Used to compare trees by content rather than by hash (which includes mtime).
+   * @param tree - Tree structure to extract file content map from
+   */
+  _getFileContentMap(tree) {
+    const map = /* @__PURE__ */ new Map();
+    for (const [, node] of tree.trees) {
+      const meta = node?.meta;
+      if (meta?.type === "file") {
+        map.set(meta.relativePath, meta.blobId ?? "");
+      } else if (meta?.type === "directory" && meta.relativePath !== ".") {
+        map.set(meta.relativePath, "<dir>");
+      }
+    }
+    return map;
+  }
+  /**
+   * Derives a deterministic string key from a content map so that two trees
+   * with identical file paths + blobIds produce the same key regardless of
+   * mtime differences.
+   * @param map - Content map (relativePath → blobId)
+   */
+  _contentKeyFromMap(map) {
+    const sorted = Array.from(map.entries()).sort(
+      (a, b) => a[0].localeCompare(b[0])
+    );
+    return sorted.map(([p, b]) => `${p}:${b}`).join("\n");
+  }
+  /**
+   * Derives a deterministic content key from an FsTree.
+   * @param tree - Tree structure to derive content key from
+   */
+  _contentKeyFromTree(tree) {
+    return this._contentKeyFromMap(this._getFileContentMap(tree));
+  }
+  /**
+   * Compares two trees by file content (relativePath + blobId).
+   * Ignores mtime differences — trees are equivalent if they have the same
+   * files with the same content. This prevents bounce-back restores from
+   * destroying locally-created files during bidirectional sync.
+   * @param a - First tree to compare
+   * @param b - Second tree to compare
+   */
+  _treesHaveEquivalentContent(a, b) {
+    const aFiles = this._getFileContentMap(a);
+    const bFiles = this._getFileContentMap(b);
+    if (aFiles.size !== bFiles.size) return false;
+    for (const [path, blobId] of aFiles) {
+      if (bFiles.get(path) !== blobId) return false;
+    }
+    return true;
+  }
   /**
    * Watches database for tree changes and syncs to filesystem
    * Uses Connector for socket-based notifications
@@ -885,24 +1010,60 @@ class FsAgent {
     if (!this._scanner["_watcher"]) {
       await this._scanner.watch();
     }
-    const syncCallback = async (treeRef) => {
-      if (!treeRef || typeof treeRef !== "string") {
-        return;
-      }
-      if (treeRef === this._lastSentRef) {
-        return;
-      }
+    let pendingRef = null;
+    let fromDbTimer = null;
+    const processRef = async (treeRef) => {
       this._scanner.pauseWatch();
       try {
-        await this.loadFromDb(db, treeKey, treeRef, void 0, restoreOptions);
+        const incomingTree = await FsAgent._withTimeout(
+          this._fetchTreeFromDb(db, treeKey, treeRef),
+          this._timeouts.fetchTree,
+          `syncFromDb → fetchTree(${treeKey}@${treeRef.slice(0, 8)}…)`
+        );
+        const currentTree = await FsAgent._withTimeout(
+          this.extract(),
+          this._timeouts.extract,
+          `syncFromDb → extract(${this._rootPath})`
+        );
+        if (this._treesHaveEquivalentContent(currentTree, incomingTree)) {
+          return;
+        }
+        await FsAgent._withTimeout(
+          this.restore(incomingTree, void 0, restoreOptions),
+          this._timeouts.restore,
+          `syncFromDb → restore(${treeKey})`
+        );
+        const postRestoreTree = await this._scanner.scan();
+        const dbAdapter = new FsDbAdapter(db, treeKey);
+        const postRestoreRef = await dbAdapter.storeFsTree(postRestoreTree, {
+          skipNotification: true
+        });
+        this._lastSentRef = postRestoreRef;
+        this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
       } catch {
       } finally {
         this._scanner.resumeWatch();
       }
     };
+    const syncCallback = async (treeRef) => {
+      if (!treeRef || typeof treeRef !== "string") {
+        return;
+      }
+      pendingRef = treeRef;
+      if (fromDbTimer) clearTimeout(fromDbTimer);
+      fromDbTimer = setTimeout(async () => {
+        fromDbTimer = null;
+        const ref = pendingRef;
+        pendingRef = null;
+        if (ref) {
+          await processRef(ref);
+        }
+      }, this._timeouts.debounceMs);
+    };
     connector.listen(syncCallback);
     return () => {
-      connector.teardown();
+      if (fromDbTimer) clearTimeout(fromDbTimer);
+      connector.tearDown();
     };
   }
   /**
@@ -913,16 +1074,21 @@ class FsAgent {
    * @param treeKey - Tree table key (route will be `/${treeKey}`)
    * @param client - Client instance with io and bs properties
    * @param socket - Socket instance for connector communication
-   * @param options - Optional FsAgent options (db and treeKey are set automatically)
+   * @param options - Optional FsAgent options (db and treeKey are set automatically).
+   *   `syncConfig` and `clientIdentity` from these options are forwarded to
+   *   the Connector so that a single config origin governs all layers.
    * @returns Configured FsAgent instance with simplified sync API
    * @example
    * ```typescript
-   * const agent = await FsAgent.fromClient('./my-folder', 'sharedTree', client, socket);
+   * const syncConfig: SyncConfig = { requireAck: true, maxDedupSetSize: 5000 };
+   * const agent = await FsAgent.fromClient(
+   *   './my-folder', 'sharedTree', client, socket, { syncConfig },
+   * );
    * // Simplified sync methods - no db/connector/treeKey needed
-   * await agent.syncToDbSimple({ notify: true });
+   * await agent.syncToDbSimple();
    * await agent.syncFromDbSimple({ cleanTarget: true });
    * // Original methods still work
-   * await agent.syncToDb(db, connector, treeKey, { notify: true });
+   * await agent.syncToDb(db, connector, treeKey);
    * ```
    */
   static async fromClient(filePath, treeKey, client, socket, options) {
@@ -935,7 +1101,13 @@ class FsAgent {
     const { Db: Db2, Connector } = await import("@rljson/db");
     const db = new Db2(client.io);
     const route = Route.fromFlat(`/${treeKey}`);
-    const connector = new Connector(db, route, socket);
+    const connector = new Connector(
+      db,
+      route,
+      socket,
+      options?.syncConfig,
+      options?.clientIdentity
+    );
     const agent = new FsAgent(filePath, client.bs, options);
     const enhancedAgent = agent;
     enhancedAgent.syncToDbSimple = async (syncOptions) => {
@@ -999,7 +1171,7 @@ async function runClientServerSetup(opts = {}) {
   const agentB = new FsAgent(folderB, clientB.bs);
   const helloPathA = join(folderA, "hello.txt");
   await writeFile(helloPathA, "Hello from Client A");
-  const rootRef = await agentA.storeInDb(clientDbA, treeKey, { notify: false });
+  const rootRef = await agentA.storeInDb(clientDbA, treeKey, { skipNotification: true });
   await agentB.loadFromDb(clientDbB, treeKey, rootRef);
   const contentB = await readFile(join(folderB, "hello.txt"), "utf8");
   const cleanup = async () => {

package/dist/fs-db-adapter.d.ts

@@ -5,12 +5,19 @@ import { FsTree } from './fs-scanner.js';
  */
 export interface StoreFsTreeOptions {
     /**
-     * Whether to trigger notifications after storing (defaults to false)
+     * Whether to skip notifications after storing (defaults to false).
+     * When false, observers (e.g. Connector) are notified automatically
+     * via the standard db.insertTrees() pipeline.
      */
-    notify?: boolean;
+    skipNotification?: boolean;
 }
 /**
- * Adapter for storing filesystem trees in a database
+ * Adapter for storing filesystem trees in a database.
+ *
+ * Uses `db.insertTrees()` to go through the standard insert pipeline:
+ * - TreeController writes each node
+ * - InsertHistoryRow is created automatically
+ * - `notify.notify()` fires so Connector observers broadcast the ref
  */
 export declare class FsDbAdapter {
     private db;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { FsAgent, type FsAgentOptions } from './fs-agent.ts';
+export { FsAgent, type FsAgentOptions, type RestoreOptions, type TimeoutConfig, } from './fs-agent.ts';
 export { FsBlobAdapter, type BlobToFileOptions, type FileBlobMeta, type FileToBlobOptions, } from './fs-blob-adapter.ts';
 export { FsDbAdapter, type StoreFsTreeOptions } from './fs-db-adapter.ts';
 export { FsScanner, type FsChange, type FsChangeCallback, type FsChangeType, type FsNodeMeta, type FsScanOptions, type FsTree, } from './fs-scanner.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",
@@ -20,40 +20,40 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@rljson/server": "^0.0.5",
+    "@rljson/server": "^0.0.6",
     "@types/node": "^25.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.55.0",
-    "@typescript-eslint/parser": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
     "@vitest/coverage-v8": "^4.0.18",
     "cross-env": "^10.1.0",
     "eslint": "~9.39.2",
-    "eslint-plugin-jsdoc": "^62.5.4",
+    "eslint-plugin-jsdoc": "^62.5.5",
     "eslint-plugin-tsdoc": "^0.5.0",
     "globals": "^17.3.0",
     "jsdoc": "^4.0.5",
     "read-pkg": "^10.1.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.55.0",
+    "typescript-eslint": "^8.56.0",
     "vite": "^7.3.1",
     "vite-node": "^5.3.0",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^6.1.0",
+    "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.0.18",
     "vitest-dom": "^0.1.1"
   },
   "dependencies": {
-    "@rljson/bs": "^0.0.20",
-    "@rljson/db": "^0.0.13",
+    "@rljson/bs": "^0.0.21",
+    "@rljson/db": "^0.0.14",
     "@rljson/hash": "^0.0.18",
-    "@rljson/io": "^0.0.65",
+    "@rljson/io": "^0.0.66",
     "@rljson/json": "^0.0.23",
-    "@rljson/rljson": "^0.0.75",
+    "@rljson/rljson": "^0.0.76",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3"
   },
   "scripts": {
-    "build": "pnpx vite build && tsc && node scripts/copy-readme-to-dist.js",
-    "test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpx vitest run --coverage && pnpm run lint",
+    "build": "pnpm exec vite build && tsc && node scripts/copy-readme-to-dist.js",
+    "test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpm exec vitest run --coverage && pnpm run lint",
     "prebuild": "npm run test",
     "lint": "pnpm exec eslint .",
     "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"