graphwise 1.1.0 → 1.2.0

package/dist/index/index.js

@@ -1,10 +1,10 @@
-import { t as AdjacencyMapGraph } from "../graph-DLWiziLB.js";
-import { i as bfsWithPath, n as dfsWithPath, r as bfs, t as dfs } from "../traversal-CQCjUwUJ.js";
-import { t as PriorityQueue } from "../structures-BPfhfqNP.js";
-import { n as normaliseFeatures, t as miniBatchKMeans } from "../kmeans-DgbsOznU.js";
-import { n as grasp, t as stratified } from "../seeds-UNZxqm_U.js";
-import { a as approximateClusteringCoefficient, i as shannonEntropy, n as localTypeEntropy, o as batchClusteringCoefficients, r as normalisedEntropy, s as localClusteringCoefficient, t as entropyFromCounts } from "../utils-Q_akvlMn.js";
-import { i as detectWebGPU, n as graphToCSR, r as GPUContext, t as csrToGPUBuffers } from "../gpu-BveuXugy.js";
+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 { grasp, stratified } from "../seeds/index.js";
+import { approximateClusteringCoefficient, batchClusteringCoefficients, entropyFromCounts, localClusteringCoefficient, localTypeEntropy, normalisedEntropy, shannonEntropy } from "../utils/index.js";
+import { GPUContext, GPUNotAvailableError, assertWebGPUAvailable, createGPUContext, createResultBuffer, csrToGPUBuffers, detectWebGPU, getGPUContext, graphToCSR, isWebGPUAvailable, readBufferToCPU } from "../gpu/index.js";
 //#region src/expansion/base.ts
 /**
 * Default priority function - degree-ordered (DOME).
@@ -242,6 +242,18 @@ function dome(graph, seeds, config) {
 		priority: domePriority
 	});
 }
+/**
+* DOME with reverse priority (high degree first).
+*/
+function domeHighDegree(graph, seeds, config) {
+	const domePriority = (nodeId, context) => {
+		return -graph.degree(nodeId);
+	};
+	return base(graph, seeds, {
+		...config,
+		priority: domePriority
+	});
+}
 //#endregion
 //#region src/expansion/edge.ts
 /**
@@ -520,6 +532,80 @@ function maze(graph, seeds, config) {
 	});
 }
 //#endregion
+//#region src/expansion/standard-bfs.ts
+/**
+* Run standard BFS expansion (FIFO discovery order).
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function standardBfs(graph, seeds, config) {
+	const bfsPriority = (_nodeId, context) => {
+		return context.iteration;
+	};
+	return base(graph, seeds, {
+		...config,
+		priority: bfsPriority
+	});
+}
+//#endregion
+//#region src/expansion/frontier-balanced.ts
+/**
+* Run frontier-balanced expansion (round-robin across frontiers).
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function frontierBalanced(graph, seeds, config) {
+	const balancedPriority = (_nodeId, context) => {
+		return context.frontierIndex * 1e9 + context.iteration;
+	};
+	return base(graph, seeds, {
+		...config,
+		priority: balancedPriority
+	});
+}
+//#endregion
+//#region src/expansion/random-priority.ts
+/**
+* Deterministic seeded random number generator.
+* Uses FNV-1a-like hash for input → [0, 1] output.
+*
+* @param input - String to hash
+* @param seed - Random seed for reproducibility
+* @returns Deterministic random value in [0, 1]
+*/
+function seededRandom$1(input, seed = 0) {
+	let h = seed;
+	for (let i = 0; i < input.length; i++) {
+		h = Math.imul(h ^ input.charCodeAt(i), 2654435769);
+		h ^= h >>> 16;
+	}
+	return (h >>> 0) / 4294967295;
+}
+/**
+* Run random-priority expansion (null hypothesis baseline).
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function randomPriority(graph, seeds, config) {
+	const { seed = 0 } = config ?? {};
+	const randomPriorityFn = (nodeId, context) => {
+		return seededRandom$1(nodeId, seed);
+	};
+	return base(graph, seeds, {
+		...config,
+		priority: randomPriorityFn
+	});
+}
+//#endregion
 //#region src/ranking/parse.ts
 /**
 * Rank paths using PARSE (Path-Aware Ranking via Salience Estimation).
@@ -812,6 +898,712 @@ function shortest(_graph, paths, config) {
 	};
 }
 //#endregion
+//#region src/ranking/baselines/degree-sum.ts
+/**
+* Rank paths by sum of node degrees.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest degree-sum first)
+*/
+function degreeSum(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "degree-sum"
+	};
+	const scored = 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 / maxScore
+		})).sort((a, b) => b.score - a.score),
+		method: "degree-sum"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/widest-path.ts
+/**
+* Rank paths by widest bottleneck (minimum edge similarity).
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest bottleneck first)
+*/
+function widestPath(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "widest-path"
+	};
+	const scored = paths.map((path) => {
+		if (path.nodes.length < 2) return {
+			path,
+			score: 1
+		};
+		let minSimilarity = Number.POSITIVE_INFINITY;
+		for (let i = 0; i < path.nodes.length - 1; i++) {
+			const source = path.nodes[i];
+			const target = path.nodes[i + 1];
+			if (source === void 0 || target === void 0) continue;
+			const edgeSimilarity = jaccard(graph, source, target);
+			minSimilarity = Math.min(minSimilarity, edgeSimilarity);
+		}
+		return {
+			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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/jaccard-arithmetic.ts
+/**
+* Rank paths by arithmetic mean of edge Jaccard similarities.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest arithmetic mean first)
+*/
+function jaccardArithmetic(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "jaccard-arithmetic"
+	};
+	const scored = paths.map((path) => {
+		if (path.nodes.length < 2) return {
+			path,
+			score: 1
+		};
+		let similaritySum = 0;
+		let edgeCount = 0;
+		for (let i = 0; i < path.nodes.length - 1; i++) {
+			const source = path.nodes[i];
+			const target = path.nodes[i + 1];
+			if (source === void 0 || target === void 0) continue;
+			const edgeSimilarity = jaccard(graph, source, target);
+			similaritySum += edgeSimilarity;
+			edgeCount++;
+		}
+		return {
+			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 / maxScore
+		})).sort((a, b) => b.score - a.score),
+		method: "jaccard-arithmetic"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/pagerank.ts
+/**
+* Compute PageRank centrality for all nodes using power iteration.
+*
+* @param graph - Source graph
+* @param damping - Damping factor (default 0.85)
+* @param tolerance - Convergence tolerance (default 1e-6)
+* @param maxIterations - Maximum iterations (default 100)
+* @returns Map of node ID to PageRank value
+*/
+function computePageRank(graph, damping = .85, tolerance = 1e-6, maxIterations = 100) {
+	const nodes = Array.from(graph.nodeIds());
+	const n = nodes.length;
+	if (n === 0) return /* @__PURE__ */ new Map();
+	const ranks = /* @__PURE__ */ new Map();
+	const newRanks = /* @__PURE__ */ new Map();
+	for (const nodeId of nodes) {
+		ranks.set(nodeId, 1 / n);
+		newRanks.set(nodeId, 0);
+	}
+	let isCurrentRanks = true;
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		let maxChange = 0;
+		const currMap = isCurrentRanks ? ranks : newRanks;
+		const nextMap = isCurrentRanks ? newRanks : ranks;
+		for (const nodeId of nodes) {
+			let incomingSum = 0;
+			for (const incomingId of graph.neighbours(nodeId, "in")) {
+				const incomingRank = currMap.get(incomingId) ?? 0;
+				const outDegree = graph.degree(incomingId);
+				if (outDegree > 0) incomingSum += incomingRank / outDegree;
+			}
+			const newRank = (1 - damping) / n + damping * incomingSum;
+			nextMap.set(nodeId, newRank);
+			const oldRank = currMap.get(nodeId) ?? 0;
+			maxChange = Math.max(maxChange, Math.abs(newRank - oldRank));
+		}
+		if (maxChange < tolerance) break;
+		isCurrentRanks = !isCurrentRanks;
+		currMap.clear();
+	}
+	return isCurrentRanks ? ranks : newRanks;
+}
+/**
+* Rank paths by sum of PageRank scores.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest PageRank sum first)
+*/
+function pagerank(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "pagerank"
+	};
+	const ranks = computePageRank(graph);
+	const scored = 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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/betweenness.ts
+/**
+* Compute betweenness centrality for all nodes using Brandes algorithm.
+*
+* @param graph - Source graph
+* @returns Map of node ID to betweenness value
+*/
+function computeBetweenness(graph) {
+	const nodes = Array.from(graph.nodeIds());
+	const betweenness = /* @__PURE__ */ new Map();
+	for (const nodeId of nodes) betweenness.set(nodeId, 0);
+	for (const source of nodes) {
+		const predecessors = /* @__PURE__ */ new Map();
+		const distance = /* @__PURE__ */ new Map();
+		const sigma = /* @__PURE__ */ new Map();
+		const queue = [];
+		for (const nodeId of nodes) {
+			predecessors.set(nodeId, []);
+			distance.set(nodeId, -1);
+			sigma.set(nodeId, 0);
+		}
+		distance.set(source, 0);
+		sigma.set(source, 1);
+		queue.push(source);
+		for (const v of queue) {
+			const vDist = distance.get(v) ?? -1;
+			const neighbours = graph.neighbours(v);
+			for (const w of neighbours) {
+				const wDist = distance.get(w) ?? -1;
+				if (wDist < 0) {
+					distance.set(w, vDist + 1);
+					queue.push(w);
+				}
+				if (wDist === vDist + 1) {
+					const wSigma = sigma.get(w) ?? 0;
+					const vSigma = sigma.get(v) ?? 0;
+					sigma.set(w, wSigma + vSigma);
+					const wPred = predecessors.get(w) ?? [];
+					wPred.push(v);
+					predecessors.set(w, wPred);
+				}
+			}
+		}
+		const delta = /* @__PURE__ */ new Map();
+		for (const nodeId of nodes) delta.set(nodeId, 0);
+		const sorted = [...nodes].sort((a, b) => {
+			const aD = distance.get(a) ?? -1;
+			return (distance.get(b) ?? -1) - aD;
+		});
+		for (const w of sorted) {
+			if (w === source) continue;
+			const wDelta = delta.get(w) ?? 0;
+			const wSigma = sigma.get(w) ?? 0;
+			const wPred = predecessors.get(w) ?? [];
+			for (const v of wPred) {
+				const vSigma = sigma.get(v) ?? 0;
+				const vDelta = delta.get(v) ?? 0;
+				if (wSigma > 0) delta.set(v, vDelta + vSigma / wSigma * (1 + wDelta));
+			}
+			if (w !== source) {
+				const current = betweenness.get(w) ?? 0;
+				betweenness.set(w, current + wDelta);
+			}
+		}
+	}
+	return betweenness;
+}
+/**
+* Rank paths by sum of betweenness scores.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest betweenness sum first)
+*/
+function betweenness(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "betweenness"
+	};
+	const bcMap = computeBetweenness(graph);
+	const scored = 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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/katz.ts
+/**
+* Compute truncated Katz centrality between two nodes.
+*
+* Uses iterative matrix-vector products to avoid full matrix powers.
+* score(s,t) = sum_{k=1}^{K} beta^k * walks_k(s,t)
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param k - Truncation depth (default 5)
+* @param beta - Attenuation factor (default 0.005)
+* @returns Katz score
+*/
+function computeKatz(graph, source, target, k = 5, beta = .005) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0) return 0;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	let walks = new Float64Array(n);
+	walks[targetIdx] = 1;
+	let katzScore = 0;
+	for (let depth = 1; depth <= k; depth++) {
+		const walksNext = new Float64Array(n);
+		for (const sourceNode of nodes) {
+			const srcIdx = nodeToIdx.get(sourceNode);
+			if (srcIdx === void 0) continue;
+			const neighbours = graph.neighbours(sourceNode);
+			for (const neighbourId of neighbours) {
+				const nIdx = nodeToIdx.get(neighbourId);
+				if (nIdx === void 0) continue;
+				walksNext[srcIdx] = (walksNext[srcIdx] ?? 0) + (walks[nIdx] ?? 0);
+			}
+		}
+		const walkCount = walksNext[sourceIdx] ?? 0;
+		katzScore += Math.pow(beta, depth) * walkCount;
+		walks = walksNext;
+	}
+	return katzScore;
+}
+/**
+* Rank paths by Katz centrality between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest Katz score first)
+*/
+function katz(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "katz"
+	};
+	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
+		};
+		return {
+			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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/communicability.ts
+/**
+* Compute truncated communicability between two nodes.
+*
+* Uses Taylor series expansion: (e^A)_{s,t} ≈ sum_{k=0}^{K} A^k_{s,t} / k!
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param k - Truncation depth (default 15)
+* @returns Communicability score
+*/
+function computeCommunicability(graph, source, target, k = 15) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0) return 0;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	let walks = new Float64Array(n);
+	walks[targetIdx] = 1;
+	let commScore = walks[sourceIdx] ?? 0;
+	let factorial = 1;
+	for (let depth = 1; depth <= k; depth++) {
+		const walksNext = new Float64Array(n);
+		for (const fromNode of nodes) {
+			const fromIdx = nodeToIdx.get(fromNode);
+			if (fromIdx === void 0) continue;
+			const neighbours = graph.neighbours(fromNode);
+			for (const toNodeId of neighbours) {
+				const toIdx = nodeToIdx.get(toNodeId);
+				if (toIdx === void 0) continue;
+				walksNext[fromIdx] = (walksNext[fromIdx] ?? 0) + (walks[toIdx] ?? 0);
+			}
+		}
+		factorial *= depth;
+		commScore += (walksNext[sourceIdx] ?? 0) / factorial;
+		walks = walksNext;
+	}
+	return commScore;
+}
+/**
+* Rank paths by communicability between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest communicability first)
+*/
+function communicability(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "communicability"
+	};
+	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
+		};
+		return {
+			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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/resistance-distance.ts
+/**
+* Compute effective resistance between two nodes via Laplacian pseudoinverse.
+*
+* Resistance = L^+_{s,s} + L^+_{t,t} - 2*L^+_{s,t}
+* where L^+ is the pseudoinverse of the Laplacian matrix.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @returns Effective resistance
+*/
+function computeResistance(graph, source, target) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0 || n > 5e3) throw new Error(`Cannot compute resistance distance: graph too large (${String(n)} nodes). Maximum 5000.`);
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	const L = Array.from({ length: n }, () => Array.from({ length: n }, () => 0));
+	for (let i = 0; i < n; i++) {
+		const nodeId = nodes[i];
+		if (nodeId === void 0) continue;
+		const degree = graph.degree(nodeId);
+		const row = L[i];
+		if (row !== void 0) row[i] = degree;
+		const neighbours = graph.neighbours(nodeId);
+		for (const neighbourId of neighbours) {
+			const j = nodeToIdx.get(neighbourId);
+			if (j !== void 0 && row !== void 0) row[j] = -1;
+		}
+	}
+	const Lpinv = pinv(L);
+	const resistance = (Lpinv[sourceIdx]?.[sourceIdx] ?? 0) + (Lpinv[targetIdx]?.[targetIdx] ?? 0) - 2 * (Lpinv[sourceIdx]?.[targetIdx] ?? 0);
+	return Math.max(resistance, 1e-10);
+}
+/**
+* Compute Moore-Penrose pseudoinverse of a matrix.
+* Simplified implementation for small dense matrices.
+*
+* @param A - Square matrix
+* @returns Pseudoinverse A^+
+*/
+function pinv(A) {
+	const n = A.length;
+	if (n === 0) return [];
+	const M = A.map((row) => [...row]);
+	const epsilon = 1e-10;
+	for (let i = 0; i < n; i++) {
+		const row = M[i];
+		if (row !== void 0) row[i] = (row[i] ?? 0) + epsilon;
+	}
+	return gaussianInverse(M);
+}
+/**
+* Compute matrix inverse using Gaussian elimination with partial pivoting.
+*
+* @param A - Matrix to invert
+* @returns Inverted matrix
+*/
+function gaussianInverse(A) {
+	const n = A.length;
+	const aug = A.map((row, i) => {
+		const identity = Array.from({ length: n }, (_, j) => i === j ? 1 : 0);
+		return [...row, ...identity];
+	});
+	for (let col = 0; col < n; col++) {
+		let maxRow = col;
+		for (let row = col + 1; row < n; row++) {
+			const currentRow = aug[row];
+			const maxRowRef = aug[maxRow];
+			if (currentRow !== void 0 && maxRowRef !== void 0 && Math.abs(currentRow[col] ?? 0) > Math.abs(maxRowRef[col] ?? 0)) maxRow = row;
+		}
+		const currentCol = aug[col];
+		const maxRowAug = aug[maxRow];
+		if (currentCol !== void 0 && maxRowAug !== void 0) {
+			aug[col] = maxRowAug;
+			aug[maxRow] = currentCol;
+		}
+		const pivotRow = aug[col];
+		const pivot = pivotRow?.[col];
+		if (pivot === void 0 || Math.abs(pivot) < 1e-12) continue;
+		if (pivotRow !== void 0) for (let j = col; j < 2 * n; j++) pivotRow[j] = (pivotRow[j] ?? 0) / pivot;
+		for (let row = 0; row < n; row++) {
+			if (row === col) continue;
+			const eliminationRow = aug[row];
+			const factor = eliminationRow?.[col] ?? 0;
+			if (eliminationRow !== void 0 && pivotRow !== void 0) for (let j = col; j < 2 * n; j++) eliminationRow[j] = (eliminationRow[j] ?? 0) - factor * (pivotRow[j] ?? 0);
+		}
+	}
+	const Ainv = [];
+	for (let i = 0; i < n; i++) Ainv[i] = (aug[i]?.slice(n) ?? []).map((v) => v);
+	return Ainv;
+}
+/**
+* Rank paths by reciprocal of resistance distance between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest conductance first)
+*/
+function resistanceDistance(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "resistance-distance"
+	};
+	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) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		return {
+			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"
+	};
+}
+//#endregion
+//#region src/ranking/baselines/random-ranking.ts
+/**
+* Deterministic seeded random number generator.
+* Uses FNV-1a-like hash for input → [0, 1] output.
+*
+* @param input - String to hash
+* @param seed - Random seed for reproducibility
+* @returns Deterministic random value in [0, 1]
+*/
+function seededRandom(input, seed = 0) {
+	let h = seed;
+	for (let i = 0; i < input.length; i++) {
+		h = Math.imul(h ^ input.charCodeAt(i), 2654435769);
+		h ^= h >>> 16;
+	}
+	return (h >>> 0) / 4294967295;
+}
+/**
+* Rank paths randomly (null hypothesis baseline).
+*
+* @param _graph - Source graph (unused)
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (randomly ordered)
+*/
+function randomRanking(_graph, paths, config) {
+	const { includeScores = true, seed = 0 } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "random"
+	};
+	const scored = paths.map((path) => {
+		return {
+			path,
+			score: seededRandom(path.nodes.join(","), seed)
+		};
+	});
+	const maxScore = Math.max(...scored.map((s) => s.score));
+	if (maxScore === 0) 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"
+	};
+}
+//#endregion
 //#region src/extraction/ego-network.ts
 /**
 * Extract the ego-network (k-hop neighbourhood) of a centre node.
@@ -1022,6 +1814,82 @@ function extractKTruss(graph, k) {
 	}
 	return result;
 }
+/**
+* Compute the truss number for each edge.
+*
+* The truss number of an edge is the largest k such that the edge
+* belongs to the k-truss.
+*
+* @param graph - The source graph
+* @returns Map from edge key (canonical "u::v") to truss number
+*
+* @example
+* ```typescript
+* const trussNumbers = computeTrussNumbers(graph);
+* const edgeKey = 'A::B'; // where A < B lexicographically
+* console.log(`Edge A-B is in the ${trussNumbers.get(edgeKey)}-truss`);
+* ```
+*/
+function computeTrussNumbers(graph) {
+	const adjacency = /* @__PURE__ */ new Map();
+	const edgeData = /* @__PURE__ */ new Map();
+	const remainingEdges = /* @__PURE__ */ new Set();
+	for (const nodeId of graph.nodeIds()) adjacency.set(nodeId, /* @__PURE__ */ new Set());
+	for (const edge of graph.edges()) {
+		const { source, target } = edge;
+		adjacency.get(source)?.add(target);
+		adjacency.get(target)?.add(source);
+		const key = source < target ? `${source}::${target}` : `${target}::${source}`;
+		edgeData.set(key, edge);
+		remainingEdges.add(key);
+	}
+	const triangleCounts = /* @__PURE__ */ new Map();
+	for (const key of remainingEdges) {
+		const edge = edgeData.get(key);
+		if (edge !== void 0) triangleCounts.set(key, countEdgeTriangles(graph, edge.source, edge.target));
+	}
+	const trussNumbers = /* @__PURE__ */ new Map();
+	const edgesByTriangleCount = /* @__PURE__ */ new Map();
+	for (const [key, count] of triangleCounts) {
+		if (!edgesByTriangleCount.has(count)) edgesByTriangleCount.set(count, /* @__PURE__ */ new Set());
+		edgesByTriangleCount.get(count)?.add(key);
+	}
+	const sortedCounts = [...edgesByTriangleCount.keys()].sort((a, b) => a - b);
+	for (const currentCount of sortedCounts) {
+		const bucket = edgesByTriangleCount.get(currentCount);
+		if (bucket === void 0) continue;
+		while (bucket.size > 0) {
+			const edgeKey = bucket.values().next().value;
+			if (edgeKey === void 0) break;
+			bucket.delete(edgeKey);
+			if (!remainingEdges.has(edgeKey)) continue;
+			const trussNumber = currentCount + 2;
+			trussNumbers.set(edgeKey, trussNumber);
+			remainingEdges.delete(edgeKey);
+			const edge = edgeData.get(edgeKey);
+			if (edge === void 0) continue;
+			const { source, target } = edge;
+			adjacency.get(source)?.delete(target);
+			adjacency.get(target)?.delete(source);
+			const sourceNeighbours = adjacency.get(source);
+			if (sourceNeighbours !== void 0) {
+				for (const w of adjacency.get(target) ?? []) if (sourceNeighbours.has(w)) {
+					const keySw = source < w ? `${source}::${w}` : `${w}::${source}`;
+					const keyTw = target < w ? `${target}::${w}` : `${w}::${target}`;
+					for (const keyToUpdate of [keySw, keyTw]) if (remainingEdges.has(keyToUpdate)) {
+						const oldCount = triangleCounts.get(keyToUpdate) ?? 0;
+						const newCount = oldCount - 1;
+						triangleCounts.set(keyToUpdate, newCount);
+						edgesByTriangleCount.get(oldCount)?.delete(keyToUpdate);
+						if (!edgesByTriangleCount.has(newCount)) edgesByTriangleCount.set(newCount, /* @__PURE__ */ new Set());
+						edgesByTriangleCount.get(newCount)?.add(keyToUpdate);
+					}
+				}
+			}
+		}
+	}
+	return trussNumbers;
+}
 //#endregion
 //#region src/extraction/motif.ts
 /**
@@ -1132,10 +2000,11 @@ function enumerate3NodeMotifs(graph, includeInstances) {
 			}
 		}
 	}
-	return {
+	if (instances !== void 0) return {
 		counts,
 		instances
 	};
+	return { counts };
 }
 /**
 * Enumerate all 4-node motifs in the graph.
@@ -1203,10 +2072,11 @@ function enumerate4NodeMotifs(graph, includeInstances) {
 			}
 		}
 	}
-	return {
+	if (instances !== void 0) return {
 		counts,
 		instances
 	};
+	return { counts };
 }
 /**
 * Human-readable names for common 3-node motifs.
@@ -1351,6 +2221,6 @@ function filterSubgraph(graph, options) {
 	return result;
 }
 //#endregion
-export { AdjacencyMapGraph, GPUContext, PriorityQueue, adamicAdar, adaptive, approximateClusteringCoefficient, base, batchClusteringCoefficients, bfs, bfsWithPath, csrToGPUBuffers, detectWebGPU, dfs, dfsWithPath, dome, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, getMotifName, graphToCSR, grasp, hae, jaccard, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, parse, pipe, reach, sage, scale, shannonEntropy, shortest, skew, span, stratified };
+export { AdjacencyMapGraph, GPUContext, GPUNotAvailableError, PriorityQueue, _computeMean, adamicAdar, adaptive, approximateClusteringCoefficient, assertWebGPUAvailable, base, batchClusteringCoefficients, betweenness, bfs, bfsWithPath, communicability, computeTrussNumbers, createGPUContext, createResultBuffer, csrToGPUBuffers, degreeSum, detectWebGPU, dfs, dfsWithPath, dome, domeHighDegree, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, frontierBalanced, getGPUContext, getMotifName, graphToCSR, grasp, hae, isWebGPUAvailable, jaccard, jaccardArithmetic, katz, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, pagerank, parse, pipe, randomPriority, randomRanking, reach, readBufferToCPU, resistanceDistance, sage, scale, shannonEntropy, shortest, skew, span, standardBfs, stratified, widestPath };
 
 //# sourceMappingURL=index.js.map