@rljson/fs-agent 0.0.39 → 0.0.40

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
@@ -653,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

@@ -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 {
@@ -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.39",
+  "version": "0.0.40",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",