@git-stunts/git-warp 10.1.1

package/src/domain/services/DagTopology.js

@@ -0,0 +1,239 @@
+/**
+ * Service for DAG topology operations: topological sort and
+ * common ancestor finding.
+ *
+ * Split from CommitDagTraversalService as part of the SRP refactor.
+ *
+ * @module domain/services/DagTopology
+ */
+
+import nullLogger from '../utils/nullLogger.js';
+import TraversalError from '../errors/TraversalError.js';
+import { checkAborted } from '../utils/cancellation.js';
+
+/**
+ * @typedef {'forward' | 'reverse'} TraversalDirection
+ */
+
+/**
+ * Default limits for topology operations.
+ * @const
+ */
+const DEFAULT_MAX_NODES = 100000;
+const DEFAULT_MAX_DEPTH = 1000;
+
+/**
+ * Service for DAG topology operations.
+ *
+ * Provides topological sort (Kahn's algorithm) and common
+ * ancestor finding using the index reader for O(1) lookups.
+ */
+export default class DagTopology {
+  /**
+   * Creates a new DagTopology service.
+   *
+   * @param {Object} options
+   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
+   * @param {import('./DagTraversal.js').default} [options.traversal] - Traversal service for ancestor enumeration
+   */
+  constructor({ indexReader, logger = nullLogger, traversal } = {}) {
+    if (!indexReader) {
+      throw new Error('DagTopology requires an indexReader');
+    }
+    this._indexReader = indexReader;
+    this._logger = logger;
+    this._traversal = traversal;
+  }
+
+  /**
+   * Gets neighbors for a node based on direction.
+   *
+   * @param {string} sha - Node SHA to get neighbors for
+   * @param {TraversalDirection} direction - 'forward' for children, 'reverse' for parents
+   * @returns {Promise<string[]>} Array of neighbor SHAs
+   * @private
+   */
+  async _getNeighbors(sha, direction) {
+    if (direction === 'forward') {
+      return await this._indexReader.getChildren(sha);
+    }
+    return await this._indexReader.getParents(sha);
+  }
+
+  /**
+   * Finds common ancestors of multiple nodes.
+   *
+   * An ancestor is "common" if it can be reached by following parent edges
+   * from ALL of the input nodes.
+   *
+   * @param {Object} options - Common ancestor options
+   * @param {string[]} options.shas - Array of node SHAs
+   * @param {number} [options.maxResults=100] - Maximum ancestors to return
+   * @param {number} [options.maxDepth=1000] - Maximum depth to search
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @returns {Promise<string[]>} Array of common ancestor SHAs
+   */
+  async commonAncestors({ shas, maxResults = 100, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
+    if (shas.length === 0) { return []; }
+    if (shas.length === 1) {
+      const ancestors = [];
+      for await (const node of this._traversal.ancestors({ sha: shas[0], maxNodes: maxResults, maxDepth, signal })) {
+        ancestors.push(node.sha);
+      }
+      return ancestors;
+    }
+
+    this._logger.debug('commonAncestors started', { shaCount: shas.length, maxDepth });
+
+    const ancestorCounts = new Map();
+    const requiredCount = shas.length;
+
+    for (const sha of shas) {
+      checkAborted(signal, 'commonAncestors');
+      const visited = new Set();
+      for await (const node of this._traversal.ancestors({ sha, maxDepth, signal })) {
+        if (!visited.has(node.sha)) {
+          visited.add(node.sha);
+          ancestorCounts.set(node.sha, (ancestorCounts.get(node.sha) || 0) + 1);
+        }
+      }
+    }
+
+    const common = [];
+    for (const [ancestor, count] of ancestorCounts) {
+      if (count === requiredCount) {
+        common.push(ancestor);
+        if (common.length >= maxResults) { break; }
+      }
+    }
+
+    this._logger.debug('commonAncestors completed', { found: common.length });
+    return common;
+  }
+
+  /**
+   * Yields nodes in topological order using Kahn's algorithm.
+   *
+   * Topological order ensures that for every directed edge A -> B, node A
+   * is yielded before node B.
+   *
+   * @param {Object} options - Topological sort options
+   * @param {string} options.start - Starting node SHA
+   * @param {number} [options.maxNodes=100000] - Maximum nodes to yield
+   * @param {TraversalDirection} [options.direction='forward'] - Direction
+   * @param {boolean} [options.throwOnCycle=false] - If true, throws on cycle detection
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @yields {{sha: string, depth: number, parent: null}} Nodes in topological order
+   * @throws {TraversalError} With code 'CYCLE_DETECTED' if throwOnCycle is true
+   */
+  async *topologicalSort({
+    start,
+    maxNodes = DEFAULT_MAX_NODES,
+    direction = 'forward',
+    throwOnCycle = false,
+    signal,
+  }) {
+    this._logger.debug('topologicalSort started', { start, direction, maxNodes });
+
+    // Phase 1: Discover all reachable nodes and compute in-degrees
+    const inDegree = new Map();
+    const allNodes = new Set();
+    const edges = new Map();
+
+    const queue = [start];
+    allNodes.add(start);
+
+    while (queue.length > 0) {
+      if (allNodes.size % 1000 === 0) {
+        checkAborted(signal, 'topologicalSort');
+      }
+
+      const sha = queue.shift();
+      const neighbors = await this._getNeighbors(sha, direction);
+      edges.set(sha, neighbors);
+
+      for (const neighbor of neighbors) {
+        inDegree.set(neighbor, (inDegree.get(neighbor) || 0) + 1);
+        if (!allNodes.has(neighbor)) {
+          allNodes.add(neighbor);
+          queue.push(neighbor);
+        }
+      }
+    }
+
+    if (!inDegree.has(start)) {
+      inDegree.set(start, 0);
+    }
+
+    // Phase 2: Yield nodes with in-degree 0
+    const ready = [];
+    for (const sha of allNodes) {
+      if (!inDegree.has(sha) || inDegree.get(sha) === 0) {
+        ready.push(sha);
+      }
+    }
+
+    let nodesYielded = 0;
+    const depthMap = new Map([[start, 0]]);
+
+    while (ready.length > 0 && nodesYielded < maxNodes) {
+      if (nodesYielded % 1000 === 0) {
+        checkAborted(signal, 'topologicalSort');
+      }
+
+      const sha = ready.shift();
+      const depth = depthMap.get(sha) || 0;
+
+      nodesYielded++;
+      yield { sha, depth, parent: null };
+
+      const neighbors = edges.get(sha) || [];
+      for (const neighbor of neighbors) {
+        const newDegree = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, newDegree);
+
+        if (!depthMap.has(neighbor)) {
+          depthMap.set(neighbor, depth + 1);
+        }
+
+        if (newDegree === 0) {
+          ready.push(neighbor);
+        }
+      }
+    }
+
+    // Phase 3: Detect cycles
+    const cycleDetected = nodesYielded < allNodes.size;
+
+    if (cycleDetected) {
+      const cycleNodeCount = allNodes.size - nodesYielded;
+      this._logger.warn('Cycle detected in topological sort', {
+        start,
+        direction,
+        nodesYielded,
+        totalNodes: allNodes.size,
+        nodesInCycle: cycleNodeCount,
+      });
+
+      if (throwOnCycle) {
+        throw new TraversalError('Cycle detected in graph during topological sort', {
+          code: 'CYCLE_DETECTED',
+          context: {
+            start,
+            direction,
+            nodesYielded,
+            totalNodes: allNodes.size,
+            nodesInCycle: cycleNodeCount,
+          },
+        });
+      }
+    }
+
+    this._logger.debug('topologicalSort completed', {
+      nodesYielded,
+      totalNodes: allNodes.size,
+      cycleDetected,
+    });
+  }
+}

package/src/domain/services/DagTraversal.js

@@ -0,0 +1,245 @@
+/**
+ * Service for DAG traversal operations: BFS, DFS, ancestor/descendant
+ * enumeration, and reachability checks.
+ *
+ * Split from CommitDagTraversalService as part of the SRP refactor.
+ *
+ * @module domain/services/DagTraversal
+ */
+
+import nullLogger from '../utils/nullLogger.js';
+import { checkAborted } from '../utils/cancellation.js';
+
+/**
+ * @typedef {'forward' | 'reverse'} TraversalDirection
+ */
+
+/**
+ * @typedef {Object} TraversalNode
+ * @property {string} sha - The node's SHA
+ * @property {number} depth - Distance from start node
+ * @property {string|null} parent - SHA of the node that led to this one
+ */
+
+/**
+ * Default limits for traversal operations.
+ * @const
+ */
+const DEFAULT_MAX_NODES = 100000;
+const DEFAULT_MAX_DEPTH = 1000;
+
+/**
+ * Service for DAG traversal operations.
+ *
+ * Provides BFS, DFS, ancestor/descendant enumeration,
+ * and reachability checks using async generators for
+ * memory-efficient processing of arbitrarily large graphs.
+ */
+export default class DagTraversal {
+  /**
+   * Creates a new DagTraversal service.
+   *
+   * @param {Object} options
+   * @param {import('./BitmapIndexReader.js').default} options.indexReader - Index reader for O(1) lookups
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger instance
+   */
+  constructor({ indexReader, logger = nullLogger } = {}) {
+    if (!indexReader) {
+      throw new Error('DagTraversal requires an indexReader');
+    }
+    this._indexReader = indexReader;
+    this._logger = logger;
+  }
+
+  /**
+   * Gets neighbors for a node based on direction.
+   *
+   * @param {string} sha - Node SHA to get neighbors for
+   * @param {TraversalDirection} direction - 'forward' for children, 'reverse' for parents
+   * @returns {Promise<string[]>} Array of neighbor SHAs
+   * @private
+   */
+  async _getNeighbors(sha, direction) {
+    if (direction === 'forward') {
+      return await this._indexReader.getChildren(sha);
+    }
+    return await this._indexReader.getParents(sha);
+  }
+
+  /**
+   * Breadth-first traversal from a starting node.
+   *
+   * BFS explores nodes level-by-level, visiting all nodes at depth N before
+   * moving to depth N+1. This guarantees that nodes are yielded in order of
+   * increasing distance from the start node.
+   *
+   * @param {Object} options - Traversal options
+   * @param {string} options.start - Starting node SHA
+   * @param {number} [options.maxNodes=100000] - Maximum nodes to visit
+   * @param {number} [options.maxDepth=1000] - Maximum depth to traverse
+   * @param {TraversalDirection} [options.direction='forward'] - Traversal direction
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @yields {TraversalNode} Nodes in BFS order
+   */
+  async *bfs({
+    start,
+    maxNodes = DEFAULT_MAX_NODES,
+    maxDepth = DEFAULT_MAX_DEPTH,
+    direction = 'forward',
+    signal,
+  }) {
+    const visited = new Set();
+    const queue = [{ sha: start, depth: 0, parent: null }];
+    let nodesYielded = 0;
+
+    this._logger.debug('BFS started', { start, direction, maxNodes, maxDepth });
+
+    while (queue.length > 0 && nodesYielded < maxNodes) {
+      if (nodesYielded % 1000 === 0) {
+        checkAborted(signal, 'bfs');
+      }
+
+      const current = queue.shift();
+
+      if (visited.has(current.sha)) { continue; }
+      if (current.depth > maxDepth) { continue; }
+
+      visited.add(current.sha);
+      nodesYielded++;
+      yield current;
+
+      if (current.depth < maxDepth) {
+        const neighbors = await this._getNeighbors(current.sha, direction);
+        for (const neighborSha of neighbors) {
+          if (!visited.has(neighborSha)) {
+            queue.push({ sha: neighborSha, depth: current.depth + 1, parent: current.sha });
+          }
+        }
+      }
+    }
+
+    this._logger.debug('BFS completed', { nodesVisited: nodesYielded, start, direction });
+  }
+
+  /**
+   * Depth-first pre-order traversal from a starting node.
+   *
+   * DFS explores as far as possible along each branch before backtracking.
+   *
+   * @param {Object} options - Traversal options
+   * @param {string} options.start - Starting node SHA
+   * @param {number} [options.maxNodes=100000] - Maximum nodes to visit
+   * @param {number} [options.maxDepth=1000] - Maximum depth to traverse
+   * @param {TraversalDirection} [options.direction='forward'] - Traversal direction
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @yields {TraversalNode} Nodes in DFS pre-order
+   */
+  async *dfs({
+    start,
+    maxNodes = DEFAULT_MAX_NODES,
+    maxDepth = DEFAULT_MAX_DEPTH,
+    direction = 'forward',
+    signal,
+  }) {
+    const visited = new Set();
+    const stack = [{ sha: start, depth: 0, parent: null }];
+    let nodesYielded = 0;
+
+    this._logger.debug('DFS started', { start, direction, maxNodes, maxDepth });
+
+    while (stack.length > 0 && nodesYielded < maxNodes) {
+      if (nodesYielded % 1000 === 0) {
+        checkAborted(signal, 'dfs');
+      }
+
+      const current = stack.pop();
+
+      if (visited.has(current.sha)) { continue; }
+      if (current.depth > maxDepth) { continue; }
+
+      visited.add(current.sha);
+      nodesYielded++;
+      yield current;
+
+      if (current.depth < maxDepth) {
+        const neighbors = await this._getNeighbors(current.sha, direction);
+        // Push in reverse order so first neighbor is processed first
+        for (let i = neighbors.length - 1; i >= 0; i--) {
+          if (!visited.has(neighbors[i])) {
+            stack.push({ sha: neighbors[i], depth: current.depth + 1, parent: current.sha });
+          }
+        }
+      }
+    }
+
+    this._logger.debug('DFS completed', { nodesVisited: nodesYielded, start, direction });
+  }
+
+  /**
+   * Yields all ancestors of a node (transitive closure going backwards).
+   *
+   * @param {Object} options - Traversal options
+   * @param {string} options.sha - Starting node SHA
+   * @param {number} [options.maxNodes=100000] - Maximum ancestor nodes to yield
+   * @param {number} [options.maxDepth=1000] - Maximum generations to traverse
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @yields {TraversalNode} Ancestor nodes in BFS order
+   */
+  async *ancestors({ sha, maxNodes = DEFAULT_MAX_NODES, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
+    yield* this.bfs({ start: sha, maxNodes, maxDepth, direction: 'reverse', signal });
+  }
+
+  /**
+   * Yields all descendants of a node (transitive closure going forwards).
+   *
+   * @param {Object} options - Traversal options
+   * @param {string} options.sha - Starting node SHA
+   * @param {number} [options.maxNodes=100000] - Maximum descendant nodes to yield
+   * @param {number} [options.maxDepth=1000] - Maximum generations to traverse
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @yields {TraversalNode} Descendant nodes in BFS order
+   */
+  async *descendants({ sha, maxNodes = DEFAULT_MAX_NODES, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
+    yield* this.bfs({ start: sha, maxNodes, maxDepth, direction: 'forward', signal });
+  }
+
+  /**
+   * Checks if there is any path from one node to another.
+   *
+   * Delegates to the path-finding service's findPath if one is set,
+   * otherwise performs its own BFS-based reachability check.
+   *
+   * @param {Object} options - Reachability options
+   * @param {string} options.from - Source node SHA
+   * @param {string} options.to - Target node SHA
+   * @param {number} [options.maxDepth=1000] - Maximum search depth
+   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation
+   * @returns {Promise<boolean>} True if a path exists
+   */
+  async isReachable({ from, to, maxDepth = DEFAULT_MAX_DEPTH, signal }) {
+    if (this._pathFinder) {
+      const result = await this._pathFinder.findPath({ from, to, maxDepth, signal });
+      return result.found;
+    }
+    // Fallback: BFS-based reachability
+    if (from === to) {
+      return true;
+    }
+    for await (const node of this.bfs({ start: from, maxDepth, direction: 'forward', signal })) {
+      if (node.sha === to) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Sets the path-finding service for reachability delegation.
+   *
+   * @param {import('./DagPathFinding.js').default} pathFinder - Path finding service
+   * @internal
+   */
+  _setPathFinder(pathFinder) {
+    this._pathFinder = pathFinder;
+  }
+}

package/src/domain/services/Frontier.js

@@ -0,0 +1,108 @@
+import defaultCodec from '../utils/defaultCodec.js';
+
+/**
+ * Frontier: Map of writerId -> lastSeenPatchSha
+ * @typedef {Map<string, string>} Frontier
+ */
+
+/**
+ * Creates an empty frontier.
+ * @returns {Frontier}
+ */
+export function createFrontier() {
+  return new Map();
+}
+
+/**
+ * Updates the frontier with a new patch.
+ * Mutates the frontier in place.
+ *
+ * @param {Frontier} frontier - The frontier to update
+ * @param {string} writerId - Writer ID
+ * @param {string} patchSha - Latest patch SHA for this writer
+ * @returns {void}
+ */
+export function updateFrontier(frontier, writerId, patchSha) {
+  frontier.set(writerId, patchSha);
+}
+
+/**
+ * Gets the last-seen patch SHA for a writer.
+ * @param {Frontier} frontier
+ * @param {string} writerId
+ * @returns {string | undefined}
+ */
+export function getFrontierEntry(frontier, writerId) {
+  return frontier.get(writerId);
+}
+
+/**
+ * Lists all writers in the frontier.
+ * @param {Frontier} frontier
+ * @returns {string[]} Sorted list of writer IDs
+ */
+export function getWriters(frontier) {
+  return Array.from(frontier.keys()).sort();
+}
+
+/**
+ * Serializes frontier to canonical CBOR bytes.
+ * Keys are sorted for determinism.
+ * @param {Frontier} frontier
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} options.codec - Codec for serialization
+ * @returns {Buffer}
+ */
+export function serializeFrontier(frontier, { codec } = {}) {
+  const c = codec || defaultCodec;
+  // Convert Map to sorted object for deterministic encoding
+  const obj = {};
+  const sortedKeys = Array.from(frontier.keys()).sort();
+  for (const key of sortedKeys) {
+    obj[key] = frontier.get(key);
+  }
+  return c.encode(obj);
+}
+
+/**
+ * Deserializes frontier from CBOR bytes.
+ * @param {Buffer} buffer
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} options.codec - Codec for deserialization
+ * @returns {Frontier}
+ */
+export function deserializeFrontier(buffer, { codec } = {}) {
+  const c = codec || defaultCodec;
+  const obj = c.decode(buffer);
+  const frontier = new Map();
+  for (const [writerId, patchSha] of Object.entries(obj)) {
+    frontier.set(writerId, patchSha);
+  }
+  return frontier;
+}
+
+/**
+ * Clones a frontier.
+ * @param {Frontier} frontier
+ * @returns {Frontier}
+ */
+export function cloneFrontier(frontier) {
+  return new Map(frontier);
+}
+
+/**
+ * Merges two frontiers, taking the "later" entry for each writer.
+ * Note: This is a simple merge that takes entries from both.
+ * For proper "later" detection, you'd need to compare patch ancestry.
+ * @param {Frontier} a
+ * @param {Frontier} b
+ * @returns {Frontier}
+ */
+export function mergeFrontiers(a, b) {
+  const merged = new Map(a);
+  for (const [writerId, patchSha] of b) {
+    // Simple: b overwrites a (caller determines order)
+    merged.set(writerId, patchSha);
+  }
+  return merged;
+}

package/src/domain/services/GCMetrics.js

@@ -0,0 +1,101 @@
+/**
+ * GCMetrics - Collects garbage collection metrics from WARP V5 state.
+ */
+
+/**
+ * @typedef {Object} GCMetrics
+ * @property {number} nodeEntries - Total dot entries in nodeAlive
+ * @property {number} edgeEntries - Total dot entries in edgeAlive
+ * @property {number} totalEntries - Sum of all entries
+ * @property {number} nodeTombstones - Tombstoned dots in nodeAlive that reference entry dots
+ * @property {number} edgeTombstones - Tombstoned dots in edgeAlive that reference entry dots
+ * @property {number} totalTombstones - Sum of all tombstones
+ * @property {number} nodeLiveDots - Live (non-tombstoned) dots in nodeAlive
+ * @property {number} edgeLiveDots - Live (non-tombstoned) dots in edgeAlive
+ * @property {number} totalLiveDots - Sum of all live dots
+ * @property {number} tombstoneRatio - Ratio of tombstones to (tombstones + liveDots)
+ */
+
+/**
+ * Counts total entries (dots) in an ORSet across all elements.
+ * @param {import('../crdt/ORSet.js').ORSet} orset
+ * @returns {number}
+ */
+export function countEntries(orset) {
+  let count = 0;
+  for (const dots of orset.entries.values()) {
+    count += dots.size;
+  }
+  return count;
+}
+
+/**
+ * Counts live dots in an ORSet (entries minus tombstoned).
+ * @param {import('../crdt/ORSet.js').ORSet} orset
+ * @returns {number}
+ */
+export function countLiveDots(orset) {
+  let count = 0;
+  for (const dots of orset.entries.values()) {
+    for (const dot of dots) {
+      if (!orset.tombstones.has(dot)) {
+        count++;
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Counts tombstones in an ORSet that reference entry dots.
+ * Only counts tombstones that actually correspond to dots in entries.
+ * @param {import('../crdt/ORSet.js').ORSet} orset
+ * @returns {number}
+ */
+export function countTombstones(orset) {
+  let count = 0;
+  for (const dots of orset.entries.values()) {
+    for (const dot of dots) {
+      if (orset.tombstones.has(dot)) {
+        count++;
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Collects GC metrics from state.
+ * @param {import('./JoinReducer.js').WarpStateV5} state
+ * @returns {GCMetrics}
+ */
+export function collectGCMetrics(state) {
+  const nodeEntries = countEntries(state.nodeAlive);
+  const edgeEntries = countEntries(state.edgeAlive);
+  const totalEntries = nodeEntries + edgeEntries;
+
+  const nodeLiveDots = countLiveDots(state.nodeAlive);
+  const edgeLiveDots = countLiveDots(state.edgeAlive);
+  const totalLiveDots = nodeLiveDots + edgeLiveDots;
+
+  const nodeTombstones = countTombstones(state.nodeAlive);
+  const edgeTombstones = countTombstones(state.edgeAlive);
+  const totalTombstones = nodeTombstones + edgeTombstones;
+
+  // tombstoneRatio = tombstones / (tombstones + liveDots)
+  const denominator = totalTombstones + totalLiveDots;
+  const tombstoneRatio = denominator > 0 ? totalTombstones / denominator : 0;
+
+  return {
+    nodeEntries,
+    edgeEntries,
+    totalEntries,
+    nodeTombstones,
+    edgeTombstones,
+    totalTombstones,
+    nodeLiveDots,
+    edgeLiveDots,
+    totalLiveDots,
+    tombstoneRatio,
+  };
+}