cojson 0.19.20 → 0.19.22

package/src/coValueCore/coValueCore.ts

@@ -373,16 +373,26 @@ export class CoValueCore {
     }
   }
 
-  unmount(garbageCollectGroups = false) {
-    if (
-      !garbageCollectGroups &&
-      this.verified?.header.ruleset.type === "group"
-    ) {
+  /**
+   * Removes the CoValue from memory.
+   *
+   * @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;
     }
 
-    if (this.listeners.size > 0) {
-      return false; // The coValue is still in use
+    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;
     }
 
     this.counter.add(-1, { state: this.loadingState });
@@ -1193,6 +1203,15 @@ export class CoValueCore {
     return matchingTransactions;
   }
 
+  /**
+   * The CoValues that this CoValue depends on.
+   * We currently track dependencies for:
+   * - Ownership (a CoValue depends on its account/group owner)
+   * - Group membership (a group depends on its direct account/group members)
+   * - Sessions (a CoValue depends on Accounts that made changes to it)
+   * - Branches (a branched CoValue depends on its branch source)
+   * See {@link dependant} for the CoValues that depend on this CoValue.
+   */
   dependencies: Set<RawCoID> = new Set();
   incompleteDependencies: Set<RawCoID> = new Set();
   private addDependency(dependency: RawCoID) {
@@ -1238,6 +1257,10 @@ export class CoValueCore {
     }
   }
 
+  /**
+   * The CoValues that depend on this CoValue.
+   * This is the inverse relationship of {@link dependencies}.
+   */
   dependant: Set<RawCoID> = new Set();
   private addDependant(dependant: RawCoID) {
     this.dependant.add(dependant);
@@ -1506,6 +1529,32 @@ 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.
+   *
+   * @param done - Callback with the storage knownState, or undefined if not found in storage
+   */
+  getKnownStateFromStorage(
+    done: (knownState: CoValueKnownState | undefined) => void,
+  ) {
+    if (!this.node.storage) {
+      done(undefined);
+      return;
+    }
+
+    // If already available in memory, return the current knownState
+    if (this.isAvailable()) {
+      done(this.knownState());
+      return;
+    }
+
+    // Delegate to storage - caching is handled at storage level
+    this.node.storage.loadKnownState(this.id, done);
+  }
+
   loadFromPeers(peers: PeerState[]) {
     if (peers.length === 0) {
       return;

package/src/coValues/account.ts

@@ -8,7 +8,7 @@ import {
   SignerID,
   SignerSecret,
 } from "../crypto/crypto.js";
-import { AgentID } from "../ids.js";
+import { AgentID, isAgentID } from "../ids.js";
 import { JsonObject } from "../jsonValue.js";
 import { LocalNode } from "../localNode.js";
 import { logger } from "../logger.js";
@@ -43,25 +43,23 @@ export class RawAccount<
   _cachedCurrentAgentID: AgentID | undefined;
 
   currentAgentID(): AgentID {
-    if (this._cachedCurrentAgentID) {
-      return this._cachedCurrentAgentID;
+    if (this._cachedCurrentAgentID) return this._cachedCurrentAgentID;
+
+    const header = this.core.verified.header;
+
+    if (header.ruleset.type !== "group") {
+      throw new Error("You can't get an agent id from a non-group value");
     }
 
-    const agents = this.keys()
-      .filter((k): k is AgentID => k.startsWith("sealer_"))
-      .sort(
-        (a, b) =>
-          (this.lastEditAt(a)?.at.getTime() || 0) -
-          (this.lastEditAt(b)?.at.getTime() || 0),
-      );
+    const initialAdmin = header.ruleset.initialAdmin;
 
-    if (agents.length !== 1) {
-      logger.warn("Account has " + agents.length + " agents", { id: this.id });
+    if (!isAgentID(initialAdmin)) {
+      throw new Error("You can read agent ids only from account values");
     }
 
-    this._cachedCurrentAgentID = agents[0];
+    this._cachedCurrentAgentID = initialAdmin;
 
-    return agents[0]!;
+    return initialAdmin;
   }
 
   override createInvite(_: AccountRole): InviteSecret {

package/src/exports.ts

@@ -206,6 +206,7 @@ export type {
 };
 
 export * from "./storage/index.js";
+export * from "./CojsonMessageChannel/index.js";
 
 // biome-ignore format: off
 // eslint-disable-next-line @typescript-eslint/no-namespace

package/src/ids.ts

@@ -28,7 +28,7 @@ export type TransactionID = {
 
 export type AgentID = `sealer_z${string}/signer_z${string}`;
 
-export function isAgentID(id: string): id is AgentID {
+export function isAgentID(id: unknown): id is AgentID {
   return (
     typeof id === "string" &&
     id.startsWith("sealer_") &&

package/src/knownState.ts

@@ -140,6 +140,30 @@ export function isKnownStateSubsetOf(
   return true;
 }
 
+/**
+ * Check if the peer already has all the content from storage.
+ * Returns true if the peer has at least as many transactions as storage for all sessions.
+ */
+export function peerHasAllContent(
+  storageKnownState: CoValueKnownState,
+  peerKnownState: CoValueKnownState | undefined,
+): boolean {
+  if (!peerKnownState) {
+    return false;
+  }
+
+  // Check if peer has the header
+  if (!peerKnownState.header && storageKnownState.header) {
+    return false;
+  }
+
+  // Check all sessions - peer must have at least as many transactions as storage
+  return isKnownStateSubsetOf(
+    storageKnownState.sessions,
+    peerKnownState.sessions,
+  );
+}
+
 /**
  * Returns the record with the sessions that need to be sent to the target
  */

package/src/localNode.ts

@@ -82,15 +82,12 @@ export class LocalNode {
     this.crypto = crypto;
   }
 
-  enableGarbageCollector(opts?: { garbageCollectGroups?: boolean }) {
+  enableGarbageCollector() {
     if (this.garbageCollector) {
       return;
     }
 
-    this.garbageCollector = new GarbageCollector(
-      this.coValues,
-      opts?.garbageCollectGroups ?? false,
-    );
+    this.garbageCollector = new GarbageCollector(this.coValues);
   }
 
   setStorage(storage: StorageAPI) {
@@ -133,6 +130,7 @@ export class LocalNode {
 
   internalDeleteCoValue(id: RawCoID) {
     this.coValues.delete(id);
+    this.storage?.onCoValueUnmounted(id);
   }
 
   getCurrentAccountOrAgentID(): RawAccountID | AgentID {
@@ -736,9 +734,16 @@ export class LocalNode {
       };
     }
 
-    const account = coValue.getCurrentContent() as RawAccount;
+    const agentId = coValue.verified.header.ruleset.initialAdmin;
+
+    if (!isAgentID(agentId)) {
+      return {
+        value: undefined,
+        error: new Error(`Unexpectedly not account: ${expectation}`),
+      };
+    }
 
-    return { value: account.currentAgentID(), error: undefined };
+    return { value: agentId, error: undefined };
   }
 
   createGroup(

package/src/storage/knownState.ts

@@ -25,6 +25,18 @@ export class StorageKnownState {
     return knownState;
   }
 
+  /**
+   * Get a cached knownState if it exists and has a header.
+   * Unlike getKnownState, this doesn't create an empty state if one doesn't exist.
+   */
+  getCachedKnownState(id: string): CoValueKnownState | undefined {
+    const knownState = this.knownStates.get(id);
+    if (knownState?.header) {
+      return knownState;
+    }
+    return undefined;
+  }
+
   setKnownState(id: string, knownState: CoValueKnownState) {
     this.knownStates.set(id, knownState);
   }

package/src/storage/sqlite/client.ts

@@ -4,6 +4,7 @@ import type {
 } from "../../coValueCore/verifiedState.js";
 import type { Signature } from "../../crypto/crypto.js";
 import type { RawCoID, SessionID } from "../../exports.js";
+import type { CoValueKnownState } from "../../knownState.js";
 import type { PeerID } from "../../sync.js";
 import { logger } from "../../logger.js";
 import type {
@@ -224,4 +225,34 @@ export class SQLiteClient
   stopTrackingSyncState(id: RawCoID): void {
     this.db.run("DELETE FROM unsynced_covalues WHERE co_value_id = ?", [id]);
   }
+
+  getCoValueKnownState(coValueId: string): CoValueKnownState | undefined {
+    // First check if the CoValue exists
+    const coValueRow = this.db.get<{ rowID: number }>(
+      "SELECT rowID FROM coValues WHERE id = ?",
+      [coValueId],
+    );
+
+    if (!coValueRow) {
+      return undefined;
+    }
+
+    // Get all session counters without loading transactions
+    const sessions = this.db.query<{ sessionID: SessionID; lastIdx: number }>(
+      "SELECT sessionID, lastIdx FROM sessions WHERE coValue = ?",
+      [coValueRow.rowID],
+    );
+
+    const knownState: CoValueKnownState = {
+      id: coValueId as RawCoID,
+      header: true,
+      sessions: {},
+    };
+
+    for (const session of sessions) {
+      knownState.sessions[session.sessionID] = session.lastIdx;
+    }
+
+    return knownState;
+  }
 }

package/src/storage/sqliteAsync/client.ts

@@ -4,6 +4,7 @@ import type {
 } from "../../coValueCore/verifiedState.js";
 import type { Signature } from "../../crypto/crypto.js";
 import type { RawCoID, SessionID } from "../../exports.js";
+import type { CoValueKnownState } from "../../knownState.js";
 import { logger } from "../../logger.js";
 import type {
   DBClientInterfaceAsync,
@@ -236,4 +237,38 @@ export class SQLiteClientAsync
       id,
     ]);
   }
+
+  async getCoValueKnownState(
+    coValueId: string,
+  ): Promise<CoValueKnownState | undefined> {
+    // First check if the CoValue exists
+    const coValueRow = await this.db.get<{ rowID: number }>(
+      "SELECT rowID FROM coValues WHERE id = ?",
+      [coValueId],
+    );
+
+    if (!coValueRow) {
+      return undefined;
+    }
+
+    // Get all session counters without loading transactions
+    const sessions = await this.db.query<{
+      sessionID: SessionID;
+      lastIdx: number;
+    }>("SELECT sessionID, lastIdx FROM sessions WHERE coValue = ?", [
+      coValueRow.rowID,
+    ]);
+
+    const knownState: CoValueKnownState = {
+      id: coValueId as RawCoID,
+      header: true,
+      sessions: {},
+    };
+
+    for (const session of sessions) {
+      knownState.sessions[session.sessionID] = session.lastIdx;
+    }
+
+    return knownState;
+  }
 }

package/src/storage/storageAsync.ts

@@ -34,7 +34,17 @@ import type {
 export class StorageApiAsync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceAsync;
 
-  private loadedCoValues = new Set<RawCoID>();
+  /**
+   * Keeps track of CoValues that are in memory, to avoid reloading them from storage
+   * when it isn't necessary
+   */
+  private inMemoryCoValues = new Set<RawCoID>();
+
+  // Track pending loads to deduplicate concurrent requests
+  private pendingKnownStateLoads = new Map<
+    string,
+    Promise<CoValueKnownState | undefined>
+  >();
 
   constructor(dbClient: DBClientInterfaceAsync) {
     this.dbClient = dbClient;
@@ -46,6 +56,51 @@ export class StorageApiAsync implements StorageAPI {
     return this.knownStates.getKnownState(id);
   }
 
+  loadKnownState(
+    id: string,
+    callback: (knownState: CoValueKnownState | undefined) => void,
+  ): void {
+    // Check in-memory cache first
+    const cached = this.knownStates.getCachedKnownState(id);
+    if (cached) {
+      callback(cached);
+      return;
+    }
+
+    // Check if there's already a pending load for this ID (deduplication)
+    const pending = this.pendingKnownStateLoads.get(id);
+    if (pending) {
+      // Ensure callback is always called, even if pending fails unexpectedly
+      pending.then(callback, () => callback(undefined));
+      return;
+    }
+
+    // Start new load and track it for deduplication
+    const loadPromise = this.dbClient
+      .getCoValueKnownState(id)
+      .then((knownState) => {
+        if (knownState) {
+          // Cache for future use
+          this.knownStates.setKnownState(id, knownState);
+        }
+        return knownState;
+      })
+      .catch((err) => {
+        // Error handling contract:
+        // - Log warning
+        // - Behave like "not found" so callers can fall back (full load / load from peers)
+        logger.warn("Failed to load knownState from storage", { id, err });
+        return undefined;
+      })
+      .finally(() => {
+        // Remove from pending map after completion (success or failure)
+        this.pendingKnownStateLoads.delete(id);
+      });
+
+    this.pendingKnownStateLoads.set(id, loadPromise);
+    loadPromise.then(callback);
+  }
+
   async load(
     id: string,
     callback: (data: NewContentMessage) => void,
@@ -102,7 +157,7 @@ export class StorageApiAsync implements StorageAPI {
       );
     }
 
-    this.loadedCoValues.add(coValueRow.id);
+    this.inMemoryCoValues.add(coValueRow.id);
 
     let contentMessage = createContentMessage(coValueRow.id, coValueRow.header);
 
@@ -173,7 +228,7 @@ export class StorageApiAsync implements StorageAPI {
     done?.(true);
   }
 
-  async pushContentWithDependencies(
+  private async pushContentWithDependencies(
     coValueRow: StoredCoValueRow,
     contentMessage: NewContentMessage,
     pushCallback: (data: NewContentMessage) => void,
@@ -186,7 +241,7 @@ export class StorageApiAsync implements StorageAPI {
     const promises = [];
 
     for (const dependedOnCoValue of dependedOnCoValuesList) {
-      if (this.loadedCoValues.has(dependedOnCoValue)) {
+      if (this.inMemoryCoValues.has(dependedOnCoValue)) {
         continue;
       }
 
@@ -313,6 +368,8 @@ export class StorageApiAsync implements StorageAPI {
       });
     }
 
+    this.inMemoryCoValues.add(id);
+
     this.knownStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
@@ -409,7 +466,12 @@ export class StorageApiAsync implements StorageAPI {
     this.dbClient.stopTrackingSyncState(id);
   }
 
+  onCoValueUnmounted(id: RawCoID): void {
+    this.inMemoryCoValues.delete(id);
+  }
+
   close() {
+    this.inMemoryCoValues.clear();
     return this.storeQueue.close();
   }
 }

package/src/storage/storageSync.ts

@@ -37,7 +37,11 @@ import { getPriorityFromHeader } from "../priority.js";
 
 export class StorageApiSync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceSync;
-  private loadedCoValues = new Set<RawCoID>();
+  /**
+   * Keeps track of CoValues that are in memory, to avoid reloading them from storage
+   * when it isn't necessary
+   */
+  private inMemoryCoValues = new Set<RawCoID>();
 
   /**
    * Queue for streaming content that will be pulled by SyncManager.
@@ -56,6 +60,28 @@ export class StorageApiSync implements StorageAPI {
     return this.knownStates.getKnownState(id);
   }
 
+  loadKnownState(
+    id: string,
+    callback: (knownState: CoValueKnownState | undefined) => void,
+  ): void {
+    // Check in-memory cache first
+    const cached = this.knownStates.getCachedKnownState(id);
+    if (cached) {
+      callback(cached);
+      return;
+    }
+
+    // Load from database
+    const knownState = this.dbClient.getCoValueKnownState(id);
+
+    if (knownState) {
+      // Cache for future use
+      this.knownStates.setKnownState(id, knownState);
+    }
+
+    callback(knownState);
+  }
+
   async load(
     id: string,
     callback: (data: NewContentMessage) => void,
@@ -116,7 +142,7 @@ export class StorageApiSync implements StorageAPI {
       );
     }
 
-    this.loadedCoValues.add(coValueRow.id);
+    this.inMemoryCoValues.add(coValueRow.id);
 
     const priority = getPriorityFromHeader(coValueRow.header);
     const contentMessage = createContentMessage(
@@ -222,7 +248,7 @@ export class StorageApiSync implements StorageAPI {
     });
   }
 
-  async pushContentWithDependencies(
+  private async pushContentWithDependencies(
     coValueRow: StoredCoValueRow,
     contentMessage: NewContentMessage,
     pushCallback: (data: NewContentMessage) => void,
@@ -233,7 +259,7 @@ export class StorageApiSync implements StorageAPI {
     );
 
     for (const dependedOnCoValue of dependedOnCoValuesList) {
-      if (this.loadedCoValues.has(dependedOnCoValue)) {
+      if (this.inMemoryCoValues.has(dependedOnCoValue)) {
         continue;
       }
 
@@ -331,6 +357,8 @@ export class StorageApiSync implements StorageAPI {
       });
     }
 
+    this.inMemoryCoValues.add(id);
+
     this.knownStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
@@ -428,7 +456,12 @@ export class StorageApiSync implements StorageAPI {
     this.dbClient.stopTrackingSyncState(id);
   }
 
+  onCoValueUnmounted(id: RawCoID): void {
+    this.inMemoryCoValues.delete(id);
+  }
+
   close() {
+    this.inMemoryCoValues.clear();
     return undefined;
   }
 }

package/src/storage/types.ts

@@ -55,6 +55,24 @@ export interface StorageAPI {
    */
   stopTrackingSyncState(id: RawCoID): void;
 
+  /**
+   * Load only the knownState (header presence + session counters) for a CoValue.
+   * This is more efficient than load() when we only need to check if a peer needs new content.
+   *
+   * @param id - The CoValue ID
+   * @param callback - Called with the knownState, or undefined if CoValue not found
+   */
+  loadKnownState(
+    id: string,
+    callback: (knownState: CoValueKnownState | undefined) => void,
+  ): void;
+
+  /**
+   * Called when a CoValue is unmounted from memory.
+   * Used to clean up the metadata associated with that CoValue.
+   */
+  onCoValueUnmounted(id: RawCoID): void;
+
   close(): Promise<unknown> | undefined;
 }
 
@@ -152,6 +170,14 @@ export interface DBClientInterfaceAsync {
   getUnsyncedCoValueIDs(): Promise<RawCoID[]>;
 
   stopTrackingSyncState(id: RawCoID): Promise<void>;
+
+  /**
+   * Get the knownState for a CoValue without loading transactions.
+   * Returns undefined if the CoValue doesn't exist.
+   */
+  getCoValueKnownState(
+    coValueId: string,
+  ): Promise<CoValueKnownState | undefined>;
 }
 
 export interface DBTransactionInterfaceSync {
@@ -212,4 +238,10 @@ export interface DBClientInterfaceSync {
   getUnsyncedCoValueIDs(): RawCoID[];
 
   stopTrackingSyncState(id: RawCoID): void;
+
+  /**
+   * Get the knownState for a CoValue without loading transactions.
+   * Returns undefined if the CoValue doesn't exist.
+   */
+  getCoValueKnownState(coValueId: string): CoValueKnownState | undefined;
 }