graphbox 1.2.1 → 1.3.0

package/dist/experiments/evaluation/__tests__/harness/fixtures.d.ts

@@ -0,0 +1,45 @@
+import { GraphFixture } from './types';
+/**
+ * Star graph: 1 hub + 50 spokes.
+ *
+ * Worst case for node explosion - expanding the hub immediately exposes all nodes.
+ * DP should defer hub expansion; BFS/FB expand hub immediately.
+ */
+export declare const starGraphFixture: GraphFixture;
+/**
+ * Hub-spoke graph: 4 interconnected hubs with 15 leaves each.
+ *
+ * Tests degree prioritisation on multi-hub topology.
+ * DP should expand leaves before hubs; baselines converge through hubs.
+ */
+export declare const hubSpokeFixture: GraphFixture;
+/**
+ * Scale-free graph with preferential attachment.
+ *
+ * Simulates real-world citation networks with power-law degree distribution.
+ * High-degree nodes emerge naturally; DP should avoid converging through them.
+ */
+export declare const scaleFreeFixture: GraphFixture;
+/**
+ * Grid graph (lattice) with uniform degree.
+ *
+ * Baseline for comparison - all algorithms should behave similarly
+ * since there are no hubs to prioritize or avoid.
+ */
+export declare const gridFixture: GraphFixture;
+/**
+ * Double-star graph: two hubs connected, each with spokes.
+ *
+ * Tests pathfinding when optimal path MUST go through hubs.
+ * Both algorithms will find the path, but DP explores more spokes first.
+ */
+export declare const doubleStarFixture: GraphFixture;
+/**
+ * All fixtures exported as a map.
+ */
+export declare const fixtures: Record<string, GraphFixture>;
+/**
+ * Get all fixtures as an array.
+ */
+export declare const allFixtures: () => GraphFixture[];
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/experiments/evaluation/__tests__/harness/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../../../src/experiments/evaluation/__tests__/harness/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAkB9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,YA4B7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAuD9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,YA8BzB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAuB/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAMjD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,QAAO,YAAY,EAA6B,CAAC"}

package/dist/experiments/evaluation/__tests__/harness/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Algorithm evaluation harness.
+ *
+ * Provides a structured framework for comparing graph traversal algorithms
+ * based on behaviour rather than raw performance.
+ *
+ * Key principles:
+ * - Correctness: Do algorithms find valid paths?
+ * - Exploration efficiency: How many nodes/edges are expanded?
+ * - Search behaviour: How does traversal order differ?
+ * - Diversity: How varied are the discovered paths?
+ */
+export * from './evaluator';
+export * from './fixtures';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/experiments/evaluation/__tests__/harness/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/experiments/evaluation/__tests__/harness/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/dist/experiments/evaluation/__tests__/harness/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Unified metrics types for algorithm evaluation harness
+ *
+ * Based on the principle that algorithm comparison should focus on:
+ * - Correctness: Does the algorithm find valid paths?
+ * - Exploration efficiency: How many nodes/edges expanded?
+ * - Search behaviour: How does traversal order differ?
+ * - Diversity: How varied are the discovered paths?
+ */
+/**
+ * Normalized statistics returned by all expansion algorithms.
+ *
+ * All algorithms (DP, BFS, Frontier-Balanced, Random) should return
+ * compatible metrics for fair comparison.
+ */
+export interface ExpansionMetrics {
+    /** Algorithm name */
+    algorithm: string;
+    /** Graph identifier */
+    graph: string;
+    /** Number of seed nodes (N) */
+    numSeeds: number;
+    /** Total nodes expanded (popped from frontiers) */
+    nodesExpanded: number;
+    /** Total edges traversed */
+    edgesTraversed: number;
+    /** Iterations (single node expansions) performed */
+    iterations: number;
+    /** Number of unique nodes in the sampled subgraph */
+    sampledNodes: number;
+    /** Number of unique edges in the sampled subgraph */
+    sampledEdges: number;
+    /** Number of paths found (N >= 2 only) */
+    pathsFound: number;
+    /** Degree distribution of expanded nodes */
+    degreeDistribution: Record<string, number>;
+    /** Hub-specific metrics (if applicable) */
+    hubMetrics?: {
+        /** Number of hub nodes expanded */
+        hubsExpanded: number;
+        /** Total nodes expanded */
+        totalExpanded: number;
+        /** Percentage of paths that traverse hub nodes */
+        hubTraversalRate: number;
+    };
+}
+/**
+ * Path analysis metrics for diversity assessment.
+ */
+export interface PathMetrics {
+    /** Algorithm name */
+    algorithm: string;
+    /** Graph identifier */
+    graph: string;
+    /** Number of paths found */
+    pathCount: number;
+    /** Minimum path length */
+    minLength: number;
+    /** Maximum path length */
+    maxLength: number;
+    /** Mean path length */
+    meanLength: number;
+    /** Median path length */
+    medianLength: number;
+    /** Path diversity score (0-1, higher = more diverse) */
+    diversity: number;
+    /** Number of unique nodes across all paths */
+    uniqueNodes: number;
+    /** Jaccard dissimilarity between paths */
+    jaccardDissimilarity: number;
+}
+/**
+ * Combined result from a single algorithm run on a graph.
+ */
+export interface AlgorithmRunResult {
+    /** Expansion metrics */
+    metrics: ExpansionMetrics;
+    /** Path analysis (if paths were found) */
+    pathMetrics?: PathMetrics;
+    /** Raw result for validation */
+    raw: {
+        paths: Array<{
+            fromSeed: number;
+            toSeed: number;
+            nodes: string[];
+        }>;
+        sampledNodes: Set<string>;
+        sampledEdges: Set<string>;
+    };
+}
+/**
+ * Comparison result between two algorithms on the same graph.
+ */
+export interface AlgorithmComparison {
+    /** Graph identifier */
+    graph: string;
+    /** Algorithm A name */
+    algorithmA: string;
+    /** Algorithm B name */
+    algorithmB: string;
+    /** Algorithm A metrics */
+    metricsA: ExpansionMetrics;
+    /** Algorithm B metrics */
+    metricsB: ExpansionMetrics;
+    /** Relative efficiency (A vs B) - negative means A expanded fewer nodes */
+    efficiencyDelta: number;
+    /** Path diversity delta */
+    diversityDelta: number;
+}
+/**
+ * Test fixture with known ground truth properties.
+ */
+export interface GraphFixture {
+    /** Unique identifier for this graph */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Expected optimal path length (for N=2 seeds from opposite ends) */
+    optimalPathLength?: number;
+    /** Number of hubs (nodes with degree > threshold) */
+    hubCount?: number;
+    /** Whether graph is sparse (affects connectivity) */
+    isSparse?: boolean;
+    /** Factory function to create the graph expander */
+    create: () => import('../../../../interfaces/graph-expander').GraphExpander<unknown>;
+    /** Default seeds for N=1, N=2, N=3 tests */
+    seeds: {
+        /** Single seed for ego-network test */
+        n1: string[];
+        /** Two seeds for bidirectional test */
+        n2: string[];
+        /** Three seeds for multi-seed test */
+        n3: string[];
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/experiments/evaluation/__tests__/harness/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/experiments/evaluation/__tests__/harness/types.ts"],"names":[],"mappings":"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"}

package/dist/experiments/evaluation/__tests__/originality-correctness-significance.integration.test.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Experimental Validation of Originality, Correctness, and Significance (OCS)
+ *
+ * This test suite provides experimental evidence for three quality dimensions
+ * derived from ACM's pre-publication evaluation criteria (originality, correctness,
+ * novelty, importance, clarity). OCS consolidates these into three claim types:
+ *
+ * 1. ORIGINALITY: Is seed-bounded expansion fundamentally different from existing methods?
+ *    - Structural difference: Different subgraphs produced
+ *    - Ordering difference: Different visitation sequences
+ *    - Path discovery difference: Different paths found
+ *
+ * 2. CORRECTNESS: Does the algorithm correctly implement the thesis specification?
+ *    - Formula correctness: Priority function matches Equation 4.106
+ *    - N-seed generalization: Works for N=1, N=2, N>=3
+ *    - Frontier exhaustion: Natural termination without depth limits
+ *
+ * 3. SIGNIFICANCE: Does the method provide practical benefits for the application?
+ *    - Hub mitigation: Defers high-degree node expansion
+ *    - Edge efficiency: Traverses fewer edges than BFS
+ *    - Representativeness: Captures diverse graph regions
+ *
+ * Test methodology: Compare Degree-Prioritised Expansion against:
+ * - Standard BFS (baseline for correctness)
+ * - Frontier-Balanced (alternative priority)
+ * - Random Priority (random baseline)
+ *
+ * @see https://www.acm.org/publications/policies/pre-publication-evaluation
+ */
+export {};
+//# sourceMappingURL=originality-correctness-significance.integration.test.d.ts.map

package/dist/experiments/evaluation/__tests__/originality-correctness-significance.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"originality-correctness-significance.integration.test.d.ts","sourceRoot":"","sources":["../../../../src/experiments/evaluation/__tests__/originality-correctness-significance.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/experiments/evaluation/__tests__/thesis-validation.exp.integration.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Thesis Validation Tests with Statistical Rigor
+ *
+ * Experimental validation for originality, correctness, and significance claims.
+ * Uses real-world benchmark datasets, statistical significance testing, and
+ * application-specific metrics.
+ *
+ * Test Structure:
+ * 1. Benchmark Dataset Tests - Real graphs (Karate Club, Les Misérables, Cora)
+ * 2. Statistical Tests - Significance testing, effect sizes, confidence intervals
+ * 3. Multi-Baseline Comparison - All 4 methods compared
+ * 4. Application Metrics - Literature review specific evaluation
+ */
+export {};
+//# sourceMappingURL=thesis-validation.exp.integration.test.d.ts.map

package/dist/experiments/evaluation/__tests__/thesis-validation.exp.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thesis-validation.exp.integration.test.d.ts","sourceRoot":"","sources":["../../../../src/experiments/evaluation/__tests__/thesis-validation.exp.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/experiments/evaluation/__tests__/validation/adapter-roundtrip.unit.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Round-Trip Tests for Graph Adapters
+ *
+ * These tests verify that data transformations preserve expected properties
+ * when converting between different representations:
+ * - Graph → BenchmarkGraphExpander → toGraph()
+ * - Edge array → TestGraphExpander → edges
+ * - Benchmark → BenchmarkGraphExpander → metrics
+ *
+ * Round-trip tests catch data loss, duplicate edge handling, and
+ * structural corruption during format conversions.
+ */
+export {};
+//# sourceMappingURL=adapter-roundtrip.unit.test.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/adapter-roundtrip.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-roundtrip.unit.test.d.ts","sourceRoot":"","sources":["../../../../../src/experiments/evaluation/__tests__/validation/adapter-roundtrip.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/experiments/evaluation/__tests__/validation/canary-tests.integration.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canary Integration Tests with Known Ground Truth
+ *
+ * These tests validate the entire pipeline (adapter → algorithm → metrics)
+ * against known-correct results. They serve as "canary in the coal mine"
+ * to detect pipeline-level bugs that unit tests miss.
+ *
+ * Purpose:
+ * - Catch bugs like the BenchmarkGraphExpander reverse edge issue
+ * - Validate end-to-end behavior with real-world graphs
+ * - Provide known ground truth baselines for regression testing
+ *
+ * Each test uses graphs with known structural properties and validates
+ * that algorithms produce expected results.
+ */
+export {};
+//# sourceMappingURL=canary-tests.integration.test.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/canary-tests.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canary-tests.integration.test.d.ts","sourceRoot":"","sources":["../../../../../src/experiments/evaluation/__tests__/validation/canary-tests.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/experiments/evaluation/__tests__/validation/common/baselines/high-degree-first.d.ts

@@ -0,0 +1,26 @@
+import { GraphExpander } from '../../../../../../interfaces/graph-expander';
+export declare class HighDegreeFirstExpansion {
+    private expander;
+    private seeds;
+    private visited;
+    private sampledEdges;
+    private paths;
+    constructor(expander: GraphExpander<{
+        id: string;
+    }>, seeds: string[]);
+    run(): Promise<{
+        sampledNodes: Set<string>;
+        sampledEdges: Set<string>;
+        paths: Array<{
+            nodes: string[];
+            edges: string[];
+        }>;
+        stats: {
+            nodesExpanded: number;
+            edgesTraversed: number;
+            iterations: number;
+        };
+    }>;
+    private checkPaths;
+}
+//# sourceMappingURL=high-degree-first.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/baselines/high-degree-first.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"high-degree-first.d.ts","sourceRoot":"","sources":["../../../../../../../src/experiments/evaluation/__tests__/validation/common/baselines/high-degree-first.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAEjF,qBAAa,wBAAwB;IACpC,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,KAAK,CAAmD;gBAEpD,QAAQ,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE;IAQ9D,GAAG,IAAI,OAAO,CAAC;QACpB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAAC,KAAK,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QACnD,KAAK,EAAE;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,cAAc,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7E,CAAC;IAuEF,OAAO,CAAC,UAAU;CA0BlB"}

package/dist/experiments/evaluation/__tests__/validation/common/baselines/low-degree-first.d.ts

@@ -0,0 +1,26 @@
+import { GraphExpander } from '../../../../../../interfaces/graph-expander';
+export declare class LowDegreeFirstExpansion {
+    private expander;
+    private seeds;
+    private visited;
+    private sampledEdges;
+    private paths;
+    constructor(expander: GraphExpander<{
+        id: string;
+    }>, seeds: string[]);
+    run(): Promise<{
+        sampledNodes: Set<string>;
+        sampledEdges: Set<string>;
+        paths: Array<{
+            nodes: string[];
+            edges: string[];
+        }>;
+        stats: {
+            nodesExpanded: number;
+            edgesTraversed: number;
+            iterations: number;
+        };
+    }>;
+    private checkPaths;
+}
+//# sourceMappingURL=low-degree-first.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/baselines/low-degree-first.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"low-degree-first.d.ts","sourceRoot":"","sources":["../../../../../../../src/experiments/evaluation/__tests__/validation/common/baselines/low-degree-first.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAEjF,qBAAa,uBAAuB;IACnC,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,KAAK,CAAmD;gBAEpD,QAAQ,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE;IAQ9D,GAAG,IAAI,OAAO,CAAC;QACpB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAAC,KAAK,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QACnD,KAAK,EAAE;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,cAAc,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7E,CAAC;IAiEF,OAAO,CAAC,UAAU;CAyBlB"}

package/dist/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.d.ts

@@ -0,0 +1,58 @@
+import { Graph } from '../../../../../algorithms/graph/graph.js';
+import { Edge, Node } from '../../../../../algorithms/types/graph.js';
+import { GraphExpander, Neighbor } from '../../../../../interfaces/graph-expander';
+export declare class BenchmarkGraphExpander implements GraphExpander<{
+    id: string;
+}> {
+    private graph;
+    private adjacency;
+    private degrees;
+    private nodeIds;
+    private nodeIndex;
+    private edgesBySource;
+    private edgesByTarget?;
+    private adjacencyBuilt;
+    private directed;
+    constructor(graph: {
+        getAllNodes: () => Array<{
+            id: string;
+        }>;
+        getAllEdges: () => Array<{
+            source: string;
+            target: string;
+        }>;
+    }, directed: boolean);
+    getNeighbors(nodeId: string): Promise<Neighbor[]>;
+    getDegree(nodeId: string): number;
+    /**
+     * Build adjacency for a specific node on-demand using binary search.
+     * Only processes the subset of edges relevant to this node.
+     * @param nodeId
+     */
+    private buildAdjacencyForNode;
+    getNode(nodeId: string): Promise<{
+        id: string;
+    } | null>;
+    addEdge(): void;
+    calculatePriority(nodeId: string, options?: {
+        nodeWeight?: number;
+        epsilon?: number;
+    }): number;
+    getNodeCount(): number;
+    getAllNodeIds(): string[];
+    /**
+     * Get the degree distribution for statistical analysis.
+     */
+    getDegreeDistribution(): Map<number, number>;
+    getAllDegrees(): Map<string, number>;
+    /**
+     * Convert this expander to a Graph instance for use with algorithms.
+     *
+     * Creates a new Graph populated with nodes and edges from this expander.
+     * This allows using the expander with algorithms that expect Graph interface.
+     *
+     * @returns A Graph instance compatible with path ranking algorithms
+     */
+    toGraph(): Promise<Graph<Node, Edge>>;
+}
+//# sourceMappingURL=benchmark-graph-expander.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-graph-expander.d.ts","sourceRoot":"","sources":["../../../../../../src/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,0CAA0C,CAAC;AACjE,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,0CAA0C,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAExF,qBAAa,sBAAuB,YAAW,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;IAW1E,OAAO,CAAC,KAAK;IAVd,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,aAAa,CAAC,CAA0C;IAChE,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAU;gBAGjB,KAAK,EAAE;QACd,WAAW,EAAE,MAAM,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACzC,WAAW,EAAE,MAAM,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC7D,EACD,QAAQ,EAAE,OAAO;IAgCZ,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAUvD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAKjC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA8EvB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAI7D,OAAO,IAAI,IAAI;IAIf,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM;IAMlG,YAAY,IAAI,MAAM;IAItB,aAAa,IAAI,MAAM,EAAE;IAIzB;;OAEG;IACH,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ5C,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIpC;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;CAsC3C"}

package/dist/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.unit.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Contract Tests for BenchmarkGraphExpander
+ *
+ * These tests verify that BenchmarkGraphExpander correctly implements
+ * the GraphExpander interface contract, with particular focus on:
+ * - Undirected graph edge handling (forward + reverse edges)
+ * - Binary search correctness for edge lookup
+ * - Lazy adjacency building
+ * - Degree calculation consistency
+ *
+ * Context: The BenchmarkGraphExpander bug (missing reverse edge lookup)
+ * caused universal false negatives in coverage metrics. These tests
+ * prevent similar bugs by validating adapter implementation correctness.
+ */
+export {};
+//# sourceMappingURL=benchmark-graph-expander.unit.test.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-graph-expander.unit.test.d.ts","sourceRoot":"","sources":["../../../../../../src/experiments/evaluation/__tests__/validation/common/benchmark-graph-expander.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/experiments/evaluation/__tests__/validation/common/graph-generators.d.ts

@@ -0,0 +1,51 @@
+import { TestGraphExpander } from './test-graph-expander';
+/**
+ * Creates a star graph - worst case for node explosion.
+ * Expanding the hub immediately exposes all nodes.
+ * @param numberSpokes - Number of spokes connected to the hub
+ */
+export declare const createStarGraph: (numberSpokes: number) => Array<[string, string]>;
+/**
+ * Creates a double-star graph with two hubs connected.
+ * Tests behavior when path goes through hubs.
+ * @param spokesPerHub - Number of spokes per hub
+ */
+export declare const createDoubleStarGraph: (spokesPerHub: number) => Array<[string, string]>;
+/**
+ * Creates a hub-and-spoke network with multiple interconnected hubs.
+ * @param numberHubs - Number of hubs
+ * @param spokesPerHub - Number of spokes per hub
+ */
+export declare const createMultiHubGraph: (numberHubs: number, spokesPerHub: number) => Array<[string, string]>;
+/**
+ * Creates a scale-free-like graph with power-law degree distribution.
+ * @param numberNodes - Number of nodes in the graph
+ * @param seed - Random seed for reproducibility
+ */
+export declare const createScaleFreeGraph: (numberNodes: number, seed?: number) => Array<[string, string]>;
+/**
+ * Creates a star graph with a central hub connected to all other nodes.
+ * @param numSpokes
+ * @param numberSpokes
+ */
+export declare const createStarGraphExpander: (numberSpokes: number) => TestGraphExpander;
+/**
+ * Creates a hub graph with multiple hubs connected to each other and to leaf nodes.
+ * @param numHubs
+ * @param numberHubs
+ * @param leavesPerHub
+ */
+export declare const createHubGraphExpander: (numberHubs: number, leavesPerHub: number) => TestGraphExpander;
+/**
+ * Creates a grid graph (lattice) with uniform degree distribution.
+ * @param rows
+ * @param cols
+ */
+export declare const createGridGraphExpander: (rows: number, cols: number) => TestGraphExpander;
+/**
+ * Creates a chain graph: A -- B -- C -- D -- ...
+ * @param length
+ */
+export declare const createChainGraphExpander: (length: number) => TestGraphExpander;
+export { TestGraphExpander } from './test-graph-expander';
+//# sourceMappingURL=graph-generators.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/graph-generators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-generators.d.ts","sourceRoot":"","sources":["../../../../../../src/experiments/evaluation/__tests__/validation/common/graph-generators.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAM1D;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,cAAc,MAAM,KAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAM5E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,cAAc,MAAM,KAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAclF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,EAAE,cAAc,MAAM,KAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBpG,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,aAAa,MAAM,EAAE,aAAS,KAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CA4C3F,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,MAAM,KAAG,iBAM9D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,YAAY,MAAM,EAAE,cAAc,MAAM,KAAG,iBAkBjF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,iBAkBpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,MAAM,KAAG,iBAMzD,CAAC;AAGF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/experiments/evaluation/__tests__/validation/common/instrumented-expander.d.ts

@@ -0,0 +1,31 @@
+import { GraphExpander, Neighbor } from '../../../../../interfaces/graph-expander';
+export interface TestNode {
+    id: string;
+}
+/**
+ * Graph expander that tracks which nodes were expanded and hub expansions.
+ */
+export declare class InstrumentedExpander implements GraphExpander<TestNode> {
+    private adjacency;
+    private degrees;
+    private nodes;
+    private expandedNodes;
+    private hubNodes;
+    private expansionOrder;
+    constructor(edges: Array<[string, string]>, hubPercentile?: number);
+    getNeighbors(nodeId: string): Promise<Neighbor[]>;
+    getDegree(nodeId: string): number;
+    getNode(nodeId: string): Promise<TestNode | null>;
+    addEdge(): void;
+    calculatePriority(nodeId: string, options?: {
+        nodeWeight?: number;
+        epsilon?: number;
+    }): number;
+    getExpandedNodes(): Set<string>;
+    getExpansionOrder(): string[];
+    getHubNodesExpanded(): number;
+    getHubNodes(): Set<string>;
+    reset(): void;
+    getAllDegrees(): Map<string, number>;
+}
+//# sourceMappingURL=instrumented-expander.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/instrumented-expander.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumented-expander.d.ts","sourceRoot":"","sources":["../../../../../../src/experiments/evaluation/__tests__/validation/common/instrumented-expander.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAOxF,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;CACX;AAMD;;GAEG;AACH,qBAAa,oBAAqB,YAAW,aAAa,CAAC,QAAQ,CAAC;IACnE,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,cAAc,CAAgB;gBAE1B,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,aAAa,SAAM;IA8BzD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQvD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI3B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIvD,OAAO,IAAI,IAAI;IAIf,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM;IAOlG,gBAAgB,IAAI,GAAG,CAAC,MAAM,CAAC;IAI/B,iBAAiB,IAAI,MAAM,EAAE;IAI7B,mBAAmB,IAAI,MAAM;IAU7B,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC;IAI1B,KAAK,IAAI,IAAI;IAKb,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAGpC"}

package/dist/experiments/evaluation/__tests__/validation/common/instrumented-expander.unit.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Contract Tests for InstrumentedExpander
+ *
+ * These tests verify that InstrumentedExpander correctly implements
+ * the GraphExpander interface contract while also providing instrumentation
+ * features for tracking:
+ * - Node expansions
+ * - Expansion order
+ * - Hub node identification
+ * - Reset functionality
+ *
+ * InstrumentedExpander is used for testing algorithms that need to
+ * verify expansion behavior (e.g., hub-deferring properties).
+ */
+export {};
+//# sourceMappingURL=instrumented-expander.unit.test.d.ts.map

package/dist/experiments/evaluation/__tests__/validation/common/instrumented-expander.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumented-expander.unit.test.d.ts","sourceRoot":"","sources":["../../../../../../src/experiments/evaluation/__tests__/validation/common/instrumented-expander.unit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}