@rljson/fs-agent 0.0.25 → 0.0.27

package/dist/fs-agent.d.ts

@@ -128,6 +128,16 @@ export declare const SYNC_ERROR_FILE = ".sync-errors.log";
  * pollutes the tree or churns the watcher.
  */
 export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
+/**
+ * Filename for the agent's own state, kept beside the synced folder's content
+ * and ignored by the scanner like the other two above.
+ *
+ * It holds one thing: the ref this folder was last known to be at. That
+ * survives a restart, which is the whole point — a process that comes back
+ * with no idea what it descends from cannot declare ancestry, and a push with
+ * no ancestry is one every peer has to treat as untrustworthy for deletion.
+ */
+export declare const AGENT_STATE_FILE = ".fsagent-state.json";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -255,6 +265,36 @@ export declare class FsAgent {
      * Gets the current timeout configuration
      */
     get timeouts(): Required<TimeoutConfig>;
+    /**
+     * Records the ref this folder is now at, so a restart can still say what it
+     * descends from.
+     *
+     * Best-effort on purpose: losing it costs ancestry on the next start, which
+     * degrades to an additive-only apply rather than to anything unsafe, so it
+     * must never be worth failing a sync over.
+     * @param ref - The ref the folder is now at.
+     */
+    /**
+     * Starts the watcher unless it is already running.
+     *
+     * Both `syncToDb` and `syncFromDb` need a live watcher and either may be
+     * started first. `syncToDb` used to call `watch()` unconditionally, so
+     * starting them in the order `syncFromDb` then `syncToDb` threw "Already
+     * watching" — which quietly forced every caller into push-first, the order
+     * that lets a reconnecting client overwrite the network with a stale tree.
+     * A crash is a poor reason to choose an unsafe order.
+     */
+    private _ensureWatching;
+    private _persistCurrentRef;
+    /**
+     * The ref this folder was last recorded at, from a previous run.
+     *
+     * Absent, unreadable and malformed all mean the same thing — this process
+     * cannot vouch for what it descends from — and all answer `undefined`, which
+     * the caller treats as "declare no ancestry".
+     * @returns The persisted ref, or `undefined`.
+     */
+    private _loadPersistedRef;
     /**
      * Appends a sync error entry to the error log file in the sync folder.
      * Uses synchronous I/O to guarantee the write completes even in catch blocks.

package/dist/fs-agent.js

@@ -1,6 +1,6 @@
 import { BsMem } from "@rljson/bs";
 import { Route, createTreesTableCfg } from "@rljson/rljson";
-import { watch, appendFileSync } from "fs";
+import { watch, writeFileSync, existsSync, readFileSync, appendFileSync } from "fs";
 import { stat, readFile, mkdir, writeFile, readdir, rename, unlink, utimes, rm } from "fs/promises";
 import { dirname, join } from "path";
 import { hip } from "@rljson/hash";
@@ -458,6 +458,10 @@ class FsScanner {
   get tree() {
     return this._tree;
   }
+  /** Whether a watcher is currently installed. */
+  get isWatching() {
+    return this._watcher !== null;
+  }
   get rootPath() {
     return this._rootPath;
   }
@@ -1022,6 +1026,7 @@ const DEFAULT_TIMEOUTS = {
 const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
+const AGENT_STATE_FILE = ".fsagent-state.json";
 const MASS_DELETE_MIN_FILES = 100;
 const MASS_DELETE_MAX_RATIO = 0.3;
 class RestoreIncompleteError extends Error {
@@ -1105,7 +1110,12 @@ class FsAgent {
     this._resolveConflicts = options.resolveConflicts ?? false;
     this._scanner = new FsScanner(rootPath, {
       ...options,
-      ignore: [...options.ignore || [], SYNC_ERROR_FILE, ATOMIC_TMP_PREFIX],
+      ignore: [
+        ...options.ignore || [],
+        SYNC_ERROR_FILE,
+        ATOMIC_TMP_PREFIX,
+        AGENT_STATE_FILE
+      ],
       bs: this._bs
     });
     this._adapter = new FsBlobAdapter(this._bs);
@@ -1146,6 +1156,60 @@ class FsAgent {
   get timeouts() {
     return this._timeouts;
   }
+  /**
+   * Records the ref this folder is now at, so a restart can still say what it
+   * descends from.
+   *
+   * Best-effort on purpose: losing it costs ancestry on the next start, which
+   * degrades to an additive-only apply rather than to anything unsafe, so it
+   * must never be worth failing a sync over.
+   * @param ref - The ref the folder is now at.
+   */
+  /**
+   * Starts the watcher unless it is already running.
+   *
+   * Both `syncToDb` and `syncFromDb` need a live watcher and either may be
+   * started first. `syncToDb` used to call `watch()` unconditionally, so
+   * starting them in the order `syncFromDb` then `syncToDb` threw "Already
+   * watching" — which quietly forced every caller into push-first, the order
+   * that lets a reconnecting client overwrite the network with a stale tree.
+   * A crash is a poor reason to choose an unsafe order.
+   */
+  async _ensureWatching() {
+    if (!this._scanner.isWatching) {
+      await this._scanner.watch();
+    }
+  }
+  _persistCurrentRef(ref) {
+    try {
+      writeFileSync(
+        join(this._rootPath, AGENT_STATE_FILE),
+        JSON.stringify({ currentRef: ref }),
+        "utf-8"
+      );
+    } catch {
+    }
+  }
+  /**
+   * The ref this folder was last recorded at, from a previous run.
+   *
+   * Absent, unreadable and malformed all mean the same thing — this process
+   * cannot vouch for what it descends from — and all answer `undefined`, which
+   * the caller treats as "declare no ancestry".
+   * @returns The persisted ref, or `undefined`.
+   */
+  _loadPersistedRef() {
+    try {
+      const file = join(this._rootPath, AGENT_STATE_FILE);
+      if (!existsSync(file)) return void 0;
+      const parsed = JSON.parse(readFileSync(file, "utf-8"));
+      if (!parsed || typeof parsed !== "object") return void 0;
+      const ref = parsed.currentRef;
+      return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Appends a sync error entry to the error log file in the sync folder.
    * Uses synchronous I/O to guarantee the write completes even in catch blocks.
@@ -1791,6 +1855,15 @@ ${err.stack}` : String(err);
    * @returns Function to stop watching
    */
   async syncToDb(db, connector, treeKey, options) {
+    if (this._currentRef === void 0) {
+      const persisted = this._loadPersistedRef();
+      if (persisted !== void 0) {
+        this._currentRef = persisted;
+        console.log(
+          `[FsAgent] resuming from recorded ref ${persisted.slice(0, 8)}… — this folder can declare its ancestry`
+        );
+      }
+    }
     const initialParentRef = this._currentRef;
     const initialTree = await FsAgent._withTimeout(
       this.extract(),
@@ -1810,6 +1883,7 @@ ${err.stack}` : String(err);
     if (initialRef) {
       this._lastSentRef = initialRef;
       this._currentRef = initialRef;
+      this._persistCurrentRef(initialRef);
       this._lastSentContentKey = this._contentKeyFromTree(initialTree);
       await this._sendRef(
         connector,
@@ -1850,6 +1924,8 @@ ${err.stack}` : String(err);
               `syncToDb storeFsTree(${treeKey})`
             );
             this._currentRef = ref;
+            this._persistCurrentRef(ref);
+            this._persistCurrentRef(ref);
             if (ref === this._lastSentRef) {
               return;
             }
@@ -1870,7 +1946,7 @@ ${err.stack}` : String(err);
       }, this._timeouts.debounceMs);
     };
     this._scanner.onChange(debouncedSync);
-    await this._scanner.watch();
+    await this._ensureWatching();
     return () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       this._scanner.offChange(debouncedSync);
@@ -2113,9 +2189,7 @@ ${err.stack}` : String(err);
    * @returns Function to stop watching
    */
   async syncFromDb(db, connector, treeKey, restoreOptions) {
-    if (!this._scanner["_watcher"]) {
-      await this._scanner.watch();
-    }
+    await this._ensureWatching();
     let pendingRef = null;
     let fromDbTimer = null;
     let pendingRecoveryAttempt = 0;
@@ -2171,8 +2245,16 @@ ${err.stack}` : String(err);
               return;
             }
           }
+          const ancestryExpected = this._resolveConflicts;
+          const declaresAncestry = (predecessorRefs?.length ?? 0) > 0;
+          const applyOptions = restoreOptions?.cleanTarget && ancestryExpected && !declaresAncestry ? { ...restoreOptions, cleanTarget: false } : restoreOptions;
+          if (applyOptions !== restoreOptions) {
+            console.warn(
+              `[FsAgent] ref=${treeRef.slice(0, 8)}… declares no ancestry — applying additively, not pruning. A sender that cannot say what it descends from must not delete.`
+            );
+          }
           await FsAgent._withTimeout(
-            this.restore(incomingTree, void 0, restoreOptions),
+            this.restore(incomingTree, void 0, applyOptions),
             this._timeouts.restore,
             `syncFromDb → restore(${treeKey})`
           );
@@ -2191,6 +2273,7 @@ ${err.stack}` : String(err);
           this._lastSentRef = postRestoreRef;
           this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
           this._currentRef = postRestoreRef;
+          this._persistCurrentRef(postRestoreRef);
           return;
         } catch (err) {
           if (err instanceof MassDeleteRefusedError) {

package/dist/fs-scanner.d.ts

@@ -121,6 +121,8 @@ export declare class FsScanner {
     private _vanishedDuringScan;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
+    /** Whether a watcher is currently installed. */
+    get isWatching(): boolean;
     get rootPath(): string;
     get bs(): Bs;
     scan(): Promise<FsTree>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",