effect 4.0.0-beta.98 → 4.0.0-beta.99

package/dist/Graph.js

@@ -13,6 +13,7 @@ import * as Equal from "./Equal.js";
 import { dual } from "./Function.js";
 import * as Hash from "./Hash.js";
 import { NodeInspectSymbol } from "./Inspectable.js";
+import * as MutableHashMap from "./MutableHashMap.js";
 import * as Option from "./Option.js";
 import { pipeArguments } from "./Pipeable.js";
 import { hasProperty } from "./Predicate.js";
@@ -33,12 +34,29 @@ const TypeId = "~effect/collections/Graph";
  * @since 3.18.0
  */
 export class Edge extends Data.Class {}
+/** @internal */
+const graphImpl = graph => graph;
+/** @internal */
+const cloneAdjacency = adjacency => {
+  const cloned = new Map();
+  for (const [nodeIndex, edges] of adjacency) {
+    cloned.set(nodeIndex, [...edges]);
+  }
+  return cloned;
+};
 // =============================================================================
 // Proto Objects
 // =============================================================================
 /** @internal */
+const edgeEquals = (type, self, that) => (type === "directed" ? self.source === that.source && self.target === that.target : self.source === that.source && self.target === that.target || self.source === that.target && self.target === that.source) && Equal.equals(self.data, that.data);
+/** @internal */
+const edgeHash = (type, edge) => type === "directed" ? Hash.hash(edge) : Hash.optimize(Hash.hash(edge.data) ^ Hash.hash(edge.source) + Hash.hash(edge.target));
+/** @internal */
 const ProtoGraph = {
-  [TypeId]: TypeId,
+  [TypeId]: {
+    _N: _ => _,
+    _E: _ => _
+  },
   [Symbol.iterator]() {
     return this.nodes[Symbol.iterator]();
   },
@@ -47,26 +65,27 @@ const ProtoGraph = {
   },
   [Equal.symbol](that) {
     if (isGraph(that)) {
-      if (this.nodes.size !== that.nodes.size || this.edges.size !== that.edges.size || this.type !== that.type) {
+      const thatImpl = graphImpl(that);
+      if (this.nodes.size !== thatImpl.nodes.size || this.edges.size !== thatImpl.edges.size || this.nextNodeIndex !== thatImpl.nextNodeIndex || this.nextEdgeIndex !== thatImpl.nextEdgeIndex || this.type !== thatImpl.type) {
         return false;
       }
       // Compare nodes
       for (const [nodeIndex, nodeData] of this.nodes) {
-        if (!that.nodes.has(nodeIndex)) {
+        if (!thatImpl.nodes.has(nodeIndex)) {
           return false;
         }
-        const otherNodeData = that.nodes.get(nodeIndex);
+        const otherNodeData = thatImpl.nodes.get(nodeIndex);
         if (!Equal.equals(nodeData, otherNodeData)) {
           return false;
         }
       }
       // Compare edges
       for (const [edgeIndex, edgeData] of this.edges) {
-        if (!that.edges.has(edgeIndex)) {
+        if (!thatImpl.edges.has(edgeIndex)) {
           return false;
         }
-        const otherEdge = that.edges.get(edgeIndex);
-        if (!Equal.equals(edgeData, otherEdge)) {
+        const otherEdge = thatImpl.edges.get(edgeIndex);
+        if (!edgeEquals(this.type, edgeData, otherEdge)) {
           return false;
         }
       }
@@ -79,11 +98,13 @@ const ProtoGraph = {
     hash = hash ^ Hash.string(this.type);
     hash = hash ^ Hash.number(this.nodes.size);
     hash = hash ^ Hash.number(this.edges.size);
+    hash = hash ^ Hash.number(this.nextNodeIndex);
+    hash = hash ^ Hash.number(this.nextEdgeIndex);
     for (const [nodeIndex, nodeData] of this.nodes) {
       hash = hash ^ Hash.hash(nodeIndex) + Hash.hash(nodeData);
     }
     for (const [edgeIndex, edgeData] of this.edges) {
-      hash = hash ^ Hash.hash(edgeIndex) + Hash.hash(edgeData);
+      hash = hash ^ Hash.hash(edgeIndex) + edgeHash(this.type, edgeData);
     }
     return hash;
   },
@@ -124,12 +145,20 @@ export class GraphError extends /*#__PURE__*/Data.TaggedError("GraphError") {}
 const missingNode = node => new GraphError({
   message: `Node ${node} does not exist`
 });
+/** @internal */
+function assertMutable(graph) {
+  if (!graph.mutable) {
+    throw new GraphError({
+      message: "Graph is not mutable"
+    });
+  }
+}
 // =============================================================================
 // Constructors
 // =============================================================================
 /**
  * Returns `true` if a value has the graph runtime type identifier, narrowing
- * it to a `Graph`.
+ * it to an immutable or mutable graph.
  *
  * **When to use**
  *
@@ -138,36 +167,42 @@ const missingNode = node => new GraphError({
  * **Gotchas**
  *
  * This guard checks the shared graph runtime type identifier and does not
- * distinguish immutable graphs from mutable graphs.
+ * distinguish immutable graphs from mutable graphs or directed graphs from
+ * undirected graphs.
  *
  * @category guards
  * @since 4.0.0
  */
 export const isGraph = u => hasProperty(u, TypeId);
 /**
- * Creates a directed graph, optionally with initial mutations.
+ * Creates a graph constructor for the specified graph kind.
  *
- * **Example** (Creating a directed graph)
+ * **When to use**
+ *
+ * Use when the graph kind is selected dynamically. Prefer `directed` or
+ * `undirected` when the kind is known statically.
+ *
+ * **Example** (Constructing by kind)
  *
  * ```ts
  * import { Graph } from "effect"
  *
- * // Directed graph with initial nodes and edges
- * const graph = Graph.directed<string, string>((mutable) => {
- *   const a = Graph.addNode(mutable, "A")
- *   const b = Graph.addNode(mutable, "B")
- *   const c = Graph.addNode(mutable, "C")
- *   Graph.addEdge(mutable, a, b, "A->B")
- *   Graph.addEdge(mutable, b, c, "B->C")
+ * const makeGraph = Graph.make("directed")
+ * const graph = makeGraph<string, number>((mutable) => {
+ *   Graph.addNode(mutable, "A")
  * })
+ *
+ * console.log(graph.type) // "directed"
  * ```
  *
+ * @see {@link directed} for constructing a directed graph directly
+ * @see {@link undirected} for constructing an undirected graph directly
  * @category constructors
- * @since 3.18.0
+ * @since 4.0.0
  */
-export const directed = mutate => {
+export const make = type => mutate => {
   const graph = Object.create(ProtoGraph);
-  graph.type = "directed";
+  graph.type = type;
   graph.nodes = new Map();
   graph.edges = new Map();
   graph.adjacency = new Map();
@@ -175,14 +210,36 @@ export const directed = mutate => {
   graph.nextNodeIndex = 0;
   graph.nextEdgeIndex = 0;
   graph.acyclic = Option.some(true);
-  graph.mutable = false;
-  if (mutate) {
-    const mutable = beginMutation(graph);
-    mutate(mutable);
-    return endMutation(mutable);
+  if (mutate === undefined) {
+    graph.mutable = false;
+    return graph;
   }
-  return graph;
+  graph.mutable = true;
+  const mutable = Equal.byReferenceUnsafe(graph);
+  return mutateScoped(mutable, mutate);
 };
+/**
+ * Creates a directed graph, optionally with initial mutations.
+ *
+ * **Example** (Creating a directed graph)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * // Directed graph with initial nodes and edges
+ * const graph = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A->B")
+ *   Graph.addEdge(mutable, b, c, "B->C")
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 3.18.0
+ */
+export const directed = /*#__PURE__*/make("directed");
 /**
  * Creates an undirected graph, optionally with initial mutations.
  *
@@ -204,24 +261,7 @@ export const directed = mutate => {
  * @category constructors
  * @since 3.18.0
  */
-export const undirected = mutate => {
-  const graph = Object.create(ProtoGraph);
-  graph.type = "undirected";
-  graph.nodes = new Map();
-  graph.edges = new Map();
-  graph.adjacency = new Map();
-  graph.reverseAdjacency = new Map();
-  graph.nextNodeIndex = 0;
-  graph.nextEdgeIndex = 0;
-  graph.acyclic = Option.some(true);
-  graph.mutable = false;
-  if (mutate) {
-    const mutable = beginMutation(graph);
-    mutate(mutable);
-    return endMutation(mutable);
-  }
-  return graph;
-};
+export const undirected = /*#__PURE__*/make("undirected");
 // =============================================================================
 // Scoped Mutable API
 // =============================================================================
@@ -242,30 +282,29 @@ export const undirected = mutate => {
  * @since 3.18.0
  */
 export const beginMutation = graph => {
-  // Copy adjacency maps with deep cloned arrays
-  const adjacency = new Map();
-  const reverseAdjacency = new Map();
-  for (const [nodeIndex, edges] of graph.adjacency) {
-    adjacency.set(nodeIndex, [...edges]);
-  }
-  for (const [nodeIndex, edges] of graph.reverseAdjacency) {
-    reverseAdjacency.set(nodeIndex, [...edges]);
-  }
+  const source = graphImpl(graph);
+  const adjacency = cloneAdjacency(source.adjacency);
+  const reverseAdjacency = cloneAdjacency(source.reverseAdjacency);
   const mutable = Object.create(ProtoGraph);
-  mutable.type = graph.type;
-  mutable.nodes = new Map(graph.nodes);
-  mutable.edges = new Map(graph.edges);
+  mutable.type = source.type;
+  mutable.nodes = new Map(source.nodes);
+  mutable.edges = new Map(source.edges);
   mutable.adjacency = adjacency;
   mutable.reverseAdjacency = reverseAdjacency;
-  mutable.nextNodeIndex = graph.nextNodeIndex;
-  mutable.nextEdgeIndex = graph.nextEdgeIndex;
-  mutable.acyclic = graph.acyclic;
+  mutable.nextNodeIndex = source.nextNodeIndex;
+  mutable.nextEdgeIndex = source.nextEdgeIndex;
+  mutable.acyclic = source.acyclic;
   mutable.mutable = true;
-  return mutable;
+  return Equal.byReferenceUnsafe(mutable);
 };
 /**
  * Converts a mutable graph back to an immutable graph, ending the mutation scope.
  *
+ * **Details**
+ *
+ * Finalizes the mutable handle. Later public mutation operations on that handle
+ * fail with a `GraphError`.
+ *
  * **Example** (Ending a mutation scope)
  *
  * ```ts
@@ -281,16 +320,29 @@ export const beginMutation = graph => {
  * @since 3.18.0
  */
 export const endMutation = mutable => {
+  assertMutable(mutable);
+  const source = graphImpl(mutable);
   const graph = Object.create(ProtoGraph);
-  graph.type = mutable.type;
-  graph.nodes = new Map(mutable.nodes);
-  graph.edges = new Map(mutable.edges);
-  graph.adjacency = mutable.adjacency;
-  graph.reverseAdjacency = mutable.reverseAdjacency;
-  graph.nextNodeIndex = mutable.nextNodeIndex;
-  graph.nextEdgeIndex = mutable.nextEdgeIndex;
-  graph.acyclic = mutable.acyclic;
+  graph.type = source.type;
+  graph.nodes = new Map(source.nodes);
+  graph.edges = new Map(source.edges);
+  graph.adjacency = cloneAdjacency(source.adjacency);
+  graph.reverseAdjacency = cloneAdjacency(source.reverseAdjacency);
+  graph.nextNodeIndex = source.nextNodeIndex;
+  graph.nextEdgeIndex = source.nextEdgeIndex;
+  graph.acyclic = source.acyclic;
   graph.mutable = false;
+  source.mutable = false;
+  return graph;
+};
+/** @internal */
+const mutateScoped = (mutable, f) => {
+  let graph;
+  try {
+    f(mutable);
+  } finally {
+    graph = endMutation(mutable);
+  }
   return graph;
 };
 /**
@@ -317,8 +369,529 @@ export const endMutation = mutable => {
  */
 export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
   const mutable = beginMutation(graph);
-  f(mutable);
-  return endMutation(mutable);
+  return mutateScoped(mutable, f);
+});
+/** @internal */
+class EdgeIdentity {
+  type;
+  source;
+  target;
+  identity;
+  constructor(type, source, target, identity) {
+    this.type = type;
+    this.source = source;
+    this.target = target;
+    this.identity = identity;
+  }
+  [Equal.symbol](that) {
+    if (!(that instanceof EdgeIdentity) || this.type !== that.type || !Equal.equals(this.identity, that.identity)) {
+      return false;
+    }
+    if (this.type === "directed") {
+      return Equal.equals(this.source, that.source) && Equal.equals(this.target, that.target);
+    }
+    return Equal.equals(this.source, that.source) && Equal.equals(this.target, that.target) || Equal.equals(this.source, that.target) && Equal.equals(this.target, that.source);
+  }
+  [Hash.symbol]() {
+    const hash = Hash.hash(this.identity);
+    return this.type === "directed" ? Hash.combine(Hash.hash(this.target))(Hash.combine(Hash.hash(this.source))(hash)) : Hash.optimize(hash ^ Hash.hash(this.source) + Hash.hash(this.target));
+  }
+}
+/** @internal */
+const buildNodeMaps = (graph, identity) => {
+  const impl = graphImpl(graph);
+  const byIdentity = MutableHashMap.empty();
+  const byIndex = new Map();
+  for (const [index, data] of impl.nodes) {
+    const nodeIdentity = identity(data);
+    MutableHashMap.set(byIdentity, nodeIdentity, data);
+    byIndex.set(index, nodeIdentity);
+  }
+  return {
+    byIdentity,
+    byIndex
+  };
+};
+/** @internal */
+const nodeIdentityAt = (maps, index) => maps.byIndex.get(index);
+/** @internal */
+const buildEdgeMap = (graph, nodeMaps, identity) => {
+  const impl = graphImpl(graph);
+  const edges = MutableHashMap.empty();
+  for (const edge of impl.edges.values()) {
+    const sourceIdentity = nodeIdentityAt(nodeMaps, edge.source);
+    const targetIdentity = nodeIdentityAt(nodeMaps, edge.target);
+    MutableHashMap.set(edges, new EdgeIdentity(graph.type, sourceIdentity, targetIdentity, identity(edge.data)), edge.data);
+  }
+  return edges;
+};
+/** @internal */
+const addNodesByIdentity = (mutable, nodes) => {
+  const indexByIdentity = MutableHashMap.empty();
+  for (const [identity, data] of nodes) {
+    MutableHashMap.set(indexByIdentity, identity, addNode(mutable, data));
+  }
+  return indexByIdentity;
+};
+/** @internal */
+const addEdgeByIdentity = (mutable, indexByIdentity, identity, data) => {
+  const sourceIndex = Option.getOrUndefined(MutableHashMap.get(indexByIdentity, identity.source));
+  const targetIndex = Option.getOrUndefined(MutableHashMap.get(indexByIdentity, identity.target));
+  if (sourceIndex !== undefined && targetIndex !== undefined) {
+    addEdge(mutable, sourceIndex, targetIndex, data);
+  }
+};
+/** @internal */
+const assertSameKind = (self, that) => {
+  if (self.type !== that.type) {
+    throw new GraphError({
+      message: `Cannot combine ${self.type} and ${that.type} graphs`
+    });
+  }
+};
+/**
+ * Composes two graphs, merging nodes by identity.
+ *
+ * **Details**
+ *
+ * Nodes and edges present in both graphs use data from `that`. The result has
+ * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+ * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+ * edge data. Edge identity also includes the endpoint identities.
+ *
+ * `G1 ∪ G2 = {V1 ∪ V2, E1 ∪ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * Parallel edges with equal identities are also coalesced, with the last edge
+ * supplying the data.
+ *
+ * **Example** (Combining graphs)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<{ id: string }, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, { id: "A" })
+ *   const b = Graph.addNode(mutable, { id: "B" })
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ * })
+ *
+ * const right = Graph.directed<{ id: string }, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, { id: "B" })
+ *   const c = Graph.addNode(mutable, { id: "C" })
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const result = Graph.compose(left, right, {
+ *   nodeIdentity: (node) => node.id
+ * })
+ *
+ * console.log(Graph.nodeCount(result)) // 3
+ * console.log(Graph.edgeCount(result)) // 2
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const compose = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(args[1]), (self, that, options) => {
+  assertSameKind(self, that);
+  const getNodeIdentity = options?.nodeIdentity ?? (node => node);
+  const getEdgeIdentity = options?.edgeIdentity ?? (edge => edge);
+  const selfMaps = buildNodeMaps(self, getNodeIdentity);
+  const thatMaps = buildNodeMaps(that, getNodeIdentity);
+  const nodes = MutableHashMap.empty();
+  const edges = buildEdgeMap(self, selfMaps, getEdgeIdentity);
+  for (const [identity, data] of selfMaps.byIdentity) {
+    MutableHashMap.set(nodes, identity, data);
+  }
+  for (const [identity, data] of thatMaps.byIdentity) {
+    MutableHashMap.set(nodes, identity, data);
+  }
+  for (const [identity, data] of buildEdgeMap(that, thatMaps, getEdgeIdentity)) {
+    MutableHashMap.set(edges, identity, data);
+  }
+  return make(self.type)(mutable => {
+    const indexByIdentity = addNodesByIdentity(mutable, nodes);
+    for (const [identity, data] of edges) {
+      addEdgeByIdentity(mutable, indexByIdentity, identity, data);
+    }
+  });
+});
+/**
+ * Returns the intersection of two graphs, matching nodes by identity.
+ *
+ * **Details**
+ *
+ * Node data comes from `self`, and edge data comes from `that`. The result has
+ * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+ * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+ * edge data. Edge identity also includes the endpoint identities.
+ *
+ * `G1 ∩ G2 = {V1 ∩ V2, E1 ∩ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * The result contains at most one edge for each shared edge identity.
+ *
+ * **Example** (Finding shared structure)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, a, b, "shared")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, a, b, "shared")
+ * })
+ *
+ * const result = Graph.intersection(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 2
+ * console.log(Graph.edgeCount(result)) // 1
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const intersection = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(args[1]), (self, that, options) => {
+  assertSameKind(self, that);
+  const thatImpl = graphImpl(that);
+  const getNodeIdentity = options?.nodeIdentity ?? (node => node);
+  const getEdgeIdentity = options?.edgeIdentity ?? (edge => edge);
+  const selfMaps = buildNodeMaps(self, getNodeIdentity);
+  const thatMaps = buildNodeMaps(that, getNodeIdentity);
+  const nodes = MutableHashMap.empty();
+  const selfEdges = buildEdgeMap(self, selfMaps, getEdgeIdentity);
+  const thatEdges = MutableHashMap.empty();
+  for (const [identity, data] of selfMaps.byIdentity) {
+    if (MutableHashMap.has(thatMaps.byIdentity, identity)) {
+      MutableHashMap.set(nodes, identity, data);
+    }
+  }
+  for (const edge of thatImpl.edges.values()) {
+    const sourceIdentity = nodeIdentityAt(thatMaps, edge.source);
+    const targetIdentity = nodeIdentityAt(thatMaps, edge.target);
+    if (MutableHashMap.has(nodes, sourceIdentity) && MutableHashMap.has(nodes, targetIdentity)) {
+      const edgeIdentity = new EdgeIdentity(that.type, sourceIdentity, targetIdentity, getEdgeIdentity(edge.data));
+      MutableHashMap.set(thatEdges, edgeIdentity, edge.data);
+    }
+  }
+  return make(self.type)(mutable => {
+    const indexByIdentity = addNodesByIdentity(mutable, nodes);
+    for (const [identity, data] of thatEdges) {
+      if (MutableHashMap.has(selfEdges, identity)) {
+        addEdgeByIdentity(mutable, indexByIdentity, identity, data);
+      }
+    }
+  });
+});
+/**
+ * Returns `self` without edges also present in `that`.
+ *
+ * **Details**
+ *
+ * All nodes from `self` are preserved. Edges are matched by endpoint and edge
+ * identities. The result has the same graph kind as `self`. Throws a
+ * `GraphError` when the graph kinds do not match. `nodeIdentity` and
+ * `edgeIdentity` default to the complete node and edge data.
+ *
+ * `G1 \ G2 = {V1, E1 \ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * If `that` contains an edge identity, every parallel edge with that identity
+ * is removed from `self`.
+ *
+ * **Example** (Removing shared edges)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const result = Graph.difference(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 3
+ * console.log(Graph.edgeCount(result)) // 1
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const difference = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(args[1]), (self, that, options) => {
+  assertSameKind(self, that);
+  const selfImpl = graphImpl(self);
+  const getNodeIdentity = options?.nodeIdentity ?? (node => node);
+  const getEdgeIdentity = options?.edgeIdentity ?? (edge => edge);
+  const selfMaps = buildNodeMaps(self, getNodeIdentity);
+  const thatMaps = buildNodeMaps(that, getNodeIdentity);
+  const thatEdges = buildEdgeMap(that, thatMaps, getEdgeIdentity);
+  return make(self.type)(mutable => {
+    const indexByIdentity = addNodesByIdentity(mutable, selfMaps.byIdentity);
+    for (const edge of selfImpl.edges.values()) {
+      const sourceIdentity = nodeIdentityAt(selfMaps, edge.source);
+      const targetIdentity = nodeIdentityAt(selfMaps, edge.target);
+      const edgeIdentity = new EdgeIdentity(self.type, sourceIdentity, targetIdentity, getEdgeIdentity(edge.data));
+      if (!MutableHashMap.has(thatEdges, edgeIdentity)) {
+        addEdgeByIdentity(mutable, indexByIdentity, edgeIdentity, edge.data);
+      }
+    }
+  });
+});
+/**
+ * Returns edges present in exactly one of two graphs.
+ *
+ * **Details**
+ *
+ * Keeps nodes from both graphs. Overlapping nodes use data from `that`. The
+ * result has the same graph kind as `self`. Throws a `GraphError` when the
+ * graph kinds do not match. `nodeIdentity` and `edgeIdentity` default to the
+ * complete node and edge data. Edge identity also includes the endpoint
+ * identities.
+ *
+ * `G1 Δ G2 = {V1 ∪ V2, (E1 ∪ E2) \ (E1 ∩ E2)}`
+ *
+ * **Gotchas**
+ *
+ * Edges with different projected identities are distinct.
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * Parallel edges with equal identities are coalesced before the graphs are
+ * compared.
+ *
+ * **Example** (Finding differing edges)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   const d = Graph.addNode(mutable, "D")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ *   Graph.addEdge(mutable, c, d, "C-D")
+ * })
+ *
+ * const result = Graph.symmetricDifference(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 4
+ * console.log(Graph.edgeCount(result)) // 2
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const symmetricDifference = /*#__PURE__*/dual(args => isGraph(args[0]) && isGraph(args[1]), (self, that, options) => {
+  assertSameKind(self, that);
+  const getNodeIdentity = options?.nodeIdentity ?? (node => node);
+  const getEdgeIdentity = options?.edgeIdentity ?? (edge => edge);
+  const selfMaps = buildNodeMaps(self, getNodeIdentity);
+  const thatMaps = buildNodeMaps(that, getNodeIdentity);
+  const nodes = MutableHashMap.empty();
+  const selfEdges = buildEdgeMap(self, selfMaps, getEdgeIdentity);
+  const thatEdges = buildEdgeMap(that, thatMaps, getEdgeIdentity);
+  for (const [identity, data] of selfMaps.byIdentity) {
+    MutableHashMap.set(nodes, identity, data);
+  }
+  for (const [identity, data] of thatMaps.byIdentity) {
+    MutableHashMap.set(nodes, identity, data);
+  }
+  return make(self.type)(mutable => {
+    const indexByIdentity = addNodesByIdentity(mutable, nodes);
+    for (const [identity, data] of selfEdges) {
+      if (!MutableHashMap.has(thatEdges, identity)) {
+        addEdgeByIdentity(mutable, indexByIdentity, identity, data);
+      }
+    }
+    for (const [identity, data] of thatEdges) {
+      if (!MutableHashMap.has(selfEdges, identity)) {
+        addEdgeByIdentity(mutable, indexByIdentity, identity, data);
+      }
+    }
+  });
+});
+/**
+ * Returns the complement over the existing node set.
+ *
+ * **Details**
+ *
+ * Adds every missing edge between distinct nodes. The `createEdge` function
+ * receives the source and target node data for each added edge. The result has
+ * the same graph kind as `self`.
+ *
+ * `G' = {V, (V x V) \ E}`
+ *
+ * **Example** (Finding missing relationships)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const graph = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ * })
+ *
+ * const result = Graph.complement(graph, (source, target) => `${source}-${target}`)
+ *
+ * console.log(Graph.edgeCount(result)) // 1
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const complement = /*#__PURE__*/dual(2, (self, createEdge) => {
+  const selfImpl = graphImpl(self);
+  const nodeEntries = Array.from(selfImpl.nodes);
+  return make(self.type)(mutable => {
+    const newIndexMap = new Map();
+    for (const [oldIndex, data] of nodeEntries) {
+      newIndexMap.set(oldIndex, addNode(mutable, data));
+    }
+    for (let i = 0; i < nodeEntries.length; i++) {
+      const [sourceOldIndex, sourceData] = nodeEntries[i];
+      const start = self.type === "undirected" ? i + 1 : 0;
+      for (let j = start; j < nodeEntries.length; j++) {
+        const [targetOldIndex, targetData] = nodeEntries[j];
+        if (sourceOldIndex === targetOldIndex || hasEdge(self, sourceOldIndex, targetOldIndex)) {
+          continue;
+        }
+        const sourceIndex = newIndexMap.get(sourceOldIndex);
+        const targetIndex = newIndexMap.get(targetOldIndex);
+        if (sourceIndex !== undefined && targetIndex !== undefined) {
+          addEdge(mutable, sourceIndex, targetIndex, createEdge(sourceData, targetData));
+        }
+      }
+    }
+  });
+});
+/**
+ * Returns the induced subgraph containing nodes within a radius of a node.
+ *
+ * **Details**
+ *
+ * The `radius` option is the maximum edge distance from `nodeIndex` and
+ * defaults to `1`. The `direction` option controls directed graph traversal and
+ * defaults to `"outgoing"`. The result has the same graph kind as `self` and
+ * keeps all original edges whose endpoints are both reached. `"undirected"`
+ * ignores edge direction while finding reachable nodes.
+ *
+ * **Example** (Getting a local neighborhood)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const graph = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const result = Graph.neighborhood(graph, 1, { radius: 1 })
+ *
+ * console.log(Graph.nodeCount(result)) // 2
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const neighborhood = /*#__PURE__*/dual(args => isGraph(args[0]), (self, nodeIndex, options) => {
+  const selfImpl = graphImpl(self);
+  const radius = options?.radius ?? 1;
+  const direction = options?.direction ?? "outgoing";
+  const reached = new Set();
+  for (const index of indices(bfs(self, {
+    start: [nodeIndex],
+    direction,
+    radius
+  }))) {
+    reached.add(index);
+  }
+  return make(self.type)(mutable => {
+    const newIndexMap = new Map();
+    for (const oldIndex of reached) {
+      newIndexMap.set(oldIndex, addNode(mutable, Option.getOrThrow(getNode(self, oldIndex))));
+    }
+    for (const edge of selfImpl.edges.values()) {
+      if (reached.has(edge.source) && reached.has(edge.target)) {
+        const sourceIndex = newIndexMap.get(edge.source);
+        const targetIndex = newIndexMap.get(edge.target);
+        if (sourceIndex !== undefined && targetIndex !== undefined) {
+          addEdge(mutable, sourceIndex, targetIndex, edge.data);
+        }
+      }
+    }
+  });
+});
+/**
+ * Returns the disjoint union of two graphs.
+ *
+ * **Details**
+ *
+ * Copies all nodes and edges from both graphs without merging equal node data.
+ * The result has the same graph kind as `self`. Throws a `GraphError` when the
+ * graph kinds do not match.
+ *
+ * `G1 + G2 = {disjoint V1 + V2, disjoint E1 + E2}`
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export const sum = /*#__PURE__*/dual(2, (self, that) => {
+  assertSameKind(self, that);
+  return make(self.type)(mutable => {
+    const copyInto = graph => {
+      const impl = graphImpl(graph);
+      const indexMap = new Map();
+      for (const [oldIndex, data] of impl.nodes) {
+        indexMap.set(oldIndex, addNode(mutable, data));
+      }
+      for (const edge of impl.edges.values()) {
+        const sourceIndex = indexMap.get(edge.source);
+        const targetIndex = indexMap.get(edge.target);
+        if (sourceIndex !== undefined && targetIndex !== undefined) {
+          addEdge(mutable, sourceIndex, targetIndex, edge.data);
+        }
+      }
+    };
+    copyInto(self);
+    copyInto(that);
+  });
 });
 // =============================================================================
 // Basic Node Operations
@@ -362,14 +935,16 @@ export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
  * @since 3.18.0
  */
 export const addNode = (mutable, data) => {
-  const nodeIndex = mutable.nextNodeIndex;
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
+  const nodeIndex = impl.nextNodeIndex;
   // Add node data
-  mutable.nodes.set(nodeIndex, data);
+  impl.nodes.set(nodeIndex, data);
   // Initialize empty adjacency lists
-  mutable.adjacency.set(nodeIndex, []);
-  mutable.reverseAdjacency.set(nodeIndex, []);
+  impl.adjacency.set(nodeIndex, []);
+  impl.reverseAdjacency.set(nodeIndex, []);
   // Update graph allocators
-  mutable.nextNodeIndex = mutable.nextNodeIndex + 1;
+  impl.nextNodeIndex = impl.nextNodeIndex + 1;
   return nodeIndex;
 };
 /**
@@ -395,7 +970,10 @@ export const addNode = (mutable, data) => {
  * @category getters
  * @since 3.18.0
  */
-export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.has(nodeIndex) ? Option.some(graph.nodes.get(nodeIndex)) : Option.none());
+export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
+  const impl = graphImpl(graph);
+  return impl.nodes.has(nodeIndex) ? Option.some(impl.nodes.get(nodeIndex)) : Option.none();
+});
 /**
  * Checks whether a node with the given index exists in the graph.
  *
@@ -420,7 +998,7 @@ export const getNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.ha
  * @category getters
  * @since 3.18.0
  */
-export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.has(nodeIndex));
+export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graphImpl(graph).nodes.has(nodeIndex));
 /**
  * Returns the number of nodes in the graph.
  *
@@ -444,7 +1022,7 @@ export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.ha
  * @category getters
  * @since 3.18.0
  */
-export const nodeCount = graph => graph.nodes.size;
+export const nodeCount = graph => graphImpl(graph).nodes.size;
 /**
  * Finds the first node that matches the given predicate.
  *
@@ -470,7 +1048,8 @@ export const nodeCount = graph => graph.nodes.size;
  * @since 3.18.0
  */
 export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
-  for (const [index, data] of graph.nodes) {
+  const impl = graphImpl(graph);
+  for (const [index, data] of impl.nodes) {
     if (predicate(data)) {
       return Option.some(index);
     }
@@ -502,8 +1081,9 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
  * @since 3.18.0
  */
 export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
+  const impl = graphImpl(graph);
   const results = [];
-  for (const [index, data] of graph.nodes) {
+  for (const [index, data] of impl.nodes) {
     if (predicate(data)) {
       results.push(index);
     }
@@ -537,7 +1117,8 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
  * @since 3.18.0
  */
 export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
-  for (const [edgeIndex, edgeData] of graph.edges) {
+  const impl = graphImpl(graph);
+  for (const [edgeIndex, edgeData] of impl.edges) {
     if (predicate(edgeData.data, edgeData.source, edgeData.target)) {
       return Option.some(edgeIndex);
     }
@@ -572,8 +1153,9 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
  * @since 3.18.0
  */
 export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
+  const impl = graphImpl(graph);
   const results = [];
-  for (const [edgeIndex, edgeData] of graph.edges) {
+  for (const [edgeIndex, edgeData] of impl.edges) {
     if (predicate(edgeData.data, edgeData.source, edgeData.target)) {
       results.push(edgeIndex);
     }
@@ -602,12 +1184,14 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
  * @since 3.18.0
  */
 export const updateNode = (mutable, index, f) => {
-  if (!mutable.nodes.has(index)) {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
+  if (!impl.nodes.has(index)) {
     return;
   }
-  const currentData = mutable.nodes.get(index);
+  const currentData = impl.nodes.get(index);
   const newData = f(currentData);
-  mutable.nodes.set(index, newData);
+  impl.nodes.set(index, newData);
 };
 /**
  * Updates a single edge's data by applying a transformation function.
@@ -632,12 +1216,14 @@ export const updateNode = (mutable, index, f) => {
  * @since 3.18.0
  */
 export const updateEdge = (mutable, edgeIndex, f) => {
-  if (!mutable.edges.has(edgeIndex)) {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
+  if (!impl.edges.has(edgeIndex)) {
     return;
   }
-  const currentEdge = mutable.edges.get(edgeIndex);
+  const currentEdge = impl.edges.get(edgeIndex);
   const newData = f(currentEdge.data);
-  mutable.edges.set(edgeIndex, new Edge({
+  impl.edges.set(edgeIndex, new Edge({
     ...currentEdge,
     data: newData
   }));
@@ -670,10 +1256,12 @@ export const updateEdge = (mutable, edgeIndex, f) => {
  * @since 3.18.0
  */
 export const mapNodes = (mutable, f) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   // Transform existing node data in place
-  for (const [index, data] of mutable.nodes) {
+  for (const [index, data] of impl.nodes) {
     const newData = f(data);
-    mutable.nodes.set(index, newData);
+    impl.nodes.set(index, newData);
   }
 };
 /**
@@ -701,13 +1289,15 @@ export const mapNodes = (mutable, f) => {
  * @since 3.18.0
  */
 export const mapEdges = (mutable, f) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   // Transform existing edge data in place
-  for (const [index, edgeData] of mutable.edges) {
+  for (const [index, edgeData] of impl.edges) {
     const newData = f(edgeData.data);
-    mutable.edges.set(index, {
+    impl.edges.set(index, new Edge({
       ...edgeData,
       data: newData
-    });
+    }));
   }
 };
 /**
@@ -754,20 +1344,22 @@ const rebuildAdjacency = mutable => {
  * @since 3.18.0
  */
 export const reverse = mutable => {
-  if (mutable.type === "undirected") {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
+  if (impl.type === "undirected") {
     return;
   }
   // Reverse all edges by swapping source and target
-  for (const [index, edgeData] of mutable.edges) {
-    mutable.edges.set(index, new Edge({
+  for (const [index, edgeData] of impl.edges) {
+    impl.edges.set(index, new Edge({
       source: edgeData.target,
       target: edgeData.source,
       data: edgeData.data
     }));
   }
-  rebuildAdjacency(mutable);
+  rebuildAdjacency(impl);
   // Invalidate cycle flag since edge directions changed
-  mutable.acyclic = Option.none();
+  impl.acyclic = Option.none();
 };
 /**
  * Filters and optionally transforms nodes in a mutable graph using a predicate function.
@@ -800,13 +1392,15 @@ export const reverse = mutable => {
  * @since 3.18.0
  */
 export const filterMapNodes = (mutable, f) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   const nodesToRemove = [];
   // First pass: identify nodes to remove and transform data for nodes to keep
-  for (const [index, data] of mutable.nodes) {
+  for (const [index, data] of impl.nodes) {
     const result = f(data);
     if (Option.isSome(result)) {
       // Transform node data
-      mutable.nodes.set(index, result.value);
+      impl.nodes.set(index, result.value);
     } else {
       // Mark for removal
       nodesToRemove.push(index);
@@ -848,16 +1442,18 @@ export const filterMapNodes = (mutable, f) => {
  * @since 3.18.0
  */
 export const filterMapEdges = (mutable, f) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   const edgesToRemove = [];
   // First pass: identify edges to remove and transform data for edges to keep
-  for (const [index, edgeData] of mutable.edges) {
+  for (const [index, edgeData] of impl.edges) {
     const result = f(edgeData.data);
     if (Option.isSome(result)) {
       // Transform edge data
-      mutable.edges.set(index, {
+      impl.edges.set(index, new Edge({
         ...edgeData,
         data: result.value
-      });
+      }));
     } else {
       // Mark for removal
       edgesToRemove.push(index);
@@ -894,9 +1490,11 @@ export const filterMapEdges = (mutable, f) => {
  * @since 3.18.0
  */
 export const filterNodes = (mutable, predicate) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   const nodesToRemove = [];
   // Identify nodes to remove
-  for (const [index, data] of mutable.nodes) {
+  for (const [index, data] of impl.nodes) {
     if (!predicate(data)) {
       nodesToRemove.push(index);
     }
@@ -935,9 +1533,11 @@ export const filterNodes = (mutable, predicate) => {
  * @since 3.18.0
  */
 export const filterEdges = (mutable, predicate) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   const edgesToRemove = [];
   // Identify edges to remove
-  for (const [index, edgeData] of mutable.edges) {
+  for (const [index, edgeData] of impl.edges) {
     if (!predicate(edgeData.data)) {
       edgesToRemove.push(index);
     }
@@ -1008,46 +1608,48 @@ const invalidateCycleFlagOnAddition = mutable => {
  * @since 3.18.0
  */
 export const addEdge = (mutable, source, target, data) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   // Validate that both nodes exist
-  if (!mutable.nodes.has(source)) {
+  if (!impl.nodes.has(source)) {
     throw missingNode(source);
   }
-  if (!mutable.nodes.has(target)) {
+  if (!impl.nodes.has(target)) {
     throw missingNode(target);
   }
-  const edgeIndex = mutable.nextEdgeIndex;
+  const edgeIndex = impl.nextEdgeIndex;
   // Create edge data
   const edgeData = new Edge({
     source,
     target,
     data
   });
-  mutable.edges.set(edgeIndex, edgeData);
+  impl.edges.set(edgeIndex, edgeData);
   // Update adjacency lists
-  const sourceAdjacency = mutable.adjacency.get(source);
+  const sourceAdjacency = impl.adjacency.get(source);
   if (sourceAdjacency !== undefined) {
     sourceAdjacency.push(edgeIndex);
   }
-  const targetReverseAdjacency = mutable.reverseAdjacency.get(target);
+  const targetReverseAdjacency = impl.reverseAdjacency.get(target);
   if (targetReverseAdjacency !== undefined) {
     targetReverseAdjacency.push(edgeIndex);
   }
   // For undirected graphs, add reverse connections
-  if (mutable.type === "undirected") {
-    const targetAdjacency = mutable.adjacency.get(target);
+  if (impl.type === "undirected") {
+    const targetAdjacency = impl.adjacency.get(target);
     if (targetAdjacency !== undefined) {
       targetAdjacency.push(edgeIndex);
     }
-    const sourceReverseAdjacency = mutable.reverseAdjacency.get(source);
+    const sourceReverseAdjacency = impl.reverseAdjacency.get(source);
     if (sourceReverseAdjacency !== undefined) {
       sourceReverseAdjacency.push(edgeIndex);
     }
   }
   // Update allocators
-  mutable.nextEdgeIndex = mutable.nextEdgeIndex + 1;
+  impl.nextEdgeIndex = impl.nextEdgeIndex + 1;
   // Only invalidate cycle flag if the graph was acyclic
   // Adding edges cannot remove cycles from cyclic graphs
-  invalidateCycleFlagOnAddition(mutable);
+  invalidateCycleFlagOnAddition(impl);
   return edgeIndex;
 };
 /**
@@ -1072,21 +1674,23 @@ export const addEdge = (mutable, source, target, data) => {
  * @since 3.18.0
  */
 export const removeNode = (mutable, nodeIndex) => {
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
   // Check if node exists
-  if (!mutable.nodes.has(nodeIndex)) {
+  if (!impl.nodes.has(nodeIndex)) {
     return; // Node doesn't exist, nothing to remove
   }
   // Collect all incident edges for removal
   const edgesToRemove = [];
   // Get outgoing edges
-  const outgoingEdges = mutable.adjacency.get(nodeIndex);
+  const outgoingEdges = impl.adjacency.get(nodeIndex);
   if (outgoingEdges !== undefined) {
     for (const edge of outgoingEdges) {
       edgesToRemove.push(edge);
     }
   }
   // Get incoming edges
-  const incomingEdges = mutable.reverseAdjacency.get(nodeIndex);
+  const incomingEdges = impl.reverseAdjacency.get(nodeIndex);
   if (incomingEdges !== undefined) {
     for (const edge of incomingEdges) {
       edgesToRemove.push(edge);
@@ -1094,15 +1698,15 @@ export const removeNode = (mutable, nodeIndex) => {
   }
   // Remove all incident edges
   for (const edgeIndex of edgesToRemove) {
-    removeEdgeInternal(mutable, edgeIndex);
+    removeEdgeInternal(impl, edgeIndex);
   }
   // Remove the node itself
-  mutable.nodes.delete(nodeIndex);
-  mutable.adjacency.delete(nodeIndex);
-  mutable.reverseAdjacency.delete(nodeIndex);
+  impl.nodes.delete(nodeIndex);
+  impl.adjacency.delete(nodeIndex);
+  impl.reverseAdjacency.delete(nodeIndex);
   // Only invalidate cycle flag if the graph wasn't already known to be acyclic
   // Removing nodes cannot introduce cycles in an acyclic graph
-  invalidateCycleFlagOnRemoval(mutable);
+  invalidateCycleFlagOnRemoval(impl);
 };
 /**
  * Removes an edge from a mutable graph.
@@ -1126,11 +1730,13 @@ export const removeNode = (mutable, nodeIndex) => {
  * @since 3.18.0
  */
 export const removeEdge = (mutable, edgeIndex) => {
-  const wasRemoved = removeEdgeInternal(mutable, edgeIndex);
+  assertMutable(mutable);
+  const impl = graphImpl(mutable);
+  const wasRemoved = removeEdgeInternal(impl, edgeIndex);
   // Only invalidate cycle flag if an edge was actually removed
   // and only if the graph wasn't already known to be acyclic
   if (wasRemoved) {
-    invalidateCycleFlagOnRemoval(mutable);
+    invalidateCycleFlagOnRemoval(impl);
   }
 };
 /** @internal */
@@ -1210,7 +1816,7 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  * @category getters
  * @since 3.18.0
  */
-export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUndefinedOr(graph.edges.get(edgeIndex)));
+export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUndefinedOr(graphImpl(graph).edges.get(edgeIndex)));
 /**
  * Checks whether an edge exists between two nodes in the graph.
  *
@@ -1241,13 +1847,14 @@ export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUnd
  * @since 3.18.0
  */
 export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
-  const adjacencyList = graph.adjacency.get(source);
+  const impl = graphImpl(graph);
+  const adjacencyList = impl.adjacency.get(source);
   if (adjacencyList === undefined) {
     return false;
   }
   // Check if any edge in the adjacency list connects to the target
   for (const edgeIndex of adjacencyList) {
-    const edge = graph.edges.get(edgeIndex);
+    const edge = impl.edges.get(edgeIndex);
     if (edge !== undefined) {
       const neighbor = graph.type === "undirected" && edge.target === source ? edge.source : edge.target;
       if (neighbor === target) {
@@ -1283,16 +1890,17 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
  * @category getters
  * @since 3.18.0
  */
-export const edgeCount = graph => graph.edges.size;
+export const edgeCount = graph => graphImpl(graph).edges.size;
 const getDirectedNeighbors = (graph, nodeIndex, direction) => {
-  const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
+  const impl = graphImpl(graph);
+  const adjacencyMap = direction === "incoming" ? impl.reverseAdjacency : impl.adjacency;
   const adjacencyList = adjacencyMap.get(nodeIndex);
   if (adjacencyList === undefined) {
     return [];
   }
   const result = [];
   for (const edgeIndex of adjacencyList) {
-    const edge = graph.edges.get(edgeIndex);
+    const edge = impl.edges.get(edgeIndex);
     if (edge !== undefined) {
       result.push(direction === "incoming" ? edge.source : edge.target);
     }
@@ -1440,6 +2048,7 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
   }
   return getDirectedNeighbors(graph, nodeIndex, direction);
 });
+const escapeGraphVizString = value => value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\r\n|\r|\n/g, "\\n");
 /**
  * Exports a graph to GraphViz DOT format for visualization.
  *
@@ -1459,7 +2068,7 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
  *
  * const dot = Graph.toGraphViz(graph)
  * console.log(dot)
- * // digraph G {
+ * // digraph "G" {
  * //   "0" [label="Node A"];
  * //   "1" [label="Node B"];
  * //   "2" [label="Node C"];
@@ -1473,6 +2082,7 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
  * @since 3.18.0
  */
 export const toGraphViz = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, options) => {
+  const impl = graphImpl(graph);
   const {
     edgeLabel = data => String(data),
     graphName = "G",
@@ -1481,16 +2091,17 @@ export const toGraphViz = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, op
   const isDirected = graph.type === "directed";
   const graphType = isDirected ? "digraph" : "graph";
   const edgeOperator = isDirected ? "->" : "--";
+  const graphId = `"${escapeGraphVizString(graphName)}"`;
   const lines = [];
-  lines.push(`${graphType} ${graphName} {`);
+  lines.push(`${graphType} ${graphId} {`);
   // Add nodes
-  for (const [nodeIndex, nodeData] of graph.nodes) {
-    const label = nodeLabel(nodeData).replace(/"/g, "\\\"");
+  for (const [nodeIndex, nodeData] of impl.nodes) {
+    const label = escapeGraphVizString(nodeLabel(nodeData));
     lines.push(`  "${nodeIndex}" [label="${label}"];`);
   }
   // Add edges
-  for (const [, edgeData] of graph.edges) {
-    const label = edgeLabel(edgeData.data).replace(/"/g, "\\\"");
+  for (const [, edgeData] of impl.edges) {
+    const label = escapeGraphVizString(edgeLabel(edgeData.data));
     lines.push(`  "${edgeData.source}" ${edgeOperator} "${edgeData.target}" [label="${label}"];`);
   }
   lines.push("}");
@@ -1661,22 +2272,22 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *     name: "MyApp",
  *     version: "1.0.0",
  *     type: "library"
- *   })
+ *   } satisfies Dependency)
  *   const react = Graph.addNode(mutable, {
  *     name: "React",
  *     version: "18.0.0",
  *     type: "framework"
- *   })
+ *   } satisfies Dependency)
  *   const lodash = Graph.addNode(mutable, {
  *     name: "Lodash",
  *     version: "4.17.0",
  *     type: "library"
- *   })
+ *   } satisfies Dependency)
  *   const webpack = Graph.addNode(mutable, {
  *     name: "Webpack",
  *     version: "5.0.0",
  *     type: "tool"
- *   })
+ *   } satisfies Dependency)
  *
  *   Graph.addEdge(mutable, app, react, "depends on")
  *   Graph.addEdge(mutable, app, lodash, "depends on")
@@ -1710,6 +2321,7 @@ const formatMermaidNode = (nodeId, label, shape) => {
  * @since 3.18.0
  */
 export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, options) => {
+  const impl = graphImpl(graph);
   // Extract and validate options with defaults
   const {
     diagramType,
@@ -1724,7 +2336,7 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
   const lines = [];
   lines.push(`${finalDiagramType} ${direction}`);
   // Add nodes
-  for (const [nodeIndex, nodeData] of graph.nodes) {
+  for (const [nodeIndex, nodeData] of impl.nodes) {
     const nodeId = String(nodeIndex);
     const label = escapeMermaidLabel(nodeLabel(nodeData));
     const shape = nodeShape(nodeData);
@@ -1733,7 +2345,7 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
   }
   // Add edges
   const edgeOperator = finalDiagramType === "flowchart" ? "-->" : "---";
-  for (const [, edgeData] of graph.edges) {
+  for (const [, edgeData] of impl.edges) {
     const sourceId = String(edgeData.source);
     const targetId = String(edgeData.target);
     const label = escapeMermaidLabel(edgeLabel(edgeData.data));
@@ -1755,7 +2367,8 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  *
  * Uses depth-first search to detect back edges, which indicate cycles.
  * For directed graphs, any back edge creates a cycle. For undirected graphs,
- * a back edge that doesn't go to the immediate parent creates a cycle.
+ * a back edge that doesn't use the same edge used to enter the current node
+ * creates a cycle.
  *
  * **Example** (Checking cycles)
  *
@@ -1786,49 +2399,61 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  * @since 3.18.0
  */
 export const isAcyclic = graph => {
+  const impl = graphImpl(graph);
   // Use existing cycle flag if available
-  if (Option.isSome(graph.acyclic)) {
-    return graph.acyclic.value;
+  if (Option.isSome(impl.acyclic)) {
+    return impl.acyclic.value;
   }
   if (graph.type === "undirected") {
     const visited = new Set();
-    for (const startNode of graph.nodes.keys()) {
+    for (const startNode of impl.nodes.keys()) {
       if (visited.has(startNode)) {
         continue;
       }
       visited.add(startNode);
       const stack = [{
         node: startNode,
-        parent: null
+        incoming: null
       }];
       while (stack.length > 0) {
         const {
           node,
-          parent
+          incoming
         } = stack.pop();
-        const nodeNeighbors = getUndirectedNeighbors(graph, node);
-        for (const neighbor of nodeNeighbors) {
+        const adjacencyList = impl.adjacency.get(node);
+        if (adjacencyList === undefined) {
+          continue;
+        }
+        for (const edgeIndex of adjacencyList) {
+          if (edgeIndex === incoming) {
+            continue;
+          }
+          const edge = impl.edges.get(edgeIndex);
+          if (edge === undefined) {
+            continue;
+          }
+          const neighbor = getTraversableNeighbor(graph, node, edge);
           if (!visited.has(neighbor)) {
             visited.add(neighbor);
             stack.push({
               node: neighbor,
-              parent: node
+              incoming: edgeIndex
             });
-          } else if (neighbor !== parent) {
-            graph.acyclic = Option.some(false);
+          } else {
+            impl.acyclic = Option.some(false);
             return false;
           }
         }
       }
     }
-    graph.acyclic = Option.some(true);
+    impl.acyclic = Option.some(true);
     return true;
   }
   // Stack-safe DFS cycle detection using iterative approach
   const visited = new Set();
   const recursionStack = new Set();
   // Get all nodes to handle disconnected components
-  for (const startNode of graph.nodes.keys()) {
+  for (const startNode of impl.nodes.keys()) {
     if (visited.has(startNode)) {
       continue; // Already processed this component
     }
@@ -1840,7 +2465,7 @@ export const isAcyclic = graph => {
       if (isFirstVisit) {
         if (recursionStack.has(node)) {
           // Back edge found - cycle detected
-          graph.acyclic = Option.some(false);
+          impl.acyclic = Option.some(false);
           return false;
         }
         if (visited.has(node)) {
@@ -1860,7 +2485,7 @@ export const isAcyclic = graph => {
         stack[stack.length - 1] = [node, neighbors, neighborIndex + 1, false];
         if (recursionStack.has(neighbor)) {
           // Back edge found - cycle detected
-          graph.acyclic = Option.some(false);
+          impl.acyclic = Option.some(false);
           return false;
         }
         if (!visited.has(neighbor)) {
@@ -1874,7 +2499,7 @@ export const isAcyclic = graph => {
     }
   }
   // Cache the result
-  graph.acyclic = Option.some(true);
+  impl.acyclic = Option.some(true);
   return true;
 };
 /**
@@ -1919,11 +2544,12 @@ export const isAcyclic = graph => {
  * @since 3.18.0
  */
 export const isBipartite = graph => {
+  const impl = graphImpl(graph);
   const coloring = new Map();
   const discovered = new Set();
   let isBipartiteGraph = true;
   // Get all nodes to handle disconnected components
-  for (const startNode of graph.nodes.keys()) {
+  for (const startNode of impl.nodes.keys()) {
     if (!discovered.has(startNode)) {
       // Start BFS coloring from this component
       const queue = [startNode];
@@ -1963,12 +2589,13 @@ export const isBipartite = graph => {
  * For undirected graphs, we need to find the other endpoint of each edge incident to the node.
  */
 const getUndirectedNeighbors = (graph, nodeIndex) => {
+  const impl = graphImpl(graph);
   const neighbors = new Set();
   // Check edges where this node is the source
-  const adjacencyList = graph.adjacency.get(nodeIndex);
+  const adjacencyList = impl.adjacency.get(nodeIndex);
   if (adjacencyList !== undefined) {
     for (const edgeIndex of adjacencyList) {
-      const edge = graph.edges.get(edgeIndex);
+      const edge = impl.edges.get(edgeIndex);
       if (edge !== undefined) {
         // For undirected graphs, the neighbor is the other endpoint
         const otherNode = edge.source === nodeIndex ? edge.target : edge.source;
@@ -1978,7 +2605,20 @@ const getUndirectedNeighbors = (graph, nodeIndex) => {
   }
   return Array.from(neighbors);
 };
-const getTraversalNeighbors = (graph, nodeIndex, direction) => graph.type === "undirected" ? getUndirectedNeighbors(graph, nodeIndex) : getDirectedNeighbors(graph, nodeIndex, direction);
+const getTraversalNeighbors = (graph, nodeIndex, direction) => {
+  if (graph.type === "undirected") {
+    return getUndirectedNeighbors(graph, nodeIndex);
+  }
+  const directed = graph;
+  if (direction !== "undirected") {
+    return getDirectedNeighbors(directed, nodeIndex, direction);
+  }
+  const neighbors = new Set(getDirectedNeighbors(directed, nodeIndex, "outgoing"));
+  for (const neighbor of getDirectedNeighbors(directed, nodeIndex, "incoming")) {
+    neighbors.add(neighbor);
+  }
+  return Array.from(neighbors);
+};
 const getTraversableNeighbor = (graph, current, edge) => graph.type === "undirected" && edge.target === current ? edge.source : edge.target;
 /**
  * Finds connected components in an undirected graph.
@@ -2006,9 +2646,10 @@ const getTraversableNeighbor = (graph, current, edge) => graph.type === "undirec
  * @since 3.18.0
  */
 export const connectedComponents = graph => {
+  const impl = graphImpl(graph);
   const visited = new Set();
   const components = [];
-  for (const startNode of graph.nodes.keys()) {
+  for (const startNode of impl.nodes.keys()) {
     if (!visited.has(startNode)) {
       // DFS to find all nodes in this component
       const component = [];
@@ -2067,9 +2708,10 @@ export const stronglyConnectedComponents = graph => {
       message: "Cannot find strongly connected components of undirected graph"
     });
   }
+  const impl = graphImpl(graph);
   const visited = new Set();
   const finishOrder = [];
-  for (const startNode of graph.nodes.keys()) {
+  for (const startNode of impl.nodes.keys()) {
     if (visited.has(startNode)) {
       continue;
     }
@@ -2118,10 +2760,10 @@ export const stronglyConnectedComponents = graph => {
       visited.add(node);
       scc.push(node);
       // Use reverse adjacency (transpose graph)
-      const reverseAdjacency = graph.reverseAdjacency.get(node);
+      const reverseAdjacency = impl.reverseAdjacency.get(node);
       if (reverseAdjacency !== undefined) {
         for (const edgeIndex of reverseAdjacency) {
-          const edge = graph.edges.get(edgeIndex);
+          const edge = impl.edges.get(edgeIndex);
           if (edge !== undefined) {
             const predecessor = edge.source;
             if (!visited.has(predecessor)) {
@@ -2135,18 +2777,42 @@ export const stronglyConnectedComponents = graph => {
   }
   return sccs;
 };
-const validateNonNegativeEdgeWeights = (graph, cost, algorithm) => {
-  const edgeWeights = new Map();
-  for (const [edgeIndex, edgeData] of graph.edges) {
-    const weight = cost(edgeData.data);
-    if (weight < 0 || Number.isNaN(weight)) {
-      throw new GraphError({
-        message: `${algorithm} requires non-negative edge weights`
-      });
+const minHeapLessThan = (self, that) => self.priority < that.priority || self.priority === that.priority && self.sequence < that.sequence;
+const minHeapPush = (heap, entry) => {
+  let index = heap.length;
+  heap.push(entry);
+  while (index > 0) {
+    const parent = index - 1 >>> 1;
+    if (!minHeapLessThan(entry, heap[parent])) {
+      break;
     }
-    edgeWeights.set(edgeIndex, weight);
+    heap[index] = heap[parent];
+    index = parent;
+  }
+  heap[index] = entry;
+};
+const minHeapPop = heap => {
+  const first = heap[0];
+  const last = heap.pop();
+  if (last === undefined || heap.length === 0) {
+    return first;
+  }
+  let index = 0;
+  while (true) {
+    const left = index * 2 + 1;
+    if (left >= heap.length) {
+      break;
+    }
+    const right = left + 1;
+    const child = right < heap.length && minHeapLessThan(heap[right], heap[left]) ? right : left;
+    if (!minHeapLessThan(heap[child], last)) {
+      break;
+    }
+    heap[index] = heap[child];
+    index = child;
   }
-  return edgeWeights;
+  heap[index] = last;
+  return first;
 };
 /**
  * Finds the shortest path from the configured source node to the target node
@@ -2154,9 +2820,10 @@ const validateNonNegativeEdgeWeights = (graph, cost, algorithm) => {
  *
  * **Details**
  *
- * Edge costs must be non-negative. Returns `Option.none()` when the target is
- * not reachable, and throws a `GraphError` when either endpoint is missing or a
- * negative edge cost is encountered.
+ * Edge costs must be non-negative and not `NaN`. `Infinity` is allowed and
+ * behaves like an impassable edge. Returns `Option.none()` when the target is
+ * not reachable, and throws a `GraphError` when either endpoint is missing or an
+ * edge cost is negative or `NaN`.
  *
  * **Example** (Finding shortest paths with Dijkstra)
  *
@@ -2188,14 +2855,24 @@ const validateNonNegativeEdgeWeights = (graph, cost, algorithm) => {
  * @since 3.18.0
  */
 export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
+  const impl = graphImpl(graph);
   // Validate that source and target nodes exist
-  if (!graph.nodes.has(config.source)) {
+  if (!impl.nodes.has(config.source)) {
     throw missingNode(config.source);
   }
-  if (!graph.nodes.has(config.target)) {
+  if (!impl.nodes.has(config.target)) {
     throw missingNode(config.target);
   }
-  const edgeWeights = validateNonNegativeEdgeWeights(graph, config.cost, "Dijkstra's algorithm");
+  const edgeWeights = new Map();
+  for (const [edgeIndex, edgeData] of impl.edges) {
+    const weight = config.cost(edgeData.data);
+    if (Number.isNaN(weight) || weight < 0) {
+      throw new GraphError({
+        message: "Dijkstra's algorithm requires non-negative edge weights"
+      });
+    }
+    edgeWeights.set(edgeIndex, weight);
+  }
   // Early return if source equals target
   if (config.source === config.target) {
     return Option.some({
@@ -2210,24 +2887,19 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
   const visited = new Set();
   // Initialize distances
   // Iterate directly over node keys
-  for (const node of graph.nodes.keys()) {
+  for (const node of impl.nodes.keys()) {
     distances.set(node, node === config.source ? 0 : Infinity);
     previous.set(node, null);
   }
-  // Simple priority queue using array (can be optimized with proper heap)
-  const priorityQueue = [{
+  const priorityQueue = [];
+  let sequence = 0;
+  minHeapPush(priorityQueue, {
     node: config.source,
-    distance: 0
-  }];
+    priority: 0,
+    sequence: sequence++
+  });
   while (priorityQueue.length > 0) {
-    // Find minimum distance node (priority queue extract-min)
-    let minIndex = 0;
-    for (let i = 1; i < priorityQueue.length; i++) {
-      if (priorityQueue[i].distance < priorityQueue[minIndex].distance) {
-        minIndex = i;
-      }
-    }
-    const current = priorityQueue.splice(minIndex, 1)[0];
+    const current = minHeapPop(priorityQueue);
     const currentNode = current.node;
     // Skip if already visited (can happen with duplicate entries)
     if (visited.has(currentNode)) {
@@ -2241,10 +2913,10 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
     // Get current distance
     const currentDistance = distances.get(currentNode);
     // Examine all outgoing edges
-    const adjacencyList = graph.adjacency.get(currentNode);
+    const adjacencyList = impl.adjacency.get(currentNode);
     if (adjacencyList !== undefined) {
       for (const edgeIndex of adjacencyList) {
-        const edge = graph.edges.get(edgeIndex);
+        const edge = impl.edges.get(edgeIndex);
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge);
           const cost = edgeWeights.get(edgeIndex);
@@ -2259,9 +2931,10 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
             });
             // Add to priority queue if not visited
             if (!visited.has(neighbor)) {
-              priorityQueue.push({
+              minHeapPush(priorityQueue, {
                 node: neighbor,
-                distance: newDistance
+                priority: newDistance,
+                sequence: sequence++
               });
             }
           }
@@ -2301,8 +2974,9 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  * **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, but
- * a `GraphError` is thrown if any negative cycle is detected.
+ * source and target pair in O(V^3) time. Negative edge weights are allowed, and
+ * `Infinity` behaves like an impassable edge. A `GraphError` is thrown if any
+ * edge weight is `NaN` or `-Infinity`, or if any negative cycle is detected.
  *
  * **Example** (Finding all-pairs shortest paths)
  *
@@ -2327,8 +3001,9 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  * @since 3.18.0
  */
 export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
+  const impl = graphImpl(graph);
   // Get all nodes for Floyd-Warshall algorithm (needs array for nested iteration)
-  const allNodes = Array.from(graph.nodes.keys());
+  const allNodes = Array.from(impl.nodes.keys());
   // Initialize distance matrix
   const distances = new Map();
   const next = new Map();
@@ -2340,13 +3015,16 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
     edgeMatrix.set(i, new Map());
     for (const j of allNodes) {
       distances.get(i).set(j, i === j ? 0 : Infinity);
-      next.get(i).set(j, null);
-      edgeMatrix.get(i).set(j, null);
     }
   }
   // Set edge weights
-  for (const [, edgeData] of graph.edges) {
+  for (const [, edgeData] of impl.edges) {
     const weight = cost(edgeData.data);
+    if (Number.isNaN(weight) || weight === -Infinity) {
+      throw new GraphError({
+        message: "Floyd-Warshall algorithm does not support NaN or -Infinity edge weights"
+      });
+    }
     const i = edgeData.source;
     const j = edgeData.target;
     // Use minimum weight if multiple edges exist
@@ -2373,8 +3051,11 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
         const distKJ = distances.get(k).get(j);
         const distIJ = distances.get(i).get(j);
         if (distIK !== Infinity && distKJ !== Infinity && distIK + distKJ < distIJ) {
-          distances.get(i).set(j, distIK + distKJ);
-          next.get(i).set(j, next.get(i).get(k));
+          const nextIK = next.get(i).get(k);
+          if (nextIK !== undefined) {
+            distances.get(i).set(j, distIK + distKJ);
+            next.get(i).set(j, nextIK);
+          }
         }
       }
     }
@@ -2408,10 +3089,10 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
         path.push(current);
         while (current !== j) {
           const nextNode = next.get(current).get(j);
-          if (nextNode === null) break;
-          const edgeData = edgeMatrix.get(current).get(nextNode);
-          if (edgeData !== null) {
-            weights.push(edgeData);
+          if (nextNode === undefined) break;
+          const edgeRow = edgeMatrix.get(current);
+          if (edgeRow.has(nextNode)) {
+            weights.push(edgeRow.get(nextNode));
           }
           current = nextNode;
           path.push(current);
@@ -2433,10 +3114,11 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
  *
  * **Details**
  *
- * The edge-cost function must return non-negative weights, and the heuristic
+ * The edge-cost function must return non-negative weights and not `NaN`.
+ * `Infinity` is allowed and behaves like an impassable edge. The heuristic
  * should be consistent to preserve shortest-path guarantees. Returns
  * `Option.none()` when the target is not reachable, and throws a `GraphError`
- * when either endpoint is missing or a negative edge cost is encountered.
+ * when either endpoint is missing or an edge cost is negative or `NaN`.
  *
  * **Example** (Finding shortest paths with A-star)
  *
@@ -2474,14 +3156,24 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
  * @since 3.18.0
  */
 export const astar = /*#__PURE__*/dual(2, (graph, config) => {
+  const impl = graphImpl(graph);
   // Validate that source and target nodes exist
-  if (!graph.nodes.has(config.source)) {
+  if (!impl.nodes.has(config.source)) {
     throw missingNode(config.source);
   }
-  if (!graph.nodes.has(config.target)) {
+  if (!impl.nodes.has(config.target)) {
     throw missingNode(config.target);
   }
-  const edgeWeights = validateNonNegativeEdgeWeights(graph, config.cost, "A* algorithm");
+  const edgeWeights = new Map();
+  for (const [edgeIndex, edgeData] of impl.edges) {
+    const weight = config.cost(edgeData.data);
+    if (Number.isNaN(weight) || weight < 0) {
+      throw new GraphError({
+        message: "A* algorithm requires non-negative edge weights"
+      });
+    }
+    edgeWeights.set(edgeIndex, weight);
+  }
   // Early return if source equals target
   if (config.source === config.target) {
     return Option.some({
@@ -2504,7 +3196,7 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
   const visited = new Set();
   // Initialize scores
   // Iterate directly over node keys
-  for (const node of graph.nodes.keys()) {
+  for (const node of impl.nodes.keys()) {
     gScore.set(node, node === config.source ? 0 : Infinity);
     fScore.set(node, Infinity);
     previous.set(node, null);
@@ -2515,20 +3207,15 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
     const h = config.heuristic(sourceNodeData.value, targetNodeData.value);
     fScore.set(config.source, h);
   }
-  // Priority queue using f-score (total estimated cost)
-  const openSet = [{
+  const openSet = [];
+  let sequence = 0;
+  minHeapPush(openSet, {
     node: config.source,
-    fScore: fScore.get(config.source)
-  }];
+    priority: fScore.get(config.source),
+    sequence: sequence++
+  });
   while (openSet.length > 0) {
-    // Find node with lowest f-score
-    let minIndex = 0;
-    for (let i = 1; i < openSet.length; i++) {
-      if (openSet[i].fScore < openSet[minIndex].fScore) {
-        minIndex = i;
-      }
-    }
-    const current = openSet.splice(minIndex, 1)[0];
+    const current = minHeapPop(openSet);
     const currentNode = current.node;
     // Skip if already visited
     if (visited.has(currentNode)) {
@@ -2542,10 +3229,10 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
     // Get current g-score
     const currentGScore = gScore.get(currentNode);
     // Examine all outgoing edges
-    const adjacencyList = graph.adjacency.get(currentNode);
+    const adjacencyList = impl.adjacency.get(currentNode);
     if (adjacencyList !== undefined) {
       for (const edgeIndex of adjacencyList) {
-        const edge = graph.edges.get(edgeIndex);
+        const edge = impl.edges.get(edgeIndex);
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge);
           const weight = edgeWeights.get(edgeIndex);
@@ -2567,9 +3254,10 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
               fScore.set(neighbor, f);
               // Add to open set if not visited
               if (!visited.has(neighbor)) {
-                openSet.push({
+                minHeapPush(openSet, {
                   node: neighbor,
-                  fScore: f
+                  priority: f,
+                  sequence: sequence++
                 });
               }
             }
@@ -2609,9 +3297,10 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
  *
  * **Details**
  *
- * Negative edge weights are allowed. Returns `Option.none()` when the target is
- * unreachable or when a negative cycle affects the path to the target. Throws a
- * `GraphError` when either endpoint is missing.
+ * Negative edge weights are allowed, and `Infinity` behaves like an impassable
+ * edge. Returns `Option.none()` when the target is unreachable or when a
+ * negative cycle affects the path to the target. Throws a `GraphError` when
+ * either endpoint is missing or an edge weight is `NaN` or `-Infinity`.
  *
  * **Example** (Finding shortest paths with Bellman-Ford)
  *
@@ -2643,33 +3332,31 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
  * @since 3.18.0
  */
 export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
+  const impl = graphImpl(graph);
   // Validate that source and target nodes exist
-  if (!graph.nodes.has(config.source)) {
+  if (!impl.nodes.has(config.source)) {
     throw missingNode(config.source);
   }
-  if (!graph.nodes.has(config.target)) {
+  if (!impl.nodes.has(config.target)) {
     throw missingNode(config.target);
   }
-  // Early return if source equals target
-  if (config.source === config.target) {
-    return Option.some({
-      path: [config.source],
-      distance: 0,
-      costs: []
-    });
-  }
   // Initialize distances and predecessors
   const distances = new Map();
   const previous = new Map();
   // Iterate directly over node keys
-  for (const node of graph.nodes.keys()) {
+  for (const node of impl.nodes.keys()) {
     distances.set(node, node === config.source ? 0 : Infinity);
     previous.set(node, null);
   }
   // Collect all edges for relaxation
   const edges = [];
-  for (const [, edgeData] of graph.edges) {
+  for (const [, edgeData] of impl.edges) {
     const weight = config.cost(edgeData.data);
+    if (Number.isNaN(weight) || weight === -Infinity) {
+      throw new GraphError({
+        message: "Bellman-Ford algorithm does not support NaN or -Infinity edge weights"
+      });
+    }
     edges.push({
       source: edgeData.source,
       target: edgeData.target,
@@ -2686,7 +3373,7 @@ export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
     }
   }
   // Relax edges up to V-1 times
-  const nodeCount = graph.nodes.size;
+  const nodeCount = impl.nodes.size;
   for (let i = 0; i < nodeCount - 1; i++) {
     let hasUpdate = false;
     for (const edge of edges) {
@@ -2868,7 +3555,7 @@ export class Walker {
    */
   visit) {
     this.visit = visit;
-    this[Symbol.iterator] = visit((index, data) => [index, data])[Symbol.iterator];
+    this[Symbol.iterator] = () => visit((index, data) => [index, data])[Symbol.iterator]();
   }
 }
 /**
@@ -2947,7 +3634,8 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  * **Details**
  *
  * If no start nodes are supplied, the iterator is empty. The `direction` option
- * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+ * chooses whether to follow outgoing or incoming edges. The `radius` option
+ * limits traversal by edge distance from the start nodes. Throws a `GraphError`
  * if any configured start node does not exist.
  *
  * **Example** (Traversing depth-first)
@@ -2980,6 +3668,7 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
 export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
+  const radius = config.radius ?? Infinity;
   // Validate that all start nodes exist
   for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
@@ -2988,26 +3677,61 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
-      const stack = [...start];
-      const discovered = new Set();
+      const depths = radius === Infinity ? undefined : new Map();
+      const stack = [];
+      const yielded = new Set();
+      if (depths === undefined) {
+        for (const node of start) {
+          stack.push([node, 0]);
+        }
+      } else {
+        const starts = new Set();
+        for (let i = start.length - 1; i >= 0; i--) {
+          const node = start[i];
+          if (!starts.has(node)) {
+            starts.add(node);
+            stack.push([node, 0]);
+            depths.set(node, 0);
+          }
+        }
+        stack.reverse();
+      }
       const nextMapped = () => {
         while (stack.length > 0) {
-          const current = stack.pop();
-          if (discovered.has(current)) {
+          const [current, depth] = stack.pop();
+          if (depths === undefined) {
+            if (yielded.has(current)) {
+              continue;
+            }
+          } else if (depths.get(current) !== depth) {
             continue;
           }
-          discovered.add(current);
           const nodeDataOption = getNode(graph, current);
           if (Option.isNone(nodeDataOption)) {
             continue;
           }
-          const neighbors = getTraversalNeighbors(graph, current, direction);
-          for (let i = neighbors.length - 1; i >= 0; i--) {
-            const neighbor = neighbors[i];
-            if (!discovered.has(neighbor)) {
-              stack.push(neighbor);
+          if (depth < radius) {
+            const neighbors = getTraversalNeighbors(graph, current, direction);
+            for (let i = neighbors.length - 1; i >= 0; i--) {
+              const neighbor = neighbors[i];
+              const nextDepth = depth + 1;
+              if (depths === undefined) {
+                if (!yielded.has(neighbor)) {
+                  stack.push([neighbor, nextDepth]);
+                }
+                continue;
+              }
+              const neighborDepth = depths.get(neighbor);
+              if (neighborDepth === undefined || nextDepth < neighborDepth) {
+                depths.set(neighbor, nextDepth);
+                stack.push([neighbor, nextDepth]);
+              }
             }
           }
+          if (yielded.has(current)) {
+            continue;
+          }
+          yielded.add(current);
           return {
             done: false,
             value: f(current, nodeDataOption.value)
@@ -3031,7 +3755,8 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * **Details**
  *
  * If no start nodes are supplied, the iterator is empty. The `direction` option
- * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+ * chooses whether to follow outgoing or incoming edges. The `radius` option
+ * limits traversal by edge distance from the start nodes. Throws a `GraphError`
  * if any configured start node does not exist.
  *
  * **Example** (Traversing breadth-first)
@@ -3064,6 +3789,7 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
 export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
+  const radius = config.radius ?? Infinity;
   // Validate that all start nodes exist
   for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
@@ -3072,17 +3798,19 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
-      const queue = [...start];
+      const queue = start.map(node => [node, 0]);
       const discovered = new Set();
       const nextMapped = () => {
         while (queue.length > 0) {
-          const current = queue.shift();
+          const [current, depth] = queue.shift();
           if (!discovered.has(current)) {
             discovered.add(current);
-            const neighbors = getTraversalNeighbors(graph, current, direction);
-            for (const neighbor of neighbors) {
-              if (!discovered.has(neighbor)) {
-                queue.push(neighbor);
+            if (depth < radius) {
+              const neighbors = getTraversalNeighbors(graph, current, direction);
+              for (const neighbor of neighbors) {
+                if (!discovered.has(neighbor)) {
+                  queue.push([neighbor, depth + 1]);
+                }
               }
             }
             const nodeData = getNode(graph, current);
@@ -3092,7 +3820,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
                 value: f(current, nodeData.value)
               };
             }
-            return nextMapped();
+            continue;
           }
         }
         return {
@@ -3173,17 +3901,18 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
+      const impl = graphImpl(graph);
       const inDegree = new Map();
       const remaining = new Set();
       const initialSet = new Set(initials);
       const queue = [...initials];
       // Initialize in-degree counts
-      for (const [nodeIndex] of graph.nodes) {
+      for (const [nodeIndex] of impl.nodes) {
         inDegree.set(nodeIndex, 0);
         remaining.add(nodeIndex);
       }
       // Calculate in-degrees
-      for (const [, edgeData] of graph.edges) {
+      for (const [, edgeData] of impl.edges) {
         const currentInDegree = inDegree.get(edgeData.target) || 0;
         inDegree.set(edgeData.target, currentInDegree + 1);
       }
@@ -3225,9 +3954,14 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
                 value: f(current, nodeData.value)
               };
             }
-            return nextMapped();
+            continue;
           }
         }
+        if (remaining.size > 0) {
+          throw new GraphError({
+            message: "Cannot perform topological sort on cyclic graph"
+          });
+        }
         return {
           done: true,
           value: undefined
@@ -3247,7 +3981,14 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  *
  * Nodes are emitted after their reachable descendants have been processed. If
  * no start nodes are supplied, the iterator is empty. The `direction` option
- * chooses whether to follow outgoing or incoming edges.
+ * chooses whether to follow outgoing or incoming edges. The `radius` option
+ * limits traversal by edge distance from the start nodes.
+ *
+ * **Gotchas**
+ *
+ * With a finite `radius`, iteration first performs a bounded breadth-first
+ * traversal to determine shortest-distance membership before emitting nodes in
+ * postorder.
  *
  * **Example** (Traversing in postorder)
  *
@@ -3275,6 +4016,7 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
 export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config = {}) => {
   const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
+  const radius = config.radius ?? Infinity;
   // Validate that all start nodes exist
   for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
@@ -3283,6 +4025,11 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
+      const reached = radius === Infinity ? undefined : new Set(indices(bfs(graph, {
+        start,
+        direction,
+        radius
+      })));
       const stack = [];
       const discovered = new Set();
       const finished = new Set();
@@ -3305,7 +4052,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
             const neighbors = getTraversalNeighbors(graph, current.node, direction);
             for (let i = neighbors.length - 1; i >= 0; i--) {
               const neighbor = neighbors[i];
-              if (!discovered.has(neighbor) && !finished.has(neighbor)) {
+              if ((reached === undefined || reached.has(neighbor)) && !discovered.has(neighbor) && !finished.has(neighbor)) {
                 stack.push({
                   node: neighbor,
                   visitedChildren: false
@@ -3323,7 +4070,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
                   value: f(nodeToEmit, nodeData.value)
                 };
               }
-              return nextMapped();
+              continue;
             }
           }
         }
@@ -3367,7 +4114,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  */
 export const nodes = graph => new Walker(f => ({
   [Symbol.iterator]() {
-    const nodeMap = graph.nodes;
+    const nodeMap = graphImpl(graph).nodes;
     const iterator = nodeMap.entries();
     return {
       next() {
@@ -3417,7 +4164,7 @@ export const nodes = graph => new Walker(f => ({
  */
 export const edges = graph => new Walker(f => ({
   [Symbol.iterator]() {
-    const edgeMap = graph.edges;
+    const edgeMap = graphImpl(graph).edges;
     const iterator = edgeMap.entries();
     return {
       next() {
@@ -3481,8 +4228,9 @@ export const externals = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, con
   const direction = config.direction ?? "outgoing";
   return new Walker(f => ({
     [Symbol.iterator]: () => {
-      const nodeMap = graph.nodes;
-      const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
+      const impl = graphImpl(graph);
+      const nodeMap = impl.nodes;
+      const adjacencyMap = direction === "incoming" ? impl.reverseAdjacency : impl.adjacency;
       const nodeIterator = nodeMap.entries();
       const nextMapped = () => {
         let current = nodeIterator.next();