graphbox 1.2.2 → 1.3.0

package/README.md

@@ -1,5 +1,7 @@
 # GraphBox
 
+This file provides guidance to Claude Code (claude.ai/code) when working with this repository.
+
 **GraphBox** = Graph Sandbox + Graph Toolbox
 
 Abstract and experimental graph algorithms for academic research. The name reflects its dual purpose:
@@ -23,14 +25,31 @@ GraphBox consolidates three previously separate BibGraph packages into a single,
 pnpm install graphbox
 ```
 
-## CLI
+## Commands
 
 ```bash
+# Development
+pnpm install              # Install dependencies
+pnpm typecheck            # TypeScript type checking
+pnpm lint                 # ESLint with auto-fix
+pnpm test                 # Run unit tests with coverage
+pnpm build                # Build library + CLI
+
+# Experiments (high memory required)
+NODE_OPTIONS="--max-old-space-size=8192" pnpm test:metrics    # Run experiments, generate metrics
+pnpm gen:latex-tables                                     # Generate LaTeX tables from metrics
+pnpm update:thesis-tables                                  # Full: experiments + LaTeX table generation
+
+# Standalone experiment orchestrator
+npx tsx src/experiments/run-experiments.ts                 # Run all experiments
+npx tsx src/experiments/run-experiments.ts --output path   # Custom output path
+
+# CLI
 npx graphbox help       # Show available commands
 npx graphbox version    # Show version
-npx graphbox generate   # Generate a graph from a specification
+npx graphbox generate   # Generate graphs from specifications
 npx graphbox analyze    # Analyze graph properties
-npx graphbox validate   # Validate a graph against constraints
+npx graphbox validate   # Validate graphs against constraints
 ```
 
 ## Key Features
@@ -105,58 +124,70 @@ import { validateGraph, checkConstraints } from 'graphbox';
 const isValid = validateGraph(graph, constraints);
 ```
 
-## Usage Examples
+## Architecture
 
-### Basic Traversal
+### Experiment Framework
 
-```typescript
-import { GraphAdapter, bfs } from 'graphbox';
+The evaluation harness provides **reusable, repeatable, reproducible** experiments:
 
-const graph = { /* your graph */ };
-const adapter = new GraphAdapter(graph);
+1. **`src/experiments/run-experiments.ts`** - Orchestrator that runs all experiments
+2. **`src/experiments/metrics/`** - Typed metrics collection system
+   - `types.ts` - All metric type interfaces (must conform for table generation)
+   - `collector.ts` - `MetricsCollector` class for recording metrics
+   - `storage.ts` - File I/O for `test-metrics.json`
+3. **`src/experiments/experiments/`** - Standalone experiment scripts
+   - `bidirectional-bfs.ts` - Degree-Prioritised vs baselines
+   - `seeded-expansion.ts` - N=1 ego-network, N=2 bidirectional, N>=3 multi-seed
+   - `path-ranking.ts` - Path Salience Ranking with MI-based ranking
 
-const result = bfs(adapter, 'startNodeId');
-console.log(result.visited); // Array of visited node IDs
-```
+4. **`scripts/export-csv.ts`** - Exports metrics as per-category CSV files for pgfplotstable
 
-### Ego Network Extraction
+**Pipeline:** Experiments → MetricsCollector → test-metrics.json → CSV files → LaTeX pgfplotstable
 
-```typescript
-import { extractEgoNetwork } from 'graphbox';
+### Three Algorithms Evaluated
 
-const adapter = new GraphAdapter(graph);
+1. **Seeded Node Expansion**
+   - N=1: Ego-network extraction
+   - N=2: Bidirectional path finding
+   - N>=3: Multi-seed expansion
 
-const egoNetwork = extractEgoNetwork(adapter, {
-  radius: 2,
-  seedNodes: ['author123'],
-  includeEdgeWeights: true
-});
+2. **Bidirectional BFS** (Degree-Prioritised Expansion)
+   - Degree-based prioritisation vs standard BFS, frontier-balanced, random priority
+   - Hub explosion mitigation
 
-console.log(egoNetwork);
-```
+3. **Salient Path Selection**
+   - Mutual Information (MI) based path ranking
+   - Statistical significance testing (Mann-Whitney U, Cohen's d)
 
-### Graph Generation
+### Graph Abstraction
 
-```typescript
-import { generateGraph, GraphSpec } from 'graphbox';
+- **`ReadableGraph<N, E>`** - Minimal interface for graph traversal
+- **`GraphAdapter`** - Adapter pattern for different graph implementations
+- **`GraphExpander`** - Interface for dynamic graph expansion (used by algorithms)
+- **`BenchmarkGraphExpander`** - Wraps loaded benchmark graphs for algorithm compatibility
 
-const spec: GraphSpec = {
-  type: 'complete',
-  nodeCount: 50,
-  edgeDensity: 0.15
-};
+### Path Aliases
 
-const graph = generateGraph(spec);
+TypeScript paths configured in `tsconfig.json`:
+```typescript
+@graph/algorithms/*    → src/algorithms/*
+@graph/interfaces/*    → src/interfaces/*
+@graph/evaluation/*    → src/experiments/evaluation/*
+@graph/experiments/*   → src/experiments/*
 ```
 
-### Graph Validation
+### Test Organization
 
-```typescript
-import { validateGraph } from 'graphbox';
+- **`.exp.integration.test.ts`** - Experiment tests (high memory, use `--max-old-space-size=8192`)
+- **Unit tests** - Co-located with algorithms
+- **Benchmarks** - `src/experiments/evaluation/__tests__/validation/*/benchmarks/`
+- **Fixtures** - `src/experiments/evaluation/__tests__/validation/*/fixtures/`
 
-const graph = { /* graph object */ };
-const isValid = validateGraph(graph);
-```
+## Build System
+
+**Dual build targets** via Vite:
+- **Library**: ES modules, CJS, UMD formats (browser-compatible)
+- **CLI**: ESM-only for Node.js command-line interface
 
 ## API Reference
 
@@ -182,6 +213,34 @@ const isValid = validateGraph(graph);
 - **generateGraph(spec)** - Generate graph from specification
 - **validateGraph(graph, constraints)** - Validate graph against constraints
 
+## Key Constraints
+
+- **Never use `any`** - Use `unknown` with type guards
+- **Serial test execution** - Parallel causes OOM on large graphs
+- **Memory limits** - Use `NODE_OPTIONS="--max-old-space-size=8192"` for experiments
+- **Metric types** - All metrics must conform to types in `src/experiments/metrics/types.ts`
+
+## LaTeX Table Generation
+
+The experiment pipeline can generate LaTeX tables (`.tex` files) consumable by `pgfplotstable`.
+
+Table-to-metric mapping:
+| Table | Metric Category |
+|-------|-----------------|
+| 06-runtime-performance.tex | runtime-performance |
+| 06-path-lengths.tex | path-lengths |
+| 06-scalability.tex | scalability |
+| 06-n-seed-hub-traversal.tex | n-seed-hub-traversal |
+| 06-statistical-significance.tex | statistical-significance |
+| 06-cross-dataset.tex | cross-dataset |
+| 06-method-ranking.tex | method-ranking |
+| 06-structural-representativeness.tex | structural-representativeness |
+| 06-n-seed-generalisation.tex | n-seed-generalization |
+| 06-n-seed-comparison.tex | n-seed-comparison |
+| 06-n-seed-path-diversity.tex | n-seed-path-diversity |
+| 06-structural-representativeness-metrics.tex | structural-representativeness-metrics |
+| 06-mi-ranking-quality.tex | mi-ranking-quality |
+
 ## Contributing
 
 This package is part of academic research work. Contributions are welcome, please open an issue first.
@@ -196,6 +255,4 @@ Joe Mearman
 
 ## Related Projects
 
-- **BibGraph**: Main BibGraph monorepo
-- **algorithms**: Graph algorithms package for BibGraph
-- **types**: Shared TypeScript types for BibGraph
+- **[BibGraph](https://github.com/Mearman/BibGraph)** - React SPA for OpenAlex literature discovery

package/dist/__tests__/integration/cliquewidth.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for cliquewidth-bounded graphs.
+ *
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for cliquewidth graph property.
+ */
+export {};
+//# sourceMappingURL=cliquewidth.integration.test.d.ts.map

package/dist/__tests__/integration/cliquewidth.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliquewidth.integration.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/cliquewidth.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/integration/modular.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for modular graphs.
+ *
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for modular graph property.
+ */
+export {};
+//# sourceMappingURL=modular.integration.test.d.ts.map

package/dist/__tests__/integration/modular.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modular.integration.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/modular.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/integration/pathwidth.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for pathwidth-bounded graphs.
+ *
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for pathwidth graph property.
+ */
+export {};
+//# sourceMappingURL=pathwidth.integration.test.d.ts.map

package/dist/__tests__/integration/pathwidth.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathwidth.integration.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/pathwidth.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/integration/planar.integration.test.d.ts

@@ -1,8 +1,8 @@
 /**
- * Integration tests for Planar graph class
+ * Integration tests for planar graphs.
  *
- * Planar: can be drawn in the plane without edge crossings.
- * Equivalent: does not contain K5 or K3,3 as a minor (Kuratowski's theorem).
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for planar graph property.
  */
 export {};
 //# sourceMappingURL=planar.integration.test.d.ts.map

package/dist/__tests__/integration/ptolemaic.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for ptolemaic graphs.
+ *
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for ptolemaic graph property.
+ */
+export {};
+//# sourceMappingURL=ptolemaic.integration.test.d.ts.map

package/dist/__tests__/integration/ptolemaic.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ptolemaic.integration.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/ptolemaic.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/integration/quasiline.integration.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Integration tests for quasi-line graphs.
+ *
+ * Tests the complete pipeline: spec → generation → analysis → validation
+ * for quasi-line graph property.
+ */
+export {};
+//# sourceMappingURL=quasiline.integration.test.d.ts.map

package/dist/__tests__/integration/quasiline.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quasiline.integration.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/quasiline.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/algorithms/clustering/louvain.d.ts

@@ -2,6 +2,22 @@ import { Graph } from '../graph/graph';
 import { Community } from '../types/clustering-types';
 import { Edge, Node } from '../types/graph';
 import { WeightFunction } from '../types/weight-function';
+/**
+ * Result of Louvain community detection including performance statistics.
+ */
+export interface LouvainResult<N extends Node> {
+    /** Detected communities */
+    communities: Community<N>[];
+    /** Performance and convergence statistics */
+    stats: {
+        /** Total iterations across all hierarchy levels */
+        totalIterations: number;
+        /** Number of hierarchy levels processed */
+        hierarchyLevels: number;
+        /** Runtime in milliseconds */
+        runtimeMs: number;
+    };
+}
 /**
  * Get adaptive convergence threshold based on graph size.
  * @param nodeCount - Number of nodes in graph
@@ -86,17 +102,17 @@ export declare const shuffle: <T>(array: T[], seed?: number) => T[];
  * // ... add nodes and edges ...
  *
  * // Basic usage (adaptive defaults)
- * const communities = detectCommunities(graph);
- * console.log(`Found ${communities.length} communities`);
+ * const { communities, stats } = detectCommunities(graph);
+ * console.log(`Found ${communities.length} communities in ${stats.totalIterations} iterations`);
  *
  * // Quality-first mode
- * const qualityCommunities = detectCommunities(graph, { mode: "best" });
+ * const result = detectCommunities(graph, { mode: "best" });
  *
  * // Speed-first mode for large graphs
- * const fastCommunities = detectCommunities(graph, { mode: "random", maxIterations: 10 });
+ * const fast = detectCommunities(graph, { mode: "random", maxIterations: 10 });
  *
  * // Reproducible results
- * const deterministicCommunities = detectCommunities(graph, { seed: 42 });
+ * const deterministic = detectCommunities(graph, { seed: 42 });
  * ```
  */
 export declare const detectCommunities: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
@@ -106,5 +122,5 @@ export declare const detectCommunities: <N extends Node, E extends Edge>(graph:
     seed?: number;
     minModularityIncrease?: number;
     maxIterations?: number;
-}) => Community<N>[];
+}) => LouvainResult<N>;
 //# sourceMappingURL=louvain.d.ts.map

package/dist/algorithms/clustering/louvain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"louvain.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/louvain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAa/D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,WAAW,MAAM,KAAG,MAAuC,CAAC;AAEjG;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,MAK5E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MAAM,GAAG,QAAkB,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,MAAM,KAAG,CAAC,EAsBvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IAC9F,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,SAAS,CAAC,CAAC,CAAC,EAwXpB,CAAC"}
+{"version":3,"file":"louvain.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/louvain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,IAAI;IAC5C,2BAA2B;IAC3B,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,KAAK,EAAE;QACN,mDAAmD;QACnD,eAAe,EAAE,MAAM,CAAC;QACxB,2CAA2C;QAC3C,eAAe,EAAE,MAAM,CAAC;QACxB,8BAA8B;QAC9B,SAAS,EAAE,MAAM,CAAC;KAClB,CAAC;CACF;AAYD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,WAAW,MAAM,KAAG,MAAuC,CAAC;AAEjG;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,MAK5E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MAAM,GAAG,QAAkB,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,MAAM,KAAG,CAAC,EAsBvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IAC9F,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,aAAa,CAAC,CAAC,CAkZvB,CAAC"}

package/dist/algorithms/extraction/forbidden-subgraphs.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Forbidden Subgraph Detection
+ *
+ * Efficient detection of induced subgraphs in graphs.
+ * Core infrastructure for 120+ forbidden subgraph graph classes.
+ *
+ * Key operations:
+ * - `hasInducedSubgraph()` - Check if graph contains specific induced subgraph
+ * - `detectMultipleSubgraphs()` - Batch detection of multiple patterns
+ * - `SUBGRAPH_PATTERNS` - Predefined pattern library
+ */
+/**
+ * Subgraph pattern template
+ *
+ * Patterns define vertex count and edge connections.
+ * Vertices are numbered 0 to size-1.
+ */
+export interface SubgraphPattern {
+    /** Pattern name (e.g., "P5", "C5", "bull") */
+    name: string;
+    /** Number of vertices in pattern */
+    size: number;
+    /** Edge connections as vertex pairs */
+    edges: Array<[number, number]>;
+}
+/**
+ * Adjacency list representation
+ *
+ * Maps vertex ID to set of adjacent vertices.
+ */
+export type AdjacencyList = ReadonlyMap<number, ReadonlySet<number>>;
+/**
+ * Build adjacency list from edge list
+ *
+ * @param vertices - Set of vertex IDs
+ * @param edges - Array of edge pairs
+ * @returns Adjacency list map
+ */
+export declare const buildAdjacencyList: (vertices: ReadonlySet<number>, edges: ReadonlyArray<readonly [number, number]>) => AdjacencyList;
+/**
+ * Check if graph contains induced subgraph matching pattern
+ *
+ * @param adjacency - Graph adjacency list
+ * @param pattern - Pattern to search for
+ * @returns true if induced subgraph exists
+ */
+export declare const hasInducedSubgraph: (adjacency: AdjacencyList, pattern: SubgraphPattern) => boolean;
+/**
+ * Detect multiple subgraph patterns in one pass
+ *
+ * Optimized batch detection that avoids redundant combination generation.
+ *
+ * @param adjacency - Graph adjacency list
+ * @param patterns - Array of patterns to detect
+ * @returns Map of pattern name to detection result
+ */
+export declare const detectMultipleSubgraphs: (adjacency: AdjacencyList, patterns: readonly SubgraphPattern[]) => ReadonlyMap<string, boolean>;
+/**
+ * Library of common forbidden subgraph patterns
+ */
+export declare const SUBGRAPH_PATTERNS: {
+    /** Path P3 (3 vertices) */
+    readonly P3: SubgraphPattern;
+    /** Path P4 (4 vertices) */
+    readonly P4: SubgraphPattern;
+    /** Path P5 (5 vertices) */
+    readonly P5: SubgraphPattern;
+    /** Path P6 (6 vertices) */
+    readonly P6: SubgraphPattern;
+    /** Path P7 (7 vertices) */
+    readonly P7: SubgraphPattern;
+    /** Cycle C3 (triangle) */
+    readonly C3: SubgraphPattern;
+    /** Cycle C4 (square) */
+    readonly C4: SubgraphPattern;
+    /** Cycle C5 (pentagon) */
+    readonly C5: SubgraphPattern;
+    /** Cycle C6 (hexagon) */
+    readonly C6: SubgraphPattern;
+    /** Cycle C7 (heptagon) */
+    readonly C7: SubgraphPattern;
+    /** Complete K2 (edge) */
+    readonly K2: SubgraphPattern;
+    /** Complete K3 (triangle) */
+    readonly K3: SubgraphPattern;
+    /** Complete K4 */
+    readonly K4: SubgraphPattern;
+    /** Complete K5 */
+    readonly K5: SubgraphPattern;
+    /**
+     * Bull graph
+     * Triangle with two pendant vertices
+     *
+     *     2
+     *     |
+     * 0 - 1 - 3
+     *     |
+     *     4
+     */
+    readonly bull: SubgraphPattern;
+    /**
+     * Gem graph
+     * P4 with a universal vertex
+     *
+     *     2
+     *     |
+     * 0 - 1 - 3
+     *     |
+     *     4
+     * plus all edges from vertex 1
+     */
+    readonly gem: SubgraphPattern;
+    /**
+     * Net graph
+     * Triangle with three pendant vertices
+     *
+     *       2
+     *      /|\
+     *     3 0 4
+     *      \|/
+     *       1
+     */
+    readonly net: SubgraphPattern;
+    /**
+     * House graph
+     * P5 with a chord forming a "roof"
+     *
+     *   2 - 3
+     *   |   |
+     * 0 - 1 - 4
+     */
+    readonly house: SubgraphPattern;
+    /**
+     * Diamond graph
+     * K4 minus one edge
+     *
+     *   2
+     *  /|\
+     * 3-0-1
+     *  \|/
+     *   4
+     */
+    readonly diamond: SubgraphPattern;
+    /**
+     * Claw graph K1,3
+     * Star with 3 leaves
+     *
+     *     2
+     *     |
+     * 0 - 1 - 3
+     *     |
+     *     4
+     */
+    readonly claw: SubgraphPattern;
+    /**
+     * Fork graph
+     * P4 with an extra pendant attached to second vertex
+     *
+     *     2
+     *     |
+     * 0 - 1 - 3 - 4
+     */
+    readonly fork: SubgraphPattern;
+    /**
+     * Chair graph
+     * P4 plus a pendant attached to center
+     *
+     *   2
+     *   |
+     *   1
+     *   |
+     * 0-1-3-4  (vertex 1 has pendant 2)
+     */
+    readonly chair: SubgraphPattern;
+    /**
+     * Dart graph
+     * Triangle with a path attached
+     *
+     *   1---2
+     *   |\ /
+     *   | 0
+     *   |/
+     *   3
+     */
+    readonly dart: SubgraphPattern;
+    /**
+     * Kite graph
+     * Diamond with a pendant
+     */
+    readonly kite: SubgraphPattern;
+    /**
+     * Banner graph
+     * Triangle with a path of length 2 attached
+     */
+    readonly banner: SubgraphPattern;
+    /**
+     * 4-cycle with chord
+     * C4 plus one diagonal
+     */
+    readonly C4_chord: SubgraphPattern;
+};
+/**
+ * Get all pattern names from library
+ */
+export declare const ALL_PATTERN_NAMES: readonly (keyof typeof SUBGRAPH_PATTERNS)[];
+/**
+ * Get pattern by name
+ * @param name
+ */
+export declare const getPattern: (name: keyof typeof SUBGRAPH_PATTERNS) => SubgraphPattern;
+//# sourceMappingURL=forbidden-subgraphs.d.ts.map

package/dist/algorithms/extraction/forbidden-subgraphs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden-subgraphs.d.ts","sourceRoot":"","sources":["../../../src/algorithms/extraction/forbidden-subgraphs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,uCAAuC;IACvC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC9B,UAAU,WAAW,CAAC,MAAM,CAAC,EAC7B,OAAO,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAC7C,aAqBF,CAAC;AA6HF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC9B,WAAW,aAAa,EACxB,SAAS,eAAe,KACtB,OAmBF,CAAC;AAgCF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,aAAa,EACxB,UAAU,SAAS,eAAe,EAAE,KAClC,WAAW,CAAC,MAAM,EAAE,OAAO,CA8C7B,CAAC;AAwEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC7B,2BAA2B;;IAG3B,2BAA2B;;IAG3B,2BAA2B;;IAG3B,2BAA2B;;IAG3B,2BAA2B;;IAG3B,0BAA0B;;IAG1B,wBAAwB;;IAGxB,0BAA0B;;IAG1B,yBAAyB;;IAGzB,0BAA0B;;IAG1B,yBAAyB;;IAGzB,6BAA6B;;IAG7B,kBAAkB;;IAGlB,kBAAkB;;IAGlB;;;;;;;;;OASG;mBAWE,eAAe;IAEpB;;;;;;;;;;OAUG;kBAaE,eAAe;IAEpB;;;;;;;;;OASG;kBAYE,eAAe;IAEpB;;;;;;;OAOG;oBAWE,eAAe;IAEpB;;;;;;;;;OASG;sBAWE,eAAe;IAEpB;;;;;;;;;OASG;mBASE,eAAe;IAEpB;;;;;;;OAOG;mBAUE,eAAe;IAEpB;;;;;;;;;OASG;oBAUE,eAAe;IAEpB;;;;;;;;;OASG;mBAWE,eAAe;IAEpB;;;OAGG;mBAYE,eAAe;IAEpB;;;OAGG;qBAWE,eAAe;IAEpB;;;OAGG;uBAWE,eAAe;CACX,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAEzB,SAAS,CAAC,MAAM,OAAO,iBAAiB,CAAC,EAAE,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,UAAU,GACtB,MAAM,MAAM,OAAO,iBAAiB,KAClC,eAMF,CAAC"}

package/dist/algorithms/pathfinding/path-ranking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-ranking.d.ts","sourceRoot":"","sources":["../../../src/algorithms/pathfinding/path-ranking.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"path-ranking.d.ts","sourceRoot":"","sources":["../../../src/algorithms/pathfinding/path-ranking.ts"],"names":[],"mappings":"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"}

package/dist/algorithms/pathfinding/random-path-sampling.d.ts

@@ -0,0 +1,31 @@
+import { Graph } from '../graph/graph.js';
+import { GraphError } from '../types/errors.js';
+import { Edge, Node } from '../types/graph.js';
+import { Result } from '../types/result.js';
+import { RankedPath } from './path-ranking.js';
+/**
+ * Configuration for random path sampling.
+ */
+export interface RandomPathSamplingConfig {
+    /** Maximum number of paths to sample */
+    maxPaths?: number;
+    /** Random seed for reproducibility */
+    seed?: number;
+    /** Maximum path length to prevent infinite walks */
+    maxLength?: number;
+    /** Maximum attempts per path before giving up */
+    maxAttemptsPerPath?: number;
+}
+/**
+ * Sample random paths between source and target using random walks.
+ *
+ * Performs multiple random walks from source, attempting to reach target.
+ * Each successful path is converted to a RankedPath with placeholder MI values.
+ * @param graph - The graph to sample paths from
+ * @param sourceId - Starting node ID
+ * @param targetId - Ending node ID
+ * @param config - Sampling configuration
+ * @returns Result containing array of ranked paths or error
+ */
+export declare const sampleRandomPaths: <N extends Node, E extends Edge>(graph: Graph<N, E>, sourceId: string, targetId: string, config?: RandomPathSamplingConfig) => Result<Array<RankedPath<N, E>>, GraphError>;
+//# sourceMappingURL=random-path-sampling.d.ts.map

package/dist/algorithms/pathfinding/random-path-sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-path-sampling.d.ts","sourceRoot":"","sources":["../../../src/algorithms/pathfinding/random-path-sampling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAeD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAC/D,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,UAAU,MAAM,EAChB,UAAU,MAAM,EAChB,SAAQ,wBAA6B,KACnC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,CA8D5C,CAAC"}

package/dist/algorithms/pathfinding/shortest-path-ranking.d.ts

@@ -0,0 +1,28 @@
+import { Graph } from '../graph/graph.js';
+import { GraphError } from '../types/errors.js';
+import { Edge, Node } from '../types/graph.js';
+import { Result } from '../types/result.js';
+import { RankedPath } from './path-ranking.js';
+/**
+ * Configuration for shortest path ranking.
+ */
+export interface ShortestPathRankingConfig {
+    /** Maximum number of paths to find */
+    maxPaths?: number;
+}
+/**
+ * Find k-shortest paths between source and target.
+ *
+ * Uses a modified Dijkstra approach: finds shortest path, then iteratively
+ * finds next-shortest paths by removing edges from previously found paths.
+ *
+ * Note: This is a simplified k-shortest paths implementation. For production,
+ * consider Yen's algorithm or Eppstein's algorithm for better performance.
+ * @param graph - The graph to search
+ * @param sourceId - Starting node ID
+ * @param targetId - Ending node ID
+ * @param config - Configuration for pathfinding
+ * @returns Result containing array of ranked paths or error
+ */
+export declare const shortestPathRanking: <N extends Node, E extends Edge>(graph: Graph<N, E>, sourceId: string, targetId: string, config?: ShortestPathRankingConfig) => Result<Array<RankedPath<N, E>>, GraphError>;
+//# sourceMappingURL=shortest-path-ranking.d.ts.map

package/dist/algorithms/pathfinding/shortest-path-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortest-path-ranking.d.ts","sourceRoot":"","sources":["../../../src/algorithms/pathfinding/shortest-path-ranking.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACzC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EACjE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,UAAU,MAAM,EAChB,UAAU,MAAM,EAChB,SAAQ,yBAA8B,KACpC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,CA4D5C,CAAC"}