@git-stunts/git-warp 12.2.0 → 12.3.0

package/src/domain/services/CheckpointService.js

@@ -28,6 +28,24 @@ import { cloneStateV5, reduceV5 } from './JoinReducer.js';
 import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
+// ============================================================================
+// Checkpoint Schema Constants
+// ============================================================================
+
+/**
+ * Standard checkpoint schema — full V5 state without index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_STANDARD = 2;
+
+/**
+ * Index-tree checkpoint schema — full V5 state with bitmap index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_INDEX_TREE = 4;
+
 // ============================================================================
 // Internal Helpers
 // ============================================================================
@@ -148,7 +166,9 @@ export async function createV5({
   // 1. Compute appliedVV from actual state dots
   const appliedVV = computeAppliedVV(state);
 
-  // 2. Optionally compact (only tombstoned dots <= appliedVV)
+  // 2. Optionally compact (only tombstoned dots <= appliedVV).
+  // When compact=false, checkpointState aliases the caller's state but the
+  // remaining path is read-only (serialize + hash), so no clone is needed.
   let checkpointState = state;
   if (compact) {
     checkpointState = cloneStateV5(state);
@@ -188,6 +208,11 @@ export async function createV5({
   // If patch commits are ever pruned, content blobs remain reachable via
   // the checkpoint tree. Without this, git gc would nuke content blobs
   // whose only anchor was the (now-pruned) patch commit tree.
+  //
+  // O(P) scan over all properties — acceptable because checkpoint creation
+  // is infrequent. The property key format is deterministic (encodePropKey /
+  // encodeEdgePropKey), but content keys are interleaved with regular keys
+  // so no prefix filter can skip non-content entries without decoding.
   const contentOids = new Set();
   for (const [propKey, register] of checkpointState.prop) {
     const { propKey: decodedKey } = isEdgePropKey(propKey)
@@ -235,7 +260,9 @@ export async function createV5({
     stateHash,
     frontierOid: frontierBlobOid,
     indexOid: treeOid,
-    schema: indexTree ? 4 : 2,
+    // Schema 3 was used for edge-property-aware patches but is never emitted
+    // by checkpoint creation. Schema 4 indicates an index tree is present.
+    schema: indexTree ? CHECKPOINT_SCHEMA_INDEX_TREE : CHECKPOINT_SCHEMA_STANDARD,
   });
 
   // 9. Create the checkpoint commit

package/src/domain/services/GCPolicy.js

@@ -4,6 +4,7 @@
 
 import { orsetCompact } from '../crdt/ORSet.js';
 import { collectGCMetrics } from './GCMetrics.js';
+import WarpError from '../errors/WarpError.js';
 
 /**
  * @typedef {Object} GCPolicy
@@ -92,21 +93,41 @@ export function shouldRunGC(metrics, policy) {
 
 /**
  * Executes GC on state. Only compacts tombstoned dots <= appliedVV.
- * Mutates state in place.
+ * Mutates state **in place** — callers must clone-then-swap to preserve
+ * a rollback copy (see CheckpointService for the canonical pattern).
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - State to compact (mutated!)
  * @param {import('../crdt/VersionVector.js').VersionVector} appliedVV - Version vector cutoff
  * @returns {GCExecuteResult}
+ * @throws {WarpError} E_GC_INVALID_VV if appliedVV is not a Map
+ * @throws {WarpError} E_GC_COMPACT_FAILED if orsetCompact throws
  */
 export function executeGC(state, appliedVV) {
+  if (!(appliedVV instanceof Map)) {
+    throw new WarpError(
+      'executeGC requires appliedVV to be a Map (VersionVector)',
+      'E_GC_INVALID_VV',
+    );
+  }
+
   const startTime = performance.now();
 
   // Collect metrics before compaction
   const beforeMetrics = collectGCMetrics(state);
 
-  // Compact both ORSets
-  orsetCompact(state.nodeAlive, appliedVV);
-  orsetCompact(state.edgeAlive, appliedVV);
+  // Compact both ORSets — wrap each phase so partial failure is diagnosable
+  let nodesDone = false;
+  try {
+    orsetCompact(state.nodeAlive, appliedVV);
+    nodesDone = true;
+    orsetCompact(state.edgeAlive, appliedVV);
+  } catch {
+    throw new WarpError(
+      `GC compaction failed during ${nodesDone ? 'edgeAlive' : 'nodeAlive'} phase`,
+      'E_GC_COMPACT_FAILED',
+      { context: { phase: nodesDone ? 'edgeAlive' : 'nodeAlive', partialCompaction: nodesDone } },
+    );
+  }
 
   // Collect metrics after compaction
   const afterMetrics = collectGCMetrics(state);

package/src/domain/services/GraphTraversal.js

@@ -165,7 +165,9 @@ export default class GraphTraversal {
       return await this._provider.getNeighbors(nodeId, direction, options);
     }
 
-    const labelsKey = options?.labels ? JSON.stringify([...options.labels].sort()) : '*';
+    const labelsKey = options?.labels
+      ? [...options.labels].sort().join('\0')
+      : '*';
     const key = `${nodeId}\0${direction}\0${labelsKey}`;
     const cached = cache.get(key);
     if (cached !== undefined) {

package/src/domain/services/IncrementalIndexUpdater.js

@@ -1,10 +1,17 @@
 /**
- * Stateless service that computes dirty shard buffers from a PatchDiff.
+ * Stateful service that computes dirty shard buffers from a PatchDiff.
  *
  * Given a diff of alive-ness transitions + a shard loader for the existing
  * index tree, produces only the shard buffers that changed. The caller
  * merges them back into the tree via `{ ...existingTree, ...dirtyShards }`.
  *
+ * Instance state:
+ * - `_edgeAdjacencyCache` stores a WeakMap keyed by `state.edgeAlive` ORSet
+ *   identity, mapping nodeId -> incident alive edge keys.
+ * - Cache lifetime is tied to the updater instance and is reconciled per diff
+ *   once initialized. Reuse one instance for a single linear state stream;
+ *   create a new instance to reset cache state across independent streams.
+ *
  * @module domain/services/IncrementalIndexUpdater
  */
 
@@ -40,6 +47,15 @@ export default class IncrementalIndexUpdater {
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;
+    /** @type {WeakMap<import('../crdt/ORSet.js').ORSet, Map<string, Set<string>>>} */
+    this._edgeAdjacencyCache = new WeakMap();
+    /**
+     * Cached next label ID — avoids O(L) max-scan per new label.
+     * Initialized lazily from existing labels on first _ensureLabel call.
+     * @type {number|null}
+     * @private
+     */
+    this._nextLabelId = null;
   }
 
   /**
@@ -63,8 +79,22 @@ export default class IncrementalIndexUpdater {
     const out = {};
 
     const labels = this._loadLabels(loadShard);
+    // Reset cached next label ID so _ensureLabel re-scans the fresh labels
+    // object loaded above. Without this, a stale _nextLabelId from a prior
+    // applyDiff call could collide with IDs already present in the new labels.
+    this._nextLabelId = null;
     let labelsDirty = false;
 
+    // Determine which added nodes are true re-adds (already have global IDs).
+    // Brand-new nodes cannot have pre-existing indexed edges to restore.
+    const readdedNodes = new Set();
+    for (const nodeId of diff.nodesAdded) {
+      const meta = this._getOrLoadMeta(computeShardKey(nodeId), metaCache, loadShard);
+      if (this._findGlobalId(meta, nodeId) !== undefined) {
+        readdedNodes.add(nodeId);
+      }
+    }
+
     for (const nodeId of diff.nodesAdded) {
       this._handleNodeAdd(nodeId, metaCache, loadShard);
     }
@@ -96,25 +126,22 @@ export default class IncrementalIndexUpdater {
       this._handleEdgeRemove(edge, labels, metaCache, fwdCache, revCache, loadShard);
     }
 
-    // Restore edges for re-added nodes. When a node transitions
-    // not-alive -> alive, edges touching it that are alive in the ORSet
-    // become visible again. The diff only tracks explicit EdgeAdd ops,
-    // not these implicit visibility transitions.
-    //
-    // Known O(E) worst-case: scans all alive edges. For genuinely new nodes
-    // (not re-adds), this scan is unnecessary since they can't have pre-existing
-    // edges. _findGlobalId returns undefined for new nodes, so this could be
-    // short-circuited — deferred for a future optimization pass.
-    if (diff.nodesAdded.length > 0) {
-      const addedSet = new Set(diff.nodesAdded);
+    // Keep adjacency cache in sync for every diff once initialized, so later
+    // re-add restores never consult stale edge membership.
+    let readdAdjacency = null;
+    if (readdedNodes.size > 0 || this._edgeAdjacencyCache.has(state.edgeAlive)) {
+      readdAdjacency = this._getOrBuildAliveEdgeAdjacency(state, diff);
+    }
+
+    // Restore edges for re-added nodes only. When a node transitions
+    // not-alive -> alive, alive OR-Set edges touching it become visible again.
+    // Brand-new nodes are skipped because they have no prior global ID.
+    if (readdedNodes.size > 0 && readdAdjacency) {
       const diffEdgeSet = new Set(
         diff.edgesAdded.map((e) => `${e.from}\0${e.to}\0${e.label}`),
       );
-      for (const edgeKey of orsetElements(state.edgeAlive)) {
+      for (const edgeKey of this._collectReaddedEdgeKeys(readdAdjacency, readdedNodes)) {
         const { from, to, label } = decodeEdgeKey(edgeKey);
-        if (!addedSet.has(from) && !addedSet.has(to)) {
-          continue;
-        }
         if (!orsetContains(state.nodeAlive, from) || !orsetContains(state.nodeAlive, to)) {
           continue;
         }
@@ -255,15 +282,16 @@ export default class IncrementalIndexUpdater {
     for (const bucket of Object.keys(fwdData)) {
       const gidStr = String(deadGid);
       if (fwdData[bucket] && fwdData[bucket][gidStr]) {
-        // Before clearing, find the targets so we can clean reverse bitmaps
-        const targets = RoaringBitmap32.deserialize(
+        // Deserialize once, collect targets, then clear+serialize in place.
+        const bm = RoaringBitmap32.deserialize(
           toBytes(fwdData[bucket][gidStr]),
           true,
-        ).toArray();
+        );
+        const targets = bm.toArray();
 
         // Clear this node's outgoing bitmap
-        const empty = new RoaringBitmap32();
-        fwdData[bucket][gidStr] = empty.serialize(true);
+        bm.clear();
+        fwdData[bucket][gidStr] = bm.serialize(true);
 
         // Remove deadGid from each target's reverse bitmap
         for (const targetGid of targets) {
@@ -273,12 +301,12 @@ export default class IncrementalIndexUpdater {
             const revData = this._getOrLoadEdgeShard(revCache, 'rev', targetShard, loadShard);
             const targetGidStr = String(targetGid);
             if (revData[bucket] && revData[bucket][targetGidStr]) {
-              const bm = RoaringBitmap32.deserialize(
+              const targetBm = RoaringBitmap32.deserialize(
                 toBytes(revData[bucket][targetGidStr]),
                 true,
               );
-              bm.remove(deadGid);
-              revData[bucket][targetGidStr] = bm.serialize(true);
+              targetBm.remove(deadGid);
+              revData[bucket][targetGidStr] = targetBm.serialize(true);
             }
           }
         }
@@ -290,13 +318,14 @@ export default class IncrementalIndexUpdater {
     for (const bucket of Object.keys(revData)) {
       const gidStr = String(deadGid);
       if (revData[bucket] && revData[bucket][gidStr]) {
-        const sources = RoaringBitmap32.deserialize(
+        const bm = RoaringBitmap32.deserialize(
           toBytes(revData[bucket][gidStr]),
           true,
-        ).toArray();
+        );
+        const sources = bm.toArray();
 
-        const empty = new RoaringBitmap32();
-        revData[bucket][gidStr] = empty.serialize(true);
+        bm.clear();
+        revData[bucket][gidStr] = bm.serialize(true);
 
         // Remove deadGid from each source's forward bitmap
         for (const sourceGid of sources) {
@@ -306,12 +335,12 @@ export default class IncrementalIndexUpdater {
             const fwdDataPeer = this._getOrLoadEdgeShard(fwdCache, 'fwd', sourceShard, loadShard);
             const sourceGidStr = String(sourceGid);
             if (fwdDataPeer[bucket] && fwdDataPeer[bucket][sourceGidStr]) {
-              const bm = RoaringBitmap32.deserialize(
+              const sourceBm = RoaringBitmap32.deserialize(
                 toBytes(fwdDataPeer[bucket][sourceGidStr]),
                 true,
               );
-              bm.remove(deadGid);
-              fwdDataPeer[bucket][sourceGidStr] = bm.serialize(true);
+              sourceBm.remove(deadGid);
+              fwdDataPeer[bucket][sourceGidStr] = sourceBm.serialize(true);
             }
           }
         }
@@ -350,13 +379,19 @@ export default class IncrementalIndexUpdater {
     if (Object.prototype.hasOwnProperty.call(labels, label)) {
       return false;
     }
-    let maxId = -1;
-    for (const id of Object.values(labels)) {
-      if (id > maxId) {
-        maxId = id;
+    // Lazily initialize _nextLabelId from existing labels (O(L) once),
+    // then O(1) per subsequent new label.
+    if (this._nextLabelId === null) {
+      let maxId = -1;
+      for (const id of Object.values(labels)) {
+        if (id > maxId) {
+          maxId = id;
+        }
       }
+      this._nextLabelId = maxId + 1;
     }
-    labels[label] = maxId + 1;
+    labels[label] = this._nextLabelId;
+    this._nextLabelId++;
     return true;
   }
 
@@ -743,6 +778,111 @@ export default class IncrementalIndexUpdater {
     return meta.nodeToGlobalMap.get(nodeId);
   }
 
+  /**
+   * Collects alive edge keys incident to re-added nodes.
+   *
+   * Uses an ORSet-keyed adjacency cache so repeated updates can enumerate
+   * candidates by degree rather than scanning all alive edges each time.
+   *
+   * @param {Map<string, Set<string>>} adjacency
+   * @param {Set<string>} readdedNodes
+   * @returns {Set<string>}
+   * @private
+   */
+  _collectReaddedEdgeKeys(adjacency, readdedNodes) {
+    const keys = new Set();
+    for (const nodeId of readdedNodes) {
+      const incident = adjacency.get(nodeId);
+      if (!incident) {
+        continue;
+      }
+      for (const edgeKey of incident) {
+        keys.add(edgeKey);
+      }
+    }
+    return keys;
+  }
+
+  /**
+   * Gets or builds a node -> alive edgeKey adjacency map for state.edgeAlive.
+   *
+   * For cached maps, applies diff edge transitions to keep membership current.
+   *
+   * @param {import('./JoinReducer.js').WarpStateV5} state
+   * @param {import('../types/PatchDiff.js').PatchDiff} diff
+   * @returns {Map<string, Set<string>>}
+   * @private
+   */
+  _getOrBuildAliveEdgeAdjacency(state, diff) {
+    const { edgeAlive } = state;
+    let adjacency = this._edgeAdjacencyCache.get(edgeAlive);
+    if (!adjacency) {
+      adjacency = new Map();
+      for (const edgeKey of orsetElements(edgeAlive)) {
+        const { from, to } = decodeEdgeKey(edgeKey);
+        this._addEdgeKeyToAdjacency(adjacency, from, edgeKey);
+        this._addEdgeKeyToAdjacency(adjacency, to, edgeKey);
+      }
+      this._edgeAdjacencyCache.set(edgeAlive, adjacency);
+      return adjacency;
+    }
+
+    for (const edge of diff.edgesAdded) {
+      const edgeKey = `${edge.from}\0${edge.to}\0${edge.label}`;
+      if (!orsetContains(edgeAlive, edgeKey)) {
+        continue;
+      }
+      this._addEdgeKeyToAdjacency(adjacency, edge.from, edgeKey);
+      this._addEdgeKeyToAdjacency(adjacency, edge.to, edgeKey);
+    }
+    for (const edge of diff.edgesRemoved) {
+      const edgeKey = `${edge.from}\0${edge.to}\0${edge.label}`;
+      if (orsetContains(edgeAlive, edgeKey)) {
+        continue;
+      }
+      this._removeEdgeKeyFromAdjacency(adjacency, edge.from, edgeKey);
+      this._removeEdgeKeyFromAdjacency(adjacency, edge.to, edgeKey);
+    }
+
+    return adjacency;
+  }
+
+  /**
+   * Adds an edge key to one endpoint's adjacency set.
+   *
+   * @param {Map<string, Set<string>>} adjacency
+   * @param {string} nodeId
+   * @param {string} edgeKey
+   * @private
+   */
+  _addEdgeKeyToAdjacency(adjacency, nodeId, edgeKey) {
+    let set = adjacency.get(nodeId);
+    if (!set) {
+      set = new Set();
+      adjacency.set(nodeId, set);
+    }
+    set.add(edgeKey);
+  }
+
+  /**
+   * Removes an edge key from one endpoint's adjacency set.
+   *
+   * @param {Map<string, Set<string>>} adjacency
+   * @param {string} nodeId
+   * @param {string} edgeKey
+   * @private
+   */
+  _removeEdgeKeyFromAdjacency(adjacency, nodeId, edgeKey) {
+    const set = adjacency.get(nodeId);
+    if (!set) {
+      return;
+    }
+    set.delete(edgeKey);
+    if (set.size === 0) {
+      adjacency.delete(nodeId);
+    }
+  }
+
   /**
    * Deserializes a bitmap from edge shard data, or creates a new one.
    *
@@ -753,6 +893,9 @@ export default class IncrementalIndexUpdater {
    * @private
    */
   _deserializeBitmap(data, bucket, ownerStr) {
+    // getRoaringBitmap32() is internally memoized (returns cached constructor
+    // after first resolution). The repeated calls are cheap but the pattern
+    // is noisy. A future cleanup could cache the constructor at instance level.
     const RoaringBitmap32 = getRoaringBitmap32();
     if (data[bucket] && data[bucket][ownerStr]) {
       return RoaringBitmap32.deserialize(