graphwise 1.0.0 → 1.1.0

package/dist/seeds-B6J9oJfU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeds-B6J9oJfU.cjs","names":[],"sources":["../src/seeds/grasp.ts","../src/seeds/stratified.ts"],"sourcesContent":["/**\n * GRASP — Graph-agnostic Representative Seed pAir Sampling.\n *\n * Novel blind structural seed selection algorithm that selects structurally\n * representative seed pairs without requiring domain knowledge or loading\n * the full graph into memory.\n *\n * Three phases:\n * 1. Reservoir sampling — stream edges, maintain reservoir of N nodes\n * 2. Structural feature computation — log-degree, clustering coeff, approx PageRank\n * 3. Mini-batch K-means clustering, then sample pairs within and across clusters\n *\n * @packageDocumentation\n */\n\nimport type { ReadableGraph, NodeId } from \"../graph\";\nimport type { Seed } from \"../schemas/index\";\nimport {\n\tminiBatchKMeans,\n\tzScoreNormalise,\n\ttype LabelledFeature,\n\ttype FeatureVector3D,\n} from \"../utils/kmeans\";\n\n/**\n * Configuration options for GRASP seed selection.\n */\nexport interface GraspOptions {\n\t/** Number of clusters for K-means (default: 100) */\n\treadonly nClusters?: number;\n\t/** Number of pairs to sample per cluster (default: 10) */\n\treadonly pairsPerCluster?: number;\n\t/** Ratio of within-cluster pairs vs cross-cluster pairs (default: 0.5) */\n\treadonly withinClusterRatio?: number;\n\t/** Reservoir sample size (default: 200000) */\n\treadonly sampleSize?: number;\n\t/** Random seed for reproducibility (default: 42) */\n\treadonly rngSeed?: number;\n\t/** Number of PageRank iterations for feature computation (default: 10) */\n\treadonly pagerankIterations?: number;\n}\n\n/**\n * A sampled seed pair with structural metadata.\n */\nexport interface GraspSeedPair {\n\t/** Source seed */\n\treadonly source: Seed;\n\t/** Target seed */\n\treadonly target: Seed;\n\t/** Euclidean distance in feature space */\n\treadonly featureDistance: number;\n\t/** Whether both seeds are from the same cluster */\n\treadonly sameCluster: boolean;\n\t/** Cluster index of source (or -1 if unclustered) */\n\treadonly sourceCluster: number;\n\t/** Cluster index of target (or -1 if unclustered) */\n\treadonly targetCluster: number;\n}\n\n/**\n * Result of GRASP seed selection.\n */\nexport interface GraspResult {\n\t/** Sampled seed pairs */\n\treadonly pairs: readonly GraspSeedPair[];\n\t/** Number of clusters used */\n\treadonly nClusters: number;\n\t/** Total nodes sampled */\n\treadonly sampledNodeCount: number;\n\t/** Features computed for sampled nodes */\n\treadonly features: readonly LabelledFeature[];\n\t/** Cluster assignments (nodeId -> cluster index) */\n\treadonly clusterAssignments: ReadonlyMap<string, number>;\n}\n\n/** Default configuration values */\nconst DEFAULTS = {\n\tnClusters: 100,\n\tpairsPerCluster: 10,\n\twithinClusterRatio: 0.5,\n\tsampleSize: 200000,\n\trngSeed: 42,\n\tpagerankIterations: 10,\n} as const;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Reservoir sampling (Vitter's Algorithm R) for streaming node selection.\n *\n * Maintains a uniform sample of nodes as edges are streamed, without\n * requiring the full graph in memory.\n */\nfunction reservoirSample(\n\tgraph: ReadableGraph,\n\tsampleSize: number,\n\trng: () => number,\n): { nodeIds: Set<NodeId>; neighbourMap: Map<NodeId, Set<NodeId>> } {\n\tconst reservoir: NodeId[] = [];\n\tconst neighbourMap = new Map<NodeId, Set<NodeId>>();\n\tconst inReservoir = new Set<NodeId>();\n\n\t// Track total nodes seen for reservoir probability\n\tlet nodesSeen = 0;\n\n\t// Stream all edges and sample nodes\n\tfor (const edge of graph.edges()) {\n\t\t// Process source node\n\t\tconst source = edge.source;\n\t\tif (!inReservoir.has(source)) {\n\t\t\tnodesSeen++;\n\t\t\tif (reservoir.length < sampleSize) {\n\t\t\t\treservoir.push(source);\n\t\t\t\tinReservoir.add(source);\n\t\t\t\tneighbourMap.set(source, new Set<NodeId>());\n\t\t\t} else {\n\t\t\t\t// Reservoir sampling: replace with probability sampleSize/nodesSeen\n\t\t\t\tconst j = Math.floor(rng() * nodesSeen);\n\t\t\t\tif (j < sampleSize) {\n\t\t\t\t\tconst oldNode = reservoir[j];\n\t\t\t\t\tif (oldNode !== undefined) {\n\t\t\t\t\t\tinReservoir.delete(oldNode);\n\t\t\t\t\t\tneighbourMap.delete(oldNode);\n\t\t\t\t\t}\n\t\t\t\t\treservoir[j] = source;\n\t\t\t\t\tinReservoir.add(source);\n\t\t\t\t\tneighbourMap.set(source, new Set<NodeId>());\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Process target node\n\t\tconst target = edge.target;\n\t\tif (!inReservoir.has(target)) {\n\t\t\tnodesSeen++;\n\t\t\tif (reservoir.length < sampleSize) {\n\t\t\t\treservoir.push(target);\n\t\t\t\tinReservoir.add(target);\n\t\t\t\tneighbourMap.set(target, new Set<NodeId>());\n\t\t\t} else {\n\t\t\t\tconst j = Math.floor(rng() * nodesSeen);\n\t\t\t\tif (j < sampleSize) {\n\t\t\t\t\tconst oldNode = reservoir[j];\n\t\t\t\t\tif (oldNode !== undefined) {\n\t\t\t\t\t\tinReservoir.delete(oldNode);\n\t\t\t\t\t\tneighbourMap.delete(oldNode);\n\t\t\t\t\t}\n\t\t\t\t\treservoir[j] = target;\n\t\t\t\t\tinReservoir.add(target);\n\t\t\t\t\tneighbourMap.set(target, new Set<NodeId>());\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Store neighbour relationships for sampled nodes\n\t\tif (inReservoir.has(source) && inReservoir.has(target)) {\n\t\t\tconst sourceNeighbours = neighbourMap.get(source);\n\t\t\tconst targetNeighbours = neighbourMap.get(target);\n\t\t\tsourceNeighbours?.add(target);\n\t\t\ttargetNeighbours?.add(source);\n\t\t}\n\t}\n\n\treturn { nodeIds: inReservoir, neighbourMap };\n}\n\n/**\n * Compute approximate PageRank scores using power iteration on the reservoir subgraph.\n *\n * This is an approximation since it only considers the sampled nodes and their\n * connections within the reservoir, not the full graph.\n */\nfunction approximatePageRank(\n\tnodeIds: Set<NodeId>,\n\tneighbourMap: Map<NodeId, Set<NodeId>>,\n\titerations: number,\n\tdampingFactor = 0.85,\n): Map<NodeId, number> {\n\tconst n = nodeIds.size;\n\tif (n === 0) return new Map();\n\n\tconst nodeIdList = [...nodeIds];\n\tconst nodeIndex = new Map(nodeIdList.map((id, i) => [id, i] as const));\n\n\t// Initialise PageRank scores uniformly\n\tconst scores = new Float64Array(n).fill(1 / n);\n\tconst newScores = new Float64Array(n);\n\n\t// Power iteration\n\tfor (let iter = 0; iter < iterations; iter++) {\n\t\tnewScores.fill((1 - dampingFactor) / n);\n\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst nodeId = nodeIdList[i];\n\t\t\tif (nodeId === undefined) continue;\n\n\t\t\tconst neighbours = neighbourMap.get(nodeId);\n\t\t\tif (neighbours === undefined) continue;\n\n\t\t\tconst outDegree = neighbours.size;\n\t\t\tif (outDegree === 0) continue;\n\n\t\t\tconst contribution = (dampingFactor * (scores[i] ?? 0)) / outDegree;\n\n\t\t\tfor (const neighbour of neighbours) {\n\t\t\t\tconst neighbourIdx = nodeIndex.get(neighbour);\n\t\t\t\tif (neighbourIdx !== undefined) {\n\t\t\t\t\tnewScores[neighbourIdx] =\n\t\t\t\t\t\t(newScores[neighbourIdx] ?? 0) + contribution;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Swap buffers\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tscores[i] = newScores[i] ?? 0;\n\t\t}\n\t}\n\n\t// Build result map\n\tconst result = new Map<NodeId, number>();\n\tfor (let i = 0; i < n; i++) {\n\t\tconst nodeId = nodeIdList[i];\n\t\tconst score = scores[i];\n\t\tif (nodeId !== undefined && score !== undefined) {\n\t\t\tresult.set(nodeId, score);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Compute structural features for sampled nodes.\n *\n * Features:\n * - f1: log(deg(v) + 1) — scale-normalised connectivity\n * - f2: clustering_coefficient(v) — local density\n * - f3: approx_pagerank(v) — positional importance\n */\nfunction computeFeatures(\n\tgraph: ReadableGraph,\n\tnodeIds: Set<NodeId>,\n\tneighbourMap: Map<NodeId, Set<NodeId>>,\n\tpagerankScores: Map<NodeId, number>,\n): LabelledFeature[] {\n\tconst features: LabelledFeature[] = [];\n\n\tfor (const nodeId of nodeIds) {\n\t\tconst degree = graph.degree(nodeId, \"both\");\n\t\tconst neighbours = neighbourMap.get(nodeId);\n\n\t\t// Compute local clustering coefficient using neighbour map\n\t\tlet clusteringCoef = 0;\n\t\tif (neighbours !== undefined && neighbours.size >= 2) {\n\t\t\tlet triangleCount = 0;\n\t\t\tconst neighbourList = [...neighbours];\n\n\t\t\tfor (let i = 0; i < neighbourList.length; i++) {\n\t\t\t\tfor (let j = i + 1; j < neighbourList.length; j++) {\n\t\t\t\t\tconst u = neighbourList[i];\n\t\t\t\t\tconst w = neighbourList[j];\n\t\t\t\t\tif (u !== undefined && w !== undefined) {\n\t\t\t\t\t\t// Check if u and w are connected\n\t\t\t\t\t\tconst uNeighbours = neighbourMap.get(u);\n\t\t\t\t\t\tif (uNeighbours?.has(w) === true) {\n\t\t\t\t\t\t\ttriangleCount++;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst possibleTriangles = (degree * (degree - 1)) / 2;\n\t\t\tclusteringCoef = triangleCount / possibleTriangles;\n\t\t}\n\n\t\tconst pagerank = pagerankScores.get(nodeId) ?? 0;\n\n\t\tfeatures.push({\n\t\t\tnodeId,\n\t\t\tf1: Math.log(degree + 1),\n\t\t\tf2: clusteringCoef,\n\t\t\tf3: pagerank,\n\t\t});\n\t}\n\n\treturn features;\n}\n\n/**\n * Sample seed pairs from clusters.\n *\n * For each cluster, samples a mix of within-cluster and cross-cluster pairs.\n */\nfunction samplePairs(\n\tfeatures: readonly LabelledFeature[],\n\tclusterAssignments: ReadonlyMap<string, number>,\n\tnClusters: number,\n\tpairsPerCluster: number,\n\twithinClusterRatio: number,\n\trng: () => number,\n): GraspSeedPair[] {\n\tconst pairs: GraspSeedPair[] = [];\n\n\t// Group nodes by cluster\n\tconst clusterNodes = new Map<number, LabelledFeature[]>();\n\tfor (const feature of features) {\n\t\tconst cluster = clusterAssignments.get(feature.nodeId);\n\t\tif (cluster === undefined) continue;\n\n\t\tlet nodes = clusterNodes.get(cluster);\n\t\tif (nodes === undefined) {\n\t\t\tnodes = [];\n\t\t\tclusterNodes.set(cluster, nodes);\n\t\t}\n\t\tnodes.push(feature);\n\t}\n\n\tconst withinCount = Math.floor(pairsPerCluster * withinClusterRatio);\n\tconst crossCount = pairsPerCluster - withinCount;\n\n\t// Sample pairs for each cluster\n\tfor (let clusterIdx = 0; clusterIdx < nClusters; clusterIdx++) {\n\t\tconst nodes = clusterNodes.get(clusterIdx);\n\t\tif (nodes === undefined || nodes.length < 2) continue;\n\n\t\t// Within-cluster pairs\n\t\tfor (let i = 0; i < withinCount; i++) {\n\t\t\t// Sample two distinct nodes\n\t\t\tconst idx1 = Math.floor(rng() * nodes.length);\n\t\t\tlet idx2 = Math.floor(rng() * nodes.length);\n\t\t\twhile (idx1 === idx2) {\n\t\t\t\tidx2 = Math.floor(rng() * nodes.length);\n\t\t\t}\n\n\t\t\tconst source = nodes[idx1];\n\t\t\tconst target = nodes[idx2];\n\t\t\tif (source === undefined || target === undefined) continue;\n\n\t\t\tconst distance = computeFeatureDistance(source, target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: source.nodeId },\n\t\t\t\ttarget: { id: target.nodeId },\n\t\t\t\tfeatureDistance: distance,\n\t\t\t\tsameCluster: true,\n\t\t\t\tsourceCluster: clusterIdx,\n\t\t\t\ttargetCluster: clusterIdx,\n\t\t\t});\n\t\t}\n\n\t\t// Cross-cluster pairs\n\t\tfor (let i = 0; i < crossCount; i++) {\n\t\t\tconst source = nodes[Math.floor(rng() * nodes.length)];\n\t\t\tif (source === undefined) continue;\n\n\t\t\t// Pick a random other cluster\n\t\t\tconst otherClusterIdx = Math.floor(rng() * nClusters);\n\t\t\tif (otherClusterIdx === clusterIdx) continue;\n\n\t\t\tconst otherNodes = clusterNodes.get(otherClusterIdx);\n\t\t\tif (otherNodes === undefined || otherNodes.length === 0) continue;\n\n\t\t\tconst target = otherNodes[Math.floor(rng() * otherNodes.length)];\n\t\t\tif (target === undefined) continue;\n\n\t\t\tconst distance = computeFeatureDistance(source, target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: source.nodeId },\n\t\t\t\ttarget: { id: target.nodeId },\n\t\t\t\tfeatureDistance: distance,\n\t\t\t\tsameCluster: false,\n\t\t\t\tsourceCluster: clusterIdx,\n\t\t\t\ttargetCluster: otherClusterIdx,\n\t\t\t});\n\t\t}\n\t}\n\n\treturn pairs;\n}\n\n/**\n * Compute Euclidean distance between two feature vectors.\n */\nfunction computeFeatureDistance(\n\ta: FeatureVector3D,\n\tb: FeatureVector3D,\n): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * GRASP — Graph-agnostic Representative Seed pAir Sampling.\n *\n * Selects structurally representative seed pairs without domain knowledge.\n * The algorithm streams edges, samples nodes via reservoir sampling, computes\n * structural features, clusters nodes, and samples pairs within/across clusters.\n *\n * @param graph - The graph to sample seeds from\n * @param options - Configuration options\n * @returns Sampled seed pairs with structural metadata\n *\n * @example\n * ```typescript\n * const graph = new AdjacencyMapGraph();\n * // ... populate graph ...\n *\n * const result = grasp(graph, {\n *   nClusters: 50,\n *   pairsPerCluster: 20,\n *   sampleSize: 100000,\n * });\n *\n * console.log(`Sampled ${result.pairs.length} pairs from ${result.sampledNodeCount} nodes`);\n * ```\n */\nexport function grasp(\n\tgraph: ReadableGraph,\n\toptions: GraspOptions = {},\n): GraspResult {\n\tconst config = {\n\t\t...DEFAULTS,\n\t\t...options,\n\t};\n\n\tconst rng = createRNG(config.rngSeed);\n\n\t// Phase 1: Reservoir sampling\n\tconst { nodeIds, neighbourMap } = reservoirSample(\n\t\tgraph,\n\t\tconfig.sampleSize,\n\t\trng,\n\t);\n\n\t// Phase 2: Approximate PageRank on reservoir subgraph\n\tconst pagerankScores = approximatePageRank(\n\t\tnodeIds,\n\t\tneighbourMap,\n\t\tconfig.pagerankIterations,\n\t);\n\n\t// Phase 2: Compute structural features\n\tlet features = computeFeatures(graph, nodeIds, neighbourMap, pagerankScores);\n\n\t// Normalise features\n\tif (features.length > 0) {\n\t\tfeatures = zScoreNormalise(features);\n\t}\n\n\t// Phase 3: K-means clustering\n\tconst k = Math.min(config.nClusters, features.length);\n\tconst kmeansResult = miniBatchKMeans(features, {\n\t\tk,\n\t\tseed: config.rngSeed,\n\t\tmaxIterations: 100,\n\t});\n\n\t// Phase 3: Sample pairs\n\tconst pairs = samplePairs(\n\t\tfeatures,\n\t\tkmeansResult.assignments,\n\t\tkmeansResult.k,\n\t\tconfig.pairsPerCluster,\n\t\tconfig.withinClusterRatio,\n\t\trng,\n\t);\n\n\treturn {\n\t\tpairs,\n\t\tnClusters: kmeansResult.k,\n\t\tsampledNodeCount: nodeIds.size,\n\t\tfeatures,\n\t\tclusterAssignments: kmeansResult.assignments,\n\t};\n}\n","/**\n * Stratified seed selection — legacy human-defined strata.\n *\n * Requires user-provided field/type classifications. This is included for comparison\n * and for users who have domain metadata.\n *\n * @packageDocumentation\n */\n\nimport type { ReadableGraph, NodeId } from \"../graph/index\";\nimport type { Seed } from \"../schemas/index\";\n\n/**\n * Field classification function type.\n * User provides a function that returns the field name for a node.\n */\nexport type FieldClassifier = (node: {\n\tid: NodeId;\n\ttype?: string;\n}) => string | undefined;\n\n/**\n * Stratum definition for seed pair selection.\n */\nexport interface StratumDefinition {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly predicate: (\n\t\tsource: { id: NodeId; type?: string },\n\t\ttarget: { id: NodeId; type?: string },\n\t) => boolean;\n}\n\n/**\n * Stratum with sampled seed pairs.\n */\nexport interface StratumResult {\n\treadonly name: string;\n\treadonly pairs: readonly SeedPair[];\n}\n\n/**\n * A seed pair with stratum metadata.\n */\nexport interface SeedPair {\n\treadonly source: Seed;\n\treadonly target: Seed;\n\treadonly stratum: string;\n\treadonly sameField: boolean;\n}\n\n/**\n * Result of stratified seed selection.\n */\nexport interface StratifiedResult {\n\treadonly strata: readonly StratumResult[];\n\treadonly totalPairs: number;\n\treadonly errors: readonly Error[];\n}\n\n/**\n * Configuration for stratified seed selection.\n */\nexport interface StratifiedOptions {\n\t/** Function to classify nodes by field */\n\treadonly fieldClassifier: FieldClassifier;\n\t/** Number of pairs to sample per stratum */\n\treadonly pairsPerStratum?: number;\n\t/** Random seed for reproducibility */\n\treadonly rngSeed?: number;\n\t/** Custom stratum definitions */\n\treadonly customStrata?: readonly StratumDefinition[];\n}\n\n/** Default values */\nconst DEFAULTS = {\n\tpairsPerStratum: 10,\n\trngSeed: 42,\n} as const;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Stratified seed selection algorithm.\n *\n * @param graph - The graph to sample seeds from\n * @param options - Configuration options including field classifier\n * @returns Stratified selection result\n *\n * @example\n * ```typescript\n * const graph = new AdjacencyMapGraph();\n * // ... populate graph ...\n *\n * const result = stratified(graph, {\n *   fieldClassifier: (node) => node.type === 'paper' ? 'computer-science' : undefined,\n *   pairsPerStratum: 20,\n * });\n *\n * for (const stratum of result.strata) {\n *   console.log(`${stratum.name}: ${stratum.pairs.length} pairs`);\n * }\n * ```\n */\nexport function stratified(\n\tgraph: ReadableGraph,\n\toptions: StratifiedOptions,\n): StratifiedResult {\n\tconst {\n\t\tfieldClassifier,\n\t\tpairsPerStratum = DEFAULTS.pairsPerStratum,\n\t\trngSeed = DEFAULTS.rngSeed,\n\t\tcustomStrata,\n\t} = options;\n\n\tconst rng = createRNG(rngSeed);\n\tconst strataDefinitions = customStrata ?? [];\n\n\t// Collect all nodes with their field classifications\n\tconst nodesWithFields: { id: NodeId; type?: string; field?: string }[] = [];\n\n\tfor (const nodeId of graph.nodeIds()) {\n\t\tconst node = graph.getNode(nodeId);\n\t\tif (node === undefined) continue;\n\n\t\tconst field = fieldClassifier({ id: nodeId, type: node.type });\n\t\tif (field === undefined) continue;\n\n\t\tnodesWithFields.push({ id: nodeId, type: node.type, field });\n\t}\n\n\tconst errors: Error[] = [];\n\tconst strataResults: StratumResult[] = [];\n\n\t// Process each stratum\n\tfor (const stratum of strataDefinitions) {\n\t\tconst pairs: SeedPair[] = [];\n\t\tconst eligiblePairs: {\n\t\t\tsource: { id: NodeId; type?: string };\n\t\t\ttarget: { id: NodeId; type?: string };\n\t\t}[] = [];\n\n\t\t// Find all node pairs that match this stratum\n\t\tfor (let i = 0; i < nodesWithFields.length; i++) {\n\t\t\tconst source = nodesWithFields[i];\n\t\t\tif (source === undefined) continue;\n\n\t\t\tfor (let j = i + 1; j < nodesWithFields.length; j++) {\n\t\t\t\tif (j === i) continue;\n\t\t\t\tconst target = nodesWithFields[j];\n\t\t\t\tif (target === undefined) continue;\n\n\t\t\t\tif (stratum.predicate(source, target)) {\n\t\t\t\t\teligiblePairs.push({ source, target });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Sample pairs from eligible pairs\n\t\tconst numToSample = Math.min(pairsPerStratum, eligiblePairs.length);\n\t\tfor (let i = 0; i < numToSample; i++) {\n\t\t\tconst idx = Math.floor(rng() * eligiblePairs.length);\n\t\t\tconst pair = eligiblePairs[idx];\n\t\t\tif (pair === undefined) continue;\n\n\t\t\tconst sourceField = fieldClassifier(pair.source);\n\t\t\tconst targetField = fieldClassifier(pair.target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: pair.source.id },\n\t\t\t\ttarget: { id: pair.target.id },\n\t\t\t\tstratum: stratum.name,\n\t\t\t\tsameField: sourceField === targetField,\n\t\t\t});\n\t\t}\n\n\t\tstrataResults.push({\n\t\t\tname: stratum.name,\n\t\t\tpairs,\n\t\t});\n\t}\n\n\t// Collect errors for empty strata\n\tfor (const stratum of strataDefinitions) {\n\t\tconst result = strataResults.find((r) => r.name === stratum.name);\n\t\tif (result === undefined || result.pairs.length === 0) {\n\t\t\terrors.push(new Error(`No pairs found for stratum: ${stratum.name}`));\n\t\t}\n\t}\n\n\tconst totalPairs = strataResults.reduce((sum, r) => sum + r.pairs.length, 0);\n\n\treturn {\n\t\tstrata: strataResults,\n\t\ttotalPairs,\n\t\terrors,\n\t};\n}\n"],"mappings":"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"}

package/dist/seeds-UNZxqm_U.js

@@ -0,0 +1,393 @@
+import { n as normaliseFeatures, t as miniBatchKMeans } from "./kmeans-DgbsOznU.js";
+//#region src/seeds/grasp.ts
+/** Default configuration values */
+var DEFAULTS$1 = {
+	nClusters: 100,
+	pairsPerCluster: 10,
+	withinClusterRatio: .5,
+	sampleSize: 2e5,
+	rngSeed: 42,
+	pagerankIterations: 10
+};
+/**
+* Simple seeded pseudo-random number generator using mulberry32.
+*/
+function createRNG$1(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = Math.imul(state ^ state >>> 15, state | 1);
+		t = (t ^ t >>> 7) * (t | 1640531527);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Reservoir sampling (Vitter's Algorithm R) for streaming node selection.
+*
+* Maintains a uniform sample of nodes as edges are streamed, without
+* requiring the full graph in memory.
+*/
+function reservoirSample(graph, sampleSize, rng) {
+	const reservoir = [];
+	const neighbourMap = /* @__PURE__ */ new Map();
+	const inReservoir = /* @__PURE__ */ new Set();
+	let nodesSeen = 0;
+	for (const edge of graph.edges()) {
+		const source = edge.source;
+		if (!inReservoir.has(source)) {
+			nodesSeen++;
+			if (reservoir.length < sampleSize) {
+				reservoir.push(source);
+				inReservoir.add(source);
+				neighbourMap.set(source, /* @__PURE__ */ new Set());
+			} else {
+				const j = Math.floor(rng() * nodesSeen);
+				if (j < sampleSize) {
+					const oldNode = reservoir[j];
+					if (oldNode !== void 0) {
+						inReservoir.delete(oldNode);
+						neighbourMap.delete(oldNode);
+					}
+					reservoir[j] = source;
+					inReservoir.add(source);
+					neighbourMap.set(source, /* @__PURE__ */ new Set());
+				}
+			}
+		}
+		const target = edge.target;
+		if (!inReservoir.has(target)) {
+			nodesSeen++;
+			if (reservoir.length < sampleSize) {
+				reservoir.push(target);
+				inReservoir.add(target);
+				neighbourMap.set(target, /* @__PURE__ */ new Set());
+			} else {
+				const j = Math.floor(rng() * nodesSeen);
+				if (j < sampleSize) {
+					const oldNode = reservoir[j];
+					if (oldNode !== void 0) {
+						inReservoir.delete(oldNode);
+						neighbourMap.delete(oldNode);
+					}
+					reservoir[j] = target;
+					inReservoir.add(target);
+					neighbourMap.set(target, /* @__PURE__ */ new Set());
+				}
+			}
+		}
+		if (inReservoir.has(source) && inReservoir.has(target)) {
+			const sourceNeighbours = neighbourMap.get(source);
+			const targetNeighbours = neighbourMap.get(target);
+			sourceNeighbours?.add(target);
+			targetNeighbours?.add(source);
+		}
+	}
+	return {
+		nodeIds: inReservoir,
+		neighbourMap
+	};
+}
+/**
+* Compute approximate PageRank scores using power iteration on the reservoir subgraph.
+*
+* This is an approximation since it only considers the sampled nodes and their
+* connections within the reservoir, not the full graph.
+*/
+function approximatePageRank(nodeIds, neighbourMap, iterations, dampingFactor = .85) {
+	const n = nodeIds.size;
+	if (n === 0) return /* @__PURE__ */ new Map();
+	const nodeIdList = [...nodeIds];
+	const nodeIndex = new Map(nodeIdList.map((id, i) => [id, i]));
+	const scores = new Float64Array(n).fill(1 / n);
+	const newScores = new Float64Array(n);
+	for (let iter = 0; iter < iterations; iter++) {
+		newScores.fill((1 - dampingFactor) / n);
+		for (let i = 0; i < n; i++) {
+			const nodeId = nodeIdList[i];
+			if (nodeId === void 0) continue;
+			const neighbours = neighbourMap.get(nodeId);
+			if (neighbours === void 0) continue;
+			const outDegree = neighbours.size;
+			if (outDegree === 0) continue;
+			const contribution = dampingFactor * (scores[i] ?? 0) / outDegree;
+			for (const neighbour of neighbours) {
+				const neighbourIdx = nodeIndex.get(neighbour);
+				if (neighbourIdx !== void 0) newScores[neighbourIdx] = (newScores[neighbourIdx] ?? 0) + contribution;
+			}
+		}
+		for (let i = 0; i < n; i++) scores[i] = newScores[i] ?? 0;
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (let i = 0; i < n; i++) {
+		const nodeId = nodeIdList[i];
+		const score = scores[i];
+		if (nodeId !== void 0 && score !== void 0) result.set(nodeId, score);
+	}
+	return result;
+}
+/**
+* Compute structural features for sampled nodes.
+*
+* Features:
+* - f1: log(deg(v) + 1) — scale-normalised connectivity
+* - f2: clustering_coefficient(v) — local density
+* - f3: approx_pagerank(v) — positional importance
+*/
+function computeFeatures(graph, nodeIds, neighbourMap, pagerankScores) {
+	const features = [];
+	for (const nodeId of nodeIds) {
+		const degree = graph.degree(nodeId, "both");
+		const neighbours = neighbourMap.get(nodeId);
+		let clusteringCoef = 0;
+		if (neighbours !== void 0 && neighbours.size >= 2) {
+			let triangleCount = 0;
+			const neighbourList = [...neighbours];
+			for (let i = 0; i < neighbourList.length; i++) for (let j = i + 1; j < neighbourList.length; j++) {
+				const u = neighbourList[i];
+				const w = neighbourList[j];
+				if (u !== void 0 && w !== void 0) {
+					if (neighbourMap.get(u)?.has(w) === true) triangleCount++;
+				}
+			}
+			const possibleTriangles = degree * (degree - 1) / 2;
+			clusteringCoef = triangleCount / possibleTriangles;
+		}
+		const pagerank = pagerankScores.get(nodeId) ?? 0;
+		features.push({
+			nodeId,
+			f1: Math.log(degree + 1),
+			f2: clusteringCoef,
+			f3: pagerank
+		});
+	}
+	return features;
+}
+/**
+* Sample seed pairs from clusters.
+*
+* For each cluster, samples a mix of within-cluster and cross-cluster pairs.
+*/
+function samplePairs(features, clusterAssignments, nClusters, pairsPerCluster, withinClusterRatio, rng) {
+	const pairs = [];
+	const clusterNodes = /* @__PURE__ */ new Map();
+	for (const feature of features) {
+		const cluster = clusterAssignments.get(feature.nodeId);
+		if (cluster === void 0) continue;
+		let nodes = clusterNodes.get(cluster);
+		if (nodes === void 0) {
+			nodes = [];
+			clusterNodes.set(cluster, nodes);
+		}
+		nodes.push(feature);
+	}
+	const withinCount = Math.floor(pairsPerCluster * withinClusterRatio);
+	const crossCount = pairsPerCluster - withinCount;
+	for (let clusterIdx = 0; clusterIdx < nClusters; clusterIdx++) {
+		const nodes = clusterNodes.get(clusterIdx);
+		if (nodes === void 0 || nodes.length < 2) continue;
+		for (let i = 0; i < withinCount; i++) {
+			const idx1 = Math.floor(rng() * nodes.length);
+			let idx2 = Math.floor(rng() * nodes.length);
+			while (idx1 === idx2) idx2 = Math.floor(rng() * nodes.length);
+			const source = nodes[idx1];
+			const target = nodes[idx2];
+			if (source === void 0 || target === void 0) continue;
+			const distance = computeFeatureDistance(source, target);
+			pairs.push({
+				source: { id: source.nodeId },
+				target: { id: target.nodeId },
+				featureDistance: distance,
+				sameCluster: true,
+				sourceCluster: clusterIdx,
+				targetCluster: clusterIdx
+			});
+		}
+		for (let i = 0; i < crossCount; i++) {
+			const source = nodes[Math.floor(rng() * nodes.length)];
+			if (source === void 0) continue;
+			const otherClusterIdx = Math.floor(rng() * nClusters);
+			if (otherClusterIdx === clusterIdx) continue;
+			const otherNodes = clusterNodes.get(otherClusterIdx);
+			if (otherNodes === void 0 || otherNodes.length === 0) continue;
+			const target = otherNodes[Math.floor(rng() * otherNodes.length)];
+			if (target === void 0) continue;
+			const distance = computeFeatureDistance(source, target);
+			pairs.push({
+				source: { id: source.nodeId },
+				target: { id: target.nodeId },
+				featureDistance: distance,
+				sameCluster: false,
+				sourceCluster: clusterIdx,
+				targetCluster: otherClusterIdx
+			});
+		}
+	}
+	return pairs;
+}
+/**
+* Compute Euclidean distance between two feature vectors.
+*/
+function computeFeatureDistance(a, b) {
+	const d1 = a.f1 - b.f1;
+	const d2 = a.f2 - b.f2;
+	const d3 = a.f3 - b.f3;
+	return Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);
+}
+/**
+* GRASP — Graph-agnostic Representative Seed pAir Sampling.
+*
+* Selects structurally representative seed pairs without domain knowledge.
+* The algorithm streams edges, samples nodes via reservoir sampling, computes
+* structural features, clusters nodes, and samples pairs within/across clusters.
+*
+* @param graph - The graph to sample seeds from
+* @param options - Configuration options
+* @returns Sampled seed pairs with structural metadata
+*
+* @example
+* ```typescript
+* const graph = new AdjacencyMapGraph();
+* // ... populate graph ...
+*
+* const result = grasp(graph, {
+*   nClusters: 50,
+*   pairsPerCluster: 20,
+*   sampleSize: 100000,
+* });
+*
+* console.log(`Sampled ${result.pairs.length} pairs from ${result.sampledNodeCount} nodes`);
+* ```
+*/
+function grasp(graph, options = {}) {
+	const config = {
+		...DEFAULTS$1,
+		...options
+	};
+	const rng = createRNG$1(config.rngSeed);
+	const { nodeIds, neighbourMap } = reservoirSample(graph, config.sampleSize, rng);
+	let features = computeFeatures(graph, nodeIds, neighbourMap, approximatePageRank(nodeIds, neighbourMap, config.pagerankIterations));
+	if (features.length > 0) features = normaliseFeatures(features);
+	const k = Math.min(config.nClusters, features.length);
+	const kmeansResult = miniBatchKMeans(features, {
+		k,
+		seed: config.rngSeed,
+		maxIterations: 100
+	});
+	return {
+		pairs: samplePairs(features, kmeansResult.assignments, kmeansResult.k, config.pairsPerCluster, config.withinClusterRatio, rng),
+		nClusters: kmeansResult.k,
+		sampledNodeCount: nodeIds.size,
+		features,
+		clusterAssignments: kmeansResult.assignments
+	};
+}
+//#endregion
+//#region src/seeds/stratified.ts
+/** Default values */
+var DEFAULTS = {
+	pairsPerStratum: 10,
+	rngSeed: 42
+};
+/**
+* Simple seeded pseudo-random number generator using mulberry32.
+*/
+function createRNG(seed) {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = Math.imul(state ^ state >>> 15, state | 1);
+		t = (t ^ t >>> 7) * (t | 1640531527);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Stratified seed selection algorithm.
+*
+* @param graph - The graph to sample seeds from
+* @param options - Configuration options including field classifier
+* @returns Stratified selection result
+*
+* @example
+* ```typescript
+* const graph = new AdjacencyMapGraph();
+* // ... populate graph ...
+*
+* const result = stratified(graph, {
+*   fieldClassifier: (node) => node.type === 'paper' ? 'computer-science' : undefined,
+*   pairsPerStratum: 20,
+* });
+*
+* for (const stratum of result.strata) {
+*   console.log(`${stratum.name}: ${stratum.pairs.length} pairs`);
+* }
+* ```
+*/
+function stratified(graph, options) {
+	const { fieldClassifier, pairsPerStratum = DEFAULTS.pairsPerStratum, rngSeed = DEFAULTS.rngSeed, customStrata } = options;
+	const rng = createRNG(rngSeed);
+	const strataDefinitions = customStrata ?? [];
+	const nodesWithFields = [];
+	for (const nodeId of graph.nodeIds()) {
+		const node = graph.getNode(nodeId);
+		if (node === void 0) continue;
+		const field = fieldClassifier({
+			id: nodeId,
+			type: node.type
+		});
+		if (field === void 0) continue;
+		nodesWithFields.push({
+			id: nodeId,
+			type: node.type,
+			field
+		});
+	}
+	const errors = [];
+	const strataResults = [];
+	for (const stratum of strataDefinitions) {
+		const pairs = [];
+		const eligiblePairs = [];
+		for (let i = 0; i < nodesWithFields.length; i++) {
+			const source = nodesWithFields[i];
+			if (source === void 0) continue;
+			for (let j = i + 1; j < nodesWithFields.length; j++) {
+				if (j === i) continue;
+				const target = nodesWithFields[j];
+				if (target === void 0) continue;
+				if (stratum.predicate(source, target)) eligiblePairs.push({
+					source,
+					target
+				});
+			}
+		}
+		const numToSample = Math.min(pairsPerStratum, eligiblePairs.length);
+		for (let i = 0; i < numToSample; i++) {
+			const pair = eligiblePairs[Math.floor(rng() * eligiblePairs.length)];
+			if (pair === void 0) continue;
+			const sourceField = fieldClassifier(pair.source);
+			const targetField = fieldClassifier(pair.target);
+			pairs.push({
+				source: { id: pair.source.id },
+				target: { id: pair.target.id },
+				stratum: stratum.name,
+				sameField: sourceField === targetField
+			});
+		}
+		strataResults.push({
+			name: stratum.name,
+			pairs
+		});
+	}
+	for (const stratum of strataDefinitions) {
+		const result = strataResults.find((r) => r.name === stratum.name);
+		if (result === void 0 || result.pairs.length === 0) errors.push(/* @__PURE__ */ new Error(`No pairs found for stratum: ${stratum.name}`));
+	}
+	return {
+		strata: strataResults,
+		totalPairs: strataResults.reduce((sum, r) => sum + r.pairs.length, 0),
+		errors
+	};
+}
+//#endregion
+export { grasp as n, stratified as t };
+
+//# sourceMappingURL=seeds-UNZxqm_U.js.map

package/dist/seeds-UNZxqm_U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeds-UNZxqm_U.js","names":[],"sources":["../src/seeds/grasp.ts","../src/seeds/stratified.ts"],"sourcesContent":["/**\n * GRASP — Graph-agnostic Representative Seed pAir Sampling.\n *\n * Novel blind structural seed selection algorithm that selects structurally\n * representative seed pairs without requiring domain knowledge or loading\n * the full graph into memory.\n *\n * Three phases:\n * 1. Reservoir sampling — stream edges, maintain reservoir of N nodes\n * 2. Structural feature computation — log-degree, clustering coeff, approx PageRank\n * 3. Mini-batch K-means clustering, then sample pairs within and across clusters\n *\n * @packageDocumentation\n */\n\nimport type { ReadableGraph, NodeId } from \"../graph\";\nimport type { Seed } from \"../schemas/index\";\nimport {\n\tminiBatchKMeans,\n\tzScoreNormalise,\n\ttype LabelledFeature,\n\ttype FeatureVector3D,\n} from \"../utils/kmeans\";\n\n/**\n * Configuration options for GRASP seed selection.\n */\nexport interface GraspOptions {\n\t/** Number of clusters for K-means (default: 100) */\n\treadonly nClusters?: number;\n\t/** Number of pairs to sample per cluster (default: 10) */\n\treadonly pairsPerCluster?: number;\n\t/** Ratio of within-cluster pairs vs cross-cluster pairs (default: 0.5) */\n\treadonly withinClusterRatio?: number;\n\t/** Reservoir sample size (default: 200000) */\n\treadonly sampleSize?: number;\n\t/** Random seed for reproducibility (default: 42) */\n\treadonly rngSeed?: number;\n\t/** Number of PageRank iterations for feature computation (default: 10) */\n\treadonly pagerankIterations?: number;\n}\n\n/**\n * A sampled seed pair with structural metadata.\n */\nexport interface GraspSeedPair {\n\t/** Source seed */\n\treadonly source: Seed;\n\t/** Target seed */\n\treadonly target: Seed;\n\t/** Euclidean distance in feature space */\n\treadonly featureDistance: number;\n\t/** Whether both seeds are from the same cluster */\n\treadonly sameCluster: boolean;\n\t/** Cluster index of source (or -1 if unclustered) */\n\treadonly sourceCluster: number;\n\t/** Cluster index of target (or -1 if unclustered) */\n\treadonly targetCluster: number;\n}\n\n/**\n * Result of GRASP seed selection.\n */\nexport interface GraspResult {\n\t/** Sampled seed pairs */\n\treadonly pairs: readonly GraspSeedPair[];\n\t/** Number of clusters used */\n\treadonly nClusters: number;\n\t/** Total nodes sampled */\n\treadonly sampledNodeCount: number;\n\t/** Features computed for sampled nodes */\n\treadonly features: readonly LabelledFeature[];\n\t/** Cluster assignments (nodeId -> cluster index) */\n\treadonly clusterAssignments: ReadonlyMap<string, number>;\n}\n\n/** Default configuration values */\nconst DEFAULTS = {\n\tnClusters: 100,\n\tpairsPerCluster: 10,\n\twithinClusterRatio: 0.5,\n\tsampleSize: 200000,\n\trngSeed: 42,\n\tpagerankIterations: 10,\n} as const;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Reservoir sampling (Vitter's Algorithm R) for streaming node selection.\n *\n * Maintains a uniform sample of nodes as edges are streamed, without\n * requiring the full graph in memory.\n */\nfunction reservoirSample(\n\tgraph: ReadableGraph,\n\tsampleSize: number,\n\trng: () => number,\n): { nodeIds: Set<NodeId>; neighbourMap: Map<NodeId, Set<NodeId>> } {\n\tconst reservoir: NodeId[] = [];\n\tconst neighbourMap = new Map<NodeId, Set<NodeId>>();\n\tconst inReservoir = new Set<NodeId>();\n\n\t// Track total nodes seen for reservoir probability\n\tlet nodesSeen = 0;\n\n\t// Stream all edges and sample nodes\n\tfor (const edge of graph.edges()) {\n\t\t// Process source node\n\t\tconst source = edge.source;\n\t\tif (!inReservoir.has(source)) {\n\t\t\tnodesSeen++;\n\t\t\tif (reservoir.length < sampleSize) {\n\t\t\t\treservoir.push(source);\n\t\t\t\tinReservoir.add(source);\n\t\t\t\tneighbourMap.set(source, new Set<NodeId>());\n\t\t\t} else {\n\t\t\t\t// Reservoir sampling: replace with probability sampleSize/nodesSeen\n\t\t\t\tconst j = Math.floor(rng() * nodesSeen);\n\t\t\t\tif (j < sampleSize) {\n\t\t\t\t\tconst oldNode = reservoir[j];\n\t\t\t\t\tif (oldNode !== undefined) {\n\t\t\t\t\t\tinReservoir.delete(oldNode);\n\t\t\t\t\t\tneighbourMap.delete(oldNode);\n\t\t\t\t\t}\n\t\t\t\t\treservoir[j] = source;\n\t\t\t\t\tinReservoir.add(source);\n\t\t\t\t\tneighbourMap.set(source, new Set<NodeId>());\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Process target node\n\t\tconst target = edge.target;\n\t\tif (!inReservoir.has(target)) {\n\t\t\tnodesSeen++;\n\t\t\tif (reservoir.length < sampleSize) {\n\t\t\t\treservoir.push(target);\n\t\t\t\tinReservoir.add(target);\n\t\t\t\tneighbourMap.set(target, new Set<NodeId>());\n\t\t\t} else {\n\t\t\t\tconst j = Math.floor(rng() * nodesSeen);\n\t\t\t\tif (j < sampleSize) {\n\t\t\t\t\tconst oldNode = reservoir[j];\n\t\t\t\t\tif (oldNode !== undefined) {\n\t\t\t\t\t\tinReservoir.delete(oldNode);\n\t\t\t\t\t\tneighbourMap.delete(oldNode);\n\t\t\t\t\t}\n\t\t\t\t\treservoir[j] = target;\n\t\t\t\t\tinReservoir.add(target);\n\t\t\t\t\tneighbourMap.set(target, new Set<NodeId>());\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Store neighbour relationships for sampled nodes\n\t\tif (inReservoir.has(source) && inReservoir.has(target)) {\n\t\t\tconst sourceNeighbours = neighbourMap.get(source);\n\t\t\tconst targetNeighbours = neighbourMap.get(target);\n\t\t\tsourceNeighbours?.add(target);\n\t\t\ttargetNeighbours?.add(source);\n\t\t}\n\t}\n\n\treturn { nodeIds: inReservoir, neighbourMap };\n}\n\n/**\n * Compute approximate PageRank scores using power iteration on the reservoir subgraph.\n *\n * This is an approximation since it only considers the sampled nodes and their\n * connections within the reservoir, not the full graph.\n */\nfunction approximatePageRank(\n\tnodeIds: Set<NodeId>,\n\tneighbourMap: Map<NodeId, Set<NodeId>>,\n\titerations: number,\n\tdampingFactor = 0.85,\n): Map<NodeId, number> {\n\tconst n = nodeIds.size;\n\tif (n === 0) return new Map();\n\n\tconst nodeIdList = [...nodeIds];\n\tconst nodeIndex = new Map(nodeIdList.map((id, i) => [id, i] as const));\n\n\t// Initialise PageRank scores uniformly\n\tconst scores = new Float64Array(n).fill(1 / n);\n\tconst newScores = new Float64Array(n);\n\n\t// Power iteration\n\tfor (let iter = 0; iter < iterations; iter++) {\n\t\tnewScores.fill((1 - dampingFactor) / n);\n\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tconst nodeId = nodeIdList[i];\n\t\t\tif (nodeId === undefined) continue;\n\n\t\t\tconst neighbours = neighbourMap.get(nodeId);\n\t\t\tif (neighbours === undefined) continue;\n\n\t\t\tconst outDegree = neighbours.size;\n\t\t\tif (outDegree === 0) continue;\n\n\t\t\tconst contribution = (dampingFactor * (scores[i] ?? 0)) / outDegree;\n\n\t\t\tfor (const neighbour of neighbours) {\n\t\t\t\tconst neighbourIdx = nodeIndex.get(neighbour);\n\t\t\t\tif (neighbourIdx !== undefined) {\n\t\t\t\t\tnewScores[neighbourIdx] =\n\t\t\t\t\t\t(newScores[neighbourIdx] ?? 0) + contribution;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Swap buffers\n\t\tfor (let i = 0; i < n; i++) {\n\t\t\tscores[i] = newScores[i] ?? 0;\n\t\t}\n\t}\n\n\t// Build result map\n\tconst result = new Map<NodeId, number>();\n\tfor (let i = 0; i < n; i++) {\n\t\tconst nodeId = nodeIdList[i];\n\t\tconst score = scores[i];\n\t\tif (nodeId !== undefined && score !== undefined) {\n\t\t\tresult.set(nodeId, score);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Compute structural features for sampled nodes.\n *\n * Features:\n * - f1: log(deg(v) + 1) — scale-normalised connectivity\n * - f2: clustering_coefficient(v) — local density\n * - f3: approx_pagerank(v) — positional importance\n */\nfunction computeFeatures(\n\tgraph: ReadableGraph,\n\tnodeIds: Set<NodeId>,\n\tneighbourMap: Map<NodeId, Set<NodeId>>,\n\tpagerankScores: Map<NodeId, number>,\n): LabelledFeature[] {\n\tconst features: LabelledFeature[] = [];\n\n\tfor (const nodeId of nodeIds) {\n\t\tconst degree = graph.degree(nodeId, \"both\");\n\t\tconst neighbours = neighbourMap.get(nodeId);\n\n\t\t// Compute local clustering coefficient using neighbour map\n\t\tlet clusteringCoef = 0;\n\t\tif (neighbours !== undefined && neighbours.size >= 2) {\n\t\t\tlet triangleCount = 0;\n\t\t\tconst neighbourList = [...neighbours];\n\n\t\t\tfor (let i = 0; i < neighbourList.length; i++) {\n\t\t\t\tfor (let j = i + 1; j < neighbourList.length; j++) {\n\t\t\t\t\tconst u = neighbourList[i];\n\t\t\t\t\tconst w = neighbourList[j];\n\t\t\t\t\tif (u !== undefined && w !== undefined) {\n\t\t\t\t\t\t// Check if u and w are connected\n\t\t\t\t\t\tconst uNeighbours = neighbourMap.get(u);\n\t\t\t\t\t\tif (uNeighbours?.has(w) === true) {\n\t\t\t\t\t\t\ttriangleCount++;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst possibleTriangles = (degree * (degree - 1)) / 2;\n\t\t\tclusteringCoef = triangleCount / possibleTriangles;\n\t\t}\n\n\t\tconst pagerank = pagerankScores.get(nodeId) ?? 0;\n\n\t\tfeatures.push({\n\t\t\tnodeId,\n\t\t\tf1: Math.log(degree + 1),\n\t\t\tf2: clusteringCoef,\n\t\t\tf3: pagerank,\n\t\t});\n\t}\n\n\treturn features;\n}\n\n/**\n * Sample seed pairs from clusters.\n *\n * For each cluster, samples a mix of within-cluster and cross-cluster pairs.\n */\nfunction samplePairs(\n\tfeatures: readonly LabelledFeature[],\n\tclusterAssignments: ReadonlyMap<string, number>,\n\tnClusters: number,\n\tpairsPerCluster: number,\n\twithinClusterRatio: number,\n\trng: () => number,\n): GraspSeedPair[] {\n\tconst pairs: GraspSeedPair[] = [];\n\n\t// Group nodes by cluster\n\tconst clusterNodes = new Map<number, LabelledFeature[]>();\n\tfor (const feature of features) {\n\t\tconst cluster = clusterAssignments.get(feature.nodeId);\n\t\tif (cluster === undefined) continue;\n\n\t\tlet nodes = clusterNodes.get(cluster);\n\t\tif (nodes === undefined) {\n\t\t\tnodes = [];\n\t\t\tclusterNodes.set(cluster, nodes);\n\t\t}\n\t\tnodes.push(feature);\n\t}\n\n\tconst withinCount = Math.floor(pairsPerCluster * withinClusterRatio);\n\tconst crossCount = pairsPerCluster - withinCount;\n\n\t// Sample pairs for each cluster\n\tfor (let clusterIdx = 0; clusterIdx < nClusters; clusterIdx++) {\n\t\tconst nodes = clusterNodes.get(clusterIdx);\n\t\tif (nodes === undefined || nodes.length < 2) continue;\n\n\t\t// Within-cluster pairs\n\t\tfor (let i = 0; i < withinCount; i++) {\n\t\t\t// Sample two distinct nodes\n\t\t\tconst idx1 = Math.floor(rng() * nodes.length);\n\t\t\tlet idx2 = Math.floor(rng() * nodes.length);\n\t\t\twhile (idx1 === idx2) {\n\t\t\t\tidx2 = Math.floor(rng() * nodes.length);\n\t\t\t}\n\n\t\t\tconst source = nodes[idx1];\n\t\t\tconst target = nodes[idx2];\n\t\t\tif (source === undefined || target === undefined) continue;\n\n\t\t\tconst distance = computeFeatureDistance(source, target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: source.nodeId },\n\t\t\t\ttarget: { id: target.nodeId },\n\t\t\t\tfeatureDistance: distance,\n\t\t\t\tsameCluster: true,\n\t\t\t\tsourceCluster: clusterIdx,\n\t\t\t\ttargetCluster: clusterIdx,\n\t\t\t});\n\t\t}\n\n\t\t// Cross-cluster pairs\n\t\tfor (let i = 0; i < crossCount; i++) {\n\t\t\tconst source = nodes[Math.floor(rng() * nodes.length)];\n\t\t\tif (source === undefined) continue;\n\n\t\t\t// Pick a random other cluster\n\t\t\tconst otherClusterIdx = Math.floor(rng() * nClusters);\n\t\t\tif (otherClusterIdx === clusterIdx) continue;\n\n\t\t\tconst otherNodes = clusterNodes.get(otherClusterIdx);\n\t\t\tif (otherNodes === undefined || otherNodes.length === 0) continue;\n\n\t\t\tconst target = otherNodes[Math.floor(rng() * otherNodes.length)];\n\t\t\tif (target === undefined) continue;\n\n\t\t\tconst distance = computeFeatureDistance(source, target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: source.nodeId },\n\t\t\t\ttarget: { id: target.nodeId },\n\t\t\t\tfeatureDistance: distance,\n\t\t\t\tsameCluster: false,\n\t\t\t\tsourceCluster: clusterIdx,\n\t\t\t\ttargetCluster: otherClusterIdx,\n\t\t\t});\n\t\t}\n\t}\n\n\treturn pairs;\n}\n\n/**\n * Compute Euclidean distance between two feature vectors.\n */\nfunction computeFeatureDistance(\n\ta: FeatureVector3D,\n\tb: FeatureVector3D,\n): number {\n\tconst d1 = a.f1 - b.f1;\n\tconst d2 = a.f2 - b.f2;\n\tconst d3 = a.f3 - b.f3;\n\treturn Math.sqrt(d1 * d1 + d2 * d2 + d3 * d3);\n}\n\n/**\n * GRASP — Graph-agnostic Representative Seed pAir Sampling.\n *\n * Selects structurally representative seed pairs without domain knowledge.\n * The algorithm streams edges, samples nodes via reservoir sampling, computes\n * structural features, clusters nodes, and samples pairs within/across clusters.\n *\n * @param graph - The graph to sample seeds from\n * @param options - Configuration options\n * @returns Sampled seed pairs with structural metadata\n *\n * @example\n * ```typescript\n * const graph = new AdjacencyMapGraph();\n * // ... populate graph ...\n *\n * const result = grasp(graph, {\n *   nClusters: 50,\n *   pairsPerCluster: 20,\n *   sampleSize: 100000,\n * });\n *\n * console.log(`Sampled ${result.pairs.length} pairs from ${result.sampledNodeCount} nodes`);\n * ```\n */\nexport function grasp(\n\tgraph: ReadableGraph,\n\toptions: GraspOptions = {},\n): GraspResult {\n\tconst config = {\n\t\t...DEFAULTS,\n\t\t...options,\n\t};\n\n\tconst rng = createRNG(config.rngSeed);\n\n\t// Phase 1: Reservoir sampling\n\tconst { nodeIds, neighbourMap } = reservoirSample(\n\t\tgraph,\n\t\tconfig.sampleSize,\n\t\trng,\n\t);\n\n\t// Phase 2: Approximate PageRank on reservoir subgraph\n\tconst pagerankScores = approximatePageRank(\n\t\tnodeIds,\n\t\tneighbourMap,\n\t\tconfig.pagerankIterations,\n\t);\n\n\t// Phase 2: Compute structural features\n\tlet features = computeFeatures(graph, nodeIds, neighbourMap, pagerankScores);\n\n\t// Normalise features\n\tif (features.length > 0) {\n\t\tfeatures = zScoreNormalise(features);\n\t}\n\n\t// Phase 3: K-means clustering\n\tconst k = Math.min(config.nClusters, features.length);\n\tconst kmeansResult = miniBatchKMeans(features, {\n\t\tk,\n\t\tseed: config.rngSeed,\n\t\tmaxIterations: 100,\n\t});\n\n\t// Phase 3: Sample pairs\n\tconst pairs = samplePairs(\n\t\tfeatures,\n\t\tkmeansResult.assignments,\n\t\tkmeansResult.k,\n\t\tconfig.pairsPerCluster,\n\t\tconfig.withinClusterRatio,\n\t\trng,\n\t);\n\n\treturn {\n\t\tpairs,\n\t\tnClusters: kmeansResult.k,\n\t\tsampledNodeCount: nodeIds.size,\n\t\tfeatures,\n\t\tclusterAssignments: kmeansResult.assignments,\n\t};\n}\n","/**\n * Stratified seed selection — legacy human-defined strata.\n *\n * Requires user-provided field/type classifications. This is included for comparison\n * and for users who have domain metadata.\n *\n * @packageDocumentation\n */\n\nimport type { ReadableGraph, NodeId } from \"../graph/index\";\nimport type { Seed } from \"../schemas/index\";\n\n/**\n * Field classification function type.\n * User provides a function that returns the field name for a node.\n */\nexport type FieldClassifier = (node: {\n\tid: NodeId;\n\ttype?: string;\n}) => string | undefined;\n\n/**\n * Stratum definition for seed pair selection.\n */\nexport interface StratumDefinition {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly predicate: (\n\t\tsource: { id: NodeId; type?: string },\n\t\ttarget: { id: NodeId; type?: string },\n\t) => boolean;\n}\n\n/**\n * Stratum with sampled seed pairs.\n */\nexport interface StratumResult {\n\treadonly name: string;\n\treadonly pairs: readonly SeedPair[];\n}\n\n/**\n * A seed pair with stratum metadata.\n */\nexport interface SeedPair {\n\treadonly source: Seed;\n\treadonly target: Seed;\n\treadonly stratum: string;\n\treadonly sameField: boolean;\n}\n\n/**\n * Result of stratified seed selection.\n */\nexport interface StratifiedResult {\n\treadonly strata: readonly StratumResult[];\n\treadonly totalPairs: number;\n\treadonly errors: readonly Error[];\n}\n\n/**\n * Configuration for stratified seed selection.\n */\nexport interface StratifiedOptions {\n\t/** Function to classify nodes by field */\n\treadonly fieldClassifier: FieldClassifier;\n\t/** Number of pairs to sample per stratum */\n\treadonly pairsPerStratum?: number;\n\t/** Random seed for reproducibility */\n\treadonly rngSeed?: number;\n\t/** Custom stratum definitions */\n\treadonly customStrata?: readonly StratumDefinition[];\n}\n\n/** Default values */\nconst DEFAULTS = {\n\tpairsPerStratum: 10,\n\trngSeed: 42,\n} as const;\n\n/**\n * Simple seeded pseudo-random number generator using mulberry32.\n */\nfunction createRNG(seed: number): () => number {\n\tlet state = seed >>> 0;\n\treturn (): number => {\n\t\tstate = (state + 0x6d2b79f5) >>> 0;\n\t\tlet t = Math.imul(state ^ (state >>> 15), state | 1);\n\t\tt = (t ^ (t >>> 7)) * (t | 0x61c88647);\n\t\treturn ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n\t};\n}\n\n/**\n * Stratified seed selection algorithm.\n *\n * @param graph - The graph to sample seeds from\n * @param options - Configuration options including field classifier\n * @returns Stratified selection result\n *\n * @example\n * ```typescript\n * const graph = new AdjacencyMapGraph();\n * // ... populate graph ...\n *\n * const result = stratified(graph, {\n *   fieldClassifier: (node) => node.type === 'paper' ? 'computer-science' : undefined,\n *   pairsPerStratum: 20,\n * });\n *\n * for (const stratum of result.strata) {\n *   console.log(`${stratum.name}: ${stratum.pairs.length} pairs`);\n * }\n * ```\n */\nexport function stratified(\n\tgraph: ReadableGraph,\n\toptions: StratifiedOptions,\n): StratifiedResult {\n\tconst {\n\t\tfieldClassifier,\n\t\tpairsPerStratum = DEFAULTS.pairsPerStratum,\n\t\trngSeed = DEFAULTS.rngSeed,\n\t\tcustomStrata,\n\t} = options;\n\n\tconst rng = createRNG(rngSeed);\n\tconst strataDefinitions = customStrata ?? [];\n\n\t// Collect all nodes with their field classifications\n\tconst nodesWithFields: { id: NodeId; type?: string; field?: string }[] = [];\n\n\tfor (const nodeId of graph.nodeIds()) {\n\t\tconst node = graph.getNode(nodeId);\n\t\tif (node === undefined) continue;\n\n\t\tconst field = fieldClassifier({ id: nodeId, type: node.type });\n\t\tif (field === undefined) continue;\n\n\t\tnodesWithFields.push({ id: nodeId, type: node.type, field });\n\t}\n\n\tconst errors: Error[] = [];\n\tconst strataResults: StratumResult[] = [];\n\n\t// Process each stratum\n\tfor (const stratum of strataDefinitions) {\n\t\tconst pairs: SeedPair[] = [];\n\t\tconst eligiblePairs: {\n\t\t\tsource: { id: NodeId; type?: string };\n\t\t\ttarget: { id: NodeId; type?: string };\n\t\t}[] = [];\n\n\t\t// Find all node pairs that match this stratum\n\t\tfor (let i = 0; i < nodesWithFields.length; i++) {\n\t\t\tconst source = nodesWithFields[i];\n\t\t\tif (source === undefined) continue;\n\n\t\t\tfor (let j = i + 1; j < nodesWithFields.length; j++) {\n\t\t\t\tif (j === i) continue;\n\t\t\t\tconst target = nodesWithFields[j];\n\t\t\t\tif (target === undefined) continue;\n\n\t\t\t\tif (stratum.predicate(source, target)) {\n\t\t\t\t\teligiblePairs.push({ source, target });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Sample pairs from eligible pairs\n\t\tconst numToSample = Math.min(pairsPerStratum, eligiblePairs.length);\n\t\tfor (let i = 0; i < numToSample; i++) {\n\t\t\tconst idx = Math.floor(rng() * eligiblePairs.length);\n\t\t\tconst pair = eligiblePairs[idx];\n\t\t\tif (pair === undefined) continue;\n\n\t\t\tconst sourceField = fieldClassifier(pair.source);\n\t\t\tconst targetField = fieldClassifier(pair.target);\n\n\t\t\tpairs.push({\n\t\t\t\tsource: { id: pair.source.id },\n\t\t\t\ttarget: { id: pair.target.id },\n\t\t\t\tstratum: stratum.name,\n\t\t\t\tsameField: sourceField === targetField,\n\t\t\t});\n\t\t}\n\n\t\tstrataResults.push({\n\t\t\tname: stratum.name,\n\t\t\tpairs,\n\t\t});\n\t}\n\n\t// Collect errors for empty strata\n\tfor (const stratum of strataDefinitions) {\n\t\tconst result = strataResults.find((r) => r.name === stratum.name);\n\t\tif (result === undefined || result.pairs.length === 0) {\n\t\t\terrors.push(new Error(`No pairs found for stratum: ${stratum.name}`));\n\t\t}\n\t}\n\n\tconst totalPairs = strataResults.reduce((sum, r) => sum + r.pairs.length, 0);\n\n\treturn {\n\t\tstrata: strataResults,\n\t\ttotalPairs,\n\t\terrors,\n\t};\n}\n"],"mappings":"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"}

package/dist/structures/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_structures = require("../structures-CJ_S_7fs.cjs");
+exports.PriorityQueue = require_structures.PriorityQueue;

package/dist/structures/index.d.ts

@@ -0,0 +1,3 @@
+export { PriorityQueue } from './priority-queue';
+export type { PriorityEntry } from './priority-queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/structures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/structures/index.js

@@ -0,0 +1,2 @@
+import { t as PriorityQueue } from "../structures-BPfhfqNP.js";
+export { PriorityQueue };

package/dist/structures/priority-queue.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Priority queue entry containing an item and its priority.
+ */
+export interface PriorityEntry<T> {
+    item: T;
+    priority: number;
+}
+/**
+ * Min-heap priority queue implementation using an array-based binary heap.
+ * Lower priority values have higher precedence (extracted first).
+ */
+export declare class PriorityQueue<T> {
+    private heap;
+    /**
+     * Returns the number of items in the queue.
+     */
+    size(): number;
+    /**
+     * Returns true if the queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Adds an item with the given priority to the queue.
+     */
+    push(item: T, priority: number): void;
+    /**
+     * Removes and returns the highest precedence item (lowest priority value).
+     * Returns undefined if the queue is empty.
+     */
+    pop(): PriorityEntry<T> | undefined;
+    /**
+     * Returns the highest precedence item without removing it.
+     * Returns undefined if the queue is empty.
+     */
+    peek(): PriorityEntry<T> | undefined;
+    /**
+     * Rebuilds the heap from the current array state.
+     * Useful when priorities have been modified externally (e.g., phase transitions).
+     */
+    rebuild(): void;
+    /**
+     * Decreases the priority of an existing item in the queue.
+     * Returns true if the item was found and updated, false otherwise.
+     *
+     * @param item - The item to find
+     * @param newPriority - The new (lower) priority value
+     * @param equals - Function to compare items for equality
+     */
+    decreaseKey(item: T, newPriority: number, equals: (a: T, b: T) => boolean): boolean;
+    /**
+     * Restores heap property by moving element up from given index.
+     */
+    private heapifyUp;
+    /**
+     * Restores heap property by moving element down from given index.
+     */
+    private heapifyDown;
+}
+//# sourceMappingURL=priority-queue.d.ts.map

package/dist/structures/priority-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.d.ts","sourceRoot":"","sources":["../../src/structures/priority-queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,CAA0B;IAEtC;;OAEG;IACI,IAAI,IAAI,MAAM;IAIrB;;OAEG;IACI,OAAO,IAAI,OAAO;IAIzB;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM5C;;;OAGG;IACI,GAAG,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS;IAuB1C;;;OAGG;IACI,IAAI,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS;IAI3C;;;OAGG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;;OAOG;IACI,WAAW,CACjB,IAAI,EAAE,CAAC,EACP,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAC7B,OAAO;IA8BV;;OAEG;IACH,OAAO,CAAC,SAAS;IAuBjB;;OAEG;IACH,OAAO,CAAC,WAAW;CAmDnB"}

package/dist/structures/priority-queue.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=priority-queue.unit.test.d.ts.map

package/dist/structures/priority-queue.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.unit.test.d.ts","sourceRoot":"","sources":["../../src/structures/priority-queue.unit.test.ts"],"names":[],"mappings":""}