@rljson/fs-agent 0.0.17 → 0.0.19

package/dist/fs-agent.d.ts

@@ -112,6 +112,14 @@ export interface TimeoutConfig {
      */
     recoveryRetries?: number;
 }
+/**
+ * Longest a disconnect may keep the watcher paused.
+ *
+ * Generous enough for an ordinary reconnect, short enough that a reconnect
+ * which never arrives costs a few seconds of missed notifications rather than
+ * every write from then on.
+ */
+export declare const DISCONNECT_PAUSE_MAX_MS = 30000;
 /** Filename for sync error log written to the sync folder */
 export declare const SYNC_ERROR_FILE = ".sync-errors.log";
 /**
@@ -133,8 +141,24 @@ export declare class FsAgent {
     private _stopSync?;
     private _stopSyncFromDb?;
     private _lastSentRef?;
+    /**
+     * The incoming ref most recently applied. Retired from the connector's dedup
+     * sets when the next one supersedes it, so a peer returning the tree to that
+     * state can still reach this agent.
+     */
+    private _lastAppliedRef?;
     /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
     private _lastSentContentKey?;
+    /**
+     * True while a ref received from a peer is being applied to disk.
+     *
+     * The safety rescan cannot tell a local change the watcher missed (which it
+     * must broadcast) from a remote change not yet applied here (which it must
+     * not). The agent can: while this is set, the disk is mid-way through
+     * someone else's revision, so a rescan-driven push would re-assert our stale
+     * view — and undo a deletion the peer just made.
+     */
+    private _remoteApplyInFlight;
     private _timeouts;
     /** Client-only: resolve DAG-branch conflicts into merge revisions. */
     private _resolveConflicts;
@@ -400,6 +424,25 @@ export declare class FsAgent {
      * @param map - Content map (relativePath → blobId)
      */
     private _contentKeyFromMap;
+    /**
+     * Records `treeRef` as the ref describing this folder's current state, and
+     * retires the one it supersedes from the connector's dedup sets.
+     *
+     * A tree ref is a pure content hash, so a folder that returns to an earlier
+     * state re-derives that state's exact ref. The connector drops an incoming
+     * ref it has already received, which assumes a state is reached once and
+     * never returned to — false for content-addressed state, and false in the
+     * most ordinary way possible: create a file, then delete it again.
+     *
+     * Retiring the SUPERSEDED ref is what keeps the return trip deliverable.
+     * The ref just adopted stays deduped, so a peer re-advertising the state
+     * this folder is actually in is still suppressed as the echo it is. That
+     * only works if every adopted state passes through here — a state adopted
+     * silently is never retired and blocks its own return for good.
+     * @param connector - Connector whose dedup sets to retire from.
+     * @param treeRef - The ref that now describes this folder.
+     */
+    private _adoptAppliedRef;
     /**
      * Derives a deterministic content key from an FsTree.
      * @param tree - Tree structure to derive content key from

package/dist/fs-agent.js

@@ -413,6 +413,9 @@ class FsDbAdapter {
     return this.db;
   }
 }
+const _envRescan = Number(process.env["RLJSON_FS_RESCAN_MS"]);
+const SAFETY_RESCAN_INTERVAL_MS = Number.isFinite(_envRescan) && _envRescan > 0 ? _envRescan : 5e3;
+const STUCK_PAUSE_MS = 15e3;
 class FsScanner {
   _rootPath;
   _tree = null;
@@ -424,6 +427,10 @@ class FsScanner {
   _missedChangesDuringPause = false;
   /** Periodic full-rescan timer that catches events the native watcher drops. */
   _safetyTimer = null;
+  /** When the current pause began, or null when not paused. */
+  _pausedAt = null;
+  /** Releases a pause whose resume never arrived (see {@link pauseWatch}). */
+  _autoResumeTimer = null;
   /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
   _stopRequested = false;
   /** Path→content cache backing {@link FsScanOptions.scanCachePath} (unused when unset). */
@@ -697,7 +704,7 @@ class FsScanner {
     if (!this._safetyTimer) {
       this._safetyTimer = setInterval(() => {
         void this._runSafetyRescan();
-      }, 3e4);
+      }, SAFETY_RESCAN_INTERVAL_MS);
       this._safetyTimer.unref?.();
     }
   }
@@ -708,7 +715,10 @@ class FsScanner {
    * scan failures are no-ops.
    */
   async _runSafetyRescan() {
-    if (this._paused || this._stopRequested) return;
+    if (this._stopRequested) return;
+    if (this._paused && !this._pauseLooksStuck({ type: "safety-rescan", path: "." })) {
+      return;
+    }
     const prevKey = this._tree ? this._safetyContentKey(this._tree) : null;
     try {
       await this.scan();
@@ -718,7 +728,7 @@ class FsScanner {
       );
       return;
     }
-    if (this._paused || this._stopRequested) return;
+    if (this._stopRequested) return;
     const nextKey = this._tree ? this._safetyContentKey(this._tree) : null;
     if (prevKey !== nextKey) {
       console.warn(
@@ -819,8 +829,24 @@ class FsScanner {
     }
     return void 0;
   }
+  /**
+   * Whether this notification should escape the pause.
+   *
+   * Only the safety rescan may, and only once the pause has outlasted any
+   * plausible restore. Letting it through a SHORT pause reintroduces exactly
+   * the echo the pause prevents — a rescan firing mid-restore notifies, the
+   * agent stores a tree built from half-restored files, and delete propagation
+   * breaks (caught by the client-server suite, not by unit tests).
+   * @param change - The pending notification.
+   * @returns `true` when the pause has lasted long enough to look stuck.
+   */
+  _pauseLooksStuck(change) {
+    if (change.type !== "safety-rescan") return false;
+    if (this._pausedAt === null) return false;
+    return Date.now() - this._pausedAt >= STUCK_PAUSE_MS;
+  }
   async _notifyChange(change) {
-    if (this._paused) {
+    if (this._paused && !this._pauseLooksStuck(change)) {
       return;
     }
     for (const callback of this._changeCallbacks) {
@@ -837,6 +863,10 @@ class FsScanner {
   }
   stopWatch() {
     this._stopRequested = true;
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
     if (this._safetyTimer) {
       clearInterval(this._safetyTimer);
       this._safetyTimer = null;
@@ -847,12 +877,37 @@ class FsScanner {
     }
   }
   /**
-   * Temporarily pause file change notifications
-   * Used to prevent loops when updating filesystem from external source
+   * Temporarily pause file change notifications, so an external restore does
+   * not loop back as a local change.
+   *
+   * `autoResumeMs` bounds the pause. A pause taken on socket disconnect is
+   * released by the matching reconnect — and when that reconnect never fires,
+   * an unbounded pause silences the node permanently. A bounded one degrades
+   * to a little duplicate work instead, which is the right way round: the
+   * loop-suppression this exists for is an optimisation, staying alive is not.
+   * @param autoResumeMs - Release the pause after this many milliseconds.
+   *   Omit to pause until an explicit `resumeWatch()`.
    */
-  pauseWatch() {
+  pauseWatch(autoResumeMs) {
+    if (!this._paused) this._pausedAt = Date.now();
     this._paused = true;
     this._missedChangesDuringPause = false;
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
+    if (autoResumeMs !== void 0) {
+      this._autoResumeTimer = setTimeout(() => {
+        this._autoResumeTimer = null;
+        if (this._paused) {
+          console.warn(
+            `[fs-scanner] pause exceeded ${autoResumeMs}ms without a resume — releasing it so ${this._rootPath} keeps syncing`
+          );
+          this.resumeWatch();
+        }
+      }, autoResumeMs);
+      this._autoResumeTimer.unref?.();
+    }
   }
   /**
    * Resume file change notifications.
@@ -860,8 +915,13 @@ class FsScanner {
    * an asynchronous rescan so that syncToDb can detect and push the changes.
    */
   resumeWatch() {
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
     const missedChanges = this._missedChangesDuringPause;
     this._paused = false;
+    this._pausedAt = null;
     this._missedChangesDuringPause = false;
     if (missedChanges) {
       void this._rescanAfterPause();
@@ -921,6 +981,7 @@ const DEFAULT_TIMEOUTS = {
   processRefRetryDelayMs: 5e3,
   recoveryRetries: 10
 };
+const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 class FsAgent {
@@ -933,8 +994,24 @@ class FsAgent {
   _stopSync;
   _stopSyncFromDb;
   _lastSentRef;
+  /**
+   * The incoming ref most recently applied. Retired from the connector's dedup
+   * sets when the next one supersedes it, so a peer returning the tree to that
+   * state can still reach this agent.
+   */
+  _lastAppliedRef;
   /** Content fingerprint of the last tree we broadcasted (paths+blobIds) */
   _lastSentContentKey;
+  /**
+   * True while a ref received from a peer is being applied to disk.
+   *
+   * The safety rescan cannot tell a local change the watcher missed (which it
+   * must broadcast) from a remote change not yet applied here (which it must
+   * not). The agent can: while this is set, the disk is mid-way through
+   * someone else's revision, so a rescan-driven push would re-assert our stale
+   * view — and undo a deletion the peer just made.
+   */
+  _remoteApplyInFlight = false;
   _timeouts;
   /** Client-only: resolve DAG-branch conflicts into merge revisions. */
   _resolveConflicts;
@@ -1119,6 +1196,7 @@ ${err.stack}` : String(err);
    *   via an explicit send, which pre-empts the Connector's db-observer path.
    */
   async _sendRef(connector, ref, predecessorRefs) {
+    connector.invalidateSent?.(ref);
     if (this._resolveConflicts) {
       connector.setPredecessors(predecessorRefs ?? []);
     }
@@ -1530,7 +1608,10 @@ ${err.stack}` : String(err);
       );
     }
     let debounceTimer = null;
-    const debouncedSync = () => {
+    const debouncedSync = (change) => {
+      if (change?.type === "safety-rescan" && this._remoteApplyInFlight) {
+        return;
+      }
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(async () => {
         debounceTimer = null;
@@ -1719,6 +1800,30 @@ ${err.stack}` : String(err);
     );
     return sorted.map(([p, b]) => `${p}:${b}`).join("\n");
   }
+  /**
+   * Records `treeRef` as the ref describing this folder's current state, and
+   * retires the one it supersedes from the connector's dedup sets.
+   *
+   * A tree ref is a pure content hash, so a folder that returns to an earlier
+   * state re-derives that state's exact ref. The connector drops an incoming
+   * ref it has already received, which assumes a state is reached once and
+   * never returned to — false for content-addressed state, and false in the
+   * most ordinary way possible: create a file, then delete it again.
+   *
+   * Retiring the SUPERSEDED ref is what keeps the return trip deliverable.
+   * The ref just adopted stays deduped, so a peer re-advertising the state
+   * this folder is actually in is still suppressed as the echo it is. That
+   * only works if every adopted state passes through here — a state adopted
+   * silently is never retired and blocks its own return for good.
+   * @param connector - Connector whose dedup sets to retire from.
+   * @param treeRef - The ref that now describes this folder.
+   */
+  _adoptAppliedRef(connector, treeRef) {
+    if (this._lastAppliedRef && this._lastAppliedRef !== treeRef) {
+      connector.invalidateSent?.(this._lastAppliedRef);
+    }
+    this._lastAppliedRef = treeRef;
+  }
   /**
    * Derives a deterministic content key from an FsTree.
    * @param tree - Tree structure to derive content key from
@@ -1809,6 +1914,7 @@ ${err.stack}` : String(err);
       const maxAttempts = this._timeouts.processRefRetries + 1;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         this._scanner.pauseWatch();
+        this._remoteApplyInFlight = true;
         try {
           const incomingTree = await FsAgent._withTimeout(
             this._fetchTreeFromDb(db, treeKey, treeRef),
@@ -1830,6 +1936,7 @@ ${err.stack}` : String(err);
             console.log(
               `[FsAgent] syncFromDb: equivalent content, skipping restore (incoming=${incomingFiles.size} entries, current=${currentFiles.size} entries, ref=${treeRef.slice(0, 8)}…)`
             );
+            this._adoptAppliedRef(connector, treeRef);
             return;
           }
           if (this._resolveConflicts && this._currentRef && predecessorRefs && predecessorRefs.length > 0) {
@@ -1870,6 +1977,7 @@ ${err.stack}` : String(err);
             skipNotification: true,
             previous
           });
+          this._adoptAppliedRef(connector, treeRef);
           this._lastSentRef = postRestoreRef;
           this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
           this._currentRef = postRestoreRef;
@@ -1903,6 +2011,7 @@ ${err.stack}` : String(err);
             );
           }
         } finally {
+          this._remoteApplyInFlight = false;
           this._scanner.resumeWatch();
         }
         await new Promise(
@@ -1911,6 +2020,9 @@ ${err.stack}` : String(err);
       }
     };
     const scheduleProcess = (ref, delayMs, recoveryAttempt, predecessorRefs) => {
+      if (pendingRef && pendingRef !== ref) {
+        connector.invalidateReceived(pendingRef);
+      }
       pendingRef = ref;
       pendingRecoveryAttempt = recoveryAttempt;
       pendingPredecessorRefs = predecessorRefs;
@@ -1991,7 +2103,7 @@ ${err.stack}` : String(err);
     };
     if (typeof client.onDisconnect === "function") {
       client.onDisconnect(() => {
-        agent.scanner.pauseWatch();
+        agent.scanner.pauseWatch(DISCONNECT_PAUSE_MAX_MS);
       });
     }
     if (typeof client.onReconnect === "function") {

package/dist/fs-scanner.d.ts

@@ -1,6 +1,16 @@
 import { Bs } from '@rljson/bs';
 import { Json } from '@rljson/json';
 import { Tree, TreeRef } from '@rljson/rljson';
+export declare const SAFETY_RESCAN_INTERVAL_MS: number;
+/**
+ * How long a pause must last before the safety rescan treats it as stuck and
+ * reports through it.
+ *
+ * Longer than any restore takes, so ordinary loop-suppression is untouched;
+ * short enough that a pause whose resume never arrives costs seconds, not
+ * every write from then on.
+ */
+export declare const STUCK_PAUSE_MS = 15000;
 /**
  * Metadata stored in Tree.meta for file system nodes
  */
@@ -93,6 +103,10 @@ export declare class FsScanner {
     private _missedChangesDuringPause;
     /** Periodic full-rescan timer that catches events the native watcher drops. */
     private _safetyTimer;
+    /** When the current pause began, or null when not paused. */
+    private _pausedAt;
+    /** Releases a pause whose resume never arrived (see {@link pauseWatch}). */
+    private _autoResumeTimer;
     /** Set by stopWatch() so a pending watcher reinstall / rescan bails out. */
     private _stopRequested;
     /** Path→content cache backing {@link FsScanOptions.scanCachePath} (unused when unset). */
@@ -146,15 +160,35 @@ export declare class FsScanner {
     private static get _isWindows();
     private _handleFileChange;
     private _findTreeByPath;
+    /**
+     * Whether this notification should escape the pause.
+     *
+     * Only the safety rescan may, and only once the pause has outlasted any
+     * plausible restore. Letting it through a SHORT pause reintroduces exactly
+     * the echo the pause prevents — a rescan firing mid-restore notifies, the
+     * agent stores a tree built from half-restored files, and delete propagation
+     * breaks (caught by the client-server suite, not by unit tests).
+     * @param change - The pending notification.
+     * @returns `true` when the pause has lasted long enough to look stuck.
+     */
+    private _pauseLooksStuck;
     private _notifyChange;
     onChange(callback: FsChangeCallback): void;
     offChange(callback: FsChangeCallback): void;
     stopWatch(): void;
     /**
-     * Temporarily pause file change notifications
-     * Used to prevent loops when updating filesystem from external source
+     * Temporarily pause file change notifications, so an external restore does
+     * not loop back as a local change.
+     *
+     * `autoResumeMs` bounds the pause. A pause taken on socket disconnect is
+     * released by the matching reconnect — and when that reconnect never fires,
+     * an unbounded pause silences the node permanently. A bounded one degrades
+     * to a little duplicate work instead, which is the right way round: the
+     * loop-suppression this exists for is an optimisation, staying alive is not.
+     * @param autoResumeMs - Release the pause after this many milliseconds.
+     *   Omit to pause until an explicit `resumeWatch()`.
      */
-    pauseWatch(): void;
+    pauseWatch(autoResumeMs?: number): void;
     /**
      * Resume file change notifications.
      * If any filesystem events were missed during the pause, triggers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",
@@ -28,7 +28,7 @@
     "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
   },
   "devDependencies": {
-    "@rljson/server": "^0.0.10",
+    "@rljson/server": "^0.0.43",
     "@types/node": "^25.3.1",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@rljson/bs": "^0.0.21",
-    "@rljson/db": "^0.0.23",
+    "@rljson/db": "^0.0.31",
     "@rljson/hash": "^0.0.18",
     "@rljson/io": "^0.0.66",
     "@rljson/json": "^0.0.23",