graphbox 1.2.2 → 1.3.0

package/dist/algorithms/traversal/bidirectional-bfs.d.ts

@@ -26,6 +26,19 @@ export interface BidirectionalBFSResult {
 /**
  * Generic bidirectional breadth-first search with degree-based node prioritization.
  *
+ * **NOTE: This is an earlier design with parameterised termination.**
+ * For the parameter-free version that aligns with the thesis theoretical framework,
+ * see DegreePrioritisedExpansion (N≥1 seeds, frontier exhaustion only).
+ *
+ * **Design Relationship**:
+ * - BidirectionalBFS: Earlier design, N=2 only, has termination parameters (targetPaths, maxIterations)
+ * - DegreePrioritisedExpansion: Refined design, N≥1 with identical code path, parameter-free
+ *
+ * This implementation is suitable for production use cases where:
+ * - Predictable resource consumption is required
+ * - Finding *a* path quickly is more important than exhaustive sampling
+ * - Service-level objectives constrain iteration count
+ *
  * Searches for paths between two seed nodes by expanding frontiers from both directions.
  * Uses priority queue to process low-degree nodes first, naturally prioritizing specific
  * connections over generic ones.
@@ -52,6 +65,8 @@ export interface BidirectionalBFSResult {
  * const result = await bfs.search();
  * console.log(`Found ${result.paths.length} paths in ${result.iterations} iterations`);
  * ```
+ *
+ * @see DegreePrioritisedExpansion - Parameter-free version for N≥1 seeds
  */
 export declare class BidirectionalBFS<T> {
     private readonly expander;

package/dist/algorithms/traversal/bidirectional-bfs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bidirectional-bfs.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/bidirectional-bfs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IAEtB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAElB,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAEtB,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAEtB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,gBAAgB,CAAC,CAAC;IAM7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IARzB,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAW;gBAGP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB;IAuBlD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,sBAAsB,CAAC;IA0E/C;;;;;OAKG;YACW,cAAc;IA8B5B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAwB/B"}
+{"version":3,"file":"bidirectional-bfs.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/bidirectional-bfs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IAEtB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAElB,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAEtB,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAEtB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,gBAAgB,CAAC,CAAC;IAM7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IARzB,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAW;gBAGP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB;IAuBlD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,sBAAsB,CAAC;IA0E/C;;;;;OAKG;YACW,cAAc;IA8B5B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;CAwB/B"}

package/dist/algorithms/traversal/degree-prioritised-expansion-intersection.unit.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Regression test for frontier intersection detection bug (Jan 21 2026).
+ *
+ * BACKGROUND:
+ * Commit bec6dbf optimized intersection checking from O(F) to O(1) using
+ * nodeToFrontierIndex Map. The bug: Map was updated on every visit instead
+ * of only first visit, preventing intersection detection.
+ *
+ * This test creates a minimal graph where two frontiers MUST meet, verifying
+ * that path recording works correctly.
+ */
+export {};
+//# sourceMappingURL=degree-prioritised-expansion-intersection.unit.test.d.ts.map

package/dist/algorithms/traversal/degree-prioritised-expansion-intersection.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree-prioritised-expansion-intersection.unit.test.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/degree-prioritised-expansion-intersection.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/algorithms/traversal/degree-prioritised-expansion.d.ts

@@ -17,6 +17,12 @@ export interface DegreePrioritisedExpansionResult {
     visitedPerFrontier: Array<Set<string>>;
     /** Statistics about the expansion */
     stats: ExpansionStats;
+    /**
+     * Maps each sampled node to the iteration when it was first discovered.
+     * Used for computing coverage efficiency metrics (first-discovery iteration,
+     * budget checkpoint coverage, area-under-curve).
+     */
+    nodeDiscoveryIteration: Map<string, number>;
 }
 /**
  * Statistics collected during expansion.
@@ -34,6 +40,22 @@ export interface ExpansionStats {
 /**
  * Degree-Prioritised Bidirectional Expansion
  *
+ * **Thesis Alignment**: This is the primary implementation of the seed-bounded
+ * sampling algorithm described in Chapter 4 of the thesis. It embodies the
+ * parameter-free design with implicit termination via frontier exhaustion.
+ *
+ * **Design Relationship**:
+ * - BidirectionalBFS: Earlier design, N=2 only, has termination parameters (targetPaths, maxIterations)
+ * - DegreePrioritisedExpansion: Refined design (this file), N≥1 with identical code path, parameter-free
+ *
+ * Use this implementation when:
+ * - Representative sampling of graph structure is required
+ * - Evaluation dataset construction demands bias-free samples
+ * - N≥1 seed nodes need to be supported
+ * - Termination should be determined by graph structure, not arbitrary limits
+ *
+ * For production pathfinding with resource constraints, consider BidirectionalBFS instead.
+ *
  * A unified algorithm for representative graph sampling between N ≥ 1 seed nodes.
  * Uses node degree as priority (low degree = high priority) to explore peripheral
  * routes before hub-dominated paths.
@@ -69,6 +91,8 @@ export interface ExpansionStats {
  * console.log(`Found ${result.paths.length} paths`);
  * console.log(`Sampled ${result.sampledNodes.size} nodes`);
  * ```
+ *
+ * @see BidirectionalBFS - Parameterised version for N=2 with resource constraints
  */
 export declare class DegreePrioritisedExpansion<T> {
     private readonly expander;
@@ -77,6 +101,12 @@ export declare class DegreePrioritisedExpansion<T> {
     private readonly paths;
     private readonly sampledEdges;
     private stats;
+    /** Tracks when each node was first discovered (iteration number) */
+    private readonly nodeDiscoveryIteration;
+    /** Track which frontier owns each node for O(1) intersection checking */
+    private readonly nodeToFrontierIndex;
+    /** Track path signatures for O(1) deduplication */
+    private readonly pathSignatures;
     /**
      * Create a new degree-prioritised expansion.
      *
@@ -120,13 +150,15 @@ export declare class DegreePrioritisedExpansion<T> {
      */
     private reconstructPath;
     /**
-     * Check if an equivalent path already exists.
+     * Create a unique signature for a path to enable O(1) deduplication.
+     * Signature is bidirectional (A-B same as B-A) and includes the actual
+     * node sequence to distinguish different paths with the same length.
      * @param fromSeed
      * @param toSeed
      * @param nodes
      * @internal
      */
-    private pathExists;
+    private createPathSignature;
     /**
      * Record degree in distribution histogram.
      * @param degree

package/dist/algorithms/traversal/degree-prioritised-expansion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"degree-prioritised-expansion.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/degree-prioritised-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAEpE,kDAAkD;IAClD,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE1B,4CAA4C;IAC5C,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE1B,kDAAkD;IAClD,kBAAkB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvC,qCAAqC;IACrC,KAAK,EAAE,cAAc,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IAEtB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IAEvB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,0BAA0B,CAAC,CAAC;IAcvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAdvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,KAAK,CAAiB;IAE9B;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IA4B1C;;;;;;;OAOG;IACG,GAAG,IAAI,OAAO,CAAC,gCAAgC,CAAC;IA6EtD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAmBlC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAmCvB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}
+{"version":3,"file":"degree-prioritised-expansion.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/degree-prioritised-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAChD,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAEpE,kDAAkD;IAClD,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE1B,4CAA4C;IAC5C,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE1B,kDAAkD;IAClD,kBAAkB,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvC,qCAAqC;IACrC,KAAK,EAAE,cAAc,CAAC;IAEtB;;;;OAIG;IACH,sBAAsB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IAEtB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IAEvB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,qBAAa,0BAA0B,CAAC,CAAC;IAsBvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAtBvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,KAAK,CAAiB;IAC9B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IAEjE,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IAkC1C;;;;;;;OAOG;IACG,GAAG,IAAI,OAAO,CAAC,gCAAgC,CAAC;IA2FtD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAmBlC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IA8CvB;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/algorithms/traversal/entropy-guided-expansion.d.ts

@@ -0,0 +1,172 @@
+import { GraphExpander } from '../../interfaces/graph-expander';
+import { DegreePrioritisedExpansionResult } from './degree-prioritised-expansion';
+/**
+ * Entropy-Guided Expansion (EGE)
+ *
+ * **Thesis Alignment**: This is an experimental variant of the seed-bounded
+ * sampling algorithm that uses local neighbourhood entropy to guide expansion
+ * instead of simple degree prioritisation.
+ *
+ * **Design Motivation**:
+ * - DegreePrioritisedExpansion: Defers hubs using degree alone
+ * - EntropyGuidedExpansion: Incorporates neighbourhood diversity via entropy
+ *
+ * Use this implementation when:
+ * - Neighbourhood diversity should influence exploration order
+ * - Homogeneous neighbourhoods (low entropy) should be explored first
+ * - Heterogeneous neighbourhoods (high entropy) should be deferred
+ *
+ * **Key Design Properties**:
+ * 1. **Parameter-free termination**: No arbitrary limits on nodes, edges, or iterations.
+ *    The sole termination condition is structural: all frontiers exhausted.
+ * 2. **N-seed generalisation**: Single algorithm handles N=1 (ego-network), N=2
+ *    (bidirectional), and N≥3 (multi-frontier) with identical code path.
+ * 3. **Entropy-based prioritisation**: Priority π_EGE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+ *    where H_local(v) is Shannon entropy of neighbour type distribution.
+ * 4. **Hub deferral maintained**: log(deg + 1) term preserves degree-based ordering.
+ *
+ * **Algorithm**:
+ * ```
+ * 1. Initialize N frontiers, one per seed
+ * 2. While any frontier is non-empty:
+ *    a. Select the frontier with the lowest entropy-weighted node at its front
+ *    b. Pop that node and expand its neighbours
+ *    c. For each new neighbour, check intersection with all other frontiers
+ *    d. If intersection found, record path between the two seeds
+ * 3. Return sampled subgraph (union of all visited nodes)
+ * ```
+ *
+ * **Priority Function**:
+ * π_EGE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+ *
+ * Where:
+ * - H_local(v) = -Σ p(τ) log p(τ) (Shannon entropy of neighbour types)
+ * - p(τ) = proportion of neighbours with relationship type τ
+ * - ε = 0.001 (prevents division by zero)
+ * - deg(v) = total degree of node v
+ *
+ * **Complexity**: O(E log V) where E = edges explored, V = vertices
+ *
+ * @template T - Type of node data returned by expander
+ * @example
+ * ```typescript
+ * const expansion = new EntropyGuidedExpansion(expander, ['seedA', 'seedB']);
+ * const result = await expansion.run();
+ * console.log(`Found ${result.paths.length} paths`);
+ * console.log(`Sampled ${result.sampledNodes.size} nodes`);
+ * ```
+ *
+ * @see DegreePrioritisedExpansion - Base implementation using degree alone
+ */
+export declare class EntropyGuidedExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private stats;
+    /** Tracks when each node was first discovered (iteration number) */
+    private readonly nodeDiscoveryIteration;
+    /** Track which frontier owns each node for O(1) intersection checking */
+    private readonly nodeToFrontierIndex;
+    /** Track path signatures for O(1) deduplication */
+    private readonly pathSignatures;
+    /** Epsilon value to prevent division by zero in entropy calculation */
+    private static readonly EPSILON;
+    /**
+     * Create a new entropy-guided expansion.
+     *
+     * @param expander - Graph expander providing neighbour access
+     * @param seeds - Array of seed node IDs (N ≥ 1)
+     * @throws Error if no seeds provided
+     */
+    constructor(expander: GraphExpander<T>, seeds: readonly string[]);
+    /**
+     * Compute local entropy H_local(v) for a node based on neighbour type distribution.
+     *
+     * H_local(v) = -Σ p(τ) log₂ p(τ)
+     *
+     * Where p(τ) is the proportion of neighbours with relationship type τ.
+     *
+     * @param nodeId - Node to compute entropy for
+     * @returns Shannon entropy of neighbour type distribution
+     * @internal
+     */
+    private computeLocalEntropy;
+    /**
+     * Calculate entropy-guided priority for a node.
+     *
+     * π_EGE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+     *
+     * Lower priority = explored first (min-heap behaviour).
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value (lower = higher priority)
+     * @internal
+     */
+    private calculateEntropyPriority;
+    /**
+     * Calculate entropy-guided priority for a node (async version).
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value (lower = higher priority)
+     * @internal
+     */
+    private calculateEntropyPriorityAsync;
+    /**
+     * Run the expansion to completion.
+     *
+     * Terminates when all frontiers are exhausted (no unexpanded nodes remain).
+     * This is the ONLY termination condition—no arbitrary limits.
+     *
+     * @returns Expansion results including paths and sampled subgraph
+     */
+    run(): Promise<DegreePrioritisedExpansionResult>;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @internal
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the frontier with the lowest entropy-weighted node at its front.
+     * Returns -1 if all frontiers are empty.
+     * @internal
+     */
+    private selectLowestEntropyFrontier;
+    /**
+     * Peek at the priority of the front item without removing it.
+     * @param queue
+     * @internal
+     */
+    private peekPriority;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @internal
+     */
+    private reconstructPath;
+    /**
+     * Create a unique signature for a path to enable O(1) deduplication.
+     * Signature is bidirectional (A-B same as B-A).
+     * @param fromSeed
+     * @param toSeed
+     * @param nodes
+     * @internal
+     */
+    private createPathSignature;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @internal
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @internal
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=entropy-guided-expansion.d.ts.map

package/dist/algorithms/traversal/entropy-guided-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entropy-guided-expansion.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/entropy-guided-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,gCAAgC,EAAkB,MAAM,gCAAgC,CAAC;AAqBlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,sBAAsB,CAAC,CAAC;IAyBnC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAzBvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,KAAK,CAAiB;IAC9B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IAEjE,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAS;IAExC;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IAkC1C;;;;;;;;;;OAUG;YACW,mBAAmB;IA6BjC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;;;;;OAMG;YACW,6BAA6B;IAW3C;;;;;;;OAOG;IACG,GAAG,IAAI,OAAO,CAAC,gCAAgC,CAAC;IAuFtD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAmBnC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAmCvB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/algorithms/traversal/entropy-guided-expansion.unit.test.d.ts

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

package/dist/algorithms/traversal/entropy-guided-expansion.unit.test.d.ts.map

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

package/dist/algorithms/traversal/heterogeneity-aware-expansion.d.ts

@@ -0,0 +1,199 @@
+import { GraphExpander } from '../../interfaces/graph-expander.js';
+import { DegreePrioritisedExpansionResult } from './degree-prioritised-expansion.js';
+/**
+ * Heterogeneity-Aware Bidirectional Expansion (HABE)
+ *
+ * **Novel Contribution**: Combines entropy-guided expansion with overlap-based
+ * termination and path salience ranking to produce cross-domain paths that
+ * traverse heterogeneous graph regions.
+ *
+ * **Key Innovation**: HABE integrates three thesis components:
+ * 1. **EGE Priority**: π_HABE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+ *    - Low-entropy (homogeneous) neighborhoods expanded first
+ *    - High-entropy (heterogeneous) neighborhoods deferred
+ * 2. **Transitive Connectivity Termination**: Terminates when overlap graph is connected
+ *    - Less strict than full pairwise, enables earlier termination
+ *    - Ensures all seeds are transitively connected
+ * 3. **Path Salience Output**: Returns paths ranked by geometric-mean MI
+ *    - M(P) = exp((1/k) Σ log I(e))
+ *    - Weak-link sensitivity without length bias
+ *
+ * **Design Motivation**:
+ * In heterogeneous graphs (e.g., citation networks with multi-domain papers),
+ * standard expansion may get trapped in homogeneous regions. HABE actively
+ * defers high-entropy nodes, encouraging exploration of cross-domain connections.
+ *
+ * **Key Properties**:
+ * 1. **Cross-domain sensitivity**: Prioritizes edges connecting different domains
+ * 2. **Parameter-free termination**: Transitive connectivity, no arbitrary cutoffs
+ * 3. **N-seed generalisation**: Single algorithm handles N=1, N=2, and N≥3
+ * 4. **Entropy-hub duality**: log(deg+1) maintains hub deferral from degree-prioritised
+ *
+ * **Algorithm**:
+ * ```
+ * 1. Pre-compute local entropy H_local(v) for frontier nodes
+ * 2. Initialize N frontiers, one per seed
+ * 3. While any frontier is non-empty AND overlap graph not connected:
+ *    a. Select frontier with lowest π_HABE(v) node at front
+ *    b. Pop that node and expand its neighbours
+ *    c. For each new neighbour:
+ *       - Compute H_local asynchronously
+ *       - Check intersection with all other frontiers
+ *       - Record overlap events for termination check
+ *    d. If intersection found, record path between seeds
+ * 4. Rank discovered paths by geometric-mean MI (Path Salience)
+ * 5. Return sampled subgraph with ranked paths
+ * ```
+ *
+ * **Priority Function**:
+ * π_HABE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+ *
+ * Where:
+ * - H_local(v) = -Σ p(τ) log₂ p(τ) (Shannon entropy of neighbour types)
+ * - p(τ) = proportion of neighbours with relationship type τ
+ * - ε = 0.001 (prevents division by zero)
+ * - deg(v) = total degree of node v
+ *
+ * **Complexity**: O(E log V) where E = edges explored, V = vertices
+ *
+ * @template T - Type of node data returned by expander
+ * @example
+ * ```typescript
+ * const expansion = new HeterogeneityAwareExpansion(expander, ['seedA', 'seedB']);
+ * const result = await expansion.run();
+ * console.log(`Found ${result.paths.length} cross-domain paths`);
+ * console.log(`Sampled ${result.sampledNodes.size} nodes`);
+ * ```
+ *
+ * @see EntropyGuidedExpansion - Entropy-based priority without overlap termination
+ * @see DegreePrioritisedExpansion - Base implementation using degree alone
+ */
+export declare class HeterogeneityAwareExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private stats;
+    /** Tracks when each node was first discovered (iteration number) */
+    private readonly nodeDiscoveryIteration;
+    /** Track which frontier owns each node for O(1) intersection checking */
+    private readonly nodeToFrontierIndex;
+    /** Track path signatures for O(1) deduplication */
+    private readonly pathSignatures;
+    /** Overlap events for transitive connectivity termination */
+    private readonly overlapEvents;
+    /** Epsilon value to prevent division by zero in entropy calculation */
+    private static readonly EPSILON;
+    /** Cache of pre-computed local entropy values */
+    private readonly entropyCache;
+    /**
+     * Create a new heterogeneity-aware expansion.
+     *
+     * @param expander - Graph expander providing neighbour access
+     * @param seeds - Array of seed node IDs (N ≥ 1)
+     * @throws Error if no seeds provided
+     */
+    constructor(expander: GraphExpander<T>, seeds: readonly string[]);
+    /**
+     * Compute local entropy H_local(v) for a node based on neighbour type distribution.
+     *
+     * H_local(v) = -Σ p(τ) log₂ p(τ)
+     *
+     * Where p(τ) is the proportion of neighbours with relationship type τ.
+     *
+     * @param nodeId - Node to compute entropy for
+     * @returns Shannon entropy of neighbour type distribution
+     * @internal
+     */
+    private computeLocalEntropy;
+    /**
+     * Calculate initial priority for seed nodes (degree-only, entropy computed lazily).
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value
+     * @internal
+     */
+    private calculateInitialPriority;
+    /**
+     * Calculate HABE priority for a node (async version with entropy).
+     *
+     * π_HABE(v) = (1 / (H_local(v) + ε)) × log(deg(v) + 1)
+     *
+     * Lower priority = explored first (min-heap behaviour).
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value (lower = higher priority)
+     * @internal
+     */
+    private calculateHABEPriority;
+    /**
+     * Check if expansion should terminate based on transitive connectivity.
+     *
+     * Terminates when overlap graph is connected (all seeds transitively connected).
+     *
+     * @returns true if expansion should terminate
+     * @internal
+     */
+    private shouldTerminate;
+    /**
+     * Check if an undirected graph is connected using BFS.
+     *
+     * @param adj - Adjacency list representation of graph
+     * @param n - Number of nodes
+     * @returns true if graph is connected
+     * @internal
+     */
+    private isConnected;
+    /**
+     * Run the expansion to completion.
+     *
+     * Terminates when:
+     * - All frontiers are exhausted (no unexpanded nodes remain), OR
+     * - Overlap graph is transitively connected (all seeds connected via overlaps)
+     *
+     * @returns Expansion results including paths and sampled subgraph
+     */
+    run(): Promise<DegreePrioritisedExpansionResult>;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @internal
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the frontier with the lowest HABE-priority node at its front.
+     * Returns -1 if all frontiers are empty.
+     * @internal
+     */
+    private selectLowestPriorityFrontier;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @internal
+     */
+    private reconstructPath;
+    /**
+     * Create a unique signature for a path to enable O(1) deduplication.
+     * Signature is bidirectional (A-B same as B-A).
+     * @param fromSeed
+     * @param toSeed
+     * @param nodes
+     * @internal
+     */
+    private createPathSignature;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @internal
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @internal
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=heterogeneity-aware-expansion.d.ts.map

package/dist/algorithms/traversal/heterogeneity-aware-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heterogeneity-aware-expansion.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/heterogeneity-aware-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,KAAK,EAAE,gCAAgC,EAAkB,MAAM,mCAAmC,CAAC;AA+B1G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,2BAA2B,CAAC,CAAC;IA+BxC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IA/BvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,KAAK,CAAiB;IAC9B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IAEjE,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IAEpD,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAS;IAExC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IAmC1C;;;;;;;;;;OAUG;YACW,mBAAmB;IAqCjC;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAKhC;;;;;;;;;;OAUG;YACW,qBAAqB;IAWnC;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IA6BvB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAuBnB;;;;;;;;OAQG;IACG,GAAG,IAAI,OAAO,CAAC,gCAAgC,CAAC;IA4GtD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAmBpC;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/algorithms/traversal/heterogeneity-aware-expansion.unit.test.d.ts

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

package/dist/algorithms/traversal/heterogeneity-aware-expansion.unit.test.d.ts.map

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

package/dist/algorithms/traversal/index.d.ts

@@ -11,5 +11,19 @@ export type { DegreePrioritisedExpansionResult, ExpansionStats } from './degree-
 export { DegreePrioritisedExpansion } from './degree-prioritised-expansion';
 export type { DFSTraversalResult } from './dfs';
 export { dfs } from './dfs';
+export { EntropyGuidedExpansion } from './entropy-guided-expansion';
+export { HeterogeneityAwareExpansion } from './heterogeneity-aware-expansion';
+export type { IntelligentDelayedTerminationConfig } from './intelligent-delayed-termination';
+export { IntelligentDelayedTermination } from './intelligent-delayed-termination';
+export type { MFASFConfig } from './multi-frontier-adaptive-expansion';
+export { MultiFrontierAdaptiveExpansion } from './multi-frontier-adaptive-expansion';
+export type { PathPreservingExpansionConfig } from './path-preserving-expansion';
+export { PathPreservingExpansion } from './path-preserving-expansion';
+export type { PriorityOptions } from './priority-calculator';
+export { calculatePriority, calculatePriorityFromNeighbors, createPriorityCalculator, DEFAULT_EPSILON, DEFAULT_NODE_WEIGHT, legacyCalculatePriority, } from './priority-calculator';
 export { PriorityQueue } from './priority-queue';
+export { RetrospectiveSalienceExpansion } from './retrospective-salience-expansion';
+export { computeNodeSalienceFromRankedPaths, computeNodeSalienceScores, SaliencePrioritisedExpansion, } from './salience-prioritised-expansion';
+export type { BetweenGraphOutput, BetweenGraphStrategy, CoverageThresholdConfig, FrontierState, N1HandlingStrategy, OverlapBasedExpansionConfig, OverlapBasedExpansionResult, OverlapDetectionStrategy, OverlapEvent, OverlapMetadata, SaliencePreservingConfig, SphereIntersectionConfig, TerminationStrategy, ThresholdSharingConfig, } from './overlap-based';
+export { CommonConvergenceStrategy, CoverageThresholdStrategy, FullPairwiseStrategy, MinimalPathsStrategy, OverlapBasedExpansion, PhysicalMeetingStrategy, SaliencePreservingStrategy, SphereIntersectionStrategy, ThresholdSharingStrategy, TransitiveConnectivityStrategy, TruncatedComponentStrategy, } from './overlap-based';
 //# sourceMappingURL=index.d.ts.map

package/dist/algorithms/traversal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,gCAAgC,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACvG,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,gCAAgC,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACvG,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,YAAY,EAAE,mCAAmC,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAAE,6BAA6B,EAAE,MAAM,mCAAmC,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,YAAY,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACN,iBAAiB,EACjB,8BAA8B,EAC9B,wBAAwB,EACxB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AACpF,OAAO,EACN,kCAAkC,EAClC,yBAAyB,EACzB,4BAA4B,GAC5B,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACX,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,wBAAwB,EACxB,YAAY,EACZ,eAAe,EACf,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEN,yBAAyB,EAEzB,yBAAyB,EACzB,oBAAoB,EAEpB,oBAAoB,EAEpB,qBAAqB,EAErB,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,EAC1B,wBAAwB,EACxB,8BAA8B,EAC9B,0BAA0B,GAC1B,MAAM,iBAAiB,CAAC"}