@rljson/fs-agent 0.0.39 → 0.0.41

package/dist/fs-agent.d.ts

@@ -176,6 +176,15 @@ export declare const TREE_FETCH_CONCURRENCY = 64;
  * which is the cheap half of the trade.
  */
 export declare const RESTORED_BLOB_MEMORY_MAX = 50000;
+/**
+ * What an agent concluded about an inbound ref.
+ *
+ * See `FsAgent._inboundRefVerdict` for why this is one decision rather than
+ * several conditions.
+ */
+export type InboundRefVerdict = 'apply' | 'own-echo' | 'stale';
+/** How each non-applying verdict reads in a log line. */
+export declare const VERDICT_REASON: Record<Exclude<InboundRefVerdict, 'apply'>, string>;
 export declare const MASS_DELETE_MIN_FILES = 100;
 /**
  * Above this share of the folder, a prune is treated as suspicious rather than
@@ -254,6 +263,16 @@ export declare class FsAgent {
      * view — and undo a deletion the peer just made.
      */
     private _remoteApplyInFlight;
+    /**
+     * Whether a safety rescan was suppressed while a remote apply was running.
+     *
+     * The rescan is what covers a watcher that drops or coalesces events, so a
+     * suppressed one has to be re-run rather than forgotten — see the deferral in
+     * `syncToDb`'s change handler.
+     */
+    private _rescanDeferred;
+    /** Re-runs a deferred rescan once the apply that blocked it has finished. */
+    private _flushDeferredRescan;
     /** Files written vs left alone by the current {@link restore}. */
     private _restoreWritten;
     private _restoreSkipped;
@@ -653,6 +672,48 @@ export declare class FsAgent {
      * @returns `true` when the tree carries no entries at all.
      */
     private _treeIsEmpty;
+    /**
+     * Whether an inbound ref is news to this agent, and if not, why.
+     *
+     * "Is this ref news to me" is the question this subsystem keeps getting
+     * wrong. It has been answered in five separate places — the connector's sent
+     * and received dedup sets, `_lastSentContentKey`, `_lastSentRef`,
+     * `_lastAppliedRef` — and each has been wrong at least once:
+     *
+     *  - an agent applied its OWN last advertisement over its own newer edit,
+     *    destroying it and then declining to re-send (fixed 0.0.30);
+     *  - a delete propagated only from the client that had created the file,
+     *    because the send path never retired the state it left (0.0.31);
+     *  - a refusal consumed the ref it refused, so the same emptiness arriving
+     *    twice was silent the second time (0.0.33);
+     *  - a restarted agent inherited its predecessor's conclusions (0.0.34);
+     *  - a quiet join announced anyway, because the connector broadcasts on
+     *    local insert and the gate was on the send (0.0.38).
+     *
+     * Collecting the pre-fetch gates here does not fix a sixth. It makes the
+     * question answerable in one place, in one order, with the reasoning
+     * attached — which is what the previous five each lacked.
+     *
+     * Order matters and is deliberate. The own-echo check comes first because it
+     * is the only one that holds regardless of what the sender believes: the two
+     * defences that ought to catch an echo both miss it. The origin filter
+     * compares the payload's origin to this connector's, and a bootstrap carries
+     * the SERVER as origin rather than the client the ref came from; the
+     * staleness check then measures the server's sequence, which did advance, so
+     * the echo reads as news.
+     *
+     * KNOWN LIMIT, stated because the next person will meet it: this compares
+     * against the LAST ref this agent sent, so an echo of an OLDER
+     * self-originated ref still gets through. Widening it to a set would also
+     * suppress a peer's legitimate revert to a state this agent once held. The
+     * real fix is for the bootstrap to carry the originating client, so the
+     * origin filter works and this check stops being needed at all.
+     * @param treeRef - The inbound ref.
+     * @param isNewestFromSender - Whether the connector judged it the newest
+     *   thing its sender has advertised. Unknown answers `true`.
+     * @returns `apply`, or the reason it is not news.
+     */
+    private _inboundRefVerdict;
     private _adoptAppliedRef;
     /**
      * Derives a deterministic content key from an FsTree.

package/dist/fs-agent.js

@@ -1030,6 +1030,10 @@ const AGENT_STATE_FILE = ".fsagent-state.json";
 const REFUSAL_ANSWER_COOLDOWN_MS = 5e3;
 const TREE_FETCH_CONCURRENCY = 64;
 const RESTORED_BLOB_MEMORY_MAX = 5e4;
+const VERDICT_REASON = {
+  "own-echo": "is this agent's own last advertisement echoed back",
+  stale: "is not the newest its sender has advertised"
+};
 const MASS_DELETE_MIN_FILES = 100;
 const MASS_DELETE_MAX_RATIO = 0.3;
 class RestoreIncompleteError extends Error {
@@ -1086,6 +1090,16 @@ class FsAgent {
    * view — and undo a deletion the peer just made.
    */
   _remoteApplyInFlight = false;
+  /**
+   * Whether a safety rescan was suppressed while a remote apply was running.
+   *
+   * The rescan is what covers a watcher that drops or coalesces events, so a
+   * suppressed one has to be re-run rather than forgotten — see the deferral in
+   * `syncToDb`'s change handler.
+   */
+  _rescanDeferred = false;
+  /** Re-runs a deferred rescan once the apply that blocked it has finished. */
+  _flushDeferredRescan;
   /** Files written vs left alone by the current {@link restore}. */
   _restoreWritten = 0;
   _restoreSkipped = 0;
@@ -1928,8 +1942,14 @@ ${err.stack}` : String(err);
       );
     }
     let debounceTimer = null;
+    this._flushDeferredRescan = () => {
+      if (!this._rescanDeferred) return;
+      this._rescanDeferred = false;
+      debouncedSync({ type: "safety-rescan" });
+    };
     const debouncedSync = (change) => {
       if (change?.type === "safety-rescan" && this._remoteApplyInFlight) {
+        this._rescanDeferred = true;
         return;
       }
       if (debounceTimer) clearTimeout(debounceTimer);
@@ -2183,6 +2203,52 @@ ${err.stack}` : String(err);
   _treeIsEmpty(tree) {
     return this._getFileContentMap(tree).size === 0;
   }
+  /**
+   * Whether an inbound ref is news to this agent, and if not, why.
+   *
+   * "Is this ref news to me" is the question this subsystem keeps getting
+   * wrong. It has been answered in five separate places — the connector's sent
+   * and received dedup sets, `_lastSentContentKey`, `_lastSentRef`,
+   * `_lastAppliedRef` — and each has been wrong at least once:
+   *
+   *  - an agent applied its OWN last advertisement over its own newer edit,
+   *    destroying it and then declining to re-send (fixed 0.0.30);
+   *  - a delete propagated only from the client that had created the file,
+   *    because the send path never retired the state it left (0.0.31);
+   *  - a refusal consumed the ref it refused, so the same emptiness arriving
+   *    twice was silent the second time (0.0.33);
+   *  - a restarted agent inherited its predecessor's conclusions (0.0.34);
+   *  - a quiet join announced anyway, because the connector broadcasts on
+   *    local insert and the gate was on the send (0.0.38).
+   *
+   * Collecting the pre-fetch gates here does not fix a sixth. It makes the
+   * question answerable in one place, in one order, with the reasoning
+   * attached — which is what the previous five each lacked.
+   *
+   * Order matters and is deliberate. The own-echo check comes first because it
+   * is the only one that holds regardless of what the sender believes: the two
+   * defences that ought to catch an echo both miss it. The origin filter
+   * compares the payload's origin to this connector's, and a bootstrap carries
+   * the SERVER as origin rather than the client the ref came from; the
+   * staleness check then measures the server's sequence, which did advance, so
+   * the echo reads as news.
+   *
+   * KNOWN LIMIT, stated because the next person will meet it: this compares
+   * against the LAST ref this agent sent, so an echo of an OLDER
+   * self-originated ref still gets through. Widening it to a set would also
+   * suppress a peer's legitimate revert to a state this agent once held. The
+   * real fix is for the bootstrap to carry the originating client, so the
+   * origin filter works and this check stops being needed at all.
+   * @param treeRef - The inbound ref.
+   * @param isNewestFromSender - Whether the connector judged it the newest
+   *   thing its sender has advertised. Unknown answers `true`.
+   * @returns `apply`, or the reason it is not news.
+   */
+  _inboundRefVerdict(treeRef, isNewestFromSender) {
+    if (treeRef === this._lastSentRef) return "own-echo";
+    if (!isNewestFromSender) return "stale";
+    return "apply";
+  }
   _adoptAppliedRef(connector, treeRef) {
     if (this._lastAppliedRef && this._lastAppliedRef !== treeRef) {
       connector.invalidateSent?.(this._lastAppliedRef);
@@ -2278,17 +2344,14 @@ ${err.stack}` : String(err);
     const processRef = async (treeRef, recoveryAttempt = 0, predecessorRefs, isNewestFromSender = true) => {
       const maxAttempts = this._timeouts.processRefRetries + 1;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        if (treeRef === this._lastSentRef) {
+        const verdict = this._inboundRefVerdict(treeRef, isNewestFromSender);
+        if (verdict !== "apply") {
           console.warn(
-            `[FsAgent] ref=${treeRef.slice(0, 8)}… is this agent's own last advertisement echoed back — ignoring it.`
+            `[FsAgent] ref=${treeRef.slice(0, 8)}… ${VERDICT_REASON[verdict]} — ignoring it.`
           );
-          return;
-        }
-        if (!isNewestFromSender) {
-          console.warn(
-            `[FsAgent] ref=${treeRef.slice(0, 8)}… is not the newest its sender has advertised — ignoring it.`
-          );
-          connector.invalidateReceived(treeRef);
+          if (verdict === "stale") {
+            connector.invalidateReceived(treeRef);
+          }
           return;
         }
         this._scanner.pauseWatch();
@@ -2412,6 +2475,7 @@ ${err.stack}` : String(err);
         } finally {
           this._remoteApplyInFlight = false;
           this._scanner.resumeWatch();
+          this._flushDeferredRescan?.();
         }
         await new Promise(
           (r) => setTimeout(r, attempt * this._timeouts.processRefRetryDelayMs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",
@@ -19,6 +19,14 @@
     "dist"
   ],
   "type": "module",
+  "scripts": {
+    "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",
+    "prepublishOnly": "npm run build",
+    "lint": "pnpm exec eslint .",
+    "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
+  },
   "devDependencies": {
     "@rljson/server": "^0.0.43",
     "@types/node": "^25.3.1",
@@ -51,11 +59,13 @@
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3"
   },
-  "scripts": {
-    "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"
-  }
-}
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ],
+    "overrides": {
+      "@rljson/rljson": "^0.0.78"
+    }
+  },
+  "packageManager": "pnpm@10.11.0"
+}