cojson 0.20.0 → 0.20.2

package/src/GarbageCollector.ts

@@ -1,6 +1,7 @@
 import { CoValueCore } from "./coValueCore/coValueCore.js";
 import { GARBAGE_COLLECTOR_CONFIG } from "./config.js";
 import { RawCoID } from "./ids.js";
+import type { LocalNode } from "./localNode.js";
 
 /**
  * TTL-based garbage collector for removing unused CoValues from memory.
@@ -8,7 +9,7 @@ import { RawCoID } from "./ids.js";
 export class GarbageCollector {
   private readonly interval: ReturnType<typeof setInterval>;
 
-  constructor(private readonly coValues: Map<RawCoID, CoValueCore>) {
+  constructor(private readonly node: LocalNode) {
     this.interval = setInterval(() => {
       this.collect();
     }, GARBAGE_COLLECTOR_CONFIG.INTERVAL);
@@ -26,7 +27,7 @@ export class GarbageCollector {
 
   collect() {
     const currentTime = this.getCurrentTime();
-    for (const coValue of this.coValues.values()) {
+    for (const coValue of this.node.allCoValues()) {
       const { verified } = coValue;
 
       if (!verified?.lastAccessed) {
@@ -36,7 +37,7 @@ export class GarbageCollector {
       const timeSinceLastAccessed = currentTime - verified.lastAccessed;
 
       if (timeSinceLastAccessed > GARBAGE_COLLECTOR_CONFIG.MAX_AGE) {
-        coValue.unmount();
+        this.node.internalUnmountCoValue(coValue.id);
       }
     }
   }

package/src/PeerState.ts

@@ -1,7 +1,9 @@
 import { PeerKnownState } from "./coValueCore/PeerKnownState.js";
+import { CoValueCore } from "./exports.js";
 import { RawCoID } from "./ids.js";
 import { CoValueKnownState } from "./knownState.js";
 import { logger } from "./logger.js";
+import { type LoadMode, OutgoingLoadQueue } from "./queue/OutgoingLoadQueue.js";
 import { Peer, SyncMessage } from "./sync.js";
 
 export class PeerState {
@@ -17,6 +19,7 @@ export class PeerState {
     knownStates: Map<RawCoID, PeerKnownState> | undefined,
   ) {
     this._knownStates = knownStates ?? new Map();
+    this.loadQueue = new OutgoingLoadQueue(peer.id);
   }
 
   getKnownState(id: RawCoID) {
@@ -54,10 +57,29 @@ export class PeerState {
 
   readonly toldKnownState: Set<RawCoID> = new Set();
   readonly loadRequestSent: Set<RawCoID> = new Set();
+  private loadQueue: OutgoingLoadQueue;
 
-  trackLoadRequestSent(id: RawCoID) {
-    this.toldKnownState.add(id);
-    this.loadRequestSent.add(id);
+  sendLoadRequest(coValue: CoValueCore, mode?: LoadMode): void {
+    this.toldKnownState.add(coValue.id);
+    this.loadRequestSent.add(coValue.id);
+    this.loadQueue.enqueue(
+      coValue,
+      () => {
+        this.pushOutgoingMessage({
+          action: "load",
+          ...coValue.knownStateWithStreaming(),
+        });
+      },
+      mode,
+    );
+  }
+
+  trackLoadRequestUpdate(coValue: CoValueCore) {
+    this.loadQueue.trackUpdate(coValue);
+  }
+
+  trackLoadRequestComplete(coValue: CoValueCore) {
+    this.loadQueue.trackComplete(coValue);
   }
 
   trackToldKnownState(id: RawCoID) {
@@ -192,6 +214,7 @@ export class PeerState {
     });
 
     this.closed = true;
+    this.loadQueue.clear();
     this.peer.outgoing.push("Disconnected");
     this.peer.outgoing.close();
     this.peer.incoming.close();

package/src/coValueCore/coValueCore.ts

@@ -1,6 +1,7 @@
 import { UpDownCounter, ValueType, metrics } from "@opentelemetry/api";
 import type { PeerState } from "../PeerState.js";
 import type { RawCoValue } from "../coValue.js";
+import type { LoadMode } from "../queue/OutgoingLoadQueue.js";
 import {
   RawAccount,
   type ControlledAccountOrAgent,
@@ -281,6 +282,15 @@ export class CoValueCore {
       }
   >();
 
+  // Tracks why we have lastKnownState (separate from loadingStatuses)
+  // - "garbageCollected": was in memory, got GC'd
+  // - "onlyKnownState": checked storage, found knownState, but didn't load full content
+  #lastKnownStateSource?: "garbageCollected" | "onlyKnownState";
+
+  // Cache the knownState when transitioning to garbageCollected/onlyKnownState
+  // Used during peer reconciliation to send accurate LOAD requests
+  #lastKnownState?: CoValueKnownState;
+
   // cached state and listeners
   private _cachedContent?: RawCoValue;
   readonly listeners: Set<(core: CoValueCore, unsub: () => void) => void> =
@@ -307,14 +317,26 @@ export class CoValueCore {
   get loadingState() {
     if (this.verified) {
       return "available";
-    } else if (this.loadingStatuses.size === 0) {
-      return "unknown";
     }
 
+    // Check for pending peers FIRST - loading takes priority over other states
     for (const peer of this.loadingStatuses.values()) {
       if (peer.type === "pending") {
         return "loading";
-      } else if (peer.type === "unknown") {
+      }
+    }
+
+    // Check for lastKnownStateSource (garbageCollected or onlyKnownState)
+    if (this.#lastKnownStateSource) {
+      return this.#lastKnownStateSource;
+    }
+
+    if (this.loadingStatuses.size === 0) {
+      return "unknown";
+    }
+
+    for (const peer of this.loadingStatuses.values()) {
+      if (peer.type === "unknown") {
         return "unknown";
       }
     }
@@ -428,32 +450,22 @@ export class CoValueCore {
   }
 
   /**
-   * Removes the CoValue from memory.
+   * Removes the CoValue content from memory but keeps a shell with cached knownState.
+   * This enables accurate LOAD requests during peer reconciliation.
    *
    * @returns true if the coValue was successfully unmounted, false otherwise
    */
   unmount(): boolean {
-    if (this.listeners.size > 0) {
-      // The coValue is still in use
-      return false;
-    }
-
-    for (const dependant of this.dependant) {
-      if (this.node.hasCoValue(dependant)) {
-        // Another in-memory coValue depends on this coValue
-        return false;
-      }
-    }
-
-    if (!this.node.syncManager.isSyncedToServerPeers(this.id)) {
-      return false;
-    }
+    return this.node.internalUnmountCoValue(this.id);
+  }
 
+  /**
+   * Decrements the counter for the current loading state.
+   * Used during unmount to properly track state transitions.
+   * @internal
+   */
+  decrementLoadingStateCounter() {
     this.counter.add(-1, { state: this.loadingState });
-
-    this.node.internalDeleteCoValue(this.id);
-
-    return true;
   }
 
   markNotFoundInPeer(peerId: PeerID) {
@@ -469,6 +481,35 @@ export class CoValueCore {
     this.scheduleNotifyUpdate();
   }
 
+  /**
+   * Clean up cached state when CoValue becomes available.
+   * Called after the CoValue transitions from garbageCollected/onlyKnownState to available.
+   */
+  private cleanupLastKnownState() {
+    // Clear both fields - in-memory verified state is now authoritative
+    this.#lastKnownStateSource = undefined;
+    this.#lastKnownState = undefined;
+  }
+
+  /**
+   * Initialize this CoValueCore as a garbageCollected shell.
+   * Called when creating a replacement CoValueCore after unmounting.
+   */
+  setGarbageCollectedState(knownState: CoValueKnownState) {
+    // Only set garbageCollected state if storage is active
+    // Without storage, we can't reload the CoValue anyway
+    if (!this.node.storage) {
+      return;
+    }
+
+    // Transition counter from 'unknown' (set by constructor) to 'garbageCollected'
+    // previousState will be 'unknown', newState will be 'garbageCollected'
+    const previousState = this.loadingState;
+    this.#lastKnownStateSource = "garbageCollected";
+    this.#lastKnownState = knownState;
+    this.updateCounter(previousState);
+  }
+
   missingDependencies = new Set<RawCoID>();
 
   isCircularDependency(dependency: CoValueCore) {
@@ -575,6 +616,10 @@ export class CoValueCore {
       header,
       new SessionMap(this.id, this.node.crypto, streamingKnownState),
     );
+    // Clean up if transitioning from garbageCollected/onlyKnownState
+    if (this.isAvailable()) {
+      this.cleanupLastKnownState();
+    }
 
     return true;
   }
@@ -605,10 +650,11 @@ export class CoValueCore {
    * Used to correctly manage the content & subscriptions during the content streaming process
    */
   knownStateWithStreaming(): CoValueKnownState {
-    return (
-      this.verified?.immutableKnownStateWithStreaming() ??
-      emptyKnownState(this.id)
-    );
+    if (this.verified) {
+      return this.verified.immutableKnownStateWithStreaming();
+    }
+
+    return this.knownState();
   }
 
   /**
@@ -617,9 +663,22 @@ export class CoValueCore {
    * The return value identity is going to be stable as long as the CoValue is not modified.
    *
    * On change the knownState is invalidated and a new object is returned.
+   *
+   * For garbageCollected/onlyKnownState CoValues, returns the cached knownState.
    */
   knownState(): CoValueKnownState {
-    return this.verified?.immutableKnownState() ?? emptyKnownState(this.id);
+    // 1. If we have verified content in memory, use that (authoritative)
+    if (this.verified) {
+      return this.verified.immutableKnownState();
+    }
+
+    // 2. If we have last known state (GC'd or onlyKnownState), use that
+    if (this.#lastKnownState) {
+      return this.#lastKnownState;
+    }
+
+    // 3. Fallback to empty state (truly unknown CoValue)
+    return emptyKnownState(this.id);
   }
 
   /**
@@ -1847,11 +1906,11 @@ export class CoValueCore {
     return this.node.syncManager.waitForSync(this.id, options?.timeout);
   }
 
-  load(peers: PeerState[]) {
+  load(peers: PeerState[], mode?: LoadMode) {
     this.loadFromStorage((found) => {
       // When found the load is triggered by handleNewContent
       if (!found) {
-        this.loadFromPeers(peers);
+        this.loadFromPeers(peers, mode);
       }
     });
   }
@@ -1890,7 +1949,16 @@ export class CoValueCore {
       return;
     }
 
-    if (currentState !== "unknown") {
+    // Check if we need to load from storage:
+    // - If storage state is not unknown (already tried), AND
+    // - Overall state is not garbageCollected/onlyKnownState (which need full content)
+    // Then return early
+    const overallState = this.loadingState;
+    if (
+      currentState !== "unknown" &&
+      overallState !== "garbageCollected" &&
+      overallState !== "onlyKnownState"
+    ) {
       done?.(currentState === "available");
       return;
     }
@@ -1915,7 +1983,8 @@ export class CoValueCore {
    * Lazily load only the knownState from storage without loading full transaction data.
    * This is useful for checking if a peer needs new content before committing to a full load.
    *
-   * Caching and deduplication are handled at the storage layer.
+   * If found in storage, marks the CoValue as onlyKnownState and caches the knownState.
+   * This enables accurate LOAD requests during peer reconciliation.
    *
    * @param done - Callback with the storage knownState, or undefined if not found in storage
    */
@@ -1927,17 +1996,29 @@ export class CoValueCore {
       return;
     }
 
-    // If already available in memory, return the current knownState
-    if (this.isAvailable()) {
-      done(this.knownState());
+    // If we already have knowledge about this CoValue (in memory or cached), return it
+    // knownState() returns verified state, lastKnownState, or empty state
+    const knownState = this.knownState();
+    if (knownState.header) {
+      done(knownState);
       return;
     }
 
     // Delegate to storage - caching is handled at storage level
-    this.node.storage.loadKnownState(this.id, done);
+    this.node.storage.loadKnownState(this.id, (knownState) => {
+      // The coValue could become available in the meantime.
+      if (knownState && !this.isAvailable()) {
+        // Cache the knownState and mark as onlyKnownState
+        const previousState = this.loadingState;
+        this.#lastKnownStateSource = "onlyKnownState";
+        this.#lastKnownState = knownState;
+        this.updateCounter(previousState);
+      }
+      done(knownState);
+    });
   }
 
-  loadFromPeers(peers: PeerState[]) {
+  loadFromPeers(peers: PeerState[], mode?: LoadMode) {
     if (peers.length === 0) {
       return;
     }
@@ -1947,29 +2028,17 @@ export class CoValueCore {
 
       if (currentState === "unknown" || currentState === "unavailable") {
         this.markPending(peer.id);
-        this.internalLoadFromPeer(peer);
+        this.internalLoadFromPeer(peer, mode);
       }
     }
   }
 
-  private internalLoadFromPeer(peer: PeerState) {
+  private internalLoadFromPeer(peer: PeerState, mode?: LoadMode) {
     if (peer.closed && !peer.persistent) {
       this.markNotFoundInPeer(peer.id);
       return;
     }
 
-    /**
-     * On reconnection persistent peers will automatically fire the load request
-     * as part of the reconnection process.
-     */
-    if (!peer.closed) {
-      peer.pushOutgoingMessage({
-        action: "load",
-        ...this.knownState(),
-      });
-      peer.trackLoadRequestSent(this.id);
-    }
-
     const markNotFound = () => {
       if (this.getLoadingStateForPeer(peer.id) === "pending") {
         logger.warn("Timeout waiting for peer to load coValue", {
@@ -1980,11 +2049,19 @@ export class CoValueCore {
       }
     };
 
-    const timeout = setTimeout(markNotFound, CO_VALUE_LOADING_CONFIG.TIMEOUT);
+    // Close listener for non-persistent peers
     const removeCloseListener = peer.persistent
       ? undefined
       : peer.addCloseListener(markNotFound);
 
+    /**
+     * On reconnection persistent peers will automatically fire the load request
+     * as part of the reconnection process.
+     */
+    if (!peer.closed) {
+      peer.sendLoadRequest(this, mode);
+    }
+
     this.subscribe((state, unsubscribe) => {
       const peerState = state.getLoadingStateForPeer(peer.id);
       if (
@@ -1995,7 +2072,6 @@ export class CoValueCore {
       ) {
         unsubscribe();
         removeCloseListener?.();
-        clearTimeout(timeout);
       }
     }, true);
   }

package/src/coValues/coList.ts

@@ -378,6 +378,10 @@ export class RawCoList<
     return arr;
   }
 
+  length() {
+    return this.entries().length;
+  }
+
   /** @internal */
   entriesUncached(): {
     value: Item;

package/src/config.ts

@@ -15,8 +15,9 @@ export function setMaxRecommendedTxSize(size: number) {
 
 export const CO_VALUE_LOADING_CONFIG = {
   MAX_RETRIES: 1,
-  TIMEOUT: 30_000,
+  TIMEOUT: 60_000,
   RETRY_DELAY: 3000,
+  MAX_IN_FLIGHT_LOADS_PER_PEER: 1000,
 };
 
 export function setCoValueLoadingMaxRetries(maxRetries: number) {
@@ -54,13 +55,12 @@ export function setGarbageCollectorInterval(interval: number) {
 
 export const WEBSOCKET_CONFIG = {
   MAX_OUTGOING_MESSAGES_CHUNK_BYTES: 25_000,
-  OUTGOING_MESSAGES_CHUNK_DELAY: 5,
 };
 
 export function setMaxOutgoingMessagesChunkBytes(bytes: number) {
   WEBSOCKET_CONFIG.MAX_OUTGOING_MESSAGES_CHUNK_BYTES = bytes;
 }
 
-export function setOutgoingMessagesChunkDelay(delay: number) {
-  WEBSOCKET_CONFIG.OUTGOING_MESSAGES_CHUNK_DELAY = delay;
+export function setMaxInFlightLoadsPerPeer(limit: number) {
+  CO_VALUE_LOADING_CONFIG.MAX_IN_FLIGHT_LOADS_PER_PEER = limit;
 }

package/src/exports.ts

@@ -88,8 +88,8 @@ import {
   setCoValueLoadingRetryDelay,
   setCoValueLoadingTimeout,
   setIncomingMessagesTimeBudget,
+  setMaxInFlightLoadsPerPeer,
   setMaxOutgoingMessagesChunkBytes,
-  setOutgoingMessagesChunkDelay,
   setMaxRecommendedTxSize,
 } from "./config.js";
 import { LogLevel, logger } from "./logger.js";
@@ -142,7 +142,7 @@ export const cojsonInternals = {
   canBeBranched,
   WEBSOCKET_CONFIG,
   setMaxOutgoingMessagesChunkBytes,
-  setOutgoingMessagesChunkDelay,
+  setMaxInFlightLoadsPerPeer,
 };
 
 export {

package/src/localNode.ts

@@ -39,7 +39,7 @@ import { accountOrAgentIDfromSessionID } from "./typeUtils/accountOrAgentIDfromS
 import { expectGroup } from "./typeUtils/expectGroup.js";
 import { canBeBranched } from "./coValueCore/branching.js";
 import { connectedPeers } from "./streamUtils.js";
-import { emptyKnownState } from "./knownState.js";
+import { CoValueKnownState, emptyKnownState } from "./knownState.js";
 
 /** A `LocalNode` represents a local view of a set of loaded `CoValue`s, from the perspective of a particular account (or primitive cryptographic agent).
 
@@ -87,7 +87,7 @@ export class LocalNode {
       return;
     }
 
-    this.garbageCollector = new GarbageCollector(this.coValues);
+    this.garbageCollector = new GarbageCollector(this);
   }
 
   setStorage(storage: StorageAPI) {
@@ -123,7 +123,13 @@ export class LocalNode {
       return false;
     }
 
-    return coValue.loadingState !== "unknown";
+    const state = coValue.loadingState;
+    // garbageCollected and onlyKnownState shells don't have actual content loaded
+    return (
+      state !== "unknown" &&
+      state !== "garbageCollected" &&
+      state !== "onlyKnownState"
+    );
   }
 
   getCoValue(id: RawCoID) {
@@ -143,11 +149,64 @@ export class LocalNode {
     return this.coValues.values();
   }
 
+  /**
+   * Simple delete of a CoValue from memory.
+   * Used for testing and forced cleanup scenarios.
+   * @internal
+   */
   internalDeleteCoValue(id: RawCoID) {
     this.coValues.delete(id);
     this.storage?.onCoValueUnmounted(id);
   }
 
+  /**
+   * Unmount a CoValue from memory, keeping a shell with cached knownState.
+   * This enables accurate LOAD requests during peer reconciliation.
+   *
+   * @returns true if the coValue was successfully unmounted, false otherwise
+   */
+  internalUnmountCoValue(id: RawCoID): boolean {
+    const coValue = this.coValues.get(id);
+
+    if (!coValue) {
+      return false;
+    }
+
+    if (coValue.listeners.size > 0) {
+      // The coValue is still in use
+      return false;
+    }
+
+    for (const dependant of coValue.dependant) {
+      if (this.hasCoValue(dependant)) {
+        // Another in-memory coValue depends on this coValue
+        return false;
+      }
+    }
+
+    if (!this.syncManager.isSyncedToServerPeers(id)) {
+      return false;
+    }
+
+    // Cache the knownState before replacing
+    const lastKnownState = coValue.knownState();
+
+    // Handle counter: decrement old coValue's state
+    coValue.decrementLoadingStateCounter();
+
+    // Create new shell CoValueCore in garbageCollected state
+    const shell = new CoValueCore(id, this);
+    shell.setGarbageCollectedState(lastKnownState);
+
+    // Single map update (replacing old with shell)
+    this.coValues.set(id, shell);
+
+    // Notify storage
+    this.storage?.onCoValueUnmounted(id);
+
+    return true;
+  }
+
   getCurrentAccountOrAgentID(): RawAccountID | AgentID {
     return accountOrAgentIDfromSessionID(this.currentSessionID);
   }
@@ -449,7 +508,9 @@ export class LocalNode {
 
       if (
         coValue.loadingState === "unknown" ||
-        coValue.loadingState === "unavailable"
+        coValue.loadingState === "unavailable" ||
+        coValue.loadingState === "garbageCollected" ||
+        coValue.loadingState === "onlyKnownState"
       ) {
         const peers = this.syncManager.getServerPeers(id, skipLoadingFromPeer);
 

package/src/queue/LinkedList.ts

@@ -10,8 +10,9 @@ type Tuple<T, N extends number, A extends unknown[] = []> = A extends {
   ? A
   : Tuple<T, N, [...A, T]>;
 export type QueueTuple = Tuple<LinkedList<SyncMessage>, 3>;
-type LinkedListNode<T> = {
+export type LinkedListNode<T> = {
   value: T;
+  prev: LinkedListNode<T> | undefined;
   next: LinkedListNode<T> | undefined;
 };
 /**
@@ -26,13 +27,14 @@ export class LinkedList<T> {
   tail: LinkedListNode<T> | undefined = undefined;
   length = 0;
 
-  push(value: T) {
-    const node = { value, next: undefined };
+  push(value: T): LinkedListNode<T> {
+    const node: LinkedListNode<T> = { value, prev: undefined, next: undefined };
 
     if (this.head === undefined) {
       this.head = node;
       this.tail = node;
     } else if (this.tail) {
+      node.prev = this.tail;
       this.tail.next = node;
       this.tail = node;
     } else {
@@ -41,6 +43,7 @@ export class LinkedList<T> {
 
     this.length++;
     this.meter?.push();
+    return node;
   }
 
   shift() {
@@ -55,6 +58,8 @@ export class LinkedList<T> {
 
     if (this.head === undefined) {
       this.tail = undefined;
+    } else {
+      this.head.prev = undefined;
     }
 
     this.length--;
@@ -63,6 +68,31 @@ export class LinkedList<T> {
     return value;
   }
 
+  /**
+   * Remove a specific node from the list in O(1) time.
+   * The node must be a valid node that was returned by push().
+   */
+  remove(node: LinkedListNode<T>): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      // Node is the head
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      // Node is the tail
+      this.tail = node.prev;
+    }
+
+    node.prev = undefined;
+    node.next = undefined;
+    this.length--;
+    this.meter?.pull();
+  }
+
   isEmpty() {
     return this.head === undefined;
   }
@@ -108,7 +138,7 @@ class QueueMeter {
   }
 }
 export function meteredList<T>(
-  type: "incoming" | "outgoing" | "storage-streaming",
+  type: "incoming" | "outgoing" | "storage-streaming" | "load-requests-queue",
   attrs?: Record<string, string | number>,
 ) {
   return new LinkedList<T>(new QueueMeter("jazz.messagequeue." + type, attrs));