effect 4.0.1 → 4.0.3

package/dist/Graph.js

@@ -6,6 +6,7 @@
  * both nodes and edges. The module includes traversal, analysis, path-finding,
  * transformation, and diagram export utilities.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 import * as Data from "./Data.js";
@@ -37,6 +38,7 @@ const copyEdge = edge => ({
  * Use when handling failures thrown by graph operations that reject invalid
  * graph structure or unsupported algorithm inputs.
  *
+ * @stability unstable
  * @category errors
  * @since 3.18.0
  */
@@ -93,6 +95,7 @@ const withMutationGuard = (graph, evaluate) => graph.mutable ? internal.withTran
  * distinguish immutable graphs from mutable graphs or directed graphs from
  * undirected graphs.
  *
+ * @stability unstable
  * @category guards
  * @since 4.0.0
  */
@@ -128,6 +131,7 @@ export const isGraph = internal.isGraph;
  * ```
  *
  * @see {@link toSnapshot} for capturing a graph snapshot
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -236,6 +240,7 @@ export const fromSnapshot = snapshot => {
  * ```
  *
  * @see {@link fromSnapshot} for reconstructing an immutable graph
+ * @stability unstable
  * @category converting
  * @since 4.0.0
  */
@@ -278,6 +283,7 @@ export const toSnapshot = graph => {
  *
  * @see {@link directed} for constructing a directed graph directly
  * @see {@link undirected} for constructing an undirected graph directly
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -323,6 +329,7 @@ export const make = type => mutate => {
  * Array.of(Graph.nodeCount(graph), Graph.edgeCount(graph)) // => [3, 2]
  * ```
  *
+ * @stability unstable
  * @category constructors
  * @since 3.18.0
  */
@@ -356,6 +363,7 @@ export const directed = /*#__PURE__*/make("directed");
  * Array.of(Graph.nodeCount(graph), Graph.edgeCount(graph)) // => [3, 2]
  * ```
  *
+ * @stability unstable
  * @category constructors
  * @since 3.18.0
  */
@@ -390,6 +398,7 @@ export const undirected = /*#__PURE__*/make("undirected");
  *
  * @see {@link endMutation} for finalizing the mutable graph
  * @see {@link mutate} for automatically scoped mutation
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -423,6 +432,7 @@ export const beginMutation = graph => {
  *
  * @see {@link beginMutation} for opening a manual mutation scope
  * @see {@link mutate} for automatically scoped mutation
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -488,6 +498,7 @@ const mutateScoped = (mutable, f) => {
  *
  * @see {@link beginMutation} for opening a manual mutation scope
  * @see {@link endMutation} for finalizing a manual mutation scope
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -626,6 +637,7 @@ const assertSameKind = (self, that) => {
  * ```
  *
  * @see {@link sum} for combining graphs without merging equal nodes
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -701,6 +713,7 @@ export const compose = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(arg
  * ```
  *
  * @see {@link compose} for identity-based graph union
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -786,6 +799,7 @@ export const intersection = /*#__PURE__*/dual(args => isGraph(args[0]) && isGrap
  * ```
  *
  * @see {@link symmetricDifference} for retaining edges unique to either graph
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -862,6 +876,7 @@ export const difference = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(
  * ```
  *
  * @see {@link difference} for removing only the edges found in another graph
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -933,6 +948,7 @@ export const symmetricDifference = /*#__PURE__*/dual(args => isGraph(args[0]) &&
  * ```
  *
  * @see {@link hasEdge} for testing one relationship
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -1001,6 +1017,7 @@ export const complement = /*#__PURE__*/dual(2, (self, createEdge) => {
  * ```
  *
  * @see {@link inducedSubgraph} for selecting nodes while preserving identifiers
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -1052,6 +1069,7 @@ export const neighborhood = /*#__PURE__*/dual(args => isGraph(args[0]), (self, n
  *
  * @see {@link neighborhood} for selecting nodes by traversal distance
  *
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -1112,6 +1130,7 @@ export const inducedSubgraph = /*#__PURE__*/dual(2, (self, nodeIndices) => {
  *
  * @see {@link compose} for merging overlapping logical nodes by identity
  *
+ * @stability unstable
  * @category set operations
  * @since 4.0.0
  */
@@ -1171,6 +1190,7 @@ export const sum = /*#__PURE__*/dual(2, (self, that) => {
  * @see {@link mutate} for obtaining a mutable graph from an immutable graph
  * @see {@link addEdge} for connecting existing nodes
  *
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -1206,6 +1226,7 @@ export const addNode = (mutable, data) => {
  * Graph.getNode(graph, 0) // => Option.some("Node A")
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1229,6 +1250,7 @@ export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * Graph.hasNode(graph, 999) // => false
  * ```
  *
+ * @stability unstable
  * @category predicates
  * @since 3.18.0
  */
@@ -1253,6 +1275,7 @@ export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => internal.toImp
  * Graph.nodeCount(graphWithNodes) // => 3
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1275,6 +1298,7 @@ export const nodeCount = graph => internal.toImpl(graph).nodes.size;
  * Graph.findNode(graph, (data) => data === "Node D") // => Option.none()
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1307,6 +1331,7 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
  * Graph.findNodes(graph, (data) => data === "Not Found") // => []
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1342,6 +1367,7 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
  * Graph.findEdge(graph, (data) => data > 100) // => Option.none()
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1377,6 +1403,7 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
  * Graph.findEdges(graph, (data) => data > 100) // => []
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -1419,6 +1446,7 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
  * Graph.getNode(graph, 0) // => Option.some("NODE A")
  * ```
  *
+ * @stability unstable
  * @category transforming
  * @since 3.18.0
  */
@@ -1461,6 +1489,7 @@ export const updateNode = (mutable, index, f) => {
  * Option.map(Graph.getEdge(result, 0), (edge) => edge.data) // => Option.some(20)
  * ```
  *
+ * @stability unstable
  * @category transforming
  * @since 3.18.0
  */
@@ -1514,6 +1543,7 @@ export const updateEdge = (mutable, edgeIndex, f) => {
  *
  * @see {@link updateNode} for updating one node
  * @see {@link filterMapNodes} for mapping while removing nodes
+ * @stability unstable
  * @category mapping
  * @since 3.18.0
  */
@@ -1563,6 +1593,7 @@ export const mapNodes = (mutable, f) => {
  *
  * @see {@link updateEdge} for updating one edge
  * @see {@link filterMapEdges} for mapping while removing edges
+ * @stability unstable
  * @category mapping
  * @since 3.18.0
  */
@@ -1613,6 +1644,7 @@ export const mapEdges = (mutable, f) => {
  * Option.map(Graph.getEdge(graph, 0), (edge) => edge.source) // => Option.some(1)
  * ```
  *
+ * @stability unstable
  * @category transforming
  * @since 3.18.0
  */
@@ -1667,6 +1699,7 @@ export const reverse = mutable => {
  * Graph.nodeCount(graph) // => 2
  * ```
  *
+ * @stability unstable
  * @category filtering
  * @since 3.18.0
  */
@@ -1721,6 +1754,7 @@ export const filterMapNodes = (mutable, f) => {
  * Graph.edgeCount(graph) // => 2
  * ```
  *
+ * @stability unstable
  * @category filtering
  * @since 3.18.0
  */
@@ -1776,6 +1810,7 @@ export const filterMapEdges = (mutable, f) => {
  * Graph.nodeCount(graph) // => 2
  * ```
  *
+ * @stability unstable
  * @category filtering
  * @since 3.18.0
  */
@@ -1824,6 +1859,7 @@ export const filterNodes = (mutable, predicate) => {
  * Graph.edgeCount(graph) // => 2
  * ```
  *
+ * @stability unstable
  * @category filtering
  * @since 3.18.0
  */
@@ -1895,6 +1931,7 @@ const invalidateCycleFlagOnAddition = mutable => {
  * @see {@link mutate} for obtaining a mutable graph from an immutable graph
  * @see {@link addNode} for creating node indexes before connecting them
  *
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -1970,6 +2007,7 @@ export const addEdge = (mutable, source, target, data) => {
  * Array.of(Graph.nodeCount(result), Graph.edgeCount(result)) // => [1, 0]
  * ```
  *
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -1998,6 +2036,7 @@ export const removeNode = (mutable, nodeIndex) => {
  *
  * @see {@link removeNode} for removing one node
  *
+ * @stability unstable
  * @category mutations
  * @since 4.0.0
  */
@@ -2079,6 +2118,7 @@ const removeNodeInternal = (impl, nodeIndex) => {
  * Array.of(Graph.nodeCount(result), Graph.edgeCount(result)) // => [2, 0]
  * ```
  *
+ * @stability unstable
  * @category mutations
  * @since 3.18.0
  */
@@ -2108,6 +2148,7 @@ export const removeEdge = (mutable, edgeIndex) => {
  *
  * @see {@link removeEdge} for removing one edge
  *
+ * @stability unstable
  * @category mutations
  * @since 4.0.0
  */
@@ -2197,6 +2238,7 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  * Graph.getEdge(graph, 0) // => Option.some({ source: 0, target: 1, data: 42 })
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -2233,6 +2275,7 @@ export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => {
  * ```
  *
  * @see {@link edgesBetween} for all matching edge identifiers
+ * @stability unstable
  * @category predicates
  * @since 3.18.0
  */
@@ -2277,6 +2320,7 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
  * Graph.edgeCount(graphWithEdges) // => 3
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -2289,6 +2333,7 @@ export const edgeCount = graph => internal.toImpl(graph).edges.size;
  * Each edge is returned once in graph edge order, including self-loops.
  * Throws a `GraphError` when the node does not exist.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2340,6 +2385,7 @@ export const incidentEdges = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * Parallel edges and self-loops are returned separately in adjacency order.
  * Throws a `GraphError` for an undirected graph or missing node.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2363,6 +2409,7 @@ export const outgoingEdges = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * Parallel edges and self-loops are returned separately in reverse-adjacency
  * order. Throws a `GraphError` for an undirected graph or missing node.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2387,6 +2434,7 @@ export const incomingEdges = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * graphs include either stored orientation. Parallel edges are retained.
  * Throws a `GraphError` when either node does not exist.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2421,6 +2469,7 @@ export const edgesBetween = /*#__PURE__*/dual(3, (graph, source, target) => {
  * Parallel edges count separately and a self-loop contributes two. Throws a
  * `GraphError` for a directed graph or missing node.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2444,6 +2493,7 @@ export const degree = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * Parallel edges count separately and a self-loop contributes one. Throws a
  * `GraphError` for an undirected graph or missing node.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2467,6 +2517,7 @@ export const outDegree = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * Parallel edges count separately and a self-loop contributes one. Throws a
  * `GraphError` for an undirected graph or missing node.
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2563,6 +2614,7 @@ const ScanDegreeLimit = 32;
  * Graph.neighbors(graph, 1) // => []
  * ```
  *
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -2592,6 +2644,7 @@ export const neighbors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * @see {@link predecessors} for incoming neighbors in a directed graph
  * @see {@link neighbors} for generic neighbor lookup across graph kinds
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2622,6 +2675,7 @@ export const successors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * @see {@link successors} for outgoing neighbors in a directed graph
  * @see {@link neighbors} for generic neighbor lookup across graph kinds
  *
+ * @stability unstable
  * @category getters
  * @since 4.0.0
  */
@@ -2672,6 +2726,7 @@ export const predecessors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  * @deprecated Use {@link successors} for outgoing neighbors or {@link predecessors} for incoming neighbors.
  * @see {@link successors} for outgoing neighbors in a directed graph
  * @see {@link predecessors} for incoming neighbors in a directed graph
+ * @stability unstable
  * @category getters
  * @since 3.18.0
  */
@@ -2710,6 +2765,7 @@ const escapeGraphVizString = value => value.replace(/\\/g, "\\\\").replace(/"/g,
  * ```
  *
  * @see {@link toMermaid} for Mermaid diagram output
+ * @stability unstable
  * @category converting
  * @since 3.18.0
  */
@@ -2804,6 +2860,7 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * ```
  *
  * @see {@link toGraphViz} for GraphViz DOT output
+ * @stability unstable
  * @category converting
  * @since 3.18.0
  */
@@ -2860,6 +2917,7 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  * one-edge cycle, and two parallel undirected edges form a two-edge cycle.
  *
  * @see {@link isAcyclic} when only a boolean cycle check is needed
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -2966,6 +3024,7 @@ export const findCycle = graph => {
  *
  * @see {@link findCycle} for retrieving one cycle witness
  * @see {@link topo} for ordering a directed acyclic graph
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -3090,6 +3149,7 @@ export const isAcyclic = graph => {
  * ```
  *
  * @see {@link maximumBipartiteMatching} for matching nodes after validation
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -3207,6 +3267,7 @@ const bipartiteColors = graph => {
  * ```
  *
  * @see {@link isBipartite} for validating the graph without computing a matching
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -3424,6 +3485,7 @@ const getUnweightedDistances = (graph, source, direction) => {
  * @see {@link bfs} for lazy traversal in increasing hop distance
  * @see {@link dijkstra} for weighted shortest paths
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -3448,6 +3510,7 @@ export const unweightedDistances = /*#__PURE__*/dual(args => isGraph(args[0]), (
  * @see {@link unweightedDistances} for hop distances to all reachable nodes
  * @see {@link dijkstra} for a minimum-cost path
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -3537,6 +3600,7 @@ export const hasPath = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, sourc
  * @see {@link isConnected} when only a boolean connectivity check is needed
  * @see {@link weaklyConnectedComponents} for directed graphs with orientation ignored
  * @see {@link stronglyConnectedComponents} for mutual directed reachability
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -3743,6 +3807,7 @@ const analyzeLowLinks = graph => {
  *
  * @see {@link articulationPoints} for single-node failure points
  * @see {@link biconnectedComponents} for maximal regions without an articulation split
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -3780,6 +3845,7 @@ export const bridges = graph => analyzeLowLinks(graph).bridges;
  *
  * @see {@link bridges} for single-edge failure points
  * @see {@link biconnectedComponents} for the regions joined at articulation points
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -3824,6 +3890,7 @@ export const articulationPoints = graph => analyzeLowLinks(graph).articulationPo
  *
  * @see {@link articulationPoints} for the nodes shared between components
  * @see {@link bridges} for edges whose removal disconnects the graph
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4011,6 +4078,7 @@ const solveMaximumFlow = (graph, config) => {
  * ```
  *
  * @see {@link minimumCut} for the residual-reachability partition
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4062,6 +4130,7 @@ export const maximumFlow = /*#__PURE__*/dual(2, (graph, config) => {
  * ```
  *
  * @see {@link maximumFlow} for per-edge flow values
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4100,6 +4169,7 @@ export const minimumCut = /*#__PURE__*/dual(2, (graph, config) => {
  * @see {@link isWeaklyConnected} when only a boolean check is needed
  * @see {@link stronglyConnectedComponents} for mutual directed reachability
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4185,6 +4255,7 @@ export const weaklyConnectedComponents = graph => {
  *
  * @see {@link isStronglyConnected} when only a boolean check is needed
  * @see {@link weaklyConnectedComponents} when edge orientation should be ignored
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -4303,6 +4374,7 @@ const csrReachesAll = (nodeCount, primary, secondary) => {
  *
  * @see {@link connectedComponents} for the component partition
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -4330,6 +4402,7 @@ export const isConnected = graph => {
  *
  * @see {@link isStronglyConnected} when edge orientation must be respected
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -4361,6 +4434,7 @@ export const isWeaklyConnected = graph => {
  *
  * @see {@link isWeaklyConnected} when edge orientation should be ignored
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -4385,6 +4459,7 @@ export const isStronglyConnected = graph => {
  * The empty graph is not a tree. Parallel edges and self-loops prevent a graph
  * from being a tree. Throws a `GraphError` when used with a directed graph.
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -4418,6 +4493,7 @@ export const isTree = graph => {
  * Throws a `GraphError` for a directed graph or when a weight is `NaN` or
  * `-Infinity`. Edges weighted `Infinity` are omitted.
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4527,6 +4603,7 @@ export const minimumSpanningForest = /*#__PURE__*/dual(2, (graph, cost) => {
  * coalesced by retaining the first edge for each required pair. Throws a
  * `GraphError` for an undirected graph or cyclic input.
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -4747,6 +4824,7 @@ const denseMinHeapPop = heap => {
  * @see {@link astar} when a useful heuristic can guide the search
  * @see {@link bellmanFord} when edge costs may be negative
  * @see {@link floydWarshall} when shortest paths are needed for all pairs
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -4860,14 +4938,16 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  *
  * **When to use**
  *
- * Use when many or all node pairs will be queried and cubic computation plus
- * quadratic result storage is acceptable.
+ * Use when many or all node pairs will be queried and cubic distance computation
+ * plus storage for reconstructed paths is acceptable.
  *
  * **Details**
  *
  * Computes distances, reconstructed node paths, and edge-data paths for every
- * source and target pair in O(V^3) time. Negative edge weights are allowed, and
- * `Infinity` behaves like an impassable edge.
+ * source and target pair. Distance computation takes O(V^3) time. Negative edge
+ * weights are allowed, and `Infinity` behaves like an impassable edge. Immutable
+ * path witnesses can require O(V^3) working storage; reconstructed paths have
+ * repeated nodes removed.
  *
  * **Gotchas**
  *
@@ -4896,6 +4976,7 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  *
  * @see {@link dijkstra} for one query with non-negative edge costs
  * @see {@link bellmanFord} for one query that may include negative edge costs
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -4905,13 +4986,10 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
   const edgeIds = csr.getEdgeIds(cache);
   const edgeCache = csr.getEdgeEndpoints(cache);
   const size = cache.nodeIds.length;
-  // Flat matrices keep the O(N^2) working set contiguous and avoid nested map lookups in the O(N^3) loop.
+  const witnesses = new Array(size * size);
+  // The flat distance matrix avoids nested map lookups in the O(N^3) loop.
   const distancesMatrix = new Float64Array(size * size);
-  const nextMatrix = new Int32Array(size * size);
-  const edgeMatrix = new Int32Array(size * size);
   distancesMatrix.fill(Infinity);
-  nextMatrix.fill(-1);
-  edgeMatrix.fill(-1);
   for (let i = 0; i < size; i++) {
     distancesMatrix[i * size + i] = 0;
   }
@@ -4928,15 +5006,19 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
       const position = source * size + target;
       if (weight < distancesMatrix[position]) {
         distancesMatrix[position] = weight;
-        nextMatrix[position] = target;
-        edgeMatrix[position] = edge;
+        witnesses[position] = {
+          target,
+          edge
+        };
       }
       if (graph.type === "undirected") {
         const reverse = target * size + source;
         if (weight < distancesMatrix[reverse]) {
           distancesMatrix[reverse] = weight;
-          nextMatrix[reverse] = source;
-          edgeMatrix[reverse] = edge;
+          witnesses[reverse] = {
+            target: source,
+            edge
+          };
         }
       }
     }
@@ -4949,7 +5031,7 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
       if (distanceIK === Infinity) {
         continue;
       }
-      const nextIK = nextMatrix[iRow + k];
+      const left = witnesses[iRow + k];
       for (let j = 0; j < size; j++) {
         const distanceKJ = distancesMatrix[kRow + j];
         if (distanceKJ === Infinity) {
@@ -4961,9 +5043,14 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
             message: "Floyd-Warshall distance calculation exceeded the finite number range"
           });
         }
-        if (candidate < distancesMatrix[iRow + j] && nextIK !== -1) {
+        if (candidate < distancesMatrix[iRow + j]) {
           distancesMatrix[iRow + j] = candidate;
-          nextMatrix[iRow + j] = nextIK;
+          const right = witnesses[kRow + j];
+          witnesses[iRow + j] = left === undefined ? right : right === undefined ? left : {
+            target: j,
+            left,
+            right
+          };
         }
       }
     }
@@ -4979,6 +5066,9 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
   const paths = new Map();
   const edgePaths = new Map();
   const costs = new Map();
+  // Reuse scratch storage; erased suffixes and completed paths clear only touched entries.
+  const positions = new Int32Array(size);
+  positions.fill(-1);
   for (let i = 0; i < size; i++) {
     const source = cache.nodeIds[i];
     const distanceRow = new Map();
@@ -5005,19 +5095,35 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
         const path = [source];
         const pathEdges = [];
         const pathCosts = [];
-        let current = i;
-        while (current !== j) {
-          const next = nextMatrix[current * size + j];
-          if (next === -1) {
-            break;
-          }
-          const edge = edgeMatrix[current * size + next];
-          if (edge !== -1) {
-            pathEdges.push(edgeIds[edge]);
-            pathCosts.push(edges[edge].data);
+        positions[i] = 0;
+        const nodes = [i];
+        const stack = [witnesses[i * size + j]];
+        // Witnesses only reference older witnesses, so this traversal cannot
+        // follow a cyclic pointer chain. Erase closed walks rather than return
+        // a truncated route or reject a valid zero-cost cycle.
+        while (stack.length > 0) {
+          const witness = stack.pop();
+          const position = positions[witness.target];
+          if (position !== -1) {
+            for (let p = position + 1; p < nodes.length; p++) {
+              positions[nodes[p]] = -1;
+            }
+            nodes.length = position + 1;
+            path.length = position + 1;
+            pathEdges.length = position;
+            pathCosts.length = position;
+          } else if ("edge" in witness) {
+            positions[witness.target] = nodes.length;
+            nodes.push(witness.target);
+            path.push(cache.nodeIds[witness.target]);
+            pathEdges.push(edgeIds[witness.edge]);
+            pathCosts.push(edges[witness.edge].data);
+          } else {
+            stack.push(witness.right, witness.left);
           }
-          current = next;
-          path.push(cache.nodeIds[current]);
+        }
+        for (const node of nodes) {
+          positions[node] = -1;
         }
         pathRow.set(target, path);
         edgePathRow.set(target, pathEdges);
@@ -5084,6 +5190,7 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
  *
  * @see {@link dijkstra} when no useful heuristic is available
  * @see {@link bellmanFord} when edge costs may be negative
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -5261,6 +5368,7 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
  * ```
  *
  * @see {@link dijkstra} for non-negative edge costs
+ * @stability unstable
  * @category algorithms
  * @since 3.18.0
  */
@@ -5442,6 +5550,7 @@ const pathWalker = iterator => ({
  *
  * @see {@link allShortestPaths} for enumerating only minimum-cost routes
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -5544,6 +5653,7 @@ export const simplePaths = /*#__PURE__*/dual(2, (graph, config) => {
  * @see {@link dijkstra} when one shortest path is sufficient
  * @see {@link simplePaths} for routes regardless of cost
  *
+ * @stability unstable
  * @category algorithms
  * @since 4.0.0
  */
@@ -5720,6 +5830,7 @@ export const allShortestPaths = /*#__PURE__*/dual(2, (graph, config) => {
  * Array.from(Graph.entries(allNodes)) // => [[0, "A"], [1, "B"]]
  * ```
  *
+ * @stability unstable
  * @category models
  * @since 3.18.0
  */
@@ -5808,6 +5919,7 @@ const traversalStartPositions = (cache, start) => {
  * Array.from(Graph.indices(dfs)) // => [0, 1]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -5830,6 +5942,7 @@ export const indices = walker => walker.visit((index, _) => index);
  * Array.from(Graph.values(dfs)) // => ["A", "B"]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -5852,6 +5965,7 @@ export const values = walker => walker.visit((_, data) => data);
  * Array.from(Graph.entries(dfs)) // => [[0, "A"], [1, "B"]]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -5898,6 +6012,7 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  *
  * @see {@link bfs} for traversal in increasing hop distance
  * @see {@link dfsPostOrder} for emitting descendants before ancestors
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6058,6 +6173,7 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  *
  * @see {@link dfs} for branch-first traversal
  * @see {@link unweightedDistances} for collecting hop counts
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6181,6 +6297,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * ```
  *
  * @see {@link isAcyclic} for checking the required graph property
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6314,6 +6431,7 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * ```
  *
  * @see {@link dfs} for emitting nodes when first visited
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6441,6 +6559,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  * Array.from(Graph.indices(Graph.nodes(graph))) // => [0, 1, 2]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6495,6 +6614,7 @@ export const nodes = graph => new Walker(f => ({
  * Array.from(Graph.indices(Graph.edges(graph))) // => [0, 1]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */
@@ -6560,6 +6680,7 @@ export const edges = graph => new Walker(f => ({
  * Array.from(Graph.indices(Graph.externals(graph, { direction: "incoming" }))) // => [0, 3]
  * ```
  *
+ * @stability unstable
  * @category iterators
  * @since 3.18.0
  */