@git-stunts/git-warp 12.1.0 → 12.2.1

package/src/domain/services/CheckpointService.js

@@ -11,7 +11,7 @@
  * @see WARP Spec Section 10
  */
 
-import { serializeStateV5, computeStateHashV5 } from './StateSerializerV5.js';
+import { computeStateHashV5 } from './StateSerializerV5.js';
 import {
   serializeFullStateV5,
   deserializeFullStateV5,
@@ -86,7 +86,6 @@ function partitionTreeOids(rawOids) {
  * ```
  * <checkpoint_commit_tree>/
  * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
- * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
  * ├── frontier.cbor        # Writer frontiers
  * ├── appliedVV.cbor       # Version vector of dots in state
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
@@ -116,7 +115,6 @@ export async function create({ persistence, graphName, state, frontier, parents
  * ```
  * <checkpoint_tree>/
  * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
- * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
  * ├── frontier.cbor        # Writer frontiers
  * ├── appliedVV.cbor       # Version vector of dots in state
  * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
@@ -150,7 +148,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);
@@ -161,8 +161,7 @@ export async function createV5({
   // 3. Serialize full state (AUTHORITATIVE)
   const stateBuffer = serializeFullStateV5(checkpointState, { codec });
 
-  // 4. Serialize visible projection (CACHE)
-  const visibleBuffer = serializeStateV5(checkpointState, { codec });
+  // 4. Compute state hash
   const stateHash = await computeStateHashV5(checkpointState, { codec, crypto: /** @type {import('../../ports/CryptoPort.js').default} */ (crypto) });
 
   // 5. Serialize frontier and appliedVV
@@ -171,7 +170,6 @@ export async function createV5({
 
   // 6. Write blobs to git
   const stateBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (stateBuffer));
-  const visibleBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (visibleBuffer));
   const frontierBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (frontierBuffer));
   const appliedVVBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (appliedVVBuffer));
 
@@ -192,6 +190,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)
@@ -207,7 +210,6 @@ export async function createV5({
     `100644 blob ${appliedVVBlobOid}\tappliedVV.cbor`,
     `100644 blob ${frontierBlobOid}\tfrontier.cbor`,
     `100644 blob ${stateBlobOid}\tstate.cbor`,
-    `100644 blob ${visibleBlobOid}\tvisible.cbor`,
   ];
 
   // Add provenance index if present
@@ -240,6 +242,8 @@ export async function createV5({
     stateHash,
     frontierOid: frontierBlobOid,
     indexOid: treeOid,
+    // 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 ? 4 : 2,
   });
 

package/src/domain/services/Frontier.js

@@ -91,6 +91,24 @@ export function cloneFrontier(frontier) {
   return new Map(frontier);
 }
 
+/**
+ * Produces a stable, deterministic fingerprint of a frontier.
+ *
+ * Sorts entries by writer ID and JSON-stringifies the sorted pairs.
+ * Two frontiers produce the same fingerprint iff they have identical
+ * writer→SHA mappings. Used for snapshot isolation checks (B63)
+ * and diagnostic logging.
+ *
+ * @param {Frontier} frontier
+ * @returns {string} Deterministic JSON string of sorted entries
+ */
+export function frontierFingerprint(frontier) {
+  const sorted = [...frontier.entries()].sort(
+    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return JSON.stringify(sorted);
+}
+
 /**
  * Merges two frontiers, taking the "later" entry for each writer.
  * Note: This is a simple merge that takes entries from both.

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) {
@@ -830,52 +832,38 @@ export default class GraphTraversal {
       }
     }
 
-    // Phase 2: Kahn's — collect zero-indegree nodes, sort them lex, yield in order
-    /** @type {string[]} */
-    const ready = [];
+    // Phase 2: Kahn's — MinHeap for O(N log N) zero-indegree processing
+    const ready = new MinHeap({ tieBreaker: lexTieBreaker });
     for (const nodeId of discovered) {
       if ((inDegree.get(nodeId) || 0) === 0) {
-        ready.push(nodeId);
+        ready.insert(nodeId, 0);
       }
     }
-    ready.sort(lexTieBreaker);
 
+    /** @type {string[]} */
     const sorted = [];
-    let rHead = 0;
-    while (rHead < ready.length && sorted.length < maxNodes) {
+    while (!ready.isEmpty() && sorted.length < maxNodes) {
       if (sorted.length % 1000 === 0) {
         checkAborted(signal, 'topologicalSort');
       }
-      const nodeId = /** @type {string} */ (ready[rHead++]);
+      const nodeId = /** @type {string} */ (ready.extractMin());
       sorted.push(nodeId);
 
       const neighbors = adjList.get(nodeId) || [];
-      /** @type {string[]} */
-      const newlyReady = [];
       for (const neighborId of neighbors) {
         const deg = /** @type {number} */ (inDegree.get(neighborId)) - 1;
         inDegree.set(neighborId, deg);
         if (deg === 0) {
-          newlyReady.push(neighborId);
+          ready.insert(neighborId, 0);
         }
       }
-      // Insert newly ready nodes in sorted position
-      if (newlyReady.length > 0) {
-        newlyReady.sort(lexTieBreaker);
-        // Compact consumed prefix before merge to keep rHead at 0
-        if (rHead > 0) {
-          ready.splice(0, rHead);
-          rHead = 0;
-        }
-        this._insertSorted(ready, newlyReady);
-      }
     }
 
     const hasCycle = computeTopoHasCycle({
       sortedLength: sorted.length,
       discoveredSize: discovered.size,
       maxNodes,
-      readyRemaining: rHead < ready.length,
+      readyRemaining: !ready.isEmpty(),
     });
     if (hasCycle && throwOnCycle) {
       // Find a back-edge as witness
@@ -1209,31 +1197,4 @@ export default class GraphTraversal {
     return candidatePred < current;
   }
 
-  /**
-   * Inserts sorted items into a sorted array maintaining order.
-   * Both input arrays must be sorted by lexTieBreaker.
-   *
-   * @param {string[]} target - Sorted array to insert into (mutated in place)
-   * @param {string[]} items - Sorted items to insert
-   * @private
-   */
-  _insertSorted(target, items) {
-    // O(n+k) merge: build merged array from two sorted inputs
-    const merged = [];
-    let ti = 0;
-    let ii = 0;
-    while (ti < target.length && ii < items.length) {
-      if (target[ti] <= items[ii]) {
-        merged.push(target[ti++]);
-      } else {
-        merged.push(items[ii++]);
-      }
-    }
-    while (ti < target.length) { merged.push(target[ti++]); }
-    while (ii < items.length) { merged.push(items[ii++]); }
-    target.length = 0;
-    for (let i = 0; i < merged.length; i++) {
-      target.push(merged[i]);
-    }
-  }
 }

package/src/domain/services/HttpSyncServer.js

@@ -10,6 +10,7 @@
 
 import { z } from 'zod';
 import SyncAuthService from './SyncAuthService.js';
+import { validateSyncRequest } from './SyncPayloadSchema.js';
 
 const DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
 const MAX_REQUEST_BYTES_CEILING = 128 * 1024 * 1024; // 134217728
@@ -117,26 +118,7 @@ function jsonResponse(data) {
   };
 }
 
-/**
- * Validates that a sync request object has the expected shape.
- *
- * @param {unknown} parsed - Parsed JSON body
- * @returns {boolean} True if valid
- * @private
- */
-function isValidSyncRequest(parsed) {
-  if (!parsed || typeof parsed !== 'object') {
-    return false;
-  }
-  const rec = /** @type {Record<string, unknown>} */ (parsed);
-  if (rec.type !== 'sync-request') {
-    return false;
-  }
-  if (!rec.frontier || typeof rec.frontier !== 'object' || Array.isArray(rec.frontier)) {
-    return false;
-  }
-  return true;
-}
+// isValidSyncRequest replaced by SyncPayloadSchema.validateSyncRequest (B64)
 
 /**
  * Checks the content-type header. Returns an error response if the
@@ -200,6 +182,7 @@ function checkBodySize(body, maxBytes) {
 
 /**
  * Parses and validates the request body as a sync request.
+ * Uses Zod-based SyncPayloadSchema for shape + resource limit validation.
  *
  * @param {Buffer|undefined} body
  * @returns {{ error: { status: number, headers: Object, body: string }, parsed: null } | { error: null, parsed: import('./SyncProtocol.js').SyncRequest }}
@@ -215,11 +198,12 @@ function parseBody(body) {
     return { error: errorResponse(400, 'Invalid JSON'), parsed: null };
   }
 
-  if (!isValidSyncRequest(parsed)) {
-    return { error: errorResponse(400, 'Invalid sync request'), parsed: null };
+  const validation = validateSyncRequest(parsed);
+  if (!validation.ok) {
+    return { error: errorResponse(400, `Invalid sync request: ${validation.error}`), parsed: null };
   }
 
-  return { error: null, parsed };
+  return { error: null, parsed: /** @type {import('./SyncProtocol.js').SyncRequest} */ (validation.value) };
 }
 
 /**
@@ -298,12 +282,17 @@ export default class HttpSyncServer {
       this._auth.recordLogOnlyPassthrough();
     }
 
-    // Writer whitelist (uses parsed body for writer IDs)
-    if (parsed.patches && typeof parsed.patches === 'object') {
-      const writerIds = Object.keys(parsed.patches);
-      const writerResult = this._auth.enforceWriters(writerIds);
-      if (!writerResult.ok) {
-        return errorResponse(writerResult.status, writerResult.reason);
+    // Writer whitelist: for sync-requests, extract writer IDs from frontier
+    // keys (the writers the peer claims to have). Sync-requests don't carry
+    // patches — the server generates the response. For sync-responses with
+    // patches, trust-gate should be on patch authors (handled client-side).
+    if (parsed.frontier && typeof parsed.frontier === 'object') {
+      const writerIds = Object.keys(/** @type {Record<string, string>} */ (parsed.frontier));
+      if (writerIds.length > 0) {
+        const writerResult = this._auth.enforceWriters(writerIds);
+        if (!writerResult.ok) {
+          return errorResponse(writerResult.status, writerResult.reason);
+        }
       }
     }
 

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(