graphwise 1.4.2 → 1.5.0

package/README.md

@@ -47,6 +47,8 @@ Three key properties:
 2. **Frontier collision detection**: when a vertex is reached by multiple frontiers, the connecting path is recorded
 3. **Implicit termination**: halts when all frontier queues are empty; no depth bound or size threshold
 
+---
+
 #### DOME: Degree-Ordered Multi-seed Expansion
 
 The default priority function uses degree-based hub deferral:
@@ -55,6 +57,8 @@ $$\pi(v) = \frac{\deg^{+}(v) + \deg^{-}(v)}{w_V(v) + \varepsilon}$$
 
 where $\deg^{+}(v)$ is weighted out-degree, $\deg^{-}(v)$ is weighted in-degree, $w_V(v)$ is node weight, and $\varepsilon > 0$ prevents division by zero.
 
+---
+
 #### Expansion Variants
 
 | Algorithm | Priority Function                                      | Phases |
@@ -73,18 +77,24 @@ where $\deg^{+}(v)$ is weighted out-degree, $\deg^{-}(v)$ is weighted in-degree,
 | **SIFT**  | MI threshold with degree fallback                      | 1      |
 | **FLUX**  | Density-adaptive strategy switching                    | 1      |
 
+---
+
 #### EDGE: Entropy-Driven Graph Expansion
 
 $$\pi_{\text{EDGE}}(v) = \frac{1}{H_{\text{local}}(v) + \varepsilon} \times \log(\deg(v) + 1)$$
 
 where $H_{\text{local}}(v) = -\sum_{\tau} p(\tau) \log p(\tau)$ is the Shannon entropy of the neighbour type distribution. Nodes bridging heterogeneous structural regimes (high entropy) are explored first.
 
+---
+
 #### PIPE: Path-potential Informed Priority Expansion
 
 $$\pi_{\text{PIPE}}(v) = \frac{\deg(v)}{1 + \mathrm{pathPotential}(v)}$$
 
 where $\mathrm{pathPotential}(v) = \lvert N(v) \cap \bigcup_{j \neq i} V_j \rvert$ counts neighbours already visited by other seed frontiers. High path potential indicates imminent path completion.
 
+---
+
 #### SAGE: Salience-Accumulation Guided Expansion
 
 $$
@@ -93,6 +103,8 @@ $$
 
 where $\text{salience}(v)$ counts discovered paths containing $v$. Salience dominates in Phase 2; degree serves as tiebreaker.
 
+---
+
 #### REACH: Retrospective Expansion with Adaptive Convergence
 
 $$
@@ -105,6 +117,8 @@ $$
 \widehat{\text{MI}}(v) = \frac{1}{\lvert \mathcal{P}\_{\text{top}} \rvert} \sum\_{p} J(N(v), N(p\_{\text{endpoint}}))
 $$
 
+---
+
 #### MAZE: Multi-frontier Adaptive Zone Expansion
 
 $$
@@ -113,30 +127,40 @@ $$
 
 Phase 1 uses PIPE's path potential until $M$ paths found. Phase 2 incorporates SAGE's salience feedback. Phase 3 evaluates diversity, path count, and salience plateau for termination.
 
+---
+
 #### TIDE: Total Interconnected Degree Expansion
 
 $$\pi_{\text{TIDE}}(v) = \deg(v) + \sum_{w \in N(v)} \deg(w)$$
 
 Nodes in sparse regions (low aggregate neighbourhood degree) are explored first. Related to EDGE but uses raw degree sums rather than entropy.
 
+---
+
 #### LACE: Local Affinity-Computed Expansion
 
 $$\pi_{\text{LACE}}(v) = 1 - \overline{\text{MI}}(v, \text{frontier})$$
 
 Prioritises nodes by average MI to already-visited frontier nodes. Related to HAE but uses MI to visited nodes rather than type entropy.
 
+---
+
 #### WARP: Weighted Adjacent Reachability Priority
 
 $$\pi_{\text{WARP}}(v) = \frac{1}{1 + \text{bridge}(v)}$$
 
 Pure cross-frontier bridge score without degree normalisation. Related to PIPE but omits the degree numerator.
 
+---
+
 #### FUSE: Fused Utility-Salience Expansion
 
 $$\pi_{\text{FUSE}}(v) = (1 - w) \cdot \deg(v) + w \cdot (1 - \overline{\text{MI}})$$
 
 Single-phase weighted blend of degree and MI. Related to SAGE but uses continuous blending rather than two-phase transition.
 
+---
+
 #### SIFT: Salience-Informed Frontier Threshold
 
 $$
@@ -145,10 +169,16 @@ $$
 
 MI-threshold-based priority with degree fallback. Related to REACH but uses a hard threshold instead of continuous MI-weighted priority.
 
+---
+
 #### FLUX: Flexible Local Utility Crossover
 
 Density-adaptive strategy switching. Selects between DOME, EDGE, and PIPE modes per-node based on local graph density and cross-frontier bridge score. Related to MAZE but adapts spatially (per-node) rather than temporally (per-phase).
 
+---
+
+---
+
 ### Path Ranking: PARSE
 
 **Path Aggregation Ranked by Salience Estimation** (PARSE) scores paths by the geometric mean of per-edge mutual information, eliminating length bias:
@@ -235,6 +265,10 @@ where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jacca
 | **Betweenness**             | Fraction of shortest paths through node             |
 | **Random**                  | Uniform random score (null baseline)                |
 
+---
+
+---
+
 ### Seed Selection: GRASP
 
 **Graph-agnostic Representative seed pAir Sampling**: selects structurally representative seed pairs from an unknown graph using reservoir sampling and structural feature clustering. Operates blind: no full graph loading, no ground-truth labels, no human-defined strata.
@@ -245,6 +279,10 @@ Three phases:
 2. **Structural features**: for each sampled node compute $\log(\deg + 1)$, clustering coefficient, approximate PageRank
 3. **Cluster and sample**: MiniBatchKMeans into $K$ groups; sample within-cluster and cross-cluster pairs
 
+---
+
+---
+
 ## Module Exports
 
 ```typescript

package/dist/__test__/fixtures/index.d.ts

@@ -7,4 +7,5 @@
 export * from './types';
 export * from './helpers';
 export * from './graphs';
+export * from './metrics';
 //# sourceMappingURL=index.d.ts.map

package/dist/__test__/fixtures/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/__test__/fixtures/metrics.d.ts

@@ -0,0 +1,86 @@
+import { NodeId, NodeData, EdgeData, ReadableGraph } from '../../graph';
+import { ExpansionResult } from '../../expansion/types';
+import { PARSEResult } from '../../ranking/parse';
+/**
+ * Fraction of visited nodes whose degree is below the 90th percentile of all
+ * sampled node degrees. A high ratio indicates the algorithm successfully
+ * defers high-degree hubs in favour of lower-degree nodes.
+ */
+export declare function hubDeferralRatio<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, result: ExpansionResult): number;
+/**
+ * Count of distinct intermediate nodes (i.e. excluding endpoints) across all
+ * discovered paths. Higher values indicate broader path diversity.
+ */
+export declare function pathDiversity(result: ExpansionResult): number;
+/**
+ * Ratio of sampled edges to sampled nodes. Reflects how densely the sampled
+ * subgraph is connected (higher = more edges per node).
+ */
+export declare function subgraphDensity(result: ExpansionResult): number;
+/**
+ * Ratio of discovered paths to total nodes visited. Measures how efficiently
+ * the expansion produced useful paths relative to exploration cost.
+ */
+export declare function coverageEfficiency(result: ExpansionResult): number;
+/**
+ * Ratio of total iterations to paths discovered. Measures how many
+ * iterations were required per path. Returns Infinity when no paths
+ * were found (expansion terminated without connecting seeds).
+ */
+export declare function firstPathLatency(result: ExpansionResult): number;
+/**
+ * Number of distinct node types present in the sampled node set.
+ * Nodes without a `type` property are counted as a single unnamed type.
+ */
+export declare function typeCoverage<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, result: ExpansionResult): number;
+/**
+ * Number of connected components that contain at least one path node,
+ * determined via union-find over the sampled edge set. Higher values
+ * indicate paths spanning structurally distant regions of the graph.
+ */
+export declare function communitySpan(result: ExpansionResult): number;
+/**
+ * Spearman rank correlation coefficient between two rankings (arrays of node
+ * IDs ordered from highest to lowest). Returns a value in [-1, 1] where 1
+ * means identical order and -1 means perfectly reversed.
+ *
+ * Only nodes present in both rankings are considered.
+ */
+export declare function spearmanRho(rankingA: readonly NodeId[], rankingB: readonly NodeId[]): number;
+/**
+ * Kendall tau rank correlation coefficient between two rankings. Returns a
+ * value in [-1, 1] where 1 means identical and -1 means fully reversed.
+ *
+ * Only nodes present in both rankings are considered.
+ */
+export declare function kendallTau(rankingA: readonly NodeId[], rankingB: readonly NodeId[]): number;
+/**
+ * Ratio of weak-link path salience to consistent-path salience. Values below
+ * 1 indicate the consistent path scores higher (expected behaviour); values
+ * above 1 indicate the weak-link path is incorrectly ranked higher.
+ *
+ * @param consistent - Mean salience of paths expected to rank highest
+ * @param weakLink   - Mean salience of paths expected to rank lower
+ */
+export declare function weakLinkSensitivity(consistent: number, weakLink: number): number;
+/**
+ * Sample variance of salience scores across all ranked paths. Returns 0 when
+ * all paths have identical scores (no discriminative power).
+ */
+export declare function scoreVariance(parseResult: PARSEResult): number;
+/**
+ * Pearson correlation between path length (number of edges) and salience
+ * score. Values near 0 indicate length-unbiased ranking; strong positive or
+ * negative values indicate length bias.
+ */
+export declare function lengthBias(parseResult: PARSEResult): number;
+/**
+ * Ratio of hub path salience to peripheral path salience. Values below 1
+ * indicate hub paths score lower (hub penalty is working); values at or above
+ * 1 indicate no penalty.
+ *
+ * @param peripheral - Mean salience of paths through low-degree nodes
+ * @param hub        - Mean salience of paths through high-degree hub nodes
+ */
+export declare function hubPenaltyStrength(peripheral: number, hub: number): number;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/__test__/fixtures/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMvD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACtE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,eAAe,GACrB,MAAM,CAaR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAa7D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAM/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAMlE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAClE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,eAAe,GACrB,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA4C7D;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CA+BR;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAsCR;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CA+B3D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK1E"}

package/dist/__test__/fixtures/metrics.unit.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for the comparison metrics module.
+ *
+ * Tests use minimal mock data to verify each metric function independently.
+ */
+export {};
+//# sourceMappingURL=metrics.unit.test.d.ts.map

package/dist/__test__/fixtures/metrics.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.unit.test.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/metrics.unit.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/expansion/dfs-priority.d.ts

@@ -0,0 +1,23 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig, PriorityContext } from './types';
+/**
+ * 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.
+ */
+export declare function dfsPriorityFn<N extends NodeData, E extends EdgeData>(_nodeId: string, context: PriorityContext<N, E>): number;
+/**
+ * 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
+ */
+export declare function dfsPriority<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=dfs-priority.d.ts.map

package/dist/expansion/dfs-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dfs-priority.d.ts","sourceRoot":"","sources":["../../src/expansion/dfs-priority.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EACf,eAAe,EACf,MAAM,SAAS,CAAC;AAGjB;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACnE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACjE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAKjB"}

package/dist/expansion/dfs-priority.unit.test.d.ts

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

package/dist/expansion/dfs-priority.unit.test.d.ts.map

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

package/dist/expansion/index.d.ts

@@ -24,4 +24,7 @@ export * from './flux';
 export * from './standard-bfs';
 export * from './frontier-balanced';
 export * from './random-priority';
+export * from './dfs-priority';
+export * from './k-hop';
+export * from './random-walk';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expansion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expansion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC"}

package/dist/expansion/k-hop.d.ts

@@ -0,0 +1,26 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for k-hop expansion.
+ */
+export interface KHopConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /**
+     * Maximum number of hops from any seed node.
+     * Defaults to 2.
+     */
+    readonly k?: number;
+}
+/**
+ * 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
+ */
+export declare function kHop<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: KHopConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=k-hop.d.ts.map

package/dist/expansion/k-hop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k-hop.d.ts","sourceRoot":"","sources":["../../src/expansion/k-hop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,UAAU,CAC1B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAC5B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,eAAe,CA4JjB"}

package/dist/expansion/k-hop.unit.test.d.ts

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

package/dist/expansion/k-hop.unit.test.d.ts.map

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

package/dist/expansion/random-walk.d.ts

@@ -0,0 +1,35 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult } from './types';
+/**
+ * Configuration for random-walk-with-restart expansion.
+ */
+export interface RandomWalkConfig {
+    /** Probability of restarting a walk from its seed node (default: 0.15). */
+    readonly restartProbability?: number;
+    /** Number of walks to perform per seed node (default: 10). */
+    readonly walks?: number;
+    /** Maximum steps per walk (default: 20). */
+    readonly walkLength?: number;
+    /** Random seed for deterministic reproducibility (default: 0). */
+    readonly seed?: number;
+}
+/**
+ * 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
+ */
+export declare function randomWalk<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: RandomWalkConfig): ExpansionResult;
+//# sourceMappingURL=random-walk.d.ts.map

package/dist/expansion/random-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-walk.d.ts","sourceRoot":"","sources":["../../src/expansion/random-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAqBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAChE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,gBAAgB,GACvB,eAAe,CAwJjB"}

package/dist/expansion/random-walk.unit.test.d.ts

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

package/dist/expansion/random-walk.unit.test.d.ts.map

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