graphbox 1.2.2 → 1.3.0

package/dist/domain/claims.d.ts

@@ -0,0 +1,56 @@
+import { EvaluationClaim } from 'ppef/types/claims';
+/**
+ * Ranking Claims for Path Salience evaluation.
+ * Tests whether information-theoretic ranking outperforms baseline methods.
+ */
+declare const RANKING_CLAIMS: EvaluationClaim[];
+/**
+ * Community Detection Claims for Louvain evaluation.
+ * Tests structural decomposition quality on benchmark graphs.
+ */
+declare const COMMUNITY_DETECTION_CLAIMS: EvaluationClaim[];
+/**
+ * K-Core Decomposition Claims.
+ * Tests hierarchical structure identification on benchmark graphs.
+ */
+declare const KCORE_CLAIMS: EvaluationClaim[];
+/**
+ * Thesis claims for GraphBox evaluation.
+ *
+ * Each claim represents a testable hypothesis about algorithm performance.
+ */
+export declare const THESIS_CLAIMS: EvaluationClaim[];
+/**
+ * Get claims by tag.
+ *
+ * @param tag - Tag to filter by
+ * @returns Matching claims
+ */
+export declare const getClaimsByTag: (tag: string) => EvaluationClaim[];
+/**
+ * Get core claims (most important for thesis).
+ */
+export declare const getCoreClaims: () => EvaluationClaim[];
+/**
+ * Get claims for a specific SUT.
+ *
+ * @param sutId - SUT identifier
+ * @returns Claims where SUT is primary
+ */
+export declare const getClaimsBySut: (sutId: string) => EvaluationClaim[];
+/**
+ * Get claims for a specific baseline.
+ *
+ * @param baselineId - Baseline SUT identifier
+ * @returns Claims comparing against this baseline
+ */
+export declare const getClaimsByBaseline: (baselineId: string) => EvaluationClaim[];
+/**
+ * Get claim by ID.
+ *
+ * @param claimId - Claim identifier
+ * @returns Claim or undefined
+ */
+export declare const getClaim: (claimId: string) => EvaluationClaim | undefined;
+export { COMMUNITY_DETECTION_CLAIMS, KCORE_CLAIMS, RANKING_CLAIMS };
+//# sourceMappingURL=claims.d.ts.map

package/dist/domain/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/domain/claims.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;GAGG;AACH,QAAA,MAAM,cAAc,EAAE,eAAe,EAyCpC,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,0BAA0B,EAAE,eAAe,EAsBhD,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,YAAY,EAAE,eAAe,EAwBlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,eAAe,EA8J1C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,eAAe,EAAwD,CAAC;AAErH;;GAEG;AACH,eAAO,MAAM,aAAa,QAAO,eAAe,EAA4B,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,eAAe,EAAkD,CAAC;AAEjH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,KAAG,eAAe,EAA4D,CAAC;AAErI;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,KAAG,eAAe,GAAG,SAA6D,CAAC;AAG3H,OAAO,EAAE,0BAA0B,EAAE,YAAY,EAAC,cAAc,EAAE,CAAC"}

package/dist/domain/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Domain Module
+ *
+ * GraphBox-specific claims and table specifications.
+ */
+export { getClaim, getClaimsByBaseline, getClaimsBySut, getClaimsByTag, getCoreClaims, RANKING_CLAIMS, THESIS_CLAIMS, } from './claims.js';
+export { getTableSpec, TABLE_SPECS } from './tables.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAC,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/domain/tables.d.ts

@@ -0,0 +1,66 @@
+import { TableRenderSpec } from 'ppef/renderers/types';
+/**
+ * Runtime performance table specification.
+ */
+export declare const RUNTIME_PERFORMANCE_SPEC: TableRenderSpec;
+/**
+ * Path lengths table specification.
+ */
+export declare const PATH_LENGTHS_SPEC: TableRenderSpec;
+/**
+ * Method ranking table specification.
+ */
+export declare const METHOD_RANKING_SPEC: TableRenderSpec;
+/**
+ * N-seed comparison table specification.
+ */
+export declare const N_SEED_COMPARISON_SPEC: TableRenderSpec;
+/**
+ * Hub traversal table specification.
+ */
+export declare const HUB_TRAVERSAL_SPEC: TableRenderSpec;
+/**
+ * Hub-avoidance metrics table specification.
+ *
+ * Displays hub-avoidance metrics comparing degree-prioritised vs BFS.
+ * Key insight: path diversity is hub-biased, while these metrics directly
+ * measure the hub-avoidance design goal of degree-prioritised.
+ *
+ * Shows N=3 (multi-seed) variant where DP efficiency difference is most pronounced.
+ */
+export declare const HUB_AVOIDANCE_SPEC: TableRenderSpec;
+/**
+ * N-seed generalization table specification.
+ */
+export declare const N_SEED_GENERALIZATION_SPEC: TableRenderSpec;
+/**
+ * MI ranking quality table specification.
+ */
+export declare const MI_RANKING_QUALITY_SPEC: TableRenderSpec;
+/**
+ * Statistical significance table specification.
+ */
+export declare const STATISTICAL_SIGNIFICANCE_SPEC: TableRenderSpec;
+/**
+ * Ranking comparison table specification.
+ *
+ * Compares Path Salience ranking against baseline methods (random, shortest-path).
+ * Shows mean MI, node coverage, and path diversity across test graphs.
+ */
+export declare const RANKING_COMPARISON_SPEC: TableRenderSpec;
+/**
+ * Ranking statistical significance table specification.
+ *
+ * Wilcoxon signed-rank test results for Path Salience vs baseline methods.
+ */
+export declare const RANKING_SIGNIFICANCE_SPEC: TableRenderSpec;
+/**
+ * All table specifications.
+ */
+export declare const TABLE_SPECS: TableRenderSpec[];
+/**
+ * Get table specification by ID.
+ * @param id
+ */
+export declare const getTableSpec: (id: string) => TableRenderSpec | undefined;
+//# sourceMappingURL=tables.d.ts.map

package/dist/domain/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/domain/tables.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAkD5D;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,eA2DtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAiB/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA0BjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAwCpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAmBhC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAkDhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAexC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,EAAE,eAqC3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAgDrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,eAiDvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,eAAe,EAYxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,eAAe,GAAG,SAAuD,CAAC"}

package/dist/experiments/baselines/betweenness-ranking.d.ts

@@ -0,0 +1,38 @@
+import { Graph } from '../../algorithms/graph/graph';
+import { RankedPath } from '../../algorithms/pathfinding/path-ranking';
+import { Edge, Node } from '../../algorithms/types/graph';
+import { Option } from '../../algorithms/types/option';
+import { Result } from '../../algorithms/types/result';
+/**
+ * Configuration for betweenness ranking.
+ */
+export interface BetweennessConfig {
+    /**
+     * Traversal mode for path finding.
+     */
+    traversalMode?: "directed" | "undirected";
+    /**
+     * Maximum number of paths to return.
+     */
+    maxPaths?: number;
+}
+/**
+ * Rank paths between two nodes by betweenness centrality.
+ *
+ * This baseline ranks paths by the sum of betweenness centrality values
+ * of nodes along the path. Paths through highly central nodes receive
+ * higher scores.
+ *
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - The graph to search
+ * @param startId - Source node ID
+ * @param endId - Target node ID
+ * @param config - Optional configuration
+ * @returns Result containing betweenness-ranked paths or error
+ */
+export declare const betweennessRanking: <N extends Node, E extends Edge>(graph: Graph<N, E>, startId: string, endId: string, config?: BetweennessConfig) => Result<Option<RankedPath<N, E>[]>, {
+    type: string;
+    message: string;
+}>;
+//# sourceMappingURL=betweenness-ranking.d.ts.map

package/dist/experiments/baselines/betweenness-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"betweenness-ranking.d.ts","sourceRoot":"","sources":["../../../src/experiments/baselines/betweenness-ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAE5E,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAQ,KAAK,MAAM,EAAQ,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAkSD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAChE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,SAAS,MAAM,EACf,OAAO,MAAM,EACb,SAAQ,iBAAsB,KAC5B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiDtE,CAAC"}

package/dist/experiments/baselines/cross-seed-affinity.d.ts

@@ -0,0 +1,141 @@
+import { GraphExpander } from '../../interfaces/graph-expander';
+/**
+ * Result from cross-seed-affinity expansion.
+ */
+export interface CrossSeedAffinityResult {
+    /** Discovered paths (only populated when N >= 2 seeds) */
+    paths: Array<{
+        fromSeed: number;
+        toSeed: number;
+        nodes: string[];
+    }>;
+    /** Union of all nodes visited by all frontiers */
+    sampledNodes: Set<string>;
+    /** Set of edges visited during expansion */
+    sampledEdges: Set<string>;
+    /** Per-frontier visited sets (for diagnostics) */
+    visitedPerFrontier: Array<Set<string>>;
+    /** Statistics about the expansion */
+    stats: CrossSeedAffinityStats;
+    /** Maps node ID to the iteration when it was first discovered */
+    nodeDiscoveryIteration: Map<string, number>;
+}
+/**
+ * Statistics collected during cross-seed-affinity expansion.
+ */
+export interface CrossSeedAffinityStats {
+    /** 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>;
+    /** Distribution of frontier visit counts */
+    frontierVisitDistribution: Map<number, number>;
+}
+/**
+ * Cross-Seed-Affinity Bidirectional Expansion
+ *
+ * Baseline algorithm that prioritises nodes based on their cross-frontier
+ * visibility. Nodes visited by multiple frontiers receive lower priority
+ * (deferred expansion) relative to their degree, testing whether avoiding
+ * "convergence zones" improves path diversity.
+ *
+ * **Priority Formula**:
+ * π(v) = deg(v) / (1 + frontierCount(v))
+ *
+ * where frontierCount(v) is the number of frontiers that have visited node v.
+ *
+ * **Key Properties**:
+ * - Prioritises low-degree nodes (like degree-prioritised)
+ * - Further deprioritises nodes in multiple frontiers' visited sets
+ * - Avoids convergence zones where frontiers would naturally meet
+ * - Tests hypothesis: "Does deferring shared nodes improve diversity?"
+ *
+ * **Experimental Purpose**:
+ * If cross-seed-affinity achieves better path diversity than simple
+ * degree-prioritised expansion, this suggests frontier interaction awareness
+ * is important. If not, simple degree ordering suffices.
+ *
+ * @template T - Type of node data returned by expander
+ */
+export declare class CrossSeedAffinityExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private readonly frontierVisitCounts;
+    private stats;
+    private readonly nodeDiscoveryIteration;
+    /**
+     * Create a new cross-seed-affinity 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[]);
+    /**
+     * Run the expansion to completion.
+     *
+     * Terminates when all frontiers are exhausted (no unexpanded nodes remain).
+     *
+     * @returns Expansion results including paths and sampled subgraph
+     */
+    run(): Promise<CrossSeedAffinityResult>;
+    /**
+     * Compute cross-seed-affinity priority for a node.
+     * Priority: π(v) = deg(v) / (1 + frontierCount(v))
+     *
+     * Lower degree = higher base priority (like degree-prioritised).
+     * Nodes in more frontiers get penalised (lower effective priority).
+     *
+     * @param nodeId - Node to compute priority for
+     * @returns Priority value (higher = should expand sooner)
+     * @internal
+     */
+    private computeCrossSeedAffinityPriority;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @internal
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the next frontier with items (round-robin).
+     * Returns -1 if all frontiers are empty.
+     * @internal
+     */
+    private selectNextFrontier;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @internal
+     */
+    private reconstructPath;
+    /**
+     * Check if an equivalent path already exists.
+     * @param fromSeed
+     * @param toSeed
+     * @param nodes
+     * @internal
+     */
+    private pathExists;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @internal
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @internal
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=cross-seed-affinity.d.ts.map

package/dist/experiments/baselines/cross-seed-affinity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-seed-affinity.d.ts","sourceRoot":"","sources":["../../../src/experiments/baselines/cross-seed-affinity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,0DAA0D;IAC1D,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,sBAAsB,CAAC;IAE9B,iEAAiE;IACjE,sBAAsB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,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;IAExC,4CAA4C;IAC5C,yBAAyB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,0BAA0B,CAAC,CAAC;IAgBvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhBvB,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,mBAAmB,CAA6B;IACjE,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IA6B1C;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAuG7C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gCAAgC;IASxC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/experiments/baselines/degree-sum-ranking.d.ts

@@ -0,0 +1,38 @@
+import { Graph } from '../../algorithms/graph/graph';
+import { RankedPath } from '../../algorithms/pathfinding/path-ranking';
+import { Edge, Node } from '../../algorithms/types/graph';
+import { Option } from '../../algorithms/types/option';
+import { Result } from '../../algorithms/types/result';
+/**
+ * Configuration for degree sum ranking.
+ */
+export interface DegreeRankingConfig {
+    /**
+     * Traversal mode for path finding.
+     */
+    traversalMode?: "directed" | "undirected";
+    /**
+     * Maximum number of paths to return.
+     */
+    maxPaths?: number;
+}
+/**
+ * Rank paths between two nodes by sum of node degrees.
+ *
+ * This baseline ranks paths by the sum of degrees of all nodes
+ * along the path. Paths through high-degree (well-connected) nodes
+ * receive higher scores.
+ *
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - The graph to search
+ * @param startId - Source node ID
+ * @param endId - Target node ID
+ * @param config - Optional configuration
+ * @returns Result containing degree-ranked paths or error
+ */
+export declare const degreeSumRanking: <N extends Node, E extends Edge>(graph: Graph<N, E>, startId: string, endId: string, config?: DegreeRankingConfig) => Result<Option<RankedPath<N, E>[]>, {
+    type: string;
+    message: string;
+}>;
+//# sourceMappingURL=degree-sum-ranking.d.ts.map

package/dist/experiments/baselines/degree-sum-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree-sum-ranking.d.ts","sourceRoot":"","sources":["../../../src/experiments/baselines/degree-sum-ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAE5E,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAQ,KAAK,MAAM,EAAQ,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAuID;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAC9D,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,SAAS,MAAM,EACf,OAAO,MAAM,EACb,SAAQ,mBAAwB,KAC9B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiDtE,CAAC"}

package/dist/experiments/baselines/degree-surprise.d.ts

@@ -0,0 +1,134 @@
+import { GraphExpander } from '../../interfaces/graph-expander';
+/**
+ * Result from degree-surprise expansion.
+ */
+export interface DegreeSurpriseResult {
+    /** Discovered paths (only populated when N >= 2 seeds) */
+    paths: Array<{
+        fromSeed: number;
+        toSeed: number;
+        nodes: string[];
+    }>;
+    /** Union of all nodes visited by all frontiers */
+    sampledNodes: Set<string>;
+    /** Set of edges visited during expansion */
+    sampledEdges: Set<string>;
+    /** Per-frontier visited sets (for diagnostics) */
+    visitedPerFrontier: Array<Set<string>>;
+    /** Statistics about the expansion */
+    stats: DegreeSurpriseStats;
+    /** Map from node ID to the iteration when it was first discovered */
+    nodeDiscoveryIteration: Map<string, number>;
+}
+/**
+ * Statistics collected during degree-surprise expansion.
+ */
+export interface DegreeSurpriseStats {
+    /** 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>;
+}
+/**
+ * Degree-Surprise Bidirectional Expansion
+ *
+ * Baseline algorithm that prioritises nodes whose degree deviates most from
+ * the local degree expectation of their neighbourhood. This tests whether
+ * local structural anomalies provide better sampling than raw degree values.
+ *
+ * **Priority Formula**:
+ * π(v) = |deg(v) - E[deg(N(v))]| / std[deg(N(v))]
+ *
+ * where N(v) are the neighbours of v, E[·] is expectation, std[·] is standard deviation.
+ *
+ * **Key Properties**:
+ * - Prioritises nodes that are structural outliers in their local neighbourhood
+ * - Low-degree nodes in high-degree regions get high priority (and vice versa)
+ * - Requires computing local degree statistics for each frontier node
+ * - Terminates when all frontiers exhausted
+ *
+ * **Experimental Purpose**:
+ * Compare local structural anomaly detection (degree surprise) against
+ * global degree ordering (degree-prioritised expansion). If degree-surprise
+ * achieves similar path diversity, local context matters more than global degree.
+ *
+ * @template T - Type of node data returned by expander
+ */
+export declare class DegreeSurpriseExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private stats;
+    private readonly nodeDiscoveryIteration;
+    /**
+     * Create a new degree-surprise 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[]);
+    /**
+     * Run the expansion to completion.
+     *
+     * Terminates when all frontiers are exhausted (no unexpanded nodes remain).
+     *
+     * @returns Expansion results including paths and sampled subgraph
+     */
+    run(): Promise<DegreeSurpriseResult>;
+    /**
+     * Compute degree surprise for a node.
+     * Priority: π(v) = |deg(v) - E[deg(N(v))]| / std[deg(N(v))]
+     *
+     * @param nodeId - Node to compute surprise for
+     * @returns Surprise value (higher = more anomalous)
+     * @internal
+     */
+    private computeDegreeSurprise;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @internal
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the next frontier with items (round-robin).
+     * Returns -1 if all frontiers are empty.
+     * @internal
+     */
+    private selectNextFrontier;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @internal
+     */
+    private reconstructPath;
+    /**
+     * Check if an equivalent path already exists.
+     * @param fromSeed
+     * @param toSeed
+     * @param nodes
+     * @internal
+     */
+    private pathExists;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @internal
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @internal
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=degree-surprise.d.ts.map

package/dist/experiments/baselines/degree-surprise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree-surprise.d.ts","sourceRoot":"","sources":["../../../src/experiments/baselines/degree-surprise.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,0DAA0D;IAC1D,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,mBAAmB,CAAC;IAE3B,qEAAqE;IACrE,sBAAsB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,uBAAuB,CAAC,CAAC;IAepC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAfvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoE;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE;;;;;;OAMG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE;IAyB1C;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,oBAAoB,CAAC;IA4F1C;;;;;;;OAOG;YACW,qBAAqB;IA2BnC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}

package/dist/experiments/baselines/delayed-termination.d.ts

@@ -0,0 +1,138 @@
+import { GraphExpander } from '../../interfaces/graph-expander';
+/**
+ * Result from delayed-termination expansion.
+ */
+export interface DelayedTerminationResult {
+    /** Discovered paths (only populated when N >= 2 seeds) */
+    paths: Array<{
+        fromSeed: number;
+        toSeed: number;
+        nodes: string[];
+    }>;
+    /** Union of all nodes visited by all frontiers */
+    sampledNodes: Set<string>;
+    /** Set of edges visited during expansion */
+    sampledEdges: Set<string>;
+    /** Per-frontier visited sets (for diagnostics) */
+    visitedPerFrontier: Array<Set<string>>;
+    /** Statistics about the expansion */
+    stats: DelayedTerminationStats;
+    /** Map from node ID to the iteration at which it was first discovered */
+    nodeDiscoveryIteration: Map<string, number>;
+}
+/**
+ * Statistics collected during delayed-termination expansion.
+ */
+export interface DelayedTerminationStats {
+    /** 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>;
+    /** Iteration at which first overlap was detected */
+    firstOverlapIteration: number;
+    /** Total additional iterations after first overlap */
+    delayedIterations: number;
+}
+/**
+ * Configuration for delayed termination.
+ */
+export interface DelayedTerminationConfig {
+    /** Number of additional iterations after first overlap (default: 100) */
+    delayIterations: number;
+}
+/**
+ * Delayed-Termination Bidirectional BFS
+ *
+ * Extends overlap-based termination by continuing expansion for N additional
+ * iterations after the first overlap is detected. This baseline tests whether
+ * the degree-prioritised algorithm's benefits come from deferred termination
+ * rather than the degree heuristic itself.
+ *
+ * **Key Properties**:
+ * - FIFO expansion order (standard BFS)
+ * - Detects first overlap between any two frontiers
+ * - Continues for N additional iterations after overlap
+ * - Tests hypothesis: "Does delayed termination alone improve diversity?"
+ *
+ * **Experimental Purpose**:
+ * If delayed-termination BFS achieves similar path diversity to degree-prioritised
+ * expansion, this suggests termination timing (not degree ordering) drives diversity.
+ * If degree-prioritised still outperforms delayed BFS, the degree heuristic provides
+ * value beyond simply deferring termination.
+ *
+ * @template T - Type of node data returned by expander
+ */
+export declare class DelayedTerminationExpansion<T> {
+    private readonly expander;
+    private readonly seeds;
+    private readonly config;
+    private readonly frontiers;
+    private readonly paths;
+    private readonly sampledEdges;
+    private readonly nodeDiscoveryIteration;
+    private stats;
+    private firstOverlapIteration;
+    private remainingDelayIterations;
+    /**
+     * Create a new delayed-termination expansion.
+     *
+     * @param expander - Graph expander providing neighbour access
+     * @param seeds - Array of seed node IDs (N >= 1)
+     * @param config - Configuration for delay iterations
+     * @throws Error if no seeds provided
+     */
+    constructor(expander: GraphExpander<T>, seeds: readonly string[], config?: DelayedTerminationConfig);
+    /**
+     * Run the expansion to completion.
+     *
+     * Terminates when delay iterations are exhausted after first overlap,
+     * or when all frontiers are exhausted (whichever comes first).
+     *
+     * @returns Expansion results including paths and sampled subgraph
+     */
+    run(): Promise<DelayedTerminationResult>;
+    /**
+     * Check if any frontier has unexpanded nodes.
+     * @internal
+     */
+    private hasNonEmptyFrontier;
+    /**
+     * Select the next frontier with items (round-robin).
+     * Returns -1 if all frontiers are empty.
+     * @internal
+     */
+    private selectNextFrontier;
+    /**
+     * Reconstruct path from meeting point between two frontiers.
+     * @param stateA
+     * @param stateB
+     * @param meetingNode
+     * @internal
+     */
+    private reconstructPath;
+    /**
+     * Check if an equivalent path already exists.
+     * @param fromSeed
+     * @param toSeed
+     * @param nodes
+     * @internal
+     */
+    private pathExists;
+    /**
+     * Record degree in distribution histogram.
+     * @param degree
+     * @internal
+     */
+    private recordDegree;
+    /**
+     * Get histogram bucket for a degree value.
+     * @param degree
+     * @internal
+     */
+    private getDegreeBucket;
+}
+//# sourceMappingURL=delayed-termination.d.ts.map

package/dist/experiments/baselines/delayed-termination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayed-termination.d.ts","sourceRoot":"","sources":["../../../src/experiments/baselines/delayed-termination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,0DAA0D;IAC1D,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,uBAAuB,CAAC;IAE/B,yEAAyE;IACzE,sBAAsB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,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;IAExC,oDAAoD;IACpD,qBAAqB,EAAE,MAAM,CAAC;IAE9B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC;CACxB;AAoBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,2BAA2B,CAAC,CAAC;IAkBxC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBxB,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,sBAAsB,CAA6B;IACpE,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,qBAAqB,CAAM;IACnC,OAAO,CAAC,wBAAwB,CAAS;IAEzC;;;;;;;OAOG;gBAEe,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,GAAE,wBAAmD;IA6B7E;;;;;;;OAOG;IACG,GAAG,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAiG9C;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASvB"}