graphwise 1.5.1 → 1.6.0

package/README.md

@@ -177,6 +177,17 @@ Density-adaptive strategy switching. Selects between DOME, EDGE, and PIPE modes
 
 ---
 
+#### Expansion Baselines
+
+| Algorithm             | Priority Function              | Description                                |
+| --------------------- | ------------------------------ | ------------------------------------------ |
+| **BFS**               | Discovery order (FIFO)         | Standard breadth-first search              |
+| **DFS**               | Negative iteration (LIFO)      | Depth-first exploration                    |
+| **Frontier-Balanced** | Round-robin across frontiers   | Fair inter-frontier distribution           |
+| **Random Priority**   | Seeded hash (FNV-1a)           | Null hypothesis baseline                   |
+| **k-Hop**             | BFS with depth limit $k$       | Fixed-depth ego-network extraction         |
+| **Random Walk**       | Stochastic neighbour selection | Random walk with restart ($\alpha = 0.15$) |
+
 ---
 
 ### Path Ranking: PARSE
@@ -251,19 +262,33 @@ where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jacca
 
 ---
 
+#### MI Baselines
+
+| Measure                 | Formula                                                                                          | Description                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| **Cosine Similarity**   | $\frac{\lvert N(u) \cap N(v) \rvert}{\sqrt{\lvert N(u) \rvert} \cdot \sqrt{\lvert N(v) \rvert}}$ | Neighbourhood vector cosine; more tolerant of degree asymmetry than Jaccard          |
+| **Sorensen-Dice**       | $\frac{2 \lvert N(u) \cap N(v) \rvert}{\lvert N(u) \rvert + \lvert N(v) \rvert}$                 | Harmonic mean variant of Jaccard; equivalent to F1-score                             |
+| **Resource Allocation** | $\sum_{w \in N(u) \cap N(v)} \frac{1}{\deg(w)}$                                                  | Like Adamic-Adar but without the log; penalises hubs more aggressively               |
+| **Overlap Coefficient** | $\frac{\lvert N(u) \cap N(v) \rvert}{\min(\lvert N(u) \rvert, \lvert N(v) \rvert)}$              | Fraction of smaller neighbourhood that is shared; less sensitive to degree asymmetry |
+| **Hub Promoted**        | $\frac{\lvert N(u) \cap N(v) \rvert}{\min(\deg(u), \deg(v))}$                                    | Promotes hub connections; edges involving high-degree nodes score higher             |
+
+---
+
 ### Ranking Baselines
 
-| Measure                     | Formula                                             |
-| --------------------------- | --------------------------------------------------- |
-| **Katz Index**              | $\sum_{k=1}^{\infty} \beta^k (A^k)_{st}$            |
-| **Communicability**         | $(e^A)_{st}$                                        |
-| **Resistance Distance**     | $L^{+}\_{ss} + L^{+}\_{tt} - 2L^{+}\_{st}$          |
-| **Jaccard Arithmetic Mean** | $\frac{1}{k} \sum J(N(u), N(v))$                    |
-| **Degree-Sum**              | $\sum_{v \in P} \deg(v)$                            |
-| **Widest Path**             | $\min_{(u,v) \in P} w(u,v)$                         |
-| **PageRank**                | Stationary distribution of random walk with damping |
-| **Betweenness**             | Fraction of shortest paths through node             |
-| **Random**                  | Uniform random score (null baseline)                |
+| Measure                     | Formula                                                                                |
+| --------------------------- | -------------------------------------------------------------------------------------- |
+| **Katz Index**              | $\sum_{k=1}^{\infty} \beta^k (A^k)_{st}$                                               |
+| **Communicability**         | $(e^A)_{st}$                                                                           |
+| **Resistance Distance**     | $L^{+}\_{ss} + L^{+}\_{tt} - 2L^{+}\_{st}$                                             |
+| **Jaccard Arithmetic Mean** | $\frac{1}{k} \sum J(N(u), N(v))$                                                       |
+| **Degree-Sum**              | $\sum_{v \in P} \deg(v)$                                                               |
+| **Widest Path**             | $\min_{(u,v) \in P} w(u,v)$                                                            |
+| **PageRank**                | Stationary distribution of random walk with damping                                    |
+| **Betweenness**             | Fraction of shortest paths through node                                                |
+| **Hitting Time**            | $H(s,t) = \left((I - Q)^{-1} \mathbf{1}\right)_s$ (exact) or Monte Carlo approximation |
+| **Shortest Path**           | Hop count on unweighted graphs                                                         |
+| **Random**                  | Uniform random score (null baseline)                                                   |
 
 ---
 

package/dist/__test__/fixtures/index.d.ts

@@ -8,4 +8,5 @@ export * from './types';
 export * from './helpers';
 export * from './graphs';
 export * from './metrics';
+export * from './wrap-async';
 //# sourceMappingURL=index.d.ts.map

package/dist/__test__/fixtures/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/__test__/fixtures/wrap-async.d.ts

@@ -0,0 +1,10 @@
+import { NodeData, EdgeData, ReadableGraph } from '../../graph';
+import { AsyncReadableGraph } from '../../graph/async-interfaces';
+/**
+ * Wrap a synchronous ReadableGraph as an AsyncReadableGraph.
+ *
+ * @param graph - The synchronous graph to wrap
+ * @returns An AsyncReadableGraph that delegates to the sync graph
+ */
+export declare function wrapAsync<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>): AsyncReadableGraph<N, E>;
+//# sourceMappingURL=wrap-async.d.ts.map

package/dist/__test__/fixtures/wrap-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-async.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/wrap-async.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEX,QAAQ,EACR,QAAQ,EAER,aAAa,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC/D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAsE1B"}

package/dist/async/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Async module — generator protocol, runners, and utilities.
+ *
+ * @module async
+ */
+export * from './protocol';
+export * from './ops';
+export * from './types';
+export * from './runners';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/async/ops.d.ts

@@ -0,0 +1,10 @@
+import { NodeId, NodeData, EdgeData, Direction } from '../graph';
+import { GraphOp, GraphOpResponse, ProgressStats } from './protocol';
+export declare function opNeighbours<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(id: NodeId, direction?: Direction): Generator<GraphOp, readonly NodeId[], GraphOpResponse<N, E>>;
+export declare function opDegree<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(id: NodeId, direction?: Direction): Generator<GraphOp, number, GraphOpResponse<N, E>>;
+export declare function opGetNode<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(id: NodeId): Generator<GraphOp, N | undefined, GraphOpResponse<N, E>>;
+export declare function opGetEdge<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(source: NodeId, target: NodeId): Generator<GraphOp, E | undefined, GraphOpResponse<N, E>>;
+export declare function opHasNode<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(id: NodeId): Generator<GraphOp, boolean, GraphOpResponse<N, E>>;
+export declare function opYield<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(): Generator<GraphOp, void, GraphOpResponse<N, E>>;
+export declare function opProgress<N extends NodeData = NodeData, E extends EdgeData = EdgeData>(stats: ProgressStats): Generator<GraphOp, void, GraphOpResponse<N, E>>;
+//# sourceMappingURL=ops.d.ts.map

package/dist/async/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/async/ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1E,wBAAiB,YAAY,CAC5B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAE7B,EAAE,EAAE,MAAM,EACV,SAAS,CAAC,EAAE,SAAS,GACnB,SAAS,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAU9D;AAED,wBAAiB,QAAQ,CACxB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAE7B,EAAE,EAAE,MAAM,EACV,SAAS,CAAC,EAAE,SAAS,GACnB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAUnD;AAED,wBAAiB,SAAS,CACzB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC5B,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAMtE;AAED,wBAAiB,SAAS,CACzB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAE7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAU1D;AAED,wBAAiB,SAAS,CACzB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC5B,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAMhE;AAED,wBAAiB,OAAO,CACvB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,KACzB,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAEnD;AAED,wBAAiB,UAAU,CAC1B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC5B,KAAK,EAAE,aAAa,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAEvE"}

package/dist/async/protocol.d.ts

@@ -0,0 +1,62 @@
+import { NodeId, NodeData, EdgeData, Direction } from '../graph';
+/** Operations the generator can yield to request graph data. */
+export type GraphOp = {
+    readonly tag: "neighbours";
+    readonly id: NodeId;
+    readonly direction?: Direction;
+} | {
+    readonly tag: "degree";
+    readonly id: NodeId;
+    readonly direction?: Direction;
+} | {
+    readonly tag: "getNode";
+    readonly id: NodeId;
+} | {
+    readonly tag: "getEdge";
+    readonly source: NodeId;
+    readonly target: NodeId;
+} | {
+    readonly tag: "hasNode";
+    readonly id: NodeId;
+} | {
+    readonly tag: "yield";
+} | {
+    readonly tag: "progress";
+    readonly stats: ProgressStats;
+};
+/**
+ * Tagged response from a runner for a graph operation.
+ *
+ * Using a discriminated union with `tag` allows type-safe narrowing
+ * without type assertions (satisfying strict lint rules).
+ */
+export type GraphOpResponse<N extends NodeData = NodeData, E extends EdgeData = EdgeData> = {
+    readonly tag: "neighbours";
+    readonly value: readonly NodeId[];
+} | {
+    readonly tag: "degree";
+    readonly value: number;
+} | {
+    readonly tag: "getNode";
+    readonly value: N | undefined;
+} | {
+    readonly tag: "getEdge";
+    readonly value: E | undefined;
+} | {
+    readonly tag: "hasNode";
+    readonly value: boolean;
+} | {
+    readonly tag: "yield";
+} | {
+    readonly tag: "progress";
+};
+/** Progress statistics emitted during expansion. */
+export interface ProgressStats {
+    readonly iterations: number;
+    readonly nodesVisited: number;
+    readonly edgesTraversed: number;
+    readonly pathsFound: number;
+    readonly frontierSizes: readonly number[];
+    readonly elapsedMs: number;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/async/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/async/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtE,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAChB;IACA,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAC9B,GACD;IACA,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAC9B,GACD;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChD;IACA,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAC1B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAE3B;IAAE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CAAE,CAAC;AAEhC,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B"}

package/dist/async/runners.d.ts

@@ -0,0 +1,55 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { AsyncReadableGraph } from '../graph/async-interfaces';
+import { GraphOp, GraphOpResponse } from './protocol';
+import { AsyncRunnerOptions } from './types';
+/**
+ * Resolve a single GraphOp against a synchronous ReadableGraph.
+ *
+ * Returns a tagged GraphOpResponse so the receiving generator can narrow
+ * the result type without type assertions.
+ *
+ * @param graph - The synchronous graph to query
+ * @param op - The operation to resolve
+ * @returns The tagged response
+ */
+export declare function resolveSyncOp<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, op: GraphOp): GraphOpResponse<N, E>;
+/**
+ * Drive a generator to completion using a synchronous graph.
+ *
+ * The generator yields GraphOp requests; each is resolved immediately
+ * against the graph and the tagged response is fed back via gen.next().
+ *
+ * @param gen - The generator to drive
+ * @param graph - The graph to resolve ops against
+ * @returns The generator's return value
+ */
+export declare function runSync<N extends NodeData, E extends EdgeData, R>(gen: Generator<GraphOp, R, GraphOpResponse<N, E>>, graph: ReadableGraph<N, E>): R;
+/**
+ * Resolve a single GraphOp against an async ReadableGraph.
+ *
+ * AsyncIterables (neighbours) are collected into readonly arrays so the
+ * generator receives the same value type as in sync mode. Returns a tagged
+ * GraphOpResponse for type-safe narrowing without assertions.
+ *
+ * @param graph - The async graph to query
+ * @param op - The operation to resolve
+ * @returns A promise resolving to the tagged response
+ */
+export declare function resolveAsyncOp<N extends NodeData, E extends EdgeData>(graph: AsyncReadableGraph<N, E>, op: GraphOp): Promise<GraphOpResponse<N, E>>;
+/**
+ * Drive a generator to completion using an async graph.
+ *
+ * Extends sync semantics with:
+ * - Cancellation via AbortSignal (throws DOMException "AbortError")
+ * - Cooperative yielding at `yield` ops (calls yieldStrategy)
+ * - Progress callbacks at `progress` ops (may be async for backpressure)
+ * - Error propagation: graph errors are forwarded via gen.throw(); if the
+ *   generator does not handle them, they propagate to the caller
+ *
+ * @param gen - The generator to drive
+ * @param graph - The async graph to resolve ops against
+ * @param options - Runner configuration
+ * @returns A promise resolving to the generator's return value
+ */
+export declare function runAsync<N extends NodeData, E extends EdgeData, R>(gen: Generator<GraphOp, R, GraphOpResponse<N, E>>, graph: AsyncReadableGraph<N, E>, options?: AsyncRunnerOptions): Promise<R>;
+//# sourceMappingURL=runners.d.ts.map

package/dist/async/runners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.d.ts","sourceRoot":"","sources":["../../src/async/runners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAOlD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACnE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,EAAE,EAAE,OAAO,GACT,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAoBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAAE,CAAC,EAChE,GAAG,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACjD,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,CAAC,CAOH;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1E,KAAK,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,EAAE,EAAE,OAAO,GACT,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAyBhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAAE,CAAC,EACvE,GAAG,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACjD,KAAK,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,OAAO,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CA0DZ"}

package/dist/async/runners.unit.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unit tests for sync and async runners.
+ *
+ * Verifies that runSync and runAsync correctly drive generator-based
+ * algorithms, resolve all op tags, handle cancellation, and propagate errors.
+ */
+export {};
+//# sourceMappingURL=runners.unit.test.d.ts.map

package/dist/async/runners.unit.test.d.ts.map

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

package/dist/async/types.d.ts

@@ -0,0 +1,15 @@
+import { ProgressStats } from './protocol';
+/** Strategy for cooperative yielding in async mode. */
+export type YieldStrategy = () => Promise<void>;
+/** Configuration for the async runner. */
+export interface AsyncRunnerOptions {
+    /** AbortSignal for cancellation. */
+    readonly signal?: AbortSignal;
+    /** Progress callback, called at yield points. Async return = backpressure. */
+    readonly onProgress?: (stats: ProgressStats) => void | Promise<void>;
+    /** Custom yield strategy (default: setTimeout(0)). */
+    readonly yieldStrategy?: YieldStrategy;
+    /** Yield every N iterations (default: 100). */
+    readonly yieldInterval?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/async/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/async/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhD,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC"}

package/dist/async/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Async utility functions.
+ *
+ * @module async/utils
+ */
+/** Collect an AsyncIterable into a readonly array. */
+export declare function collectAsyncIterable<T>(iter: AsyncIterable<T>): Promise<readonly T[]>;
+/** Default yield strategy: setTimeout(0) to yield to the event loop. */
+export declare function defaultYieldStrategy(): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/async/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/async/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sDAAsD;AACtD,wBAAsB,oBAAoB,CAAC,CAAC,EAC3C,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAIvB;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD"}

package/dist/expansion/comparison.integration.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cross-algorithm comparison integration tests for expansion algorithms.
+ *
+ * Runs all expansion algorithms head-to-head on the same graphs to verify
+ * relative performance properties. Tests are structural rather than exact —
+ * they validate ordering relationships and quality bounds with tolerance.
+ *
+ * Graphs used:
+ * - Three-community (bob → mia): rich inter-community structure, liaison bridges
+ * - Two-department (alice → jack): dense clusters with bottleneck edges
+ * - Social hub (bob → kate): hub node with niche interest clusters
+ */
+export {};
+//# sourceMappingURL=comparison.integration.test.d.ts.map

package/dist/expansion/comparison.integration.test.d.ts.map

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

package/dist/graph/async-interfaces.d.ts

@@ -0,0 +1,31 @@
+import { NodeId, NodeData, EdgeData, Direction } from './types';
+/**
+ * Async read-only interface for graph traversal and queries.
+ *
+ * Mirrors ReadableGraph but all operations return Promises or AsyncIterables,
+ * enabling use with remote graph data sources where each operation may
+ * require a network fetch.
+ */
+export interface AsyncReadableGraph<N extends NodeData = NodeData, E extends EdgeData = EdgeData> {
+    /** Whether the graph is directed (true) or undirected (false) */
+    readonly directed: boolean;
+    /** Total number of nodes in the graph */
+    readonly nodeCount: Promise<number>;
+    /** Total number of edges in the graph */
+    readonly edgeCount: Promise<number>;
+    /** Check if a node exists in the graph. */
+    hasNode(id: NodeId): Promise<boolean>;
+    /** Retrieve node data by identifier. */
+    getNode(id: NodeId): Promise<N | undefined>;
+    /** Iterate over all node identifiers in the graph. */
+    nodeIds(): AsyncIterable<NodeId>;
+    /** Get neighbouring node identifiers in the specified direction. */
+    neighbours(id: NodeId, direction?: Direction): AsyncIterable<NodeId>;
+    /** Get the degree (number of connected edges) for a node. */
+    degree(id: NodeId, direction?: Direction): Promise<number>;
+    /** Retrieve edge data between two nodes. */
+    getEdge(source: NodeId, target: NodeId): Promise<E | undefined>;
+    /** Iterate over all edges in the graph. */
+    edges(): AsyncIterable<E>;
+}
+//# sourceMappingURL=async-interfaces.d.ts.map

package/dist/graph/async-interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-interfaces.d.ts","sourceRoot":"","sources":["../../src/graph/async-interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAClC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAE7B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC,wCAAwC;IACxC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5C,sDAAsD;IACtD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAEjC,oEAAoE;IACpE,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAErE,6DAA6D;IAC7D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE3D,4CAA4C;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEhE,2CAA2C;IAC3C,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC;CAC1B"}

package/dist/graph/async-interfaces.unit.test.d.ts

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

package/dist/graph/async-interfaces.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-interfaces.unit.test.d.ts","sourceRoot":"","sources":["../../src/graph/async-interfaces.unit.test.ts"],"names":[],"mappings":""}

package/dist/graph/index.d.ts

@@ -6,4 +6,5 @@
 export * from './types';
 export * from './interfaces';
 export * from './adjacency-map';
+export * from './async-interfaces';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/ranking/mi/comparison.integration.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-variant comparison integration tests for MI functions.
+ *
+ * Runs all MI variants through PARSE on the same paths and compares their
+ * structural properties. Tests verify:
+ * - All variants produce non-zero salience
+ * - Novel variants produce distinct salience from jaccard baseline
+ * - PARSE exhibits near-zero length bias across all variants
+ * - Ranking order is consistent with MI variant semantics
+ *
+ * Graphs used:
+ * - Three-community (bob → mia): rich clustering structure for SPAN
+ * - City-village (nightclub → shop): density contrast for SCALE
+ * - Social hub (bob → kate): hub/peripheral contrast for SKEW/NOTCH
+ * - Quality-vs-popularity (source → target): explicit high/low MI paths
+ */
+export {};
+//# sourceMappingURL=comparison.integration.test.d.ts.map

package/dist/ranking/mi/comparison.integration.test.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphwise",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Graph algorithms for citation network analysis - novel expansion, MI variants, and path ranking",
   "type": "module",
   "sideEffects": false,