graphwise 1.4.3 → 1.5.1

package/dist/index/index.js

@@ -2,7 +2,7 @@ import { AdjacencyMapGraph } from "../graph/index.js";
 import { bfs, bfsWithPath, dfs, dfsWithPath } from "../traversal/index.js";
 import { PriorityQueue } from "../structures/index.js";
 import { n as miniBatchKMeans, r as normaliseFeatures, t as _computeMean } from "../kmeans-87ExSUNZ.js";
-import { approximateClusteringCoefficient, batchClusteringCoefficients, countEdgesOfType, countNodesOfType, entropyFromCounts, localClusteringCoefficient, localTypeEntropy, neighbourIntersection, neighbourOverlap, neighbourSet, normalisedEntropy, shannonEntropy } from "../utils/index.js";
+import { approximateClusteringCoefficient, batchClusteringCoefficients, computeJaccard, countEdgesOfType, countNodesOfType, entropyFromCounts, localClusteringCoefficient, localTypeEntropy, neighbourIntersection, neighbourOverlap, neighbourSet, normalisedEntropy, shannonEntropy } from "../utils/index.js";
 import { grasp, stratified } from "../seeds/index.js";
 import { GPUContext, GPUNotAvailableError, assertWebGPUAvailable, createGPUContext, createResultBuffer, csrToGPUBuffers, detectWebGPU, getGPUContext, graphToCSR, isWebGPUAvailable, readBufferToCPU } from "../gpu/index.js";
 //#region src/expansion/base.ts
@@ -23,7 +23,7 @@ function degreePriority(_nodeId, context) {
 function base(graph, seeds, config) {
 	const startTime = performance.now();
 	const { maxNodes = 0, maxIterations = 0, maxPaths = 0, priority = degreePriority, debug = false } = config ?? {};
-	if (seeds.length === 0) return emptyResult("base", startTime);
+	if (seeds.length === 0) return emptyResult$2("base", startTime);
 	const numFrontiers = seeds.length;
 	const allVisited = /* @__PURE__ */ new Set();
 	const combinedVisited = /* @__PURE__ */ new Map();
@@ -104,7 +104,7 @@ function base(graph, seeds, config) {
 			const otherVisited = visitedByFrontier[otherFrontier];
 			if (otherVisited === void 0) continue;
 			if (otherVisited.has(nodeId)) {
-				const path = reconstructPath(nodeId, activeFrontier, otherFrontier, predecessors, seeds);
+				const path = reconstructPath$1(nodeId, activeFrontier, otherFrontier, predecessors, seeds);
 				if (path !== null) {
 					discoveredPaths.push(path);
 					if (debug) console.log(`[BASE] Path found: ${path.nodes.join(" -> ")}`);
@@ -169,7 +169,7 @@ function createPriorityContext(graph, nodeId, frontierIndex, combinedVisited, al
 /**
 * Reconstruct path from collision point.
 */
-function reconstructPath(collisionNode, frontierA, frontierB, predecessors, seeds) {
+function reconstructPath$1(collisionNode, frontierA, frontierB, predecessors, seeds) {
 	const pathA = [collisionNode];
 	const predA = predecessors[frontierA];
 	if (predA !== void 0) {
@@ -205,7 +205,7 @@ function reconstructPath(collisionNode, frontierA, frontierB, predecessors, seed
 /**
 * Create an empty result for early termination.
 */
-function emptyResult(algorithm, startTime) {
+function emptyResult$2(algorithm, startTime) {
 	return {
 		paths: [],
 		sampledNodes: /* @__PURE__ */ new Set(),
@@ -254,46 +254,12 @@ function domeHighDegree(graph, seeds, config) {
 	});
 }
 //#endregion
-//#region src/expansion/edge.ts
-var EPSILON$1 = 1e-10;
-/**
-* Priority function using local type entropy.
-* Lower values = higher priority (expanded first).
-*/
-function edgePriority(nodeId, context) {
-	const graph = context.graph;
-	const neighbours = graph.neighbours(nodeId);
-	const neighbourTypes = [];
-	for (const neighbour of neighbours) {
-		const node = graph.getNode(neighbour);
-		neighbourTypes.push(node?.type ?? "default");
-	}
-	return 1 / (localTypeEntropy(neighbourTypes) + EPSILON$1) * Math.log(context.degree + 1);
-}
-/**
-* Run EDGE expansion (Entropy-Driven Graph Expansion).
-*
-* Discovers paths by prioritising nodes with diverse neighbour types,
-* deferring nodes with homogeneous neighbourhoods.
-*
-* @param graph - Source graph
-* @param seeds - Seed nodes for expansion
-* @param config - Expansion configuration
-* @returns Expansion result with discovered paths
-*/
-function edge(graph, seeds, config) {
-	return base(graph, seeds, {
-		...config,
-		priority: edgePriority
-	});
-}
-//#endregion
 //#region src/expansion/hae.ts
 var EPSILON = 1e-10;
 /**
 * Default type mapper - uses node.type property.
 */
-function defaultTypeMapper(node) {
+function defaultTypeMapper$1(node) {
 	return node.type ?? "default";
 }
 /**
@@ -323,13 +289,34 @@ function createHAEPriority(typeMapper) {
 * @returns Expansion result with discovered paths
 */
 function hae(graph, seeds, config) {
-	const typeMapper = config?.typeMapper ?? defaultTypeMapper;
+	const typeMapper = config?.typeMapper ?? defaultTypeMapper$1;
 	return base(graph, seeds, {
 		...config,
 		priority: createHAEPriority(typeMapper)
 	});
 }
 //#endregion
+//#region src/expansion/edge.ts
+/** Default type mapper: reads `node.type`, falling back to "default". */
+var defaultTypeMapper = (n) => typeof n.type === "string" ? n.type : "default";
+/**
+* Run EDGE expansion (Entropy-Driven Graph Expansion).
+*
+* Discovers paths by prioritising nodes with diverse neighbour types,
+* deferring nodes with homogeneous neighbourhoods.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function edge(graph, seeds, config) {
+	return hae(graph, seeds, {
+		...config,
+		typeMapper: defaultTypeMapper
+	});
+}
+//#endregion
 //#region src/expansion/pipe.ts
 /**
 * Priority function using path potential.
@@ -365,6 +352,69 @@ function pipe(graph, seeds, config) {
 	});
 }
 //#endregion
+//#region src/expansion/priority-helpers.ts
+/**
+* Compute the average mutual information between a node and all visited
+* nodes in the same frontier.
+*
+* Returns a value in [0, 1] — higher means the node is more similar
+* (on average) to already-visited same-frontier nodes.
+*
+* @param graph - Source graph
+* @param nodeId - Node being prioritised
+* @param context - Current priority context
+* @param mi - MI function to use for pairwise scoring
+* @returns Average MI score, or 0 if no same-frontier visited nodes exist
+*/
+function avgFrontierMI(graph, nodeId, context, mi) {
+	const { frontierIndex, visitedByFrontier } = context;
+	let total = 0;
+	let count = 0;
+	for (const [visitedId, idx] of visitedByFrontier) if (idx === frontierIndex && visitedId !== nodeId) {
+		total += mi(graph, visitedId, nodeId);
+		count++;
+	}
+	return count > 0 ? total / count : 0;
+}
+/**
+* Count the number of a node's neighbours that have been visited by
+* frontiers other than the node's own frontier.
+*
+* A higher count indicates this node is likely to bridge two frontiers,
+* making it a strong candidate for path completion.
+*
+* @param graph - Source graph
+* @param nodeId - Node being evaluated
+* @param context - Current priority context
+* @returns Number of neighbours visited by other frontiers
+*/
+function countCrossFrontierNeighbours(graph, nodeId, context) {
+	const { frontierIndex, visitedByFrontier } = context;
+	const nodeNeighbours = new Set(graph.neighbours(nodeId));
+	let count = 0;
+	for (const [visitedId, idx] of visitedByFrontier) if (idx !== frontierIndex && nodeNeighbours.has(visitedId)) count++;
+	return count;
+}
+/**
+* Incrementally update salience counts for paths discovered since the
+* last update.
+*
+* Iterates only over paths from `fromIndex` onwards, avoiding redundant
+* re-processing of already-counted paths.
+*
+* @param salienceCounts - Mutable map of node ID to salience count (mutated in place)
+* @param paths - Full list of discovered paths
+* @param fromIndex - Index to start counting from (exclusive of earlier paths)
+* @returns The new `fromIndex` value (i.e. `paths.length` after update)
+*/
+function updateSalienceCounts(salienceCounts, paths, fromIndex) {
+	for (let i = fromIndex; i < paths.length; i++) {
+		const path = paths[i];
+		if (path !== void 0) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
+	}
+	return paths.length;
+}
+//#endregion
 //#region src/expansion/sage.ts
 /**
 * Run SAGE expansion algorithm.
@@ -388,13 +438,7 @@ function sage(graph, seeds, config) {
 	function sagePriority(nodeId, context) {
 		const pathCount = context.discoveredPaths.length;
 		if (pathCount > 0 && !inPhase2) inPhase2 = true;
-		if (pathCount > lastPathCount) {
-			for (let i = lastPathCount; i < pathCount; i++) {
-				const path = context.discoveredPaths[i];
-				if (path !== void 0) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
-			}
-			lastPathCount = pathCount;
-		}
+		if (pathCount > lastPathCount) lastPathCount = updateSalienceCounts(salienceCounts, context.discoveredPaths, lastPathCount);
 		if (!inPhase2) return Math.log(context.degree + 1);
 		return -((salienceCounts.get(nodeId) ?? 0) * 1e3 - context.degree);
 	}
@@ -416,10 +460,9 @@ function sage(graph, seeds, config) {
 */
 function jaccard(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	if (union === 0) return 0;
-	const score = intersection / union;
-	return Math.max(epsilon, score);
+	const { jaccard: jaccardScore, sourceNeighbours, targetNeighbours } = computeJaccard(graph, source, target);
+	if (sourceNeighbours.size === 0 && targetNeighbours.size === 0) return 0;
+	return Math.max(epsilon, jaccardScore);
 }
 //#endregion
 //#region src/expansion/reach.ts
@@ -505,15 +548,9 @@ function maze(graph, seeds, config) {
 		const pathCount = context.discoveredPaths.length;
 		if (pathCount >= DEFAULT_PHASE2_THRESHOLD && !inPhase2) {
 			inPhase2 = true;
-			for (const path of context.discoveredPaths) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
-		}
-		if (inPhase2 && pathCount > lastPathCount) {
-			for (let i = lastPathCount; i < pathCount; i++) {
-				const path = context.discoveredPaths[i];
-				if (path !== void 0) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
-			}
-			lastPathCount = pathCount;
+			updateSalienceCounts(salienceCounts, context.discoveredPaths, 0);
 		}
+		if (inPhase2 && pathCount > lastPathCount) lastPathCount = updateSalienceCounts(salienceCounts, context.discoveredPaths, lastPathCount);
 		const nodeNeighbours = graph.neighbours(nodeId);
 		let pathPotential = 0;
 		for (const neighbour of nodeNeighbours) {
@@ -565,22 +602,11 @@ function tide(graph, seeds, config) {
 /**
 * LACE priority function.
 *
-* Priority = 1 - MI(source, neighbour)
-* Higher MI = lower priority value = explored first
+* Priority = 1 - avgMI(node, same-frontier visited nodes)
+* Higher average MI = lower priority value = explored first
 */
 function lacePriority(nodeId, context, mi) {
-	const graph = context.graph;
-	const frontierIndex = context.frontierIndex;
-	let maxMi = 0;
-	let totalMi = 0;
-	let count = 0;
-	for (const [visitedId, idx] of context.visitedByFrontier) if (idx === frontierIndex && visitedId !== nodeId) {
-		const edgeMi = mi(graph, visitedId, nodeId);
-		totalMi += edgeMi;
-		count++;
-		if (edgeMi > maxMi) maxMi = edgeMi;
-	}
-	return 1 - (count > 0 ? totalMi / count : 0);
+	return 1 - avgFrontierMI(context.graph, nodeId, context, mi);
 }
 /**
 * Run LACE expansion algorithm.
@@ -604,18 +630,15 @@ function lace(graph, seeds, config) {
 //#endregion
 //#region src/expansion/warp.ts
 /**
-* PIPE priority function.
+* WARP priority function.
 *
 * Priority = 1 / (1 + bridge_score)
-* Bridge score = neighbourhood overlap with other frontiers
-* Higher bridge score = more likely to be on paths = explored first
+* Bridge score = cross-frontier neighbour count plus bonus for nodes
+* already on discovered paths.
+* Higher bridge score = more likely to complete paths = explored first.
 */
 function warpPriority(nodeId, context) {
-	const graph = context.graph;
-	const currentFrontier = context.frontierIndex;
-	const nodeNeighbours = new Set(graph.neighbours(nodeId));
-	let bridgeScore = 0;
-	for (const [visitedId, frontierIdx] of context.visitedByFrontier) if (frontierIdx !== currentFrontier && nodeNeighbours.has(visitedId)) bridgeScore++;
+	let bridgeScore = countCrossFrontierNeighbours(context.graph, nodeId, context);
 	for (const path of context.discoveredPaths) if (path.nodes.includes(nodeId)) bridgeScore += 2;
 	return 1 / (1 + bridgeScore);
 }
@@ -639,24 +662,15 @@ function warp(graph, seeds, config) {
 //#endregion
 //#region src/expansion/fuse.ts
 /**
-* SAGE priority function.
+* FUSE priority function.
 *
-* Combines degree with salience:
-* Priority = (1 - w) * degree + w * (1 - avg_salience)
-* Lower values = higher priority
+* Combines degree with average frontier MI as a salience proxy:
+* Priority = (1 - w) * degree + w * (1 - avgMI)
+* Lower values = higher priority; high salience lowers priority
 */
 function fusePriority(nodeId, context, mi, salienceWeight) {
-	const graph = context.graph;
-	const degree = context.degree;
-	const frontierIndex = context.frontierIndex;
-	let totalSalience = 0;
-	let count = 0;
-	for (const [visitedId, idx] of context.visitedByFrontier) if (idx === frontierIndex && visitedId !== nodeId) {
-		totalSalience += mi(graph, visitedId, nodeId);
-		count++;
-	}
-	const avgSalience = count > 0 ? totalSalience / count : 0;
-	return (1 - salienceWeight) * degree + salienceWeight * (1 - avgSalience);
+	const avgSalience = avgFrontierMI(context.graph, nodeId, context, mi);
+	return (1 - salienceWeight) * context.degree + salienceWeight * (1 - avgSalience);
 }
 /**
 * Run FUSE expansion algorithm.
@@ -680,20 +694,13 @@ function fuse(graph, seeds, config) {
 //#endregion
 //#region src/expansion/sift.ts
 /**
-* REACH priority function (phase 2).
+* REACH (SIFT) priority function.
 *
-* Uses learned MI threshold to prioritise high-MI edges.
+* Prioritises nodes with average frontier MI above the threshold;
+* falls back to degree-based ordering for those below it.
 */
 function siftPriority(nodeId, context, mi, miThreshold) {
-	const graph = context.graph;
-	const frontierIndex = context.frontierIndex;
-	let totalMi = 0;
-	let count = 0;
-	for (const [visitedId, idx] of context.visitedByFrontier) if (idx === frontierIndex && visitedId !== nodeId) {
-		totalMi += mi(graph, visitedId, nodeId);
-		count++;
-	}
-	const avgMi = count > 0 ? totalMi / count : 0;
+	const avgMi = avgFrontierMI(context.graph, nodeId, context, mi);
 	if (avgMi >= miThreshold) return 1 - avgMi;
 	else return context.degree + 100;
 }
@@ -735,16 +742,6 @@ function localDensity(graph, nodeId) {
 	return edges / maxEdges;
 }
 /**
-* Compute bridge score (how many other frontiers visit neighbours).
-*/
-function bridgeScore(nodeId, context) {
-	const currentFrontier = context.frontierIndex;
-	const nodeNeighbours = new Set(context.graph.neighbours(nodeId));
-	let score = 0;
-	for (const [visitedId, idx] of context.visitedByFrontier) if (idx !== currentFrontier && nodeNeighbours.has(visitedId)) score++;
-	return score;
-}
-/**
 * MAZE adaptive priority function.
 *
 * Switches strategies based on local conditions:
@@ -756,10 +753,10 @@ function fluxPriority(nodeId, context, densityThreshold, bridgeThreshold) {
 	const graph = context.graph;
 	const degree = context.degree;
 	const density = localDensity(graph, nodeId);
-	const bridge = bridgeScore(nodeId, context);
+	const bridge = countCrossFrontierNeighbours(graph, nodeId, context);
 	const numFrontiers = new Set(context.visitedByFrontier.values()).size;
 	if ((numFrontiers > 0 ? bridge / numFrontiers : 0) >= bridgeThreshold) return 1 / (1 + bridge);
-	else if (density >= densityThreshold) return -degree;
+	else if (density >= densityThreshold) return 1 / (degree + 1);
 	else return degree;
 }
 /**
@@ -857,6 +854,346 @@ function randomPriority(graph, seeds, config) {
 	});
 }
 //#endregion
+//#region src/expansion/dfs-priority.ts
+/**
+* DFS priority function: negative iteration produces LIFO ordering.
+*
+* Lower priority values are expanded first, so negating the iteration
+* counter ensures the most recently enqueued node is always next.
+*/
+function dfsPriorityFn(_nodeId, context) {
+	return -context.iteration;
+}
+/**
+* Run DFS-priority expansion (LIFO discovery order).
+*
+* Uses the BASE framework with a negative-iteration priority function,
+* which causes the most recently discovered node to be expanded first —
+* equivalent to depth-first search behaviour.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function dfsPriority(graph, seeds, config) {
+	return base(graph, seeds, {
+		...config,
+		priority: dfsPriorityFn
+	});
+}
+//#endregion
+//#region src/expansion/k-hop.ts
+/**
+* Run k-hop expansion (fixed-depth BFS).
+*
+* Explores all nodes reachable within exactly k hops of any seed using
+* breadth-first search. Paths between seeds are detected when a node
+* is reached by frontiers from two different seeds.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - K-hop configuration (k defaults to 2)
+* @returns Expansion result with discovered paths
+*/
+function kHop(graph, seeds, config) {
+	const startTime = performance.now();
+	const { k = 2 } = config ?? {};
+	if (seeds.length === 0) return emptyResult$1(startTime);
+	const visitedByFrontier = seeds.map(() => /* @__PURE__ */ new Map());
+	const firstVisitedBy = /* @__PURE__ */ new Map();
+	const allVisited = /* @__PURE__ */ new Set();
+	const sampledEdgeMap = /* @__PURE__ */ new Map();
+	const discoveredPaths = [];
+	let iterations = 0;
+	let edgesTraversed = 0;
+	for (let i = 0; i < seeds.length; i++) {
+		const seed = seeds[i];
+		if (seed === void 0) continue;
+		if (!graph.hasNode(seed.id)) continue;
+		visitedByFrontier[i]?.set(seed.id, null);
+		allVisited.add(seed.id);
+		if (!firstVisitedBy.has(seed.id)) firstVisitedBy.set(seed.id, i);
+		else {
+			const otherIdx = firstVisitedBy.get(seed.id) ?? -1;
+			if (otherIdx < 0) continue;
+			const fromSeed = seeds[otherIdx];
+			const toSeed = seeds[i];
+			if (fromSeed !== void 0 && toSeed !== void 0) discoveredPaths.push({
+				fromSeed,
+				toSeed,
+				nodes: [seed.id]
+			});
+		}
+	}
+	let currentLevel = seeds.map((s, i) => {
+		const frontier = visitedByFrontier[i];
+		if (frontier === void 0) return [];
+		return frontier.has(s.id) ? [s.id] : [];
+	});
+	for (let hop = 0; hop < k; hop++) {
+		const nextLevel = seeds.map(() => []);
+		for (let i = 0; i < seeds.length; i++) {
+			const level = currentLevel[i];
+			if (level === void 0) continue;
+			const frontierVisited = visitedByFrontier[i];
+			if (frontierVisited === void 0) continue;
+			for (const nodeId of level) {
+				iterations++;
+				for (const neighbour of graph.neighbours(nodeId)) {
+					edgesTraversed++;
+					const [s, t] = nodeId < neighbour ? [nodeId, neighbour] : [neighbour, nodeId];
+					let targets = sampledEdgeMap.get(s);
+					if (targets === void 0) {
+						targets = /* @__PURE__ */ new Set();
+						sampledEdgeMap.set(s, targets);
+					}
+					targets.add(t);
+					if (frontierVisited.has(neighbour)) continue;
+					frontierVisited.set(neighbour, nodeId);
+					allVisited.add(neighbour);
+					nextLevel[i]?.push(neighbour);
+					const previousFrontier = firstVisitedBy.get(neighbour);
+					if (previousFrontier !== void 0 && previousFrontier !== i) {
+						const fromSeed = seeds[previousFrontier];
+						const toSeed = seeds[i];
+						if (fromSeed !== void 0 && toSeed !== void 0) {
+							const path = reconstructPath(neighbour, previousFrontier, i, visitedByFrontier, seeds);
+							if (path !== null) {
+								if (!discoveredPaths.some((p) => p.fromSeed.id === fromSeed.id && p.toSeed.id === toSeed.id || p.fromSeed.id === toSeed.id && p.toSeed.id === fromSeed.id)) discoveredPaths.push(path);
+							}
+						}
+					}
+					if (!firstVisitedBy.has(neighbour)) firstVisitedBy.set(neighbour, i);
+				}
+			}
+		}
+		currentLevel = nextLevel;
+		if (currentLevel.every((level) => level.length === 0)) break;
+	}
+	const endTime = performance.now();
+	const edgeTuples = /* @__PURE__ */ new Set();
+	for (const [source, targets] of sampledEdgeMap) for (const target of targets) edgeTuples.add([source, target]);
+	return {
+		paths: discoveredPaths,
+		sampledNodes: allVisited,
+		sampledEdges: edgeTuples,
+		visitedPerFrontier: visitedByFrontier.map((m) => new Set(m.keys())),
+		stats: {
+			iterations,
+			nodesVisited: allVisited.size,
+			edgesTraversed,
+			pathsFound: discoveredPaths.length,
+			durationMs: endTime - startTime,
+			algorithm: "k-hop",
+			termination: "exhausted"
+		}
+	};
+}
+/**
+* Reconstruct the path between two colliding frontiers.
+*/
+function reconstructPath(collisionNode, frontierA, frontierB, visitedByFrontier, seeds) {
+	const seedA = seeds[frontierA];
+	const seedB = seeds[frontierB];
+	if (seedA === void 0 || seedB === void 0) return null;
+	const pathA = [collisionNode];
+	const predA = visitedByFrontier[frontierA];
+	if (predA !== void 0) {
+		let node = collisionNode;
+		let pred = predA.get(node);
+		while (pred !== null && pred !== void 0) {
+			pathA.unshift(pred);
+			node = pred;
+			pred = predA.get(node);
+		}
+	}
+	const pathB = [];
+	const predB = visitedByFrontier[frontierB];
+	if (predB !== void 0) {
+		let node = collisionNode;
+		let pred = predB.get(node);
+		while (pred !== null && pred !== void 0) {
+			pathB.push(pred);
+			node = pred;
+			pred = predB.get(node);
+		}
+	}
+	return {
+		fromSeed: seedA,
+		toSeed: seedB,
+		nodes: [...pathA, ...pathB]
+	};
+}
+/**
+* Create an empty result for early termination (no seeds).
+*/
+function emptyResult$1(startTime) {
+	return {
+		paths: [],
+		sampledNodes: /* @__PURE__ */ new Set(),
+		sampledEdges: /* @__PURE__ */ new Set(),
+		visitedPerFrontier: [],
+		stats: {
+			iterations: 0,
+			nodesVisited: 0,
+			edgesTraversed: 0,
+			pathsFound: 0,
+			durationMs: performance.now() - startTime,
+			algorithm: "k-hop",
+			termination: "exhausted"
+		}
+	};
+}
+//#endregion
+//#region src/expansion/random-walk.ts
+/**
+* Mulberry32 seeded PRNG — fast, compact, and high-quality for simulation.
+*
+* Returns a closure that yields the next pseudo-random value in [0, 1)
+* on each call.
+*
+* @param seed - 32-bit integer seed
+*/
+function mulberry32(seed) {
+	let s = seed;
+	return () => {
+		s += 1831565813;
+		let t = s;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Run random-walk-with-restart expansion.
+*
+* For each seed, performs `walks` independent random walks of up to
+* `walkLength` steps. At each step the walk either restarts (with
+* probability `restartProbability`) or moves to a uniformly sampled
+* neighbour. All visited nodes and traversed edges are collected.
+*
+* Inter-seed paths are detected when a walk reaches a node that was
+* previously reached by a walk originating from a different seed.
+* The recorded path contains only the two seed endpoints rather than
+* the full walk trajectory, consistent with the ExpansionPath contract.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Random walk configuration
+* @returns Expansion result with discovered paths
+*/
+function randomWalk(graph, seeds, config) {
+	const startTime = performance.now();
+	const { restartProbability = .15, walks = 10, walkLength = 20, seed = 0 } = config ?? {};
+	if (seeds.length === 0) return emptyResult(startTime);
+	const rand = mulberry32(seed);
+	const firstVisitedBySeed = /* @__PURE__ */ new Map();
+	const allVisited = /* @__PURE__ */ new Set();
+	const sampledEdgeMap = /* @__PURE__ */ new Map();
+	const discoveredPaths = [];
+	let iterations = 0;
+	let edgesTraversed = 0;
+	const visitedPerFrontier = seeds.map(() => /* @__PURE__ */ new Set());
+	for (let seedIdx = 0; seedIdx < seeds.length; seedIdx++) {
+		const seed_ = seeds[seedIdx];
+		if (seed_ === void 0) continue;
+		const seedId = seed_.id;
+		if (!graph.hasNode(seedId)) continue;
+		if (!firstVisitedBySeed.has(seedId)) firstVisitedBySeed.set(seedId, seedIdx);
+		allVisited.add(seedId);
+		visitedPerFrontier[seedIdx]?.add(seedId);
+		for (let w = 0; w < walks; w++) {
+			let current = seedId;
+			for (let step = 0; step < walkLength; step++) {
+				iterations++;
+				if (rand() < restartProbability) {
+					current = seedId;
+					continue;
+				}
+				const neighbourList = [];
+				for (const nb of graph.neighbours(current)) neighbourList.push(nb);
+				if (neighbourList.length === 0) {
+					current = seedId;
+					continue;
+				}
+				const next = neighbourList[Math.floor(rand() * neighbourList.length)];
+				if (next === void 0) {
+					current = seedId;
+					continue;
+				}
+				edgesTraversed++;
+				const [s, t] = current < next ? [current, next] : [next, current];
+				let targets = sampledEdgeMap.get(s);
+				if (targets === void 0) {
+					targets = /* @__PURE__ */ new Set();
+					sampledEdgeMap.set(s, targets);
+				}
+				targets.add(t);
+				const previousSeedIdx = firstVisitedBySeed.get(next);
+				if (previousSeedIdx !== void 0 && previousSeedIdx !== seedIdx) {
+					const fromSeed = seeds[previousSeedIdx];
+					const toSeed = seeds[seedIdx];
+					if (fromSeed !== void 0 && toSeed !== void 0) {
+						const path = {
+							fromSeed,
+							toSeed,
+							nodes: [
+								fromSeed.id,
+								next,
+								toSeed.id
+							].filter((n, i, arr) => arr.indexOf(n) === i)
+						};
+						if (!discoveredPaths.some((p) => p.fromSeed.id === fromSeed.id && p.toSeed.id === toSeed.id || p.fromSeed.id === toSeed.id && p.toSeed.id === fromSeed.id)) discoveredPaths.push(path);
+					}
+				}
+				if (!firstVisitedBySeed.has(next)) firstVisitedBySeed.set(next, seedIdx);
+				allVisited.add(next);
+				visitedPerFrontier[seedIdx]?.add(next);
+				current = next;
+			}
+		}
+	}
+	const endTime = performance.now();
+	const edgeTuples = /* @__PURE__ */ new Set();
+	for (const [source, targets] of sampledEdgeMap) for (const target of targets) edgeTuples.add([source, target]);
+	return {
+		paths: discoveredPaths,
+		sampledNodes: allVisited,
+		sampledEdges: edgeTuples,
+		visitedPerFrontier,
+		stats: {
+			iterations,
+			nodesVisited: allVisited.size,
+			edgesTraversed,
+			pathsFound: discoveredPaths.length,
+			durationMs: endTime - startTime,
+			algorithm: "random-walk",
+			termination: "exhausted"
+		}
+	};
+}
+/**
+* Create an empty result for early termination (no seeds).
+*/
+function emptyResult(startTime) {
+	return {
+		paths: [],
+		sampledNodes: /* @__PURE__ */ new Set(),
+		sampledEdges: /* @__PURE__ */ new Set(),
+		visitedPerFrontier: [],
+		stats: {
+			iterations: 0,
+			nodesVisited: 0,
+			edgesTraversed: 0,
+			pathsFound: 0,
+			durationMs: performance.now() - startTime,
+			algorithm: "random-walk",
+			termination: "exhausted"
+		}
+	};
+}
+//#endregion
 //#region src/ranking/parse.ts
 /**
 * Rank paths using PARSE (Path-Aware Ranking via Salience Estimation).
@@ -950,20 +1287,128 @@ function adamicAdar(graph, source, target, config) {
 	return Math.max(epsilon, score);
 }
 //#endregion
+//#region src/ranking/mi/cosine.ts
+/**
+* Compute cosine similarity between neighbourhoods of two nodes.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param config - Optional configuration
+* @returns Cosine similarity in [0, 1]
+*/
+function cosine(graph, source, target, config) {
+	const { epsilon = 1e-10 } = config ?? {};
+	const sourceNeighbours = neighbourSet(graph, source, target);
+	const targetNeighbours = neighbourSet(graph, target, source);
+	const { intersection } = neighbourOverlap(sourceNeighbours, targetNeighbours);
+	const denominator = Math.sqrt(sourceNeighbours.size) * Math.sqrt(targetNeighbours.size);
+	if (denominator === 0) return 0;
+	const score = intersection / denominator;
+	return Math.max(epsilon, score);
+}
+//#endregion
+//#region src/ranking/mi/sorensen.ts
+/**
+* Compute Sorensen-Dice similarity between neighbourhoods of two nodes.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param config - Optional configuration
+* @returns Sorensen-Dice coefficient in [0, 1]
+*/
+function sorensen(graph, source, target, config) {
+	const { epsilon = 1e-10 } = config ?? {};
+	const sourceNeighbours = neighbourSet(graph, source, target);
+	const targetNeighbours = neighbourSet(graph, target, source);
+	const { intersection } = neighbourOverlap(sourceNeighbours, targetNeighbours);
+	const denominator = sourceNeighbours.size + targetNeighbours.size;
+	if (denominator === 0) return 0;
+	const score = 2 * intersection / denominator;
+	return Math.max(epsilon, score);
+}
+//#endregion
+//#region src/ranking/mi/resource-allocation.ts
+/**
+* Compute Resource Allocation index between neighbourhoods of two nodes.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param config - Optional configuration
+* @returns Resource Allocation index (normalised to [0, 1] if configured)
+*/
+function resourceAllocation(graph, source, target, config) {
+	const { epsilon = 1e-10, normalise = true } = config ?? {};
+	const commonNeighbours = neighbourIntersection(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
+	let score = 0;
+	for (const neighbour of commonNeighbours) {
+		const degree = graph.degree(neighbour);
+		if (degree > 0) score += 1 / degree;
+	}
+	if (normalise && commonNeighbours.size > 0) {
+		const maxScore = commonNeighbours.size;
+		score = score / maxScore;
+	}
+	return Math.max(epsilon, score);
+}
+//#endregion
+//#region src/ranking/mi/overlap-coefficient.ts
+/**
+* Compute Overlap Coefficient between neighbourhoods of two nodes.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param config - Optional configuration
+* @returns Overlap Coefficient in [0, 1]
+*/
+function overlapCoefficient(graph, source, target, config) {
+	const { epsilon = 1e-10 } = config ?? {};
+	const sourceNeighbours = neighbourSet(graph, source, target);
+	const targetNeighbours = neighbourSet(graph, target, source);
+	const { intersection } = neighbourOverlap(sourceNeighbours, targetNeighbours);
+	const denominator = Math.min(sourceNeighbours.size, targetNeighbours.size);
+	if (denominator === 0) return 0;
+	const score = intersection / denominator;
+	return Math.max(epsilon, score);
+}
+//#endregion
+//#region src/ranking/mi/hub-promoted.ts
+/**
+* Compute Hub Promoted index between neighbourhoods of two nodes.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param config - Optional configuration
+* @returns Hub Promoted index in [0, 1]
+*/
+function hubPromoted(graph, source, target, config) {
+	const { epsilon = 1e-10 } = config ?? {};
+	const { intersection } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
+	const sourceDegree = graph.degree(source);
+	const targetDegree = graph.degree(target);
+	const denominator = Math.min(sourceDegree, targetDegree);
+	if (denominator === 0) return 0;
+	const score = intersection / denominator;
+	return Math.max(epsilon, score);
+}
+//#endregion
 //#region src/ranking/mi/scale.ts
 /**
 * Compute SCALE MI between two nodes.
 */
 function scale(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	const jaccard = union > 0 ? intersection / union : 0;
+	const { jaccard: jaccardScore } = computeJaccard(graph, source, target);
 	const n = graph.nodeCount;
 	const m = graph.edgeCount;
 	const possibleEdges = n * (n - 1);
 	const density = possibleEdges > 0 ? (graph.directed ? m : 2 * m) / possibleEdges : 0;
 	if (density === 0) return epsilon;
-	const score = jaccard / density;
+	const score = jaccardScore / density;
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -973,14 +1418,13 @@ function scale(graph, source, target, config) {
 */
 function skew(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	const jaccard = union > 0 ? intersection / union : 0;
+	const { jaccard: jaccardScore } = computeJaccard(graph, source, target);
 	const N = graph.nodeCount;
 	const sourceDegree = graph.degree(source);
 	const targetDegree = graph.degree(target);
 	const sourceIdf = Math.log(N / (sourceDegree + 1));
 	const targetIdf = Math.log(N / (targetDegree + 1));
-	const score = jaccard * sourceIdf * targetIdf;
+	const score = jaccardScore * sourceIdf * targetIdf;
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -990,11 +1434,10 @@ function skew(graph, source, target, config) {
 */
 function span(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	const jaccard = union > 0 ? intersection / union : 0;
+	const { jaccard: jaccardScore } = computeJaccard(graph, source, target);
 	const sourceCc = localClusteringCoefficient(graph, source);
 	const targetCc = localClusteringCoefficient(graph, target);
-	const score = jaccard * (1 - Math.max(sourceCc, targetCc));
+	const score = jaccardScore * (1 - Math.max(sourceCc, targetCc));
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -1004,13 +1447,12 @@ function span(graph, source, target, config) {
 */
 function etch(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	const jaccard = union > 0 ? intersection / union : 0;
+	const { jaccard: jaccardScore } = computeJaccard(graph, source, target);
 	const edge = graph.getEdge(source, target);
-	if (edge?.type === void 0) return Math.max(epsilon, jaccard);
+	if (edge?.type === void 0) return Math.max(epsilon, jaccardScore);
 	const edgeTypeCount = countEdgesOfType(graph, edge.type);
-	if (edgeTypeCount === 0) return Math.max(epsilon, jaccard);
-	const score = jaccard * Math.log(graph.edgeCount / edgeTypeCount);
+	if (edgeTypeCount === 0) return Math.max(epsilon, jaccardScore);
+	const score = jaccardScore * Math.log(graph.edgeCount / edgeTypeCount);
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -1020,17 +1462,16 @@ function etch(graph, source, target, config) {
 */
 function notch(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const { intersection, union } = neighbourOverlap(neighbourSet(graph, source, target), neighbourSet(graph, target, source));
-	const jaccard = union > 0 ? intersection / union : 0;
+	const { jaccard: jaccardScore } = computeJaccard(graph, source, target);
 	const sourceNode = graph.getNode(source);
 	const targetNode = graph.getNode(target);
-	if (sourceNode?.type === void 0 || targetNode?.type === void 0) return Math.max(epsilon, jaccard);
+	if (sourceNode?.type === void 0 || targetNode?.type === void 0) return Math.max(epsilon, jaccardScore);
 	const sourceTypeCount = countNodesOfType(graph, sourceNode.type);
 	const targetTypeCount = countNodesOfType(graph, targetNode.type);
-	if (sourceTypeCount === 0 || targetTypeCount === 0) return Math.max(epsilon, jaccard);
+	if (sourceTypeCount === 0 || targetTypeCount === 0) return Math.max(epsilon, jaccardScore);
 	const sourceRarity = Math.log(graph.nodeCount / sourceTypeCount);
 	const targetRarity = Math.log(graph.nodeCount / targetTypeCount);
-	const score = jaccard * sourceRarity * targetRarity;
+	const score = jaccardScore * sourceRarity * targetRarity;
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -1049,13 +1490,12 @@ function notch(graph, source, target, config) {
 */
 function adaptive(graph, source, target, config) {
 	const { epsilon = 1e-10, structuralWeight = .4, degreeWeight = .3, overlapWeight = .3 } = config ?? {};
-	const structural = jaccard(graph, source, target, { epsilon });
+	const { jaccard: jaccardScore, sourceNeighbours, targetNeighbours } = computeJaccard(graph, source, target);
+	const structural = sourceNeighbours.size === 0 && targetNeighbours.size === 0 ? 0 : Math.max(epsilon, jaccardScore);
 	const degreeComponent = adamicAdar(graph, source, target, {
 		epsilon,
 		normalise: true
 	});
-	const sourceNeighbours = neighbourSet(graph, source, target);
-	const targetNeighbours = neighbourSet(graph, target, source);
 	let overlap;
 	if (sourceNeighbours.size > 0 && targetNeighbours.size > 0) {
 		const { intersection } = neighbourOverlap(sourceNeighbours, targetNeighbours);
@@ -1067,6 +1507,42 @@ function adaptive(graph, source, target, config) {
 	return Math.max(epsilon, Math.min(1, score));
 }
 //#endregion
+//#region src/ranking/baselines/utils.ts
+/**
+* Normalise a set of scored paths and return them sorted highest-first.
+*
+* All scores are normalised relative to the maximum observed score.
+* When `includeScores` is false, raw (un-normalised) scores are preserved.
+* Handles degenerate cases: empty input and all-zero scores.
+*
+* @param paths - Original paths in input order
+* @param scored - Paths paired with their computed scores
+* @param method - Method name to embed in the result
+* @param includeScores - When true, normalise scores to [0, 1]; when false, keep raw scores
+* @returns BaselineResult with ranked paths
+*/
+function normaliseAndRank(paths, scored, method, includeScores) {
+	if (scored.length === 0) return {
+		paths: [],
+		method
+	};
+	const maxScore = Math.max(...scored.map((s) => s.score));
+	if (maxScore === 0) return {
+		paths: paths.map((path) => ({
+			...path,
+			score: 0
+		})),
+		method
+	};
+	return {
+		paths: scored.map(({ path, score }) => ({
+			...path,
+			score: includeScores ? score / maxScore : score
+		})).sort((a, b) => b.score - a.score),
+		method
+	};
+}
+//#endregion
 //#region src/ranking/baselines/shortest.ts
 /**
 * Rank paths by length (shortest first).
@@ -1084,18 +1560,10 @@ function shortest(_graph, paths, config) {
 		paths: [],
 		method: "shortest"
 	};
-	const scored = paths.map((path) => ({
+	return normaliseAndRank(paths, paths.map((path) => ({
 		path,
 		score: 1 / path.nodes.length
-	}));
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "shortest"
-	};
+	})), "shortest", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/degree-sum.ts
@@ -1113,29 +1581,14 @@ function degreeSum(graph, paths, config) {
 		paths: [],
 		method: "degree-sum"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		let degreeSum = 0;
 		for (const nodeId of path.nodes) degreeSum += graph.degree(nodeId);
 		return {
 			path,
 			score: degreeSum
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "degree-sum"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score
-		})).sort((a, b) => b.score - a.score),
-		method: "degree-sum"
-	};
+	}), "degree-sum", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/widest-path.ts
@@ -1153,7 +1606,7 @@ function widestPath(graph, paths, config) {
 		paths: [],
 		method: "widest-path"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		if (path.nodes.length < 2) return {
 			path,
 			score: 1
@@ -1170,22 +1623,7 @@ function widestPath(graph, paths, config) {
 			path,
 			score: minSimilarity === Number.POSITIVE_INFINITY ? 1 : minSimilarity
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "widest-path"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "widest-path"
-	};
+	}), "widest-path", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/jaccard-arithmetic.ts
@@ -1203,7 +1641,7 @@ function jaccardArithmetic(graph, paths, config) {
 		paths: [],
 		method: "jaccard-arithmetic"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		if (path.nodes.length < 2) return {
 			path,
 			score: 1
@@ -1222,22 +1660,7 @@ function jaccardArithmetic(graph, paths, config) {
 			path,
 			score: edgeCount > 0 ? similaritySum / edgeCount : 1
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "jaccard-arithmetic"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score
-		})).sort((a, b) => b.score - a.score),
-		method: "jaccard-arithmetic"
-	};
+	}), "jaccard-arithmetic", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/pagerank.ts
@@ -1298,29 +1721,14 @@ function pagerank(graph, paths, config) {
 		method: "pagerank"
 	};
 	const ranks = computePageRank(graph);
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		let prSum = 0;
 		for (const nodeId of path.nodes) prSum += ranks.get(nodeId) ?? 0;
 		return {
 			path,
 			score: prSum
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "pagerank"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "pagerank"
-	};
+	}), "pagerank", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/betweenness.ts
@@ -1405,29 +1813,14 @@ function betweenness(graph, paths, config) {
 		method: "betweenness"
 	};
 	const bcMap = computeBetweenness(graph);
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		let bcSum = 0;
 		for (const nodeId of path.nodes) bcSum += bcMap.get(nodeId) ?? 0;
 		return {
 			path,
 			score: bcSum
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "betweenness"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "betweenness"
-	};
+	}), "betweenness", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/katz.ts
@@ -1490,7 +1883,7 @@ function katz(graph, paths, config) {
 		paths: [],
 		method: "katz"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		const source = path.nodes[0];
 		const target = path.nodes[path.nodes.length - 1];
 		if (source === void 0 || target === void 0) return {
@@ -1501,22 +1894,7 @@ function katz(graph, paths, config) {
 			path,
 			score: computeKatz(graph, source, target)
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "katz"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "katz"
-	};
+	}), "katz", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/communicability.ts
@@ -1578,7 +1956,7 @@ function communicability(graph, paths, config) {
 		paths: [],
 		method: "communicability"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		const source = path.nodes[0];
 		const target = path.nodes[path.nodes.length - 1];
 		if (source === void 0 || target === void 0) return {
@@ -1589,22 +1967,7 @@ function communicability(graph, paths, config) {
 			path,
 			score: computeCommunicability(graph, source, target)
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "communicability"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "communicability"
-	};
+	}), "communicability", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/resistance-distance.ts
@@ -1721,7 +2084,7 @@ function resistanceDistance(graph, paths, config) {
 	};
 	const nodeCount = Array.from(graph.nodeIds()).length;
 	if (nodeCount > 5e3) throw new Error(`Cannot rank paths: graph too large (${String(nodeCount)} nodes). Resistance distance requires O(n^3) computation; maximum 5000 nodes.`);
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		const source = path.nodes[0];
 		const target = path.nodes[path.nodes.length - 1];
 		if (source === void 0 || target === void 0) return {
@@ -1732,22 +2095,7 @@ function resistanceDistance(graph, paths, config) {
 			path,
 			score: 1 / computeResistance(graph, source, target)
 		};
-	});
-	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
-		paths: paths.map((path) => ({
-			...path,
-			score: 0
-		})),
-		method: "resistance-distance"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "resistance-distance"
-	};
+	}), "resistance-distance", includeScores);
 }
 //#endregion
 //#region src/ranking/baselines/random-ranking.ts
@@ -1781,27 +2129,258 @@ function randomRanking(_graph, paths, config) {
 		paths: [],
 		method: "random"
 	};
-	const scored = paths.map((path) => {
+	return normaliseAndRank(paths, paths.map((path) => {
 		return {
 			path,
 			score: seededRandom(path.nodes.join(","), seed)
 		};
+	}), "random", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/hitting-time.ts
+/**
+* Seeded deterministic random number generator (LCG).
+* Suitable for reproducible random walk simulation.
+*/
+var SeededRNG = class {
+	state;
+	constructor(seed) {
+		this.state = seed;
+	}
+	/**
+	* Generate next pseudorandom value in [0, 1).
+	*/
+	next() {
+		this.state = this.state * 1103515245 + 12345 & 2147483647;
+		return this.state / 2147483647;
+	}
+};
+/**
+* Compute hitting time via Monte Carlo random walk simulation.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param walks - Number of walks to simulate
+* @param maxSteps - Maximum steps per walk
+* @param rng - Seeded RNG instance
+* @returns Average hitting time across walks
+*/
+function computeHittingTimeApproximate(graph, source, target, walks, maxSteps, rng) {
+	if (source === target) return 0;
+	let totalSteps = 0;
+	let successfulWalks = 0;
+	for (let w = 0; w < walks; w++) {
+		let current = source;
+		let steps = 0;
+		while (current !== target && steps < maxSteps) {
+			const neighbours = Array.from(graph.neighbours(current));
+			if (neighbours.length === 0) break;
+			const nextNode = neighbours[Math.floor(rng.next() * neighbours.length)];
+			if (nextNode === void 0) break;
+			current = nextNode;
+			steps++;
+		}
+		if (current === target) {
+			totalSteps += steps;
+			successfulWalks++;
+		}
+	}
+	if (successfulWalks > 0) return totalSteps / successfulWalks;
+	return maxSteps;
+}
+/**
+* Compute hitting time via exact fundamental matrix method.
+*
+* For small graphs, computes exact expected hitting times using
+* the fundamental matrix of the random walk.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @returns Exact hitting time (or approximation if convergence fails)
+*/
+function computeHittingTimeExact(graph, source, target) {
+	if (source === target) return 0;
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	const P = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		for (let j = 0; j < n; j++) row[j] = 0;
+		P[i] = row;
+	}
+	for (const nodeId of nodes) {
+		const idx = nodeToIdx.get(nodeId);
+		if (idx === void 0) continue;
+		const pRow = P[idx];
+		if (pRow === void 0) continue;
+		if (idx === targetIdx) pRow[idx] = 1;
+		else {
+			const neighbours = Array.from(graph.neighbours(nodeId));
+			const degree = neighbours.length;
+			if (degree > 0) for (const neighbourId of neighbours) {
+				const nIdx = nodeToIdx.get(neighbourId);
+				if (nIdx !== void 0) pRow[nIdx] = 1 / degree;
+			}
+		}
+	}
+	const transientIndices = [];
+	for (let i = 0; i < n; i++) if (i !== targetIdx) transientIndices.push(i);
+	const m = transientIndices.length;
+	const Q = [];
+	for (let i = 0; i < m; i++) {
+		const row = [];
+		for (let j = 0; j < m; j++) row[j] = 0;
+		Q[i] = row;
+	}
+	for (let i = 0; i < m; i++) {
+		const qRow = Q[i];
+		if (qRow === void 0) continue;
+		const origI = transientIndices[i];
+		if (origI === void 0) continue;
+		const pRow = P[origI];
+		if (pRow === void 0) continue;
+		for (let j = 0; j < m; j++) {
+			const origJ = transientIndices[j];
+			if (origJ === void 0) continue;
+			qRow[j] = pRow[origJ] ?? 0;
+		}
+	}
+	const IMQ = [];
+	for (let i = 0; i < m; i++) {
+		const row = [];
+		for (let j = 0; j < m; j++) row[j] = i === j ? 1 : 0;
+		IMQ[i] = row;
+	}
+	for (let i = 0; i < m; i++) {
+		const imqRow = IMQ[i];
+		if (imqRow === void 0) continue;
+		const qRow = Q[i];
+		for (let j = 0; j < m; j++) {
+			const qVal = qRow?.[j] ?? 0;
+			imqRow[j] = (i === j ? 1 : 0) - qVal;
+		}
+	}
+	const N = invertMatrix(IMQ);
+	if (N === null) return 1;
+	const sourceTransientIdx = transientIndices.indexOf(sourceIdx);
+	if (sourceTransientIdx < 0) return 0;
+	let hittingTime = 0;
+	const row = N[sourceTransientIdx];
+	if (row !== void 0) for (const val of row) hittingTime += val;
+	return hittingTime;
+}
+/**
+* Invert a square matrix using Gaussian elimination with partial pivoting.
+*
+* @param matrix - Input matrix (n × n)
+* @returns Inverted matrix, or null if singular
+*/
+function invertMatrix(matrix) {
+	const n = matrix.length;
+	const aug = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		const matRow = matrix[i];
+		for (let j = 0; j < n; j++) row[j] = matRow?.[j] ?? 0;
+		for (let j = 0; j < n; j++) row[n + j] = i === j ? 1 : 0;
+		aug[i] = row;
+	}
+	for (let col = 0; col < n; col++) {
+		let pivotRow = col;
+		const pivotCol = aug[pivotRow];
+		if (pivotCol === void 0) return null;
+		for (let row = col + 1; row < n; row++) {
+			const currRowVal = aug[row]?.[col] ?? 0;
+			const pivotRowVal = pivotCol[col] ?? 0;
+			if (Math.abs(currRowVal) > Math.abs(pivotRowVal)) pivotRow = row;
+		}
+		const augPivot = aug[pivotRow];
+		if (augPivot === void 0 || Math.abs(augPivot[col] ?? 0) < 1e-10) return null;
+		[aug[col], aug[pivotRow]] = [aug[pivotRow] ?? [], aug[col] ?? []];
+		const scaledPivotRow = aug[col];
+		if (scaledPivotRow === void 0) return null;
+		const pivot = scaledPivotRow[col] ?? 1;
+		for (let j = 0; j < 2 * n; j++) scaledPivotRow[j] = (scaledPivotRow[j] ?? 0) / pivot;
+		for (let row = col + 1; row < n; row++) {
+			const currRow = aug[row];
+			if (currRow === void 0) continue;
+			const factor = currRow[col] ?? 0;
+			for (let j = 0; j < 2 * n; j++) currRow[j] = (currRow[j] ?? 0) - factor * (scaledPivotRow[j] ?? 0);
+		}
+	}
+	for (let col = n - 1; col > 0; col--) {
+		const colRow = aug[col];
+		if (colRow === void 0) return null;
+		for (let row = col - 1; row >= 0; row--) {
+			const currRow = aug[row];
+			if (currRow === void 0) continue;
+			const factor = currRow[col] ?? 0;
+			for (let j = 0; j < 2 * n; j++) currRow[j] = (currRow[j] ?? 0) - factor * (colRow[j] ?? 0);
+		}
+	}
+	const inv = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		for (let j = 0; j < n; j++) row[j] = 0;
+		inv[i] = row;
+	}
+	for (let i = 0; i < n; i++) {
+		const invRow = inv[i];
+		if (invRow === void 0) continue;
+		const augRow = aug[i];
+		if (augRow === void 0) continue;
+		for (let j = 0; j < n; j++) invRow[j] = augRow[n + j] ?? 0;
+	}
+	return inv;
+}
+/**
+* Rank paths by inverse hitting time between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest inverse hitting time first)
+*/
+function hittingTime(graph, paths, config) {
+	const { includeScores = true, mode = "auto", walks = 1e3, maxSteps = 1e4, seed = 42 } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "hitting-time"
+	};
+	const nodeCount = Array.from(graph.nodeIds()).length;
+	const actualMode = mode === "auto" ? nodeCount < 100 ? "exact" : "approximate" : mode;
+	const rng = new SeededRNG(seed);
+	const scored = paths.map((path) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		const ht = actualMode === "exact" ? computeHittingTimeExact(graph, source, target) : computeHittingTimeApproximate(graph, source, target, walks, maxSteps, rng);
+		return {
+			path,
+			score: ht > 0 ? 1 / ht : 0
+		};
 	});
 	const maxScore = Math.max(...scored.map((s) => s.score));
-	if (maxScore === 0) return {
+	if (!Number.isFinite(maxScore)) return {
 		paths: paths.map((path) => ({
 			...path,
 			score: 0
 		})),
-		method: "random"
-	};
-	return {
-		paths: scored.map(({ path, score }) => ({
-			...path,
-			score: includeScores ? score / maxScore : score / maxScore
-		})).sort((a, b) => b.score - a.score),
-		method: "random"
+		method: "hitting-time"
 	};
+	return normaliseAndRank(paths, scored, "hitting-time", includeScores);
 }
 //#endregion
 //#region src/extraction/ego-network.ts
@@ -2421,6 +3000,6 @@ function filterSubgraph(graph, options) {
 	return result;
 }
 //#endregion
-export { AdjacencyMapGraph, GPUContext, GPUNotAvailableError, PriorityQueue, _computeMean, adamicAdar, adaptive, approximateClusteringCoefficient, assertWebGPUAvailable, base, batchClusteringCoefficients, betweenness, bfs, bfsWithPath, communicability, computeTrussNumbers, countEdgesOfType, countNodesOfType, createGPUContext, createResultBuffer, csrToGPUBuffers, degreeSum, detectWebGPU, dfs, dfsWithPath, dome, domeHighDegree, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, flux, frontierBalanced, fuse, getGPUContext, getMotifName, graphToCSR, grasp, hae, isWebGPUAvailable, jaccard, jaccardArithmetic, katz, lace, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, neighbourIntersection, neighbourOverlap, neighbourSet, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, pagerank, parse, pipe, randomPriority, randomRanking, reach, readBufferToCPU, resistanceDistance, sage, scale, shannonEntropy, shortest, sift, skew, span, standardBfs, stratified, tide, warp, widestPath };
+export { AdjacencyMapGraph, GPUContext, GPUNotAvailableError, PriorityQueue, _computeMean, adamicAdar, adaptive, approximateClusteringCoefficient, assertWebGPUAvailable, base, batchClusteringCoefficients, betweenness, bfs, bfsWithPath, communicability, computeJaccard, computeTrussNumbers, cosine, countEdgesOfType, countNodesOfType, createGPUContext, createResultBuffer, csrToGPUBuffers, degreeSum, detectWebGPU, dfs, dfsPriority, dfsPriorityFn, dfsWithPath, dome, domeHighDegree, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, flux, frontierBalanced, fuse, getGPUContext, getMotifName, graphToCSR, grasp, hae, hittingTime, hubPromoted, isWebGPUAvailable, jaccard, jaccardArithmetic, kHop, katz, lace, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, neighbourIntersection, neighbourOverlap, neighbourSet, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, overlapCoefficient, pagerank, parse, pipe, randomPriority, randomRanking, randomWalk, reach, readBufferToCPU, resistanceDistance, resourceAllocation, sage, scale, shannonEntropy, shortest, sift, skew, sorensen, span, standardBfs, stratified, tide, warp, widestPath };
 
 //# sourceMappingURL=index.js.map