@git-stunts/git-warp 12.2.0 → 12.2.1

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(

package/src/domain/services/JoinReducer.js

@@ -9,7 +9,7 @@
  * }
  */
 
-import { createORSet, orsetAdd, orsetRemove, orsetJoin, orsetContains } from '../crdt/ORSet.js';
+import { createORSet, orsetAdd, orsetRemove, orsetJoin, orsetContains, orsetClone } from '../crdt/ORSet.js';
 import { createVersionVector, vvMerge, vvClone, vvDeserialize } from '../crdt/VersionVector.js';
 import { lwwSet, lwwMax } from '../crdt/LWW.js';
 import { createEventId, compareEventIds } from '../utils/EventId.js';
@@ -17,6 +17,7 @@ import { createTickReceipt, OP_TYPES } from '../types/TickReceipt.js';
 import { encodeDot } from '../crdt/Dot.js';
 import { encodeEdgeKey, decodeEdgeKey, encodePropKey } from './KeyCodec.js';
 import { createEmptyDiff, mergeDiffs } from '../types/PatchDiff.js';
+import PatchError from '../errors/PatchError.js';
 
 // Re-export key codec functions for backward compatibility
 export {
@@ -32,7 +33,11 @@ export {
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
  * @property {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
- * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
+ * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility).
+ *   Always present at runtime (initialized to empty Map by createEmptyStateV5 and
+ *   deserializeFullStateV5). Edge birth events were introduced in a later schema
+ *   version; older checkpoints serialize without this field, but the deserializer
+ *   always produces an empty Map for them.
  */
 
 /**
@@ -102,6 +107,111 @@ export function isKnownOp(op) {
   return op && typeof op.type === 'string' && KNOWN_OPS.has(op.type);
 }
 
+/**
+ * Asserts that `op[field]` is a string. Throws PatchError if not.
+ * @param {Record<string, unknown>} op
+ * @param {string} field
+ */
+function requireString(op, field) {
+  if (typeof op[field] !== 'string') {
+    throw new PatchError(
+      `${op.type} op requires '${field}' to be a string, got ${typeof op[field]}`,
+      { context: { opType: op.type, field, actual: typeof op[field] } },
+    );
+  }
+}
+
+/**
+ * Asserts that `op[field]` is iterable (Array, Set, or any Symbol.iterator).
+ * @param {Record<string, unknown>} op
+ * @param {string} field
+ */
+function requireIterable(op, field) {
+  const val = op[field];
+  if (
+    val === null ||
+    val === undefined ||
+    typeof val !== 'object' ||
+    typeof /** @type {Iterable<unknown>} */ (val)[Symbol.iterator] !== 'function'
+  ) {
+    throw new PatchError(
+      `${op.type} op requires '${field}' to be iterable, got ${typeof val}`,
+      { context: { opType: op.type, field, actual: typeof val } },
+    );
+  }
+}
+
+/**
+ * Asserts that `op.dot` is an object with writerId (string) and counter (number).
+ * @param {Record<string, unknown>} op
+ */
+function requireDot(op) {
+  const { dot } = op;
+  if (!dot || typeof dot !== 'object') {
+    throw new PatchError(
+      `${op.type} op requires 'dot' to be an object, got ${typeof dot}`,
+      { context: { opType: op.type, field: 'dot', actual: typeof dot } },
+    );
+  }
+  const d = /** @type {Record<string, unknown>} */ (dot);
+  if (typeof d.writerId !== 'string') {
+    throw new PatchError(
+      `${op.type} op requires 'dot.writerId' to be a string, got ${typeof d.writerId}`,
+      { context: { opType: op.type, field: 'dot.writerId', actual: typeof d.writerId } },
+    );
+  }
+  if (typeof d.counter !== 'number') {
+    throw new PatchError(
+      `${op.type} op requires 'dot.counter' to be a number, got ${typeof d.counter}`,
+      { context: { opType: op.type, field: 'dot.counter', actual: typeof d.counter } },
+    );
+  }
+}
+
+/**
+ * Validates that an operation has the required fields for its type.
+ * Throws PatchError for malformed ops. Unknown/BlobValue types pass through
+ * for forward compatibility.
+ *
+ * @param {Record<string, unknown>} op
+ */
+function validateOp(op) {
+  if (!op || typeof op.type !== 'string') {
+    throw new PatchError(
+      `Invalid op: expected object with string 'type', got ${op === null || op === undefined ? String(op) : typeof op.type}`,
+      { context: { actual: op === null || op === undefined ? String(op) : typeof op.type } },
+    );
+  }
+
+  switch (op.type) {
+    case 'NodeAdd':
+      requireString(op, 'node');
+      requireDot(op);
+      break;
+    case 'NodeRemove':
+      // node is optional (informational for receipts); observedDots is required for mutation
+      requireIterable(op, 'observedDots');
+      break;
+    case 'EdgeAdd':
+      requireString(op, 'from');
+      requireString(op, 'to');
+      requireString(op, 'label');
+      requireDot(op);
+      break;
+    case 'EdgeRemove':
+      // from/to/label are optional (informational for receipts); observedDots is required for mutation
+      requireIterable(op, 'observedDots');
+      break;
+    case 'PropSet':
+      requireString(op, 'node');
+      requireString(op, 'key');
+      break;
+    default:
+      // BlobValue and unknown types: no validation (forward-compat)
+      break;
+  }
+}
+
 /**
  * Applies a single V2 operation to the given CRDT state.
  *
@@ -110,6 +220,7 @@ export function isKnownOp(op) {
  * @param {import('../utils/EventId.js').EventId} eventId - The event ID for LWW ordering
  */
 export function applyOpV2(state, op, eventId) {
+  validateOp(/** @type {Record<string, unknown>} */ (op));
   switch (op.type) {
     case 'NodeAdd':
       orsetAdd(state.nodeAlive, /** @type {string} */ (op.node), /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
@@ -213,21 +324,18 @@ function nodeAddOutcome(orset, op) {
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID (or '*') as target
  */
 function nodeRemoveOutcome(orset, op) {
-  // Check if any of the observed dots are currently non-tombstoned
+  // Build a reverse index (dot → elementId) for the observed dots to avoid
+  // O(|observedDots| × |entries|) scanning. Same pattern as buildDotToElement.
+  const targetDots = op.observedDots instanceof Set
+    ? op.observedDots
+    : new Set(op.observedDots);
+  const dotToElement = buildDotToElement(orset, targetDots);
+
   let effective = false;
-  for (const encodedDot of op.observedDots) {
-    if (!orset.tombstones.has(encodedDot)) {
-      // This dot exists and is not yet tombstoned, so the remove is effective
-      // Check if any entry actually has this dot
-      for (const dots of orset.entries.values()) {
-        if (dots.has(encodedDot)) {
-          effective = true;
-          break;
-        }
-      }
-      if (effective) {
-        break;
-      }
+  for (const encodedDot of targetDots) {
+    if (!orset.tombstones.has(encodedDot) && dotToElement.has(encodedDot)) {
+      effective = true;
+      break;
     }
   }
   const target = op.node || '*';
@@ -279,18 +387,18 @@ function edgeAddOutcome(orset, op, edgeKey) {
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key (or '*') as target
  */
 function edgeRemoveOutcome(orset, op) {
+  // Build a reverse index (dot → elementId) for the observed dots to avoid
+  // O(|observedDots| × |entries|) scanning. Same pattern as buildDotToElement.
+  const targetDots = op.observedDots instanceof Set
+    ? op.observedDots
+    : new Set(op.observedDots);
+  const dotToElement = buildDotToElement(orset, targetDots);
+
   let effective = false;
-  for (const encodedDot of op.observedDots) {
-    if (!orset.tombstones.has(encodedDot)) {
-      for (const dots of orset.entries.values()) {
-        if (dots.has(encodedDot)) {
-          effective = true;
-          break;
-        }
-      }
-      if (effective) {
-        break;
-      }
+  for (const encodedDot of targetDots) {
+    if (!orset.tombstones.has(encodedDot) && dotToElement.has(encodedDot)) {
+      effective = true;
+      break;
     }
   }
   // Construct target from op fields if available
@@ -603,6 +711,7 @@ export function applyWithDiff(state, patch, patchSha) {
 
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
+    validateOp(/** @type {Record<string, unknown>} */ (op));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
     const typedOp = /** @type {import('../types/WarpTypesV2.js').OpV2} */ (op);
     const before = snapshotBeforeOp(state, typedOp);
@@ -631,6 +740,7 @@ export function applyWithReceipt(state, patch, patchSha) {
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
+    validateOp(/** @type {Record<string, unknown>} */ (op));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
 
     // Determine outcome BEFORE applying the op (state is pre-op)
@@ -868,16 +978,16 @@ export function reduceV5(patches, initialState, options) {
  * - Creating a branch point for speculative execution
  * - Ensuring immutability when passing state across API boundaries
  *
- * **Implementation Note**: OR-Sets are cloned by joining with an empty set,
- * which creates new data structures with identical contents.
+ * **Implementation Note**: OR-Sets are cloned via `orsetClone()` which
+ * directly copies entries and tombstones without merge logic overhead.
  *
  * @param {WarpStateV5} state - The state to clone
  * @returns {WarpStateV5} A new state with identical contents but independent data structures
  */
 export function cloneStateV5(state) {
   return {
-    nodeAlive: orsetJoin(state.nodeAlive, createORSet()),
-    edgeAlive: orsetJoin(state.edgeAlive, createORSet()),
+    nodeAlive: orsetClone(state.nodeAlive),
+    edgeAlive: orsetClone(state.edgeAlive),
     prop: new Map(state.prop),
     observedFrontier: vvClone(state.observedFrontier),
     edgeBirthEvent: new Map(state.edgeBirthEvent || []),

package/src/domain/services/MaterializedViewService.js

@@ -21,6 +21,9 @@ import IncrementalIndexUpdater from './IncrementalIndexUpdater.js';
 import { orsetElements, orsetContains } from '../crdt/ORSet.js';
 import { decodeEdgeKey } from './KeyCodec.js';
 
+/** Prefix for property shard paths in the index tree. */
+const PROPS_PREFIX = 'props_';
+
 /**
  * @typedef {import('./BitmapNeighborProvider.js').LogicalIndex} LogicalIndex
  */
@@ -66,7 +69,7 @@ function buildInMemoryPropertyReader(tree, codec) {
   /** @type {Record<string, string>} */
   const propShardOids = {};
   for (const path of Object.keys(tree)) {
-    if (path.startsWith('props_')) {
+    if (path.startsWith(PROPS_PREFIX)) {
       propShardOids[path] = path;
     }
   }
@@ -93,7 +96,7 @@ function partitionShardOids(shardOids) {
   const propOids = {};
 
   for (const [path, oid] of Object.entries(shardOids)) {
-    if (path.startsWith('props_')) {
+    if (path.startsWith(PROPS_PREFIX)) {
       propOids[path] = oid;
     } else {
       indexOids[path] = oid;
@@ -105,6 +108,10 @@ function partitionShardOids(shardOids) {
 /**
  * Mulberry32 PRNG — deterministic 32-bit generator from a seed.
  *
+ * mulberry32 is a fast 32-bit PRNG by Tommy Ettinger. The magic constants
+ * (0x6D2B79F5, shifts 15/13/16) are part of the published algorithm.
+ * See: https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+ *
  * @param {number} seed
  * @returns {() => number} Returns values in [0, 1)
  */
@@ -134,6 +141,10 @@ function sampleNodes(allNodes, sampleRate, seed) {
   }
   const rng = mulberry32(seed);
   const sampled = allNodes.filter(() => rng() < sampleRate);
+  // When the initial sample is empty (e.g., graph has fewer nodes than
+  // sample size), we fall back to using all available nodes. This changes
+  // the distribution but is acceptable since the sample is only used for
+  // layout heuristics.
   if (sampled.length === 0) {
     sampled.push(allNodes[Math.floor(rng() * allNodes.length)]);
   }