feat(traversal): add node discovery iteration tracking to novel algorithms

add nodeDiscoveryIteration tracking to entropy-guided, path-preserving,
retrospective-salience, intelligent-delayed-termination, and overlap-based
expansion algorithms. seeds recorded at iteration 0.

Author: Mearman

src/algorithms/traversal/entropy-guided-expansion.ts

@@ -83,6 +83,8 @@ export class EntropyGuidedExpansion<T> {
 	private readonly paths: Array<{ fromSeed: number; toSeed: number; nodes: string[] }> = [];
 	private readonly sampledEdges = new Set<string>();
 	private stats: ExpansionStats;
+	/** Tracks when each node was first discovered (iteration number) */
+	private readonly nodeDiscoveryIteration = new Map<string, number>();
 
 	/** Track which frontier owns each node for O(1) intersection checking */
 	private readonly nodeToFrontierIndex = new Map<string, number>();
@@ -123,6 +125,9 @@ export class EntropyGuidedExpansion<T> {
 
 			// Track which frontier owns this seed
 			this.nodeToFrontierIndex.set(seed, index);
+
+			// Seeds are discovered at iteration 0
+			this.nodeDiscoveryIteration.set(seed, 0);
 		}
 
 		this.stats = {
@@ -254,6 +259,11 @@ export class EntropyGuidedExpansion<T> {
 				activeState.visited.add(targetId);
 				activeState.parents.set(targetId, { parent: node, edge: relationshipType });
 
+				// Track first discovery iteration (only if not already discovered)
+				if (!this.nodeDiscoveryIteration.has(targetId)) {
+					this.nodeDiscoveryIteration.set(targetId, this.stats.iterations);
+				}
+
 				// Track which frontier owns this node (for O(1) intersection checking)
 				this.nodeToFrontierIndex.set(targetId, activeIndex);
 
@@ -298,6 +308,7 @@ export class EntropyGuidedExpansion<T> {
 			sampledEdges: this.sampledEdges,
 			visitedPerFrontier,
 			stats: this.stats,
+			nodeDiscoveryIteration: this.nodeDiscoveryIteration,
 		};
 	}
 

src/algorithms/traversal/intelligent-delayed-termination.ts

@@ -66,6 +66,8 @@ export class IntelligentDelayedTermination<T> {
 	private readonly paths: Array<{ fromSeed: number; toSeed: number; nodes: string[] }> = [];
 	private readonly sampledEdges = new Set<string>();
 	private stats: ExpansionStats;
+	/** Tracks when each node was first discovered (iteration number) */
+	private readonly nodeDiscoveryIteration = new Map<string, number>();
 
 	/** Track which frontier owns each node for O(1) intersection checking */
 	private readonly nodeToFrontierIndex = new Map<string, number>();
@@ -124,6 +126,9 @@ export class IntelligentDelayedTermination<T> {
 
 			// Track which frontier owns this seed
 			this.nodeToFrontierIndex.set(seed, index);
+
+			// Seeds are discovered at iteration 0
+			this.nodeDiscoveryIteration.set(seed, 0);
 		}
 
 		this.stats = {
@@ -182,6 +187,11 @@ export class IntelligentDelayedTermination<T> {
 				activeState.visited.add(targetId);
 				activeState.parents.set(targetId, { parent: node, edge: relationshipType });
 
+				// Track first discovery iteration (only if not already discovered)
+				if (!this.nodeDiscoveryIteration.has(targetId)) {
+					this.nodeDiscoveryIteration.set(targetId, this.stats.iterations);
+				}
+
 				// Track which frontier owns this node (for O(1) intersection checking)
 				this.nodeToFrontierIndex.set(targetId, activeIndex);
 
@@ -238,6 +248,7 @@ export class IntelligentDelayedTermination<T> {
 			sampledEdges: this.sampledEdges,
 			visitedPerFrontier,
 			stats: this.stats,
+			nodeDiscoveryIteration: this.nodeDiscoveryIteration,
 		};
 	}
 

src/algorithms/traversal/overlap-based/overlap-based-expansion.ts

@@ -83,6 +83,8 @@ export class OverlapBasedExpansion<T> {
 	}> = [];
 	private stats: ExpansionStats;
 	private iteration = 0;
+	/** Tracks when each node was first discovered (iteration number) */
+	private readonly nodeDiscoveryIteration = new Map<string, number>();
 
 	/** Track which frontier owns each node for O(1) overlap detection */
 	private readonly nodeToFrontierIndex = new Map<string, number>();
@@ -126,6 +128,9 @@ export class OverlapBasedExpansion<T> {
 
 			// Track which frontier owns this seed
 			this.nodeToFrontierIndex.set(seed, index);
+
+			// Seeds are discovered at iteration 0
+			this.nodeDiscoveryIteration.set(seed, 0);
 		}
 
 		this.stats = {
@@ -236,6 +241,11 @@ export class OverlapBasedExpansion<T> {
 				activeState.visited.add(targetId);
 				activeState.parents.set(targetId, { parent: node, edge: relationshipType });
 
+				// Track first discovery iteration (only if not already discovered)
+				if (!this.nodeDiscoveryIteration.has(targetId)) {
+					this.nodeDiscoveryIteration.set(targetId, this.iteration);
+				}
+
 				// Update nodeDistances for SphereIntersectionStrategy
 				if (activeState.nodeDistances) {
 					const parentDistance = activeState.nodeDistances.get(node) ?? 0;
@@ -336,6 +346,11 @@ export class OverlapBasedExpansion<T> {
 			frontier.visited.add(targetId);
 			frontier.parents.set(targetId, { parent: node, edge: relationshipType });
 
+			// Track first discovery iteration (only if not already discovered)
+			if (!this.nodeDiscoveryIteration.has(targetId)) {
+				this.nodeDiscoveryIteration.set(targetId, this.iteration);
+			}
+
 			// Update nodeDistances for SphereIntersectionStrategy
 			if (frontier.nodeDistances) {
 				const parentDistance = frontier.nodeDistances.get(node) ?? 0;
@@ -379,6 +394,7 @@ export class OverlapBasedExpansion<T> {
 				iterations: this.iteration,
 				overlapMatrix: this.overlapMatrix,
 			},
+			nodeDiscoveryIteration: this.nodeDiscoveryIteration,
 		};
 
 		// Apply between-graph strategy to refine output

src/algorithms/traversal/path-preserving-expansion.ts

@@ -96,6 +96,8 @@ export class PathPreservingExpansion<T> {
 	private readonly paths: Array<{ fromSeed: number; toSeed: number; nodes: string[] }> = [];
 	private readonly sampledEdges = new Set<string>();
 	private stats: ExpansionStats;
+	/** Tracks when each node was first discovered (iteration number) */
+	private readonly nodeDiscoveryIteration = new Map<string, number>();
 
 	/** Track which frontier owns each node for O(1) intersection checking */
 	private readonly nodeToFrontierIndex = new Map<string, number>();
@@ -138,6 +140,9 @@ export class PathPreservingExpansion<T> {
 
 			// Track which frontier owns this seed
 			this.nodeToFrontierIndex.set(seed, index);
+
+			// Seeds are discovered at iteration 0
+			this.nodeDiscoveryIteration.set(seed, 0);
 		}
 
 		this.stats = {
@@ -191,6 +196,11 @@ export class PathPreservingExpansion<T> {
 				activeState.visited.add(targetId);
 				activeState.parents.set(targetId, { parent: node, edge: relationshipType });
 
+				// Track first discovery iteration (only if not already discovered)
+				if (!this.nodeDiscoveryIteration.has(targetId)) {
+					this.nodeDiscoveryIteration.set(targetId, this.stats.iterations);
+				}
+
 				// Track which frontier owns this node (for O(1) intersection checking)
 				this.nodeToFrontierIndex.set(targetId, activeIndex);
 
@@ -240,6 +250,7 @@ export class PathPreservingExpansion<T> {
 			sampledEdges: this.sampledEdges,
 			visitedPerFrontier,
 			stats: this.stats,
+			nodeDiscoveryIteration: this.nodeDiscoveryIteration,
 		};
 	}
 

src/algorithms/traversal/retrospective-salience-expansion.ts

@@ -51,6 +51,8 @@ export class RetrospectiveSalienceExpansion<T> {
 	private readonly paths: Array<{ fromSeed: number; toSeed: number; nodes: string[] }> = [];
 	private readonly sampledEdges = new Set<string>();
 	private stats: ExpansionStats;
+	/** Tracks when each node was first discovered (iteration number) */
+	private readonly nodeDiscoveryIteration = new Map<string, number>();
 
 	/** Track which frontier owns each node for O(1) intersection checking */
 	private readonly nodeToFrontierIndex = new Map<string, number>();
@@ -97,6 +99,9 @@ export class RetrospectiveSalienceExpansion<T> {
 
 			// Track which frontier owns this seed
 			this.nodeToFrontierIndex.set(seed, index);
+
+			// Seeds are discovered at iteration 0
+			this.nodeDiscoveryIteration.set(seed, 0);
 		}
 
 		this.stats = {
@@ -149,6 +154,11 @@ export class RetrospectiveSalienceExpansion<T> {
 				activeState.visited.add(targetId);
 				activeState.parents.set(targetId, { parent: node, edge: relationshipType });
 
+				// Track first discovery iteration (only if not already discovered)
+				if (!this.nodeDiscoveryIteration.has(targetId)) {
+					this.nodeDiscoveryIteration.set(targetId, this.stats.iterations);
+				}
+
 				// Track which frontier owns this node (for O(1) intersection checking)
 				this.nodeToFrontierIndex.set(targetId, activeIndex);
 
@@ -202,6 +212,7 @@ export class RetrospectiveSalienceExpansion<T> {
 			sampledEdges: this.sampledEdges,
 			visitedPerFrontier,
 			stats: this.stats,
+			nodeDiscoveryIteration: this.nodeDiscoveryIteration,
 		};
 	}