graphwise 1.4.2 → 1.5.0

package/dist/index/index.js

@@ -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(),
@@ -759,7 +759,7 @@ function fluxPriority(nodeId, context, densityThreshold, bridgeThreshold) {
 	const bridge = bridgeScore(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 +857,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,6 +1290,115 @@ 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.
@@ -1804,6 +2253,258 @@ function randomRanking(_graph, paths, config) {
 	};
 }
 //#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 || !Number.isFinite(maxScore)) return {
+		paths: paths.map((path) => ({
+			...path,
+			score: 0
+		})),
+		method: "hitting-time"
+	};
+	return {
+		paths: scored.map(({ path, score }) => ({
+			...path,
+			score: includeScores ? score / maxScore : score / maxScore
+		})).sort((a, b) => b.score - a.score),
+		method: "hitting-time"
+	};
+}
+//#endregion
 //#region src/extraction/ego-network.ts
 /**
 * Extract the ego-network (k-hop neighbourhood) of a centre node.
@@ -2421,6 +3122,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, 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