@rljson/fs-agent 0.0.38 → 0.0.40

package/dist/fs-agent.d.ts

@@ -166,6 +166,25 @@ export declare const REFUSAL_ANSWER_COOLDOWN_MS = 5000;
  * which trades a latency problem for a queueing one.
  */
 export declare const TREE_FETCH_CONCURRENCY = 64;
+/**
+ * How many restored paths an agent remembers writing.
+ *
+ * The memory exists so a repeat restore recognises this agent's own work
+ * without re-reading the file. Nothing ever removed an entry, so a long-lived
+ * agent over a large catalogue held one per file it had ever written. Dropping
+ * the oldest costs a stat on a file that has not been touched in a long time,
+ * 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
@@ -501,7 +520,7 @@ export declare class FsAgent {
      * @param route - Route to tree table
      * @param treeKey - Tree table key
      * @param rootHash - Hash of the root node to start fetching from
-     * @returns Array of all tree nodes in the tree
+     * @returns Every node in the tree, keyed by its content hash
      */
     private _fetchTreeRecursively;
     /**
@@ -643,6 +662,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

@@ -1029,6 +1029,11 @@ const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 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 {
@@ -1534,6 +1539,10 @@ ${err.stack}` : String(err);
             await utimes(filePath, mtime, mtime);
           }
           if (meta.size !== void 0 && meta.mtime !== void 0) {
+            if (this._restoredBlobs.size >= RESTORED_BLOB_MEMORY_MAX) {
+              const oldest = this._restoredBlobs.keys().next().value;
+              this._restoredBlobs.delete(oldest);
+            }
             this._restoredBlobs.set(filePath, {
               blobId: meta.blobId,
               size: meta.size,
@@ -1687,7 +1696,7 @@ ${err.stack}` : String(err);
    * @param route - Route to tree table
    * @param treeKey - Tree table key
    * @param rootHash - Hash of the root node to start fetching from
-   * @returns Array of all tree nodes in the tree
+   * @returns Every node in the tree, keyed by its content hash
    */
   async _fetchTreeRecursively(db, route, treeKey, rootHash) {
     const fetchedNodes = /* @__PURE__ */ new Map();
@@ -1760,7 +1769,7 @@ ${err.stack}` : String(err);
       }
       frontier = next;
     }
-    return Array.from(fetchedNodes.values());
+    return fetchedNodes;
   }
   /**
    * Fetches tree from database without restoring to filesystem.
@@ -1780,17 +1789,12 @@ ${err.stack}` : String(err);
       this._timeouts.fetchTree,
       `fetchTree(${treeKey}@${rootRef.slice(0, 8)}…)`
     );
-    if (allNodes.length === 0) {
+    if (allNodes.size === 0) {
       throw new Error(
         `No tree nodes found for ${treeKey}@${rootRef}. The tree may have been deleted or the reference is invalid.`
       );
     }
-    const trees = /* @__PURE__ */ new Map();
-    for (const treeNode of allNodes) {
-      if (treeNode._hash) {
-        trees.set(treeNode._hash, treeNode);
-      }
-    }
+    const trees = allNodes;
     if (!trees.has(rootRef)) {
       throw new Error(
         `Root tree node "${rootRef}" not found in tree data. Available hashes: ${Array.from(trees.keys()).slice(0, 5).join(", ")}${trees.size > 5 ? "..." : ""}`
@@ -2183,6 +2187,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 +2328,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();

package/package.json

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