effect 4.0.0-beta.98 → 4.0.0-rc.108

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**
  *
- * ```ts
+ * Use when the graph kind is selected dynamically. Prefer `directed` or
+ * `undirected` when the kind is known statically.
+ *
+ * **Example** (Constructing by kind)
+ *
+ * ```ts import.meta.vitest
  * 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")
  * })
+ *
+ * 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,20 +210,43 @@ 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.meta.vitest
+ * 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")
+ * })
+ * Array.of(Graph.nodeCount(graph), Graph.edgeCount(graph)) // => [3, 2]
+ * ```
+ *
+ * @category constructors
+ * @since 3.18.0
+ */
+export const directed = /*#__PURE__*/make("directed");
 /**
  * Creates an undirected graph, optionally with initial mutations.
  *
  * **Example** (Creating an undirected graph)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Undirected graph with initial nodes and edges
@@ -199,29 +257,13 @@ export const directed = mutate => {
  *   Graph.addEdge(mutable, a, b, "A-B")
  *   Graph.addEdge(mutable, b, c, "B-C")
  * })
+ * Array.of(Graph.nodeCount(graph), Graph.edgeCount(graph)) // => [3, 2]
  * ```
  *
  * @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
 // =============================================================================
@@ -230,67 +272,80 @@ export const undirected = mutate => {
  *
  * **Example** (Beginning a mutation scope)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>()
  * const mutable = Graph.beginMutation(graph)
  * // Now mutable can be safely modified without affecting original graph
+ * Array.of(Graph.nodeCount(mutable), Graph.nodeCount(graph)) // => [0, 0]
  * ```
  *
  * @category mutations
  * @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
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>()
  * const mutable = Graph.beginMutation(graph)
  * // ... perform mutations on mutable ...
- * const newGraph = Graph.endMutation(mutable)
+ * Graph.nodeCount(Graph.endMutation(mutable)) // => 0
  * ```
  *
  * @category mutations
  * @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;
 };
 /**
@@ -298,7 +353,7 @@ export const endMutation = mutable => {
  *
  * **Example** (Applying scoped mutations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>()
@@ -308,8 +363,8 @@ export const endMutation = mutable => {
  *   Graph.addEdge(mutable, nodeA, nodeB, 1)
  * })
  *
- * console.log(Graph.nodeCount(newGraph)) // 2
- * console.log(Graph.edgeCount(newGraph)) // 1
+ * Graph.nodeCount(newGraph) // => 2
+ * Graph.edgeCount(newGraph) // => 1
  * ```
  *
  * @category mutations
@@ -317,8 +372,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.meta.vitest
+ * 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
+ * })
+ *
+ * Graph.nodeCount(result) // => 3
+ * 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.meta.vitest
+ * 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)
+ *
+ * Graph.nodeCount(result) // => 2
+ * 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.meta.vitest
+ * 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)
+ *
+ * Graph.nodeCount(result) // => 3
+ * 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.meta.vitest
+ * 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)
+ *
+ * Graph.nodeCount(result) // => 4
+ * 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.meta.vitest
+ * 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}`)
+ *
+ * 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.meta.vitest
+ * 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 })
+ *
+ * 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
@@ -343,14 +919,12 @@ export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
  *
  * **Example** (Adding nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
- * const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
- *   const nodeA = Graph.addNode(mutable, "Node A")
- *   const nodeB = Graph.addNode(mutable, "Node B")
- *   console.log(nodeA) // NodeIndex with value 0
- *   console.log(nodeB) // NodeIndex with value 1
+ * Graph.mutate(Graph.directed<string, number>(), (mutable) => {
+ *   Graph.addNode(mutable, "Node A") // => 0
+ *   Graph.addNode(mutable, "Node B") // => 1
  * })
  * ```
  *
@@ -362,14 +936,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;
 };
 /**
@@ -377,60 +953,53 @@ export const addNode = (mutable, data) => {
  *
  * **Example** (Getting node data)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph, Option } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   Graph.addNode(mutable, "Node A")
  * })
  *
- * const nodeIndex = 0
- * const nodeData = Graph.getNode(graph, nodeIndex)
- *
- * if (Option.isSome(nodeData)) {
- *   console.log(nodeData.value) // "Node A"
- * }
+ * Graph.getNode(graph, 0) // => Option.some("Node A")
  * ```
  *
  * @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.
  *
  * **Example** (Checking node existence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   Graph.addNode(mutable, "Node A")
  * })
  *
- * const nodeIndex = 0
- * const exists = Graph.hasNode(graph, nodeIndex)
- * console.log(exists) // true
- *
- * const nonExistentIndex = 999
- * const notExists = Graph.hasNode(graph, nonExistentIndex)
- * console.log(notExists) // false
+ * Graph.hasNode(graph, 0) // => true
+ * Graph.hasNode(graph, 999) // => false
  * ```
  *
  * @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.
  *
  * **Example** (Counting nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const emptyGraph = Graph.directed<string, number>()
- * console.log(Graph.nodeCount(emptyGraph)) // 0
+ * Graph.nodeCount(emptyGraph) // => 0
  *
  * const graphWithNodes = Graph.mutate(emptyGraph, (mutable) => {
  *   Graph.addNode(mutable, "Node A")
@@ -438,20 +1007,20 @@ export const hasNode = /*#__PURE__*/dual(2, (graph, nodeIndex) => graph.nodes.ha
  *   Graph.addNode(mutable, "Node C")
  * })
  *
- * console.log(Graph.nodeCount(graphWithNodes)) // 3
+ * Graph.nodeCount(graphWithNodes) // => 3
  * ```
  *
  * @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.
  *
  * **Example** (Finding the first matching node)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   Graph.addNode(mutable, "Node A")
@@ -459,18 +1028,16 @@ export const nodeCount = graph => graph.nodes.size;
  *   Graph.addNode(mutable, "Node C")
  * })
  *
- * const result = Graph.findNode(graph, (data) => data.startsWith("Node B"))
- * console.log(result) // Option.some(1)
- *
- * const notFound = Graph.findNode(graph, (data) => data === "Node D")
- * console.log(notFound) // Option.none()
+ * Graph.findNode(graph, (data) => data.startsWith("Node B")) // => Option.some(1)
+ * Graph.findNode(graph, (data) => data === "Node D") // => Option.none()
  * ```
  *
  * @category getters
  * @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);
     }
@@ -482,7 +1049,7 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
  *
  * **Example** (Finding matching nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -491,19 +1058,17 @@ export const findNode = /*#__PURE__*/dual(2, (graph, predicate) => {
  *   Graph.addNode(mutable, "Start C")
  * })
  *
- * const result = Graph.findNodes(graph, (data) => data.startsWith("Start"))
- * console.log(result) // [0, 2]
- *
- * const empty = Graph.findNodes(graph, (data) => data === "Not Found")
- * console.log(empty) // []
+ * Graph.findNodes(graph, (data) => data.startsWith("Start")) // => [0, 2]
+ * Graph.findNodes(graph, (data) => data === "Not Found") // => []
  * ```
  *
  * @category getters
  * @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);
     }
@@ -515,8 +1080,8 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
  *
  * **Example** (Finding the first matching edge)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   const nodeA = Graph.addNode(mutable, "Node A")
@@ -526,18 +1091,16 @@ export const findNodes = /*#__PURE__*/dual(2, (graph, predicate) => {
  *   Graph.addEdge(mutable, nodeB, nodeC, 20)
  * })
  *
- * const result = Graph.findEdge(graph, (data) => data > 15)
- * console.log(result) // Option.some(1)
- *
- * const notFound = Graph.findEdge(graph, (data) => data > 100)
- * console.log(notFound) // Option.none()
+ * Graph.findEdge(graph, (data) => data > 15) // => Option.some(1)
+ * Graph.findEdge(graph, (data) => data > 100) // => Option.none()
  * ```
  *
  * @category getters
  * @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);
     }
@@ -549,7 +1112,7 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
  *
  * **Example** (Finding matching edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -561,19 +1124,17 @@ export const findEdge = /*#__PURE__*/dual(2, (graph, predicate) => {
  *   Graph.addEdge(mutable, nodeC, nodeA, 30)
  * })
  *
- * const result = Graph.findEdges(graph, (data) => data >= 20)
- * console.log(result) // [1, 2]
- *
- * const empty = Graph.findEdges(graph, (data) => data > 100)
- * console.log(empty) // []
+ * Graph.findEdges(graph, (data) => data >= 20) // => [1, 2]
+ * Graph.findEdges(graph, (data) => data > 100) // => []
  * ```
  *
  * @category getters
  * @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);
     }
@@ -585,8 +1146,8 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
  *
  * **Example** (Updating node data)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   Graph.addNode(mutable, "Node A")
@@ -594,28 +1155,29 @@ export const findEdges = /*#__PURE__*/dual(2, (graph, predicate) => {
  *   Graph.updateNode(mutable, 0, (data) => data.toUpperCase())
  * })
  *
- * const nodeData = Graph.getNode(graph, 0)
- * console.log(nodeData) // Option.some("NODE A")
+ * Graph.getNode(graph, 0) // => Option.some("NODE A")
  * ```
  *
  * @category transforming
  * @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.
  *
  * **Example** (Updating edge data)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   const nodeA = Graph.addNode(mutable, "Node A")
@@ -624,20 +1186,21 @@ export const updateNode = (mutable, index, f) => {
  *   Graph.updateEdge(mutable, edgeIndex, (data) => data * 2)
  * })
  *
- * const edgeData = Graph.getEdge(result, 0)
- * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
+ * Option.map(Graph.getEdge(result, 0), (edge) => edge.data) // => Option.some(20)
  * ```
  *
  * @category mutations
  * @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
   }));
@@ -652,8 +1215,8 @@ export const updateEdge = (mutable, edgeIndex, f) => {
  *
  * **Example** (Mapping node data)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   Graph.addNode(mutable, "node a")
@@ -662,18 +1225,19 @@ export const updateEdge = (mutable, edgeIndex, f) => {
  *   Graph.mapNodes(mutable, (data) => data.toUpperCase())
  * })
  *
- * const nodeData = Graph.getNode(graph, 0)
- * console.log(nodeData) // Option.some("NODE A")
+ * Graph.getNode(graph, 0) // => Option.some("NODE A")
  * ```
  *
  * @category transforming
  * @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);
   }
 };
 /**
@@ -681,8 +1245,8 @@ export const mapNodes = (mutable, f) => {
  *
  * **Example** (Mapping edge data)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
@@ -693,21 +1257,22 @@ export const mapNodes = (mutable, f) => {
  *   Graph.mapEdges(mutable, (data) => data * 2)
  * })
  *
- * const edgeData = Graph.getEdge(graph, 0)
- * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
+ * Option.map(Graph.getEdge(graph, 0), (edge) => edge.data) // => Option.some(20)
  * ```
  *
  * @category transforming
  * @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
-    });
+    }));
   }
 };
 /**
@@ -734,8 +1299,8 @@ const rebuildAdjacency = mutable => {
  *
  * **Example** (Reversing edge directions)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
@@ -746,28 +1311,29 @@ const rebuildAdjacency = mutable => {
  *   Graph.reverse(mutable) // Now B -> A, C -> B
  * })
  *
- * const edge0 = Graph.getEdge(graph, 0)
- * console.log(edge0) // Option.some(new Graph.Edge({ source: 1, target: 0, data: 1 }))
+ * Option.map(Graph.getEdge(graph, 0), (edge) => edge.source) // => Option.some(1)
  * ```
  *
  * @category transforming
  * @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.
@@ -775,7 +1341,7 @@ export const reverse = mutable => {
  *
  * **Example** (Filtering and mapping nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -793,20 +1359,22 @@ export const reverse = mutable => {
  *   )
  * })
  *
- * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
+ * Graph.nodeCount(graph) // => 2
  * ```
  *
  * @category transforming
  * @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);
@@ -823,7 +1391,7 @@ export const filterMapNodes = (mutable, f) => {
  *
  * **Example** (Filtering and mapping edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -841,23 +1409,25 @@ export const filterMapNodes = (mutable, f) => {
  *   )
  * })
  *
- * console.log(Graph.edgeCount(graph)) // 2 (edges with weight 5 removed)
+ * Graph.edgeCount(graph) // => 2
  * ```
  *
  * @category transforming
  * @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);
@@ -874,7 +1444,7 @@ export const filterMapEdges = (mutable, f) => {
  *
  * **Example** (Filtering nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -887,16 +1457,18 @@ export const filterMapEdges = (mutable, f) => {
  *   Graph.filterNodes(mutable, (data) => data === "active")
  * })
  *
- * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
+ * Graph.nodeCount(graph) // => 2
  * ```
  *
  * @category transforming
  * @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);
     }
@@ -912,7 +1484,7 @@ export const filterNodes = (mutable, predicate) => {
  *
  * **Example** (Filtering edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -928,16 +1500,18 @@ export const filterNodes = (mutable, predicate) => {
  *   Graph.filterEdges(mutable, (data) => data >= 10)
  * })
  *
- * console.log(Graph.edgeCount(graph)) // 2 (edge with weight 5 removed)
+ * Graph.edgeCount(graph) // => 2
  * ```
  *
  * @category transforming
  * @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);
     }
@@ -988,14 +1562,13 @@ const invalidateCycleFlagOnAddition = mutable => {
  *
  * **Example** (Adding edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
- * const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
+ * Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   const nodeA = Graph.addNode(mutable, "Node A")
  *   const nodeB = Graph.addNode(mutable, "Node B")
- *   const edge = Graph.addEdge(mutable, nodeA, nodeB, 42)
- *   console.log(edge) // EdgeIndex with value 0
+ *   Graph.addEdge(mutable, nodeA, nodeB, 42) // => 0
  * })
  * ```
  *
@@ -1008,46 +1581,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;
 };
 /**
@@ -1055,7 +1630,7 @@ export const addEdge = (mutable, source, target, data) => {
  *
  * **Example** (Removing a node)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -1066,27 +1641,30 @@ export const addEdge = (mutable, source, target, data) => {
  *   // Remove nodeA and all edges connected to it
  *   Graph.removeNode(mutable, nodeA)
  * })
+ * Array.of(Graph.nodeCount(result), Graph.edgeCount(result)) // => [1, 0]
  * ```
  *
  * @category mutations
  * @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,22 +1672,22 @@ 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.
  *
  * **Example** (Removing an edge)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -1120,17 +1698,20 @@ export const removeNode = (mutable, nodeIndex) => {
  *   // Remove the edge
  *   Graph.removeEdge(mutable, edge)
  * })
+ * Array.of(Graph.nodeCount(result), Graph.edgeCount(result)) // => [2, 0]
  * ```
  *
  * @category mutations
  * @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 */
@@ -1188,8 +1769,8 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  *
  * **Example** (Getting edge data)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
  *   const nodeA = Graph.addNode(mutable, "Node A")
@@ -1197,26 +1778,19 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  *   Graph.addEdge(mutable, nodeA, nodeB, 42)
  * })
  *
- * const edgeIndex = 0
- * const edgeData = Graph.getEdge(graph, edgeIndex)
- *
- * if (edgeData._tag === "Some") {
- *   console.log(edgeData.value.data) // 42
- *   console.log(edgeData.value.source) // 0
- *   console.log(edgeData.value.target) // 1
- * }
+ * Graph.getEdge(graph, 0) // => Option.some(new Graph.Edge({ source: 0, target: 1, data: 42 }))
  * ```
  *
  * @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.
  *
  * **Example** (Checking edge existence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -1226,28 +1800,22 @@ export const getEdge = /*#__PURE__*/dual(2, (graph, edgeIndex) => Option.fromUnd
  *   Graph.addEdge(mutable, nodeA, nodeB, 42)
  * })
  *
- * const nodeA = 0
- * const nodeB = 1
- * const nodeC = 2
- *
- * const hasAB = Graph.hasEdge(graph, nodeA, nodeB)
- * console.log(hasAB) // true
- *
- * const hasAC = Graph.hasEdge(graph, nodeA, nodeC)
- * console.log(hasAC) // false
+ * Graph.hasEdge(graph, 0, 1) // => true
+ * Graph.hasEdge(graph, 0, 2) // => false
  * ```
  *
  * @category getters
  * @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) {
@@ -1262,11 +1830,11 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
  *
  * **Example** (Counting edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const emptyGraph = Graph.directed<string, number>()
- * console.log(Graph.edgeCount(emptyGraph)) // 0
+ * Graph.edgeCount(emptyGraph) // => 0
  *
  * const graphWithEdges = Graph.mutate(emptyGraph, (mutable) => {
  *   const nodeA = Graph.addNode(mutable, "Node A")
@@ -1277,22 +1845,23 @@ export const hasEdge = /*#__PURE__*/dual(3, (graph, source, target) => {
  *   Graph.addEdge(mutable, nodeC, nodeA, 3)
  * })
  *
- * console.log(Graph.edgeCount(graphWithEdges)) // 3
+ * Graph.edgeCount(graphWithEdges) // => 3
  * ```
  *
  * @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);
     }
@@ -1309,7 +1878,7 @@ const getDirectedNeighbors = (graph, nodeIndex, direction) => {
  *
  * **Example** (Getting outgoing neighbors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -1320,15 +1889,8 @@ const getDirectedNeighbors = (graph, nodeIndex, direction) => {
  *   Graph.addEdge(mutable, nodeA, nodeC, 2)
  * })
  *
- * const nodeA = 0
- * const nodeB = 1
- * const nodeC = 2
- *
- * const neighborsA = Graph.neighbors(graph, nodeA)
- * console.log(neighborsA) // [1, 2]
- *
- * const neighborsB = Graph.neighbors(graph, nodeB)
- * console.log(neighborsB) // []
+ * Graph.neighbors(graph, 0) // => [1, 2]
+ * Graph.neighbors(graph, 1) // => []
  * ```
  *
  * @category getters
@@ -1356,7 +1918,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
  *
- * @category queries
+ * @category getters
  * @since 4.0.0
  */
 export const successors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
@@ -1382,7 +1944,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
  *
- * @category queries
+ * @category getters
  * @since 4.0.0
  */
 export const predecessors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
@@ -1407,7 +1969,7 @@ export const predecessors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  *
  * **Example** (Traversing directed neighbors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, string>((mutable) => {
@@ -1424,12 +1986,13 @@ export const predecessors = /*#__PURE__*/dual(2, (graph, nodeIndex) => {
  *
  * // Get incoming neighbors (nodes that point to nodeB)
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
+ * Array.of(outgoing, incoming) // => [[1], [0]]
  * ```
  *
  * @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
- * @category queries
+ * @category getters
  * @since 3.18.0
  */
 export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, direction) => {
@@ -1440,12 +2003,13 @@ 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.
  *
  * **Example** (Exporting GraphViz DOT)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
@@ -1457,22 +2021,14 @@ export const neighborsDirected = /*#__PURE__*/dual(3, (graph, nodeIndex, directi
  *   Graph.addEdge(mutable, nodeC, nodeA, 3)
  * })
  *
- * const dot = Graph.toGraphViz(graph)
- * console.log(dot)
- * // digraph G {
- * //   "0" [label="Node A"];
- * //   "1" [label="Node B"];
- * //   "2" [label="Node C"];
- * //   "0" -> "1" [label="1"];
- * //   "1" -> "2" [label="2"];
- * //   "2" -> "0" [label="3"];
- * // }
+ * Graph.toGraphViz(graph).split("\n") // => ['digraph "G" {', '  "0" [label="Node A"];', '  "1" [label="Node B"];', '  "2" [label="Node C"];', '  "0" -> "1" [label="1"];', '  "1" -> "2" [label="2"];', '  "2" -> "0" [label="3"];', "}"]
  * ```
  *
  * @category converting
  * @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 +2037,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("}");
@@ -1542,7 +2099,7 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *
  * **Example** (Exporting a directed Mermaid diagram)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Basic directed graph export
@@ -1554,19 +2111,12 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *   Graph.addEdge(mutable, app, cache, 2)
  * })
  *
- * const mermaid = Graph.toMermaid(graph)
- * console.log(mermaid)
- * // flowchart TD
- * //   0["App"]
- * //   1["Database"]
- * //   2["Cache"]
- * //   0 -->|"1"| 1
- * //   0 -->|"2"| 2
+ * Graph.toMermaid(graph).split("\n") // => ["flowchart TD", '  0["App"]', '  1["Database"]', '  2["Cache"]', '  0 -->|"1"| 1', '  0 -->|"2"| 2']
  * ```
  *
  * **Example** (Exporting an undirected Mermaid diagram)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Undirected graph with custom labels and direction
@@ -1583,18 +2133,12 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *   edgeLabel: (relationship) => relationship,
  *   direction: "LR"
  * })
- * console.log(mermaid)
- * // graph LR
- * //   0["Alice"]
- * //   1["Bob"]
- * //   2["Charlie"]
- * //   0 ---|"friends"| 1
- * //   1 ---|"colleagues"| 2
+ * mermaid.split("\n") // => ["graph LR", '  0["Alice"]', '  1["Bob"]', '  2["Charlie"]', '  0 ---|"friends"| 1', '  1 ---|"colleagues"| 2']
  * ```
  *
  * **Example** (Customizing Mermaid node shapes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Advanced styling with node shapes for flowchart
@@ -1633,20 +2177,12 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *     }
  *   }
  * })
- * console.log(mermaid)
- * // flowchart TD
- * //   0(["Begin"])
- * //   1["Process Data"]
- * //   2{"Valid?"}
- * //   3(["Complete"])
- * //   0 --> 1
- * //   1 --> 2
- * //   2 --> 3
+ * mermaid.split("\n") // => ["flowchart TD", '  0(["Begin"])', '  1["Process Data"]', '  2{"Valid?"}', '  3(["Complete"])', "  0 --> 1", "  1 --> 2", '  2 -->|"yes"| 3']
  * ```
  *
  * **Example** (Visualizing dependency graphs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Real-world example: Software dependency graph
@@ -1661,22 +2197,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")
@@ -1695,21 +2231,14 @@ const formatMermaidNode = (nodeId, label, shape) => {
  *   direction: "TB"
  * })
  *
- * console.log(dependencyDiagram)
- * // flowchart TB
- * //   0["MyApp\nv1.0.0"]
- * //   1{{"React\nv18.0.0"}}
- * //   2["Lodash\nv4.17.0"]
- * //   3{"Webpack\nv5.0.0"}
- * //   0 -->|"depends on"| 1
- * //   0 -->|"depends on"| 2
- * //   0 -->|"builds with"| 3
+ * dependencyDiagram.split("\n") // => ["flowchart TB", '  0["MyApp#92;nv1.0.0"]', '  1{{"React#92;nv18.0.0"}}', '  2["Lodash#92;nv4.17.0"]', '  3{"Webpack#92;nv5.0.0"}', '  0 -->|"depends on"| 1', '  0 -->|"depends on"| 2', '  0 -->|"builds with"| 3']
  * ```
  *
  * @category converting
  * @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 +2253,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 +2262,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,11 +2284,12 @@ 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)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Acyclic directed graph (DAG)
@@ -1770,7 +2300,7 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  *   Graph.addEdge(mutable, a, b, "A->B")
  *   Graph.addEdge(mutable, b, c, "B->C")
  * })
- * console.log(Graph.isAcyclic(dag)) // true
+ * Graph.isAcyclic(dag) // => true
  *
  * // Cyclic directed graph
  * const cyclic = Graph.directed<string, string>((mutable) => {
@@ -1779,56 +2309,68 @@ export const toMermaid = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, opt
  *   Graph.addEdge(mutable, a, b, "A->B")
  *   Graph.addEdge(mutable, b, a, "B->A") // Creates cycle
  * })
- * console.log(Graph.isAcyclic(cyclic)) // false
+ * Graph.isAcyclic(cyclic) // => false
  * ```
  *
  * @category algorithms
  * @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 +2382,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 +2402,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 +2416,7 @@ export const isAcyclic = graph => {
     }
   }
   // Cache the result
-  graph.acyclic = Option.some(true);
+  impl.acyclic = Option.some(true);
   return true;
 };
 /**
@@ -1888,7 +2430,7 @@ export const isAcyclic = graph => {
  *
  * **Example** (Checking bipartite graphs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * // Bipartite graph (alternating coloring possible)
@@ -1901,7 +2443,7 @@ export const isAcyclic = graph => {
  *   Graph.addEdge(mutable, b, c, "edge")
  *   Graph.addEdge(mutable, c, d, "edge")
  * })
- * console.log(Graph.isBipartite(bipartite)) // true
+ * Graph.isBipartite(bipartite) // => true
  *
  * // Non-bipartite graph (odd cycle)
  * const triangle = Graph.undirected<string, string>((mutable) => {
@@ -1912,18 +2454,19 @@ export const isAcyclic = graph => {
  *   Graph.addEdge(mutable, b, c, "edge")
  *   Graph.addEdge(mutable, c, a, "edge") // Triangle (3-cycle)
  * })
- * console.log(Graph.isBipartite(triangle)) // false
+ * Graph.isBipartite(triangle) // => false
  * ```
  *
  * @category algorithms
  * @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 +2506,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 +2522,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.
@@ -1986,7 +2543,7 @@ const getTraversableNeighbor = (graph, current, edge) => graph.type === "undirec
  *
  * **Example** (Finding connected components)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.undirected<string, string>((mutable) => {
@@ -1998,17 +2555,17 @@ const getTraversableNeighbor = (graph, current, edge) => graph.type === "undirec
  *   Graph.addEdge(mutable, c, d, "edge") // Component 2: C-D
  * })
  *
- * const components = Graph.connectedComponents(graph)
- * console.log(components) // [[0, 1], [2, 3]]
+ * Graph.connectedComponents(graph) // => [[0, 1], [2, 3]]
  * ```
  *
  * @category algorithms
  * @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 = [];
@@ -2042,7 +2599,7 @@ export const connectedComponents = graph => {
  *
  * **Example** (Finding strongly connected components)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, string>((mutable) => {
@@ -2054,8 +2611,7 @@ export const connectedComponents = graph => {
  *   Graph.addEdge(mutable, c, a, "C->A") // Creates SCC: A-B-C
  * })
  *
- * const sccs = Graph.stronglyConnectedComponents(graph)
- * console.log(sccs) // [[0, 1, 2]]
+ * Graph.stronglyConnectedComponents(graph) // => [[0, 2, 1]]
  * ```
  *
  * @category algorithms
@@ -2067,9 +2623,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 +2675,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 +2692,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,14 +2735,15 @@ 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)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
@@ -2178,24 +2760,31 @@ const validateNonNegativeEdgeWeights = (graph, cost, algorithm) => {
  *   cost: (edgeData) => edgeData
  * })
  *
- * if (result._tag === "Some") {
- *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
- *   console.log(result.value.distance) // 7 - total distance
- * }
+ * Option.map(result, ({ distance, path }) => [distance, path] as const) // => Option.some([7, [0, 1, 2]])
  * ```
  *
  * @category algorithms
  * @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 +2799,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 +2825,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 +2843,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,12 +2886,13 @@ 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)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2319,16 +2905,17 @@ export const dijkstra = /*#__PURE__*/dual(2, (graph, config) => {
  * })
  *
  * const result = Graph.floydWarshall(graph, (edgeData) => edgeData)
- * const distanceAToC = result.distances.get(0)?.get(2) // 5 (A->B->C)
- * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
+ * const shortest = { distance: result.distances.get(0)?.get(2), path: result.paths.get(0)?.get(2) }
+ * shortest // => { distance: 5, path: [0, 1, 2] }
  * ```
  *
  * @category algorithms
  * @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 +2927,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 +2963,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 +3001,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,15 +3026,16 @@ 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)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<{ x: number; y: number }, number>((mutable) => {
  *   const a = Graph.addNode(mutable, { x: 0, y: 0 })
@@ -2464,24 +3058,31 @@ export const floydWarshall = /*#__PURE__*/dual(2, (graph, cost) => {
  *   heuristic
  * })
  *
- * if (result._tag === "Some") {
- *   console.log(result.value.path) // [0, 1, 2] - shortest path
- *   console.log(result.value.distance) // 2 - total distance
- * }
+ * Option.map(result, ({ distance, path }) => [distance, path] as const) // => Option.some([2, [0, 1, 2]])
  * ```
  *
  * @category algorithms
  * @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 +3105,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 +3116,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 +3138,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 +3163,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,14 +3206,15 @@ 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)
  *
- * ```ts
- * import { Graph } from "effect"
+ * ```ts import.meta.vitest
+ * import { Graph, Option } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
@@ -2633,43 +3231,38 @@ export const astar = /*#__PURE__*/dual(2, (graph, config) => {
  *   cost: (edgeData) => edgeData
  * })
  *
- * if (result._tag === "Some") {
- *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
- *   console.log(result.value.distance) // 2 - total distance
- * }
+ * Option.map(result, ({ distance, path }) => [distance, path] as const) // => Option.some([2, [0, 1, 2]])
  * ```
  *
  * @category algorithms
  * @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 +3279,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) {
@@ -2766,7 +3359,7 @@ export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
  *
  * **Example** (Working with node walkers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2785,8 +3378,8 @@ export const bellmanFord = /*#__PURE__*/dual(2, (graph, config) => {
  * }
  *
  * // Access node data using values() or entries()
- * const nodeData = Array.from(Graph.values(dfsNodes)) // ["A", "B"]
- * const nodeEntries = Array.from(Graph.entries(allNodes)) // [[0, "A"], [1, "B"]]
+ * Array.from(Graph.values(dfsNodes)) // => ["A", "B"]
+ * Array.from(Graph.entries(allNodes)) // => [[0, "A"], [1, "B"]]
  * ```
  *
  * @category models
@@ -2806,7 +3399,7 @@ export class Walker {
    *
    * **Example** (Visiting walker elements)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Graph } from "effect"
    *
    * const graph = Graph.directed<string, number>((mutable) => {
@@ -2818,14 +3411,10 @@ export class Walker {
    * const dfs = Graph.dfs(graph, { start: [0] })
    *
    * // Map to just the node data
-   * const values = Array.from(dfs.visit((index, data) => data))
-   * console.log(values) // ["A", "B"]
+   * Array.from(dfs.visit((index, data) => data)) // => ["A", "B"]
    *
    * // Map to custom objects
-   * const custom = Array.from(
-   *   dfs.visit((index, data) => ({ id: index, name: data }))
-   * )
-   * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
+   * Array.from(dfs.visit((index, data) => ({ id: index, name: data }))) // => [{ id: 0, name: "A" }, { id: 1, name: "B" }]
    * ```
    *
    * @since 4.0.0
@@ -2841,7 +3430,7 @@ export class Walker {
    *
    * **Example** (Visiting walker elements)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Graph } from "effect"
    *
    * const graph = Graph.directed<string, number>((mutable) => {
@@ -2853,14 +3442,10 @@ export class Walker {
    * const dfs = Graph.dfs(graph, { start: [0] })
    *
    * // Map to just the node data
-   * const values = Array.from(dfs.visit((index, data) => data))
-   * console.log(values) // ["A", "B"]
+   * Array.from(dfs.visit((index, data) => data)) // => ["A", "B"]
    *
    * // Map to custom objects
-   * const custom = Array.from(
-   *   dfs.visit((index, data) => ({ id: index, name: data }))
-   * )
-   * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
+   * Array.from(dfs.visit((index, data) => ({ id: index, name: data }))) // => [{ id: 0, name: "A" }, { id: 1, name: "B" }]
    * ```
    *
    * @category iterators
@@ -2868,7 +3453,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]();
   }
 }
 /**
@@ -2876,7 +3461,7 @@ export class Walker {
  *
  * **Example** (Iterating walker indices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2886,8 +3471,7 @@ export class Walker {
  * })
  *
  * const dfs = Graph.dfs(graph, { start: [0] })
- * const indices = Array.from(Graph.indices(dfs))
- * console.log(indices) // [0, 1]
+ * Array.from(Graph.indices(dfs)) // => [0, 1]
  * ```
  *
  * @category iterators
@@ -2899,7 +3483,7 @@ export const indices = walker => walker.visit((index, _) => index);
  *
  * **Example** (Iterating walker values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2909,8 +3493,7 @@ export const indices = walker => walker.visit((index, _) => index);
  * })
  *
  * const dfs = Graph.dfs(graph, { start: [0] })
- * const values = Array.from(Graph.values(dfs))
- * console.log(values) // ["A", "B"]
+ * Array.from(Graph.values(dfs)) // => ["A", "B"]
  * ```
  *
  * @category iterators
@@ -2922,7 +3505,7 @@ export const values = walker => walker.visit((_, data) => data);
  *
  * **Example** (Iterating walker entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2932,8 +3515,7 @@ export const values = walker => walker.visit((_, data) => data);
  * })
  *
  * const dfs = Graph.dfs(graph, { start: [0] })
- * const entries = Array.from(Graph.entries(dfs))
- * console.log(entries) // [[0, "A"], [1, "B"]]
+ * Array.from(Graph.entries(dfs)) // => [[0, "A"], [1, "B"]]
  * ```
  *
  * @category iterators
@@ -2947,12 +3529,13 @@ 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)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -2964,14 +3547,10 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  * })
  *
  * // Start from a specific node
- * const dfs1 = Graph.dfs(graph, { start: [0] })
- * for (const nodeIndex of Graph.indices(dfs1)) {
- *   console.log(nodeIndex) // Traverses in DFS order: 0, 1, 2
- * }
+ * Array.from(Graph.indices(Graph.dfs(graph, { start: [0] }))) // => [0, 1, 2]
  *
  * // Empty iterator (no starting nodes)
- * const dfs2 = Graph.dfs(graph)
- * // Can be used programmatically
+ * Graph.dfs(graph)
  * ```
  *
  * @category iterators
@@ -2980,6 +3559,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 +3568,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,12 +3646,13 @@ 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)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3048,14 +3664,10 @@ export const dfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * })
  *
  * // Start from a specific node
- * const bfs1 = Graph.bfs(graph, { start: [0] })
- * for (const nodeIndex of Graph.indices(bfs1)) {
- *   console.log(nodeIndex) // Traverses in BFS order: 0, 1, 2
- * }
+ * Array.from(Graph.indices(Graph.bfs(graph, { start: [0] }))) // => [0, 1, 2]
  *
  * // Empty iterator (no starting nodes)
- * const bfs2 = Graph.bfs(graph)
- * // Can be used programmatically
+ * Graph.bfs(graph)
  * ```
  *
  * @category iterators
@@ -3064,6 +3676,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 +3685,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 +3707,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
                 value: f(current, nodeData.value)
               };
             }
-            return nextMapped();
+            continue;
           }
         }
         return {
@@ -3116,7 +3731,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  *
  * **Example** (Sorting topologically)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3128,13 +3743,10 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * })
  *
  * // Standard topological sort
- * const topo1 = Graph.topo(graph)
- * for (const nodeIndex of Graph.indices(topo1)) {
- *   console.log(nodeIndex) // 0, 1, 2 (topological order)
- * }
+ * Array.from(Graph.indices(Graph.topo(graph))) // => [0, 1, 2]
  *
  * // With initial nodes
- * const topo2 = Graph.topo(graph, { initials: [0] })
+ * Graph.topo(graph, { initials: [0] })
  *
  * // Check before sorting a cyclic graph
  * const cyclicGraph = Graph.directed<string, number>((mutable) => {
@@ -3144,9 +3756,7 @@ export const bfs = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  *   Graph.addEdge(mutable, b, a, 2) // Creates cycle
  * })
  *
- * if (!Graph.isAcyclic(cyclicGraph)) {
- *   console.log("cyclic graph") // cyclic graph
- * }
+ * Graph.isAcyclic(cyclicGraph) // => false
  * ```
  *
  * @category iterators
@@ -3173,17 +3783,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 +3836,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,11 +3863,18 @@ 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)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3263,10 +3886,7 @@ export const topo = /*#__PURE__*/dual(args => isGraph(args[0]), (graph, config =
  * })
  *
  * // Postorder: children before parents
- * const postOrder = Graph.dfsPostOrder(graph, { start: [0] })
- * for (const node of postOrder) {
- *   console.log(node) // 1, 2, 0
- * }
+ * Array.from(Graph.indices(Graph.dfsPostOrder(graph, { start: [0] }))) // => [1, 2, 0]
  * ```
  *
  * @category iterators
@@ -3275,6 +3895,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 +3904,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 +3931,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 +3949,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
                   value: f(nodeToEmit, nodeData.value)
                 };
               }
-              return nextMapped();
+              continue;
             }
           }
         }
@@ -3348,7 +3974,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  *
  * **Example** (Iterating all nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3358,8 +3984,7 @@ export const dfsPostOrder = /*#__PURE__*/dual(args => isGraph(args[0]), (graph,
  *   Graph.addEdge(mutable, a, b, 1)
  * })
  *
- * const indices = Array.from(Graph.indices(Graph.nodes(graph)))
- * console.log(indices) // [0, 1, 2]
+ * Array.from(Graph.indices(Graph.nodes(graph))) // => [0, 1, 2]
  * ```
  *
  * @category iterators
@@ -3367,7 +3992,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() {
@@ -3397,7 +4022,7 @@ export const nodes = graph => new Walker(f => ({
  *
  * **Example** (Iterating all edges)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3408,8 +4033,7 @@ export const nodes = graph => new Walker(f => ({
  *   Graph.addEdge(mutable, b, c, 2)
  * })
  *
- * const indices = Array.from(Graph.indices(Graph.edges(graph)))
- * console.log(indices) // [0, 1]
+ * Array.from(Graph.indices(Graph.edges(graph))) // => [0, 1]
  * ```
  *
  * @category iterators
@@ -3417,7 +4041,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() {
@@ -3448,7 +4072,7 @@ export const edges = graph => new Walker(f => ({
  *
  * **Example** (Iterating external nodes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>((mutable) => {
@@ -3462,16 +4086,10 @@ export const edges = graph => new Walker(f => ({
  * })
  *
  * // Nodes with no outgoing edges (sinks + isolated)
- * const sinks = Array.from(
- *   Graph.indices(Graph.externals(graph, { direction: "outgoing" }))
- * )
- * console.log(sinks) // [2, 3]
+ * Array.from(Graph.indices(Graph.externals(graph, { direction: "outgoing" }))) // => [2, 3]
  *
  * // Nodes with no incoming edges (sources + isolated)
- * const sources = Array.from(
- *   Graph.indices(Graph.externals(graph, { direction: "incoming" }))
- * )
- * console.log(sources) // [0, 3]
+ * Array.from(Graph.indices(Graph.externals(graph, { direction: "incoming" }))) // => [0, 3]
  * ```
  *
  * @category iterators
@@ -3481,8 +4099,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();