graphbox 1.2.1 → 1.3.0

package/dist/algorithms/traversal/intelligent-delayed-termination.unit.test.d.ts

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

package/dist/algorithms/traversal/intelligent-delayed-termination.unit.test.d.ts.map

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

package/dist/algorithms/traversal/multi-frontier-adaptive-expansion.d.ts

@@ -0,0 +1,245 @@
+import { GraphExpander } from '../../interfaces/graph-expander.js';
+import { DegreePrioritisedExpansionResult } from './degree-prioritised-expansion.js';
+/**
+ * Configuration for MFASF algorithm.
+ */
+export interface MFASFConfig {
+    /**
+     * Minimum number of paths to discover before considering phase 3 termination.
+     * @default 3
+     */
+    minPaths?: number;
+    /**
+     * Diversity threshold τ for phase 3 termination.
+     * Diversity = |unique nodes in paths| / |total path nodes|
+     * @default 0.5
+     */
+    diversityThreshold?: number;
+    /**
+     * Salience feedback weight λ for phase 2 priority.
+     * Higher values give more weight to salience feedback.
+     * @default 1.0
+     */
+    salienceFeedbackWeight?: number;
+    /**
+     * Rolling window size for salience plateau detection.
+     * @default 5
+     */
+    plateauWindowSize?: number;
+    /**
+     * Threshold for salience plateau detection (relative change).
+     * If salience improves by less than this ratio, consider plateaued.
+     * @default 0.01
+     */
+    plateauThreshold?: number;
+}
+/**
+ * Multi-Frontier Adaptive Salience-Feedback (MFASF)
+ *
+ * **Novel Contribution**: Three-phase adaptive expansion that dynamically adjusts
+ * priority based on salience feedback from discovered paths, achieving higher
+ * mean path salience than static prioritization strategies.
+ *
+ * **Key Innovation**: Unlike static prioritization (degree-only, salience-only),
+ * MFASF adapts its exploration strategy based on real-time feedback from path
+ * quality. The algorithm transitions through three phases:
+ *
+ * **Phase 1: Path Potential Discovery**
+ * - Priority: π_MFASF_1(v) = deg(v) / (1 + path_potential(v))
+ * - path_potential(v) = count of v's neighbours visited by OTHER frontiers
+ * - Goal: Discover diverse connecting paths between seeds
+ * - Duration: Until M paths discovered (M = minPaths config)
+ *
+ * **Phase 2: Salience Feedback Expansion**
+ * - Priority: π_MFASF_2(v) = π_MFASF_1(v) × (1 + λ × salience_feedback(v))
+ * - salience_feedback(v) = estimated MI based on similarity to high-salience paths
+ * - Goal: Exploit discovered high-quality paths to find more
+ * - Duration: Until salience plateau detected
+ *
+ * **Phase 3: Termination**
+ * - Conditions: salience plateau reached AND diversity > τ AND |P| ≥ K
+ * - salience plateau: mean salience not improving significantly over window
+ * - diversity: ratio of unique nodes to total path nodes
+ * - Goal: Ensure sufficient quality and diversity before termination
+ *
+ * **Expected Behavior**:
+ * - Higher mean path salience than degree-prioritised expansion
+ * - Better exploration efficiency (fewer nodes per salient path)
+ * - Adaptive exploration balances exploitation and exploration
+ *
+ * **Complexity**:
+ * - Time: O(E log V + P × D) where E = edges, V = vertices, P = paths, D = avg degree
+ * - Space: O(V + E + P × K) where K = avg path length
+ *
+ * @template T - Node data type
+ */
+export declare class MultiFrontierAdaptiveExpansion<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;
+    /** Current phase (1, 2, or 3) */
+    private currentPhase;
+    /** Salience feedback scores for nodes */
+    private readonly salienceFeedback;
+    /** Rolling window of mean salience values for plateau detection */
+    private readonly salienceHistory;
+    /** Cache of neighbor sets for path potential computation */
+    private readonly neighborCache;
+    /** Configuration with defaults applied */
+    private readonly config;
+    /**
+     * Create a new multi-frontier adaptive expansion.
+     *
+     * @param expander - Graph expander providing neighbour access
+     * @param seeds - Array of seed node IDs (N ≥ 1)
+     * @param config - Optional configuration overrides
+     * @throws Error if no seeds provided
+     */
+    constructor(expander: GraphExpander<T>, seeds: readonly string[], config?: MFASFConfig);
+    /**
+     * Calculate Phase 1 priority: π_MFASF_1(v) = deg(v) / (1 + path_potential(v))
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value (lower = higher priority)
+     * @internal
+     */
+    private calculatePhase1Priority;
+    /**
+     * Calculate Phase 2 priority: π_MFASF_2(v) = π_MFASF_1(v) × (1 + λ × salience_feedback(v))
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value (lower = higher priority)
+     * @internal
+     */
+    private calculatePhase2Priority;
+    /**
+     * Calculate priority based on current phase.
+     *
+     * @param nodeId - Node to calculate priority for
+     * @returns Priority value
+     * @internal
+     */
+    private calculateCurrentPriority;
+    /**
+     * Compute path potential for a node: count of neighbours visited by OTHER frontiers.
+     *
+     * @param nodeId - Node to compute potential for
+     * @returns Path potential count
+     * @internal
+     */
+    private computePathPotential;
+    /**
+     * Update salience feedback based on newly discovered path.
+     *
+     * For each node, computes similarity to path nodes and updates feedback score.
+     *
+     * @param pathNodes - Nodes in the discovered path
+     * @param pathSalience - Estimated salience of the path
+     * @internal
+     */
+    private updateSalienceFeedback;
+    /**
+     * Get neighbours for a node, caching for efficiency.
+     *
+     * @param nodeId - Node to get neighbours for
+     * @returns Set of neighbour node IDs
+     * @internal
+     */
+    private getOrCacheNeighbors;
+    /**
+     * Estimate salience for a path based on node degrees.
+     *
+     * Uses degree-based heuristic: paths through lower-degree nodes are typically
+     * more salient (higher MI) because they represent more specific connections.
+     *
+     * @param pathNodes - Nodes in the path
+     * @returns Estimated salience in [0, 1]
+     * @internal
+     */
+    private estimatePathSalience;
+    /**
+     * Check if salience has plateaued (not improving significantly).
+     *
+     * @returns true if plateau detected
+     * @internal
+     */
+    private isSaliencePlateaued;
+    /**
+     * Compute path diversity: ratio of unique nodes to total path nodes.
+     *
+     * @returns Diversity ratio in [0, 1]
+     * @internal
+     */
+    private computePathDiversity;
+    /**
+     * Check phase transition and termination conditions.
+     *
+     * @returns true if expansion should terminate
+     * @internal
+     */
+    private checkPhaseTransition;
+    /**
+     * Rebuild all frontier priorities after phase transition.
+     *
+     * @internal
+     */
+    private rebuildFrontierPriorities;
+    /**
+     * Run the expansion to completion.
+     *
+     * Transitions through three phases and terminates when phase 3 conditions met
+     * or all frontiers are exhausted.
+     *
+     * @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-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.
+     * @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=multi-frontier-adaptive-expansion.d.ts.map

package/dist/algorithms/traversal/multi-frontier-adaptive-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-frontier-adaptive-expansion.d.ts","sourceRoot":"","sources":["../../../src/algorithms/traversal/multi-frontier-adaptive-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,KAAK,EAAE,gCAAgC,EAAkB,MAAM,mCAAmC,CAAC;AAqB1G;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,8BAA8B,CAAC,CAAC;IAsC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAtCvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuF;IAC7G,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,iCAAiC;IACjC,OAAO,CAAC,YAAY,CAAgB;IAEpC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgB;IAEhD,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAE/C;;;;;;;OAOG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACzC,MAAM,GAAE,WAAgB;IA2CzB;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAQ/B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAQhC;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAwB5B;;;;;;;;OAQG;YACW,sBAAsB;IA8BpC;;;;;;OAMG;YACW,mBAAmB;IAajC;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAsBjC;;;;;;;OAOG;IACG,GAAG,IAAI,OAAO,CAAC,gCAAgC,CAAC;IAuHtD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IAkBpC;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/algorithms/traversal/multi-frontier-adaptive-expansion.unit.test.d.ts

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

package/dist/algorithms/traversal/multi-frontier-adaptive-expansion.unit.test.d.ts.map

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

package/dist/algorithms/traversal/overlap-based/frontier-state.d.ts

@@ -0,0 +1,25 @@
+import { PriorityQueue } from '../priority-queue';
+/**
+ * State of a single frontier during expansion.
+ *
+ * This type is shared across the overlap-based expansion system
+ * for use in strategy interfaces.
+ *
+ * @template T - Type of priority queue items (node IDs as strings)
+ */
+export interface FrontierState {
+    /** Index of this frontier (corresponds to seed position) */
+    index: number;
+    /** Priority queue of nodes to expand */
+    frontier: PriorityQueue<string>;
+    /** Set of nodes visited by this frontier */
+    visited: Set<string>;
+    /** Parent pointers for path reconstruction */
+    parents: Map<string, {
+        parent: string;
+        edge: string;
+    }>;
+    /** Optional: Map of node ID to distance from seed (used by SphereIntersectionStrategy) */
+    nodeDistances?: Map<string, number>;
+}
+//# sourceMappingURL=frontier-state.d.ts.map

package/dist/algorithms/traversal/overlap-based/frontier-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontier-state.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/traversal/overlap-based/frontier-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IAEd,wCAAwC;IACxC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhC,4CAA4C;IAC5C,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAErB,8CAA8C;IAC9C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEvD,0FAA0F;IAC1F,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC"}

package/dist/algorithms/traversal/overlap-based/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Overlap-Based Expansion Algorithm Family
+ *
+ * A modular implementation of overlap-based termination for N-seed graph traversal.
+ * This system enables efficient sampling of the "between-graph" (region connecting N seeds)
+ * while preserving sufficient structure for Path Salience ranking.
+ *
+ * ## Architecture
+ *
+ * The system uses a strategy pattern with 4 independent dimensions:
+ *
+ * 1. **Overlap Detection** (3 variants): How to detect when seeds' regions meet
+ *    - PhysicalMeeting: O(1) physical node sharing
+ *    - ThresholdSharing: Jaccard similarity threshold
+ *    - SphereIntersection: Geometric radius-based detection
+ *
+ * 2. **N=1 Handling** (1 variant): Single-seed termination
+ *    - CoverageThreshold: Terminate when X% of graph visited
+ *
+ * 3. **Termination** (3 variants): When overall algorithm terminates (N≥2)
+ *    - FullPairwise: All C(N,2) seed pairs must overlap
+ *    - TransitiveConnectivity: Overlap graph must be connected
+ *    - CommonConvergence: All seeds share a common node
+ *
+ * 4. **Between-Graph** (3 variants): What subgraph to output
+ *    - MinimalPaths: Only nodes/edges in discovered paths
+ *    - TruncatedComponent: Connected component containing overlaps
+ *    - SaliencePreserving: MI-based node ranking
+ *
+ * ## Total Variants
+ *
+ * 3 × 1 × 3 × 3 = 27 algorithm variants
+ *
+ * @example
+ * ```typescript
+ * import { OverlapBasedExpansion, PhysicalMeetingStrategy, FullPairwiseStrategy } from './overlap-based';
+ *
+ * const expansion = new OverlapBasedExpansion(expander, ['seedA', 'seedB'], {
+ *   overlapDetection: new PhysicalMeetingStrategy(),
+ *   termination: new FullPairwiseStrategy(),
+ *   n1Handling: new CoverageThresholdStrategy(),
+ *   betweenGraph: new MinimalPathsStrategy(),
+ * });
+ *
+ * const result = await expansion.run();
+ * ```
+ */
+export type { FrontierState } from './frontier-state.js';
+export type { OverlapBasedExpansionConfig } from './overlap-based-expansion.js';
+export { OverlapBasedExpansion } from './overlap-based-expansion.js';
+export type { ExpansionStats, OverlapBasedExpansionResult, OverlapEvent, OverlapMetadata, } from './overlap-result.js';
+export type { OverlapDetectionStrategy } from './strategies/overlap-detection/overlap-detection-strategy.js';
+export { PhysicalMeetingStrategy } from './strategies/overlap-detection/physical-meeting.strategy.js';
+export type { SphereIntersectionConfig } from './strategies/overlap-detection/sphere-intersection.strategy.js';
+export { SphereIntersectionStrategy } from './strategies/overlap-detection/sphere-intersection.strategy.js';
+export type { ThresholdSharingConfig } from './strategies/overlap-detection/threshold-sharing.strategy.js';
+export { ThresholdSharingStrategy } from './strategies/overlap-detection/threshold-sharing.strategy.js';
+export type { CoverageThresholdConfig } from './strategies/n1-handling/coverage-threshold.strategy.js';
+export { CoverageThresholdStrategy } from './strategies/n1-handling/coverage-threshold.strategy.js';
+export type { N1HandlingStrategy } from './strategies/n1-handling/n1-handling-strategy.js';
+export { CommonConvergenceStrategy } from './strategies/termination/common-convergence.strategy.js';
+export { FullPairwiseStrategy } from './strategies/termination/full-pairwise.strategy.js';
+export type { TerminationStrategy } from './strategies/termination/termination-strategy.js';
+export { TransitiveConnectivityStrategy } from './strategies/termination/transitive-connectivity.strategy.js';
+export type { BetweenGraphStrategy } from './strategies/between-graph/between-graph-strategy.js';
+export type { BetweenGraphOutput } from './strategies/between-graph/between-graph-strategy.js';
+export { MinimalPathsStrategy } from './strategies/between-graph/minimal-paths.strategy.js';
+export type { SaliencePreservingConfig } from './strategies/between-graph/salience-preserving.strategy.js';
+export { SaliencePreservingStrategy } from './strategies/between-graph/salience-preserving.strategy.js';
+export { TruncatedComponentStrategy } from './strategies/between-graph/truncated-component.strategy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/algorithms/traversal/overlap-based/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/traversal/overlap-based/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,YAAY,EACX,cAAc,EACd,2BAA2B,EAC3B,YAAY,EACZ,eAAe,GACf,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAC7G,OAAO,EAAE,uBAAuB,EAAE,MAAM,6DAA6D,CAAC;AACtG,YAAY,EAAE,wBAAwB,EAAE,MAAM,gEAAgE,CAAC;AAC/G,OAAO,EAAE,0BAA0B,EAAE,MAAM,gEAAgE,CAAC;AAC5G,YAAY,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAC;AAC3G,OAAO,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAGxG,YAAY,EAAE,uBAAuB,EAAE,MAAM,yDAAyD,CAAC;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAC;AACpG,YAAY,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAG3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAC;AAC1F,YAAY,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAC5F,OAAO,EAAE,8BAA8B,EAAE,MAAM,8DAA8D,CAAC;AAG9G,YAAY,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAC;AACjG,YAAY,EAAE,kBAAkB,EAAE,MAAM,sDAAsD,CAAC;AAC/F,OAAO,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAC;AAC5F,YAAY,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAC;AAC3G,OAAO,EAAE,0BAA0B,EAAE,MAAM,4DAA4D,CAAC;AACxG,OAAO,EAAE,0BAA0B,EAAE,MAAM,4DAA4D,CAAC"}

package/dist/algorithms/traversal/overlap-based/overlap-based-expansion.d.ts

@@ -0,0 +1,182 @@
+import { GraphExpander } from '../../../interfaces/graph-expander';
+import { OverlapBasedExpansionResult } from './overlap-result.js';
+import { BetweenGraphStrategy } from './strategies/between-graph/between-graph-strategy.js';
+import { N1HandlingStrategy } from './strategies/n1-handling/n1-handling-strategy.js';
+import { OverlapDetectionStrategy } from './strategies/overlap-detection/overlap-detection-strategy.js';
+import { TerminationStrategy } from './strategies/termination/termination-strategy.js';
+/**
+ * Configuration for OverlapBasedExpansion.
+ */
+export interface OverlapBasedExpansionConfig {
+    /**
+     * Strategy for detecting overlap between seed search regions.
+     */
+    overlapDetection: OverlapDetectionStrategy;
+    /**
+     * Strategy for determining when expansion should terminate.
+     */
+    termination: TerminationStrategy;
+    /**
+     * Strategy for handling N=1 (single seed) scenario.
+     */
+    n1Handling: N1HandlingStrategy;
+    /**
+     * Strategy for extracting the between-graph subgraph.
+     */
+    betweenGraph: BetweenGraphStrategy;
+    /**
+     * Maximum iterations before forced termination (safety limit).
+     * Default: Infinity (no limit unless strategy terminates).
+     */
+    maxIterations?: number;
+    /**
+     * Total nodes in graph (for N=1 coverage calculation).
+     * Optional - only used if n1Handling strategy requires it.
+     */
+    totalNodes?: number;
+}
+/**
+ * Overlap-Based Expansion
+ *
+ * **Thesis Alignment**: Extends the seed-bounded sampling concept with overlap-based
+ * termination instead of frontier exhaustion. This enables efficient sampling of the
+ * "between-graph" (region connecting N seeds) while preserving sufficient structure
+ * for Path Salience ranking.
+ *
+ * **Key Design Properties**:
+ * 1. **Overlap-based termination**: Stops when seed search regions sufficiently overlap
+ * 2. **Strategy pattern architecture**: Modular dimensions for experimental comparison
+ * 3. **N-seed generalisation**: Handles N=1 (ego-network), N=2 (bidirectional), N≥3
+ * 4. **Degree prioritisation**: Expands globally lowest-degree node across all frontiers
+ *
+ * **Algorithm**:
+ * ```
+ * 1. Initialize N frontiers, one per seed
+ * 2. While termination condition not met:
+ *    a. Select frontier with lowest-degree node at front
+ *    b. Pop and expand neighbors
+ *    c. Detect overlaps using strategy
+ *    d. Check termination condition
+ * 3. Extract between-graph subgraph using strategy
+ * ```
+ *
+ * @template T - Type of node data returned by expander
+ */
+export declare class OverlapBasedExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly config;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private readonly overlapEvents;
+    private stats;
+    private iteration;
+    /** Tracks when each node was first discovered (iteration number) */
+    private readonly nodeDiscoveryIteration;
+    /** Track which frontier owns each node for O(1) overlap detection */
+    private readonly nodeToFrontierIndex;
+    /** Track path signatures for O(1) deduplication */
+    private readonly pathSignatures;
+    /** Overlap matrix: "0-1" → Set of meeting nodes */
+    private readonly overlapMatrix;
+    /**
+     * Create a new overlap-based expansion.
+     *
+     * @param expander - Graph expander providing neighbour access
+     * @param seeds - Array of seed node IDs (N ≥ 1)
+     * @param config - Strategy configuration
+     * @throws Error if no seeds provided
+     */
+    constructor(expander: GraphExpander<T>, seeds: readonly string[], config: OverlapBasedExpansionConfig);
+    /**
+     * Run the expansion to termination.
+     *
+     * @returns Expansion results including between-graph subgraph
+     */
+    run(): Promise<OverlapBasedExpansionResult>;
+    /**
+     * Run expansion for N=1 (single seed) scenario.
+     *
+     * Uses n1Handling strategy to determine when to terminate.
+     *
+     * @private
+     */
+    private runN1;
+    /**
+     * Run expansion for N≥2 scenario with overlap detection.
+     *
+     * @private
+     */
+    private runNPlus;
+    /**
+     * Expand a single node (used in N=1 case).
+     *
+     * @param node - Node to expand
+     * @param frontier - Frontier state
+     * @param frontierIndex - Index of the frontier
+     * @private
+     */
+    private expandNode;
+    /**
+     * Build the final result with between-graph subgraph extraction.
+     *
+     * @param terminationReason - Reason for termination
+     * @private
+     */
+    private buildResult;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @private
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the frontier with the lowest-degree node at its front.
+     * Returns -1 if all frontiers are empty.
+     * @private
+     */
+    private selectLowestDegreeFrontier;
+    /**
+     * Peek at the priority of the front item without removing it.
+     * @param queue
+     * @private
+     */
+    private peekPriority;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @private
+     */
+    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
+     * @private
+     */
+    private createPathSignature;
+    /**
+     * Get matrix key for overlap tracking (always sorted).
+     * @param a
+     * @param b
+     * @private
+     */
+    private getMatrixKey;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @private
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @private
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=overlap-based-expansion.d.ts.map

package/dist/algorithms/traversal/overlap-based/overlap-based-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap-based-expansion.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/traversal/overlap-based/overlap-based-expansion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGnE,OAAO,KAAK,EAAiB,2BAA2B,EAAmB,MAAM,qBAAqB,CAAC;AACvG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAC;AACjG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAC3F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAC7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,gBAAgB,EAAE,wBAAwB,CAAC;IAE3C;;OAEG;IACH,WAAW,EAAE,mBAAmB,CAAC;IAEjC;;OAEG;IACH,UAAU,EAAE,kBAAkB,CAAC;IAE/B;;OAEG;IACH,YAAY,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,qBAAqB,CAAC,CAAC;IAiClC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlCxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAKtB;IACR,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,SAAS,CAAK;IACtB,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IAEjE,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE;;;;;;;OAOG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,2BAA2B;IAmCrD;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,2BAA2B,CAAC;IAUjD;;;;;;OAMG;YACW,KAAK;IA4BnB;;;;OAIG;YACW,QAAQ;IA4HtB;;;;;;;OAOG;YACW,UAAU;IAoCxB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAuCnB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAmCvB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/algorithms/traversal/overlap-based/overlap-result.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Result from overlap-based expansion.
+ *
+ * Extends the base DegreePrioritisedExpansionResult with overlap-specific metadata.
+ */
+export interface OverlapBasedExpansionResult {
+    /** Discovered paths (only when N ≥ 2 seeds) */
+    paths: Array<{
+        fromSeed: number;
+        toSeed: number;
+        nodes: string[];
+    }>;
+    /** Union of all nodes visited by all frontiers */
+    sampledNodes: Set<string>;
+    /** Edges traversed during expansion */
+    sampledEdges: Set<string>;
+    /** Per-frontier visited sets (for diagnostics) */
+    visitedPerFrontier: Array<Set<string>>;
+    /** Statistics about the expansion */
+    stats: ExpansionStats;
+    /** Overlap-specific metadata */
+    overlapMetadata: OverlapMetadata;
+    /**
+     * 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 (from base DegreePrioritisedExpansionResult).
+ */
+export interface ExpansionStats {
+    /** Total nodes expanded (popped from frontiers) */
+    nodesExpanded: number;
+    /** Total edges traversed */
+    edgesTraversed: number;
+    /** Iterations (single node expansions) performed */
+    iterations: number;
+    /** Breakdown of nodes by degree ranges */
+    degreeDistribution: Map<string, number>;
+}
+/**
+ * Metadata about overlap events during expansion.
+ */
+export interface OverlapMetadata {
+    /**
+     * Termination reason - why the algorithm stopped.
+     */
+    terminationReason: "overlap-satisfied" | "n1-coverage" | "max-iterations" | "exhaustion";
+    /**
+     * All overlap events recorded during expansion.
+     */
+    overlapEvents: OverlapEvent[];
+    /**
+     * Iteration count at termination.
+     */
+    iterations: number;
+    /**
+     * Overlap matrix showing which frontiers overlapped.
+     * Key format: "0-1" → Set of meeting nodes between frontier 0 and 1.
+     */
+    overlapMatrix: Map<string, Set<string>>;
+    /**
+     * Coverage percentage (for N=1 case or when total graph size known).
+     */
+    coverage?: number;
+}
+/**
+ * Overlap event recorded during expansion.
+ */
+export interface OverlapEvent {
+    /** Iteration when overlap occurred */
+    readonly iteration: number;
+    /** Index of first frontier involved in overlap */
+    readonly frontierA: number;
+    /** Index of second frontier involved in overlap */
+    readonly frontierB: number;
+    /** Node where frontiers met */
+    readonly meetingNode: string;
+}
+//# sourceMappingURL=overlap-result.d.ts.map

package/dist/algorithms/traversal/overlap-based/overlap-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap-result.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/traversal/overlap-based/overlap-result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC3C,+CAA+C;IAC/C,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,uCAAuC;IACvC,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,gCAAgC;IAChC,eAAe,EAAE,eAAe,CAAC;IAEjC;;;;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;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,iBAAiB,EAAE,mBAAmB,GAAG,aAAa,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAEzF;;OAEG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;IAE9B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B"}