effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/Graph.ts

@@ -1,4 +1,54 @@
 /**
+ * The `Graph` module provides immutable and scoped-mutable graph data
+ * structures for modeling relationships between indexed nodes and edges. A
+ * graph can be directed or undirected, stores user-defined data on both nodes
+ * and edges, and exposes traversal, analysis, path finding, transformation, and
+ * diagram export utilities.
+ *
+ * **Mental model**
+ *
+ * - Nodes and edges are addressed by stable numeric indices: {@link NodeIndex}
+ *   and {@link EdgeIndex}
+ * - Node data has type `N`; edge data has type `E`
+ * - {@link Graph} values are immutable snapshots; use {@link MutableGraph}
+ *   through {@link mutate}, {@link beginMutation}, or constructor callbacks to
+ *   add, remove, or update nodes and edges
+ * - Directed graphs follow edge direction for neighbors and traversals, while
+ *   undirected graphs treat each edge as connecting both endpoints
+ * - Missing lookups return `Option`, while structurally invalid operations such
+ *   as adding an edge to a missing node throw {@link GraphError}
+ *
+ * **Common tasks**
+ *
+ * - Create graphs: {@link directed}, {@link undirected}
+ * - Mutate safely: {@link mutate}, {@link addNode}, {@link addEdge},
+ *   {@link removeNode}, {@link removeEdge}
+ * - Query contents: {@link getNode}, {@link getEdge}, {@link hasNode},
+ *   {@link hasEdge}, {@link nodeCount}, {@link edgeCount}, {@link neighbors}
+ * - Transform data: {@link updateNode}, {@link updateEdge}, {@link mapNodes},
+ *   {@link mapEdges}, {@link filterNodes}, {@link filterEdges},
+ *   {@link filterMapNodes}, {@link filterMapEdges}
+ * - Traverse lazily: {@link dfs}, {@link bfs}, {@link topo},
+ *   {@link dfsPostOrder}, {@link nodes}, {@link edges}, {@link Walker}
+ * - Analyze structure: {@link isAcyclic}, {@link isBipartite},
+ *   {@link connectedComponents}, {@link stronglyConnectedComponents},
+ *   {@link externals}
+ * - Find paths: {@link dijkstra}, {@link astar}, {@link bellmanFord},
+ *   {@link floydWarshall}
+ * - Export diagrams: {@link toGraphViz}, {@link toMermaid}
+ *
+ * **Gotchas**
+ *
+ * - Only mutable graphs can be changed. Create one with {@link mutate} or by
+ *   passing a callback to {@link directed} / {@link undirected}.
+ * - Traversal APIs return lazy {@link Walker} values. Use {@link indices},
+ *   {@link values}, or {@link entries} to choose what each iteration yields.
+ * - `NodeIndex` and `EdgeIndex` values are identifiers, not array offsets. They
+ *   are not reused after removals.
+ * - Shortest-path algorithms require a cost function. {@link dijkstra} and
+ *   {@link astar} reject negative weights; use {@link bellmanFord} or
+ *   {@link floydWarshall} when negative weights are part of the model.
+ *
  * @since 4.0.0
  */
 
@@ -19,24 +69,24 @@ const TypeId = "~effect/collections/Graph"
 /**
  * Node index for node identification using plain numbers.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NodeIndex = number
 
 /**
  * Edge index for edge identification using plain numbers.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type EdgeIndex = number
 
 /**
  * Edge data containing source, target, and user data.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Edge<E> extends Data.Class<{
   readonly source: NodeIndex
@@ -47,16 +97,21 @@ export class Edge<E> extends Data.Class<{
 /**
  * Graph type for distinguishing directed and undirected graphs.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Kind = "directed" | "undirected"
 
 /**
- * Graph prototype interface.
+ * Common structural interface shared by immutable and mutable graphs.
+ *
+ * **Details**
+ *
+ * Contains the node and edge maps, adjacency indexes, allocation counters, and
+ * shared protocols used by both `Graph` and `MutableGraph`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>, Equal.Equal, Pipeable, Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -72,8 +127,8 @@ export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>,
 /**
  * Immutable graph interface.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<N, E> {
   readonly type: T
@@ -83,8 +138,8 @@ export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<
 /**
  * Mutable graph interface.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends Proto<N, E> {
   readonly type: T
@@ -94,32 +149,32 @@ export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends
 /**
  * Directed graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type DirectedGraph<N, E> = Graph<N, E, "directed">
 
 /**
  * Undirected graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type UndirectedGraph<N, E> = Graph<N, E, "undirected">
 
 /**
  * Mutable directed graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MutableDirectedGraph<N, E> = MutableGraph<N, E, "directed">
 
 /**
  * Mutable undirected graph type alias.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MutableUndirectedGraph<N, E> = MutableGraph<N, E, "undirected">
 
@@ -205,8 +260,12 @@ const ProtoGraph = {
 // TODO: Do we need safe variants for these?
 
 /**
- * @since 4.0.0
+ * Error thrown by graph operations when the requested graph structure is
+ * invalid, such as referencing a missing node or using unsupported edge
+ * weights.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class GraphError extends Data.TaggedError("GraphError")<{
   readonly message: string
@@ -220,15 +279,19 @@ const missingNode = (node: number) => new GraphError({ message: `Node ${node} do
 // =============================================================================
 
 /**
- * @since 4.0.0
+ * Returns `true` if a value has the graph runtime type identifier, narrowing
+ * it to a `Graph`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isGraph = (u: unknown): u is Graph<unknown, unknown> => hasProperty(u, TypeId)
 
 /**
  * Creates a directed graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating a directed graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -242,8 +305,8 @@ export const isGraph = (u: unknown): u is Graph<unknown, unknown> => hasProperty
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directed = <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) => void): DirectedGraph<N, E> => {
   const graph: Mutable<DirectedGraph<N, E>> = Object.create(ProtoGraph)
@@ -269,7 +332,8 @@ export const directed = <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) =>
 /**
  * Creates an undirected graph, optionally with initial mutations.
  *
- * @example
+ * **Example** (Creating an undirected graph)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -283,8 +347,8 @@ export const directed = <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const undirected = <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>) => void): UndirectedGraph<N, E> => {
   const graph: Mutable<UndirectedGraph<N, E>> = Object.create(ProtoGraph)
@@ -314,7 +378,8 @@ export const undirected = <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>
 /**
  * Creates a mutable scope for safe graph mutations by copying the data structure.
  *
- * @example
+ * **Example** (Beginning a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -323,8 +388,8 @@ export const undirected = <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>
  * // Now mutable can be safely modified without affecting original graph
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const beginMutation = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T>
@@ -358,7 +423,8 @@ export const beginMutation = <N, E, T extends Kind = "directed">(
 /**
  * Converts a mutable graph back to an immutable graph, ending the mutation scope.
  *
- * @example
+ * **Example** (Ending a mutation scope)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -368,8 +434,8 @@ export const beginMutation = <N, E, T extends Kind = "directed">(
  * const newGraph = Graph.endMutation(mutable)
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const endMutation = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>
@@ -391,55 +457,70 @@ export const endMutation = <N, E, T extends Kind = "directed">(
 /**
  * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
  *
- * @example
+ * **Example** (Applying scoped mutations)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
  * const graph = Graph.directed<string, number>()
  * const newGraph = Graph.mutate(graph, (mutable) => {
- *   // Safe mutations go here
- *   // mutable gets automatically converted back to immutable
+ *   const nodeA = Graph.addNode(mutable, "A")
+ *   const nodeB = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, nodeA, nodeB, 1)
  * })
+ *
+ * console.log(Graph.nodeCount(newGraph)) // 2
+ * console.log(Graph.edgeCount(newGraph)) // 1
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const mutate: {
   /**
    * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
    *
-   * @example
+   * **Example** (Applying scoped mutations)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
    * const graph = Graph.directed<string, number>()
    * const newGraph = Graph.mutate(graph, (mutable) => {
-   *   // Safe mutations go here
-   *   // mutable gets automatically converted back to immutable
+   *   const nodeA = Graph.addNode(mutable, "A")
+   *   const nodeB = Graph.addNode(mutable, "B")
+   *   Graph.addEdge(mutable, nodeA, nodeB, 1)
    * })
+   *
+   * console.log(Graph.nodeCount(newGraph)) // 2
+   * console.log(Graph.edgeCount(newGraph)) // 1
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(f: (mutable: MutableGraph<N, E, T>) => void): (graph: Graph<N, E, T>) => Graph<N, E, T>
   /**
    * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
    *
-   * @example
+   * **Example** (Applying scoped mutations)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
    * const graph = Graph.directed<string, number>()
    * const newGraph = Graph.mutate(graph, (mutable) => {
-   *   // Safe mutations go here
-   *   // mutable gets automatically converted back to immutable
+   *   const nodeA = Graph.addNode(mutable, "A")
+   *   const nodeB = Graph.addNode(mutable, "B")
+   *   Graph.addEdge(mutable, nodeA, nodeB, 1)
    * })
+   *
+   * console.log(Graph.nodeCount(newGraph)) // 2
+   * console.log(Graph.edgeCount(newGraph)) // 1
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>, f: (mutable: MutableGraph<N, E, T>) => void): Graph<N, E, T>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -458,7 +539,8 @@ export const mutate: {
 /**
  * Adds a new node to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -470,8 +552,8 @@ export const mutate: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const addNode = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -495,7 +577,8 @@ export const addNode = <N, E, T extends Kind = "directed">(
 /**
  * Gets the data associated with a node index, if it exists.
  *
- * @example
+ * **Example** (Getting node data)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -512,14 +595,15 @@ export const addNode = <N, E, T extends Kind = "directed">(
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getNode: {
   /**
    * Gets the data associated with a node index, if it exists.
    *
-   * @example
+   * **Example** (Getting node data)
+   *
    * ```ts
    * import { Graph } from "effect"
    * import * as Option from "effect/Option"
@@ -536,14 +620,15 @@ export const getNode: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(nodeIndex: NodeIndex): (graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<N>
   /**
    * Gets the data associated with a node index, if it exists.
    *
-   * @example
+   * **Example** (Getting node data)
+   *
    * ```ts
    * import { Graph } from "effect"
    * import * as Option from "effect/Option"
@@ -560,8 +645,8 @@ export const getNode: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): Option.Option<N>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -572,7 +657,8 @@ export const getNode: {
 /**
  * Checks if a node with the given index exists in the graph.
  *
- * @example
+ * **Example** (Checking node existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -589,14 +675,15 @@ export const getNode: {
  * console.log(notExists) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const hasNode: {
   /**
    * Checks if a node with the given index exists in the graph.
    *
-   * @example
+   * **Example** (Checking node existence)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -613,14 +700,15 @@ export const hasNode: {
    * console.log(notExists) // false
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   (nodeIndex: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean
   /**
    * Checks if a node with the given index exists in the graph.
    *
-   * @example
+   * **Example** (Checking node existence)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -637,8 +725,8 @@ export const hasNode: {
    * console.log(notExists) // false
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): boolean
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -649,7 +737,8 @@ export const hasNode: {
 /**
  * Returns the number of nodes in the graph.
  *
- * @example
+ * **Example** (Counting nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -665,8 +754,8 @@ export const hasNode: {
  * console.log(Graph.nodeCount(graphWithNodes)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const nodeCount = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
@@ -675,7 +764,8 @@ export const nodeCount = <N, E, T extends Kind = "directed">(
 /**
  * Finds the first node that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -692,14 +782,15 @@ export const nodeCount = <N, E, T extends Kind = "directed">(
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findNode: {
   /**
    * Finds the first node that matches the given predicate.
    *
-   * @example
+   * **Example** (Finding the first matching node)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -716,14 +807,15 @@ export const findNode: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<NodeIndex>
   /**
    * Finds the first node that matches the given predicate.
    *
-   * @example
+   * **Example** (Finding the first matching node)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -740,8 +832,8 @@ export const findNode: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -762,7 +854,8 @@ export const findNode: {
 /**
  * Finds all nodes that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -779,14 +872,15 @@ export const findNode: {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findNodes: {
   /**
    * Finds all nodes that match the given predicate.
    *
-   * @example
+   * **Example** (Finding matching nodes)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -803,14 +897,15 @@ export const findNodes: {
    * console.log(empty) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>
   /**
    * Finds all nodes that match the given predicate.
    *
-   * @example
+   * **Example** (Finding matching nodes)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -827,8 +922,8 @@ export const findNodes: {
    * console.log(empty) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -850,7 +945,8 @@ export const findNodes: {
 /**
  * Finds the first edge that matches the given predicate.
  *
- * @example
+ * **Example** (Finding the first matching edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -869,14 +965,15 @@ export const findNodes: {
  * console.log(notFound) // Option.none()
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findEdge: {
   /**
    * Finds the first edge that matches the given predicate.
    *
-   * @example
+   * **Example** (Finding the first matching edge)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -895,14 +992,15 @@ export const findEdge: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<EdgeIndex>
   /**
    * Finds the first edge that matches the given predicate.
    *
-   * @example
+   * **Example** (Finding the first matching edge)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -921,8 +1019,8 @@ export const findEdge: {
    * console.log(notFound) // Option.none()
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -943,7 +1041,8 @@ export const findEdge: {
 /**
  * Finds all edges that match the given predicate.
  *
- * @example
+ * **Example** (Finding matching edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -963,14 +1062,15 @@ export const findEdge: {
  * console.log(empty) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const findEdges: {
   /**
    * Finds all edges that match the given predicate.
    *
-   * @example
+   * **Example** (Finding matching edges)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -990,14 +1090,15 @@ export const findEdges: {
    * console.log(empty) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<EdgeIndex>
   /**
    * Finds all edges that match the given predicate.
    *
-   * @example
+   * **Example** (Finding matching edges)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1017,8 +1118,8 @@ export const findEdges: {
    * console.log(empty) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -1040,7 +1141,8 @@ export const findEdges: {
 /**
  * Updates a single node's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating node data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1054,8 +1156,8 @@ export const findEdges: {
  * console.log(nodeData) // Option.some("NODE A")
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const updateNode = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1074,7 +1176,8 @@ export const updateNode = <N, E, T extends Kind = "directed">(
 /**
  * Updates a single edge's data by applying a transformation function.
  *
- * @example
+ * **Example** (Updating edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1086,11 +1189,11 @@ export const updateNode = <N, E, T extends Kind = "directed">(
  * })
  *
  * const edgeData = Graph.getEdge(result, 0)
- * console.log(edgeData) // new Graph.Edge({ source: 0, target: 1, data: 20 })
+ * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const updateEdge = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1107,9 +1210,15 @@ export const updateEdge = <N, E, T extends Kind = "directed">(
 }
 
 /**
- * Creates a new graph with transformed node data using the provided mapping function.
+ * Transforms every node's data in a mutable graph in place using the provided
+ * mapping function.
+ *
+ * **Details**
+ *
+ * Node indices and edges are preserved; only the stored node data is replaced.
+ *
+ * **Example** (Mapping node data)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1121,11 +1230,11 @@ export const updateEdge = <N, E, T extends Kind = "directed">(
  * })
  *
  * const nodeData = Graph.getNode(graph, 0)
- * console.log(nodeData) // new Graph.Node("NODE A")
+ * console.log(nodeData) // Option.some("NODE A")
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const mapNodes = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1141,7 +1250,8 @@ export const mapNodes = <N, E, T extends Kind = "directed">(
 /**
  * Transforms all edge data in a mutable graph using the provided mapping function.
  *
- * @example
+ * **Example** (Mapping edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1155,11 +1265,11 @@ export const mapNodes = <N, E, T extends Kind = "directed">(
  * })
  *
  * const edgeData = Graph.getEdge(graph, 0)
- * console.log(edgeData) // new Graph.Edge({ source: 0, target: 1, data: 20 })
+ * console.log(edgeData) // Option.some(new Graph.Edge({ source: 0, target: 1, data: 20 }))
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const mapEdges = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1178,7 +1288,8 @@ export const mapEdges = <N, E, T extends Kind = "directed">(
 /**
  * Reverses all edge directions in a mutable graph by swapping source and target nodes.
  *
- * @example
+ * **Example** (Reversing edge directions)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1192,11 +1303,11 @@ export const mapEdges = <N, E, T extends Kind = "directed">(
  * })
  *
  * const edge0 = Graph.getEdge(graph, 0)
- * console.log(edge0) // new Graph.Edge({ source: 1, target: 0, data: 1 }) - B -> A
+ * console.log(edge0) // Option.some(new Graph.Edge({ source: 1, target: 0, data: 1 }))
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const reverse = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>
@@ -1238,7 +1349,8 @@ export const reverse = <N, E, T extends Kind = "directed">(
  * Filters and optionally transforms nodes in a mutable graph using a predicate function.
  * Nodes that return Option.none are removed along with all their connected edges.
  *
- * @example
+ * **Example** (Filtering and mapping nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -1261,8 +1373,8 @@ export const reverse = <N, E, T extends Kind = "directed">(
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterMapNodes = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1292,7 +1404,8 @@ export const filterMapNodes = <N, E, T extends Kind = "directed">(
  * Filters and optionally transforms edges in a mutable graph using a predicate function.
  * Edges that return Option.none are removed from the graph.
  *
- * @example
+ * **Example** (Filtering and mapping edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  * import * as Option from "effect/Option"
@@ -1315,8 +1428,8 @@ export const filterMapNodes = <N, E, T extends Kind = "directed">(
  * console.log(Graph.edgeCount(graph)) // 2 (edges with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterMapEdges = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1349,7 +1462,8 @@ export const filterMapEdges = <N, E, T extends Kind = "directed">(
  * Filters nodes by removing those that don't match the predicate.
  * This function modifies the mutable graph in place.
  *
- * @example
+ * **Example** (Filtering nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1366,8 +1480,8 @@ export const filterMapEdges = <N, E, T extends Kind = "directed">(
  * console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterNodes = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1392,7 +1506,8 @@ export const filterNodes = <N, E, T extends Kind = "directed">(
  * Filters edges by removing those that don't match the predicate.
  * This function modifies the mutable graph in place.
  *
- * @example
+ * **Example** (Filtering edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1412,8 +1527,8 @@ export const filterNodes = <N, E, T extends Kind = "directed">(
  * console.log(Graph.edgeCount(graph)) // 2 (edge with weight 5 removed)
  * ```
  *
- * @since 4.0.0
  * @category transformations
+ * @since 4.0.0
  */
 export const filterEdges = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1465,7 +1580,8 @@ const invalidateCycleFlagOnAddition = <N, E, T extends Kind = "directed">(
 /**
  * Adds a new edge to a mutable graph and returns its index.
  *
- * @example
+ * **Example** (Adding edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1477,8 +1593,8 @@ const invalidateCycleFlagOnAddition = <N, E, T extends Kind = "directed">(
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const addEdge = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1537,7 +1653,8 @@ export const addEdge = <N, E, T extends Kind = "directed">(
 /**
  * Removes a node and all its incident edges from a mutable graph.
  *
- * @example
+ * **Example** (Removing a node)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1551,8 +1668,8 @@ export const addEdge = <N, E, T extends Kind = "directed">(
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const removeNode = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1600,7 +1717,8 @@ export const removeNode = <N, E, T extends Kind = "directed">(
 /**
  * Removes an edge from a mutable graph.
  *
- * @example
+ * **Example** (Removing an edge)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1614,8 +1732,8 @@ export const removeNode = <N, E, T extends Kind = "directed">(
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const removeEdge = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>,
@@ -1692,7 +1810,8 @@ const removeEdgeInternal = <N, E, T extends Kind = "directed">(
 /**
  * Gets the edge data associated with an edge index, if it exists.
  *
- * @example
+ * **Example** (Getting edge data)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1707,13 +1826,13 @@ const removeEdgeInternal = <N, E, T extends Kind = "directed">(
  *
  * if (edgeData._tag === "Some") {
  *   console.log(edgeData.value.data) // 42
- *   console.log(edgeData.value.source) // NodeIndex(0)
- *   console.log(edgeData.value.target) // NodeIndex(1)
+ *   console.log(edgeData.value.source) // 0
+ *   console.log(edgeData.value.target) // 1
  * }
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getEdge: {
   // =============================================================================
@@ -1723,7 +1842,8 @@ export const getEdge: {
   /**
    * Gets the edge data associated with an edge index, if it exists.
    *
-   * @example
+   * **Example** (Getting edge data)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1738,13 +1858,13 @@ export const getEdge: {
    *
    * if (edgeData._tag === "Some") {
    *   console.log(edgeData.value.data) // 42
-   *   console.log(edgeData.value.source) // NodeIndex(0)
-   *   console.log(edgeData.value.target) // NodeIndex(1)
+   *   console.log(edgeData.value.source) // 0
+   *   console.log(edgeData.value.target) // 1
    * }
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <E>(edgeIndex: EdgeIndex): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<Edge<E>>
   // =============================================================================
@@ -1754,7 +1874,8 @@ export const getEdge: {
   /**
    * Gets the edge data associated with an edge index, if it exists.
    *
-   * @example
+   * **Example** (Getting edge data)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1769,13 +1890,13 @@ export const getEdge: {
    *
    * if (edgeData._tag === "Some") {
    *   console.log(edgeData.value.data) // 42
-   *   console.log(edgeData.value.source) // NodeIndex(0)
-   *   console.log(edgeData.value.target) // NodeIndex(1)
+   *   console.log(edgeData.value.source) // 0
+   *   console.log(edgeData.value.target) // 1
    * }
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, edgeIndex: EdgeIndex): Option.Option<Edge<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -1786,7 +1907,8 @@ export const getEdge: {
 /**
  * Checks if an edge exists between two nodes in the graph.
  *
- * @example
+ * **Example** (Checking edge existence)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1808,14 +1930,15 @@ export const getEdge: {
  * console.log(hasAC) // false
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const hasEdge: {
   /**
    * Checks if an edge exists between two nodes in the graph.
    *
-   * @example
+   * **Example** (Checking edge existence)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1837,14 +1960,15 @@ export const hasEdge: {
    * console.log(hasAC) // false
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   (source: NodeIndex, target: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => boolean
   /**
    * Checks if an edge exists between two nodes in the graph.
    *
-   * @example
+   * **Example** (Checking edge existence)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1866,8 +1990,8 @@ export const hasEdge: {
    * console.log(hasAC) // false
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -1898,7 +2022,8 @@ export const hasEdge: {
 /**
  * Returns the number of edges in the graph.
  *
- * @example
+ * **Example** (Counting edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1917,17 +2042,23 @@ export const hasEdge: {
  * console.log(Graph.edgeCount(graphWithEdges)) // 3
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const edgeCount = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
 ): number => graph.edges.size
 
 /**
- * Returns the neighboring nodes (targets of outgoing edges) for a given node.
+ * Returns the neighboring node indices for a node.
+ *
+ * **Details**
+ *
+ * For directed graphs, neighbors are the targets of outgoing edges. For
+ * undirected graphs, neighbors are the other endpoints of incident edges.
+ *
+ * **Example** (Getting outgoing neighbors)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -1944,20 +2075,26 @@ export const edgeCount = <N, E, T extends Kind = "directed">(
  * const nodeC = 2
  *
  * const neighborsA = Graph.neighbors(graph, nodeA)
- * console.log(neighborsA) // [NodeIndex(1), NodeIndex(2)]
+ * console.log(neighborsA) // [1, 2]
  *
  * const neighborsB = Graph.neighbors(graph, nodeB)
  * console.log(neighborsB) // []
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const neighbors: {
   /**
-   * Returns the neighboring nodes (targets of outgoing edges) for a given node.
+   * Returns the neighboring node indices for a node.
+   *
+   * **Details**
+   *
+   * For directed graphs, neighbors are the targets of outgoing edges. For
+   * undirected graphs, neighbors are the other endpoints of incident edges.
+   *
+   * **Example** (Getting outgoing neighbors)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -1974,20 +2111,26 @@ export const neighbors: {
    * const nodeC = 2
    *
    * const neighborsA = Graph.neighbors(graph, nodeA)
-   * console.log(neighborsA) // [NodeIndex(1), NodeIndex(2)]
+   * console.log(neighborsA) // [1, 2]
    *
    * const neighborsB = Graph.neighbors(graph, nodeB)
    * console.log(neighborsB) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   (nodeIndex: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>
   /**
-   * Returns the neighboring nodes (targets of outgoing edges) for a given node.
+   * Returns the neighboring node indices for a node.
+   *
+   * **Details**
+   *
+   * For directed graphs, neighbors are the targets of outgoing edges. For
+   * undirected graphs, neighbors are the other endpoints of incident edges.
+   *
+   * **Example** (Getting outgoing neighbors)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2004,14 +2147,14 @@ export const neighbors: {
    * const nodeC = 2
    *
    * const neighborsA = Graph.neighbors(graph, nodeA)
-   * console.log(neighborsA) // [NodeIndex(1), NodeIndex(2)]
+   * console.log(neighborsA) // [1, 2]
    *
    * const neighborsB = Graph.neighbors(graph, nodeB)
    * console.log(neighborsB) // []
    * ```
    *
-   * @since 4.0.0
    * @category getters
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, nodeIndex: NodeIndex): Array<NodeIndex>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -2042,7 +2185,8 @@ export const neighbors: {
 /**
  * Get neighbors of a node in a specific direction for bidirectional traversal.
  *
- * @example
+ * **Example** (Traversing directed neighbors)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2062,14 +2206,15 @@ export const neighbors: {
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
  * ```
  *
- * @since 4.0.0
  * @category queries
+ * @since 4.0.0
  */
 export const neighborsDirected: {
   /**
    * Get neighbors of a node in a specific direction for bidirectional traversal.
    *
-   * @example
+   * **Example** (Traversing directed neighbors)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2089,14 +2234,15 @@ export const neighborsDirected: {
    * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
    * ```
    *
-   * @since 4.0.0
    * @category queries
+   * @since 4.0.0
    */
   (nodeIndex: NodeIndex, direction: Direction): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>
   /**
    * Get neighbors of a node in a specific direction for bidirectional traversal.
    *
-   * @example
+   * **Example** (Traversing directed neighbors)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2116,8 +2262,8 @@ export const neighborsDirected: {
    * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
    * ```
    *
-   * @since 4.0.0
    * @category queries
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -2163,7 +2309,8 @@ export const neighborsDirected: {
  * Provides customization for node labels, edge labels, and graph naming
  * in DOT format compatible with GraphViz tools.
  *
- * @example
+ * **Example** (Configuring GraphViz labels)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -2181,8 +2328,8 @@ export const neighborsDirected: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface GraphVizOptions<N, E> {
   /**
@@ -2207,7 +2354,8 @@ export interface GraphVizOptions<N, E> {
 /**
  * Exports a graph to GraphViz DOT format for visualization.
  *
- * @example
+ * **Example** (Exporting GraphViz DOT)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -2232,14 +2380,15 @@ export interface GraphVizOptions<N, E> {
  * // }
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const toGraphViz: {
   /**
    * Exports a graph to GraphViz DOT format for visualization.
    *
-   * @example
+   * **Example** (Exporting GraphViz DOT)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2264,14 +2413,15 @@ export const toGraphViz: {
    * // }
    * ```
    *
-   * @since 4.0.0
    * @category utils
+   * @since 4.0.0
    */
   <N, E>(options?: GraphVizOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string
   /**
    * Exports a graph to GraphViz DOT format for visualization.
    *
-   * @example
+   * **Example** (Exporting GraphViz DOT)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -2296,8 +2446,8 @@ export const toGraphViz: {
    * // }
    * ```
    *
-   * @since 4.0.0
    * @category utils
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -2353,7 +2503,8 @@ export const toGraphViz: {
  * - `subroutine`: Subroutine-style nodes `A[["label"]]`
  * - `cylindrical`: Cylindrical database-style nodes `A[("label")]`
  *
- * @example
+ * **Example** (Selecting Mermaid node shapes)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -2371,8 +2522,8 @@ export const toGraphViz: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidNodeShape =
   | "rectangle" // A["label"]
@@ -2393,7 +2544,8 @@ export type MermaidNodeShape =
  * - `LR`: Left to Right (horizontal layout)
  * - `RL`: Right to Left (reverse horizontal)
  *
- * @example
+ * **Example** (Configuring Mermaid directions)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -2413,8 +2565,8 @@ export type MermaidNodeShape =
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidDirection =
   | "TB" // Top to Bottom (default)
@@ -2433,7 +2585,8 @@ export type MermaidDirection =
  * When not specified, automatically selects based on graph type:
  * directed graphs use "flowchart", undirected graphs use "graph".
  *
- * @example
+ * **Example** (Selecting Mermaid diagram types)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -2451,8 +2604,8 @@ export type MermaidDirection =
  * const autoOptions: Graph.MermaidOptions<string, string> = {}
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MermaidDiagramType =
   | "flowchart" // For directed graphs
@@ -2461,8 +2614,8 @@ export type MermaidDiagramType =
 /**
  * Configuration options for Mermaid diagram generation, following GraphViz pattern.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 /**
  * Configuration options for Mermaid diagram generation from graphs.
@@ -2470,7 +2623,8 @@ export type MermaidDiagramType =
  * Provides customization for node labels, edge labels, diagram type,
  * layout direction, node shapes, and graph naming in Mermaid format.
  *
- * @example
+ * **Example** (Configuring Mermaid output)
+ *
  * ```ts
  * import type * as Graph from "effect/Graph"
  *
@@ -2490,8 +2644,8 @@ export type MermaidDiagramType =
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MermaidOptions<N, E> {
   /**
@@ -2587,7 +2741,8 @@ const formatMermaidNode = (
  * structures to valid Mermaid syntax for use in documentation, web applications,
  * and visualization tools.
  *
- * @example
+ * **Example** (Exporting a directed Mermaid diagram)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -2610,7 +2765,8 @@ const formatMermaidNode = (
  * //   0 -->|"2"| 2
  * ```
  *
- * @example
+ * **Example** (Exporting an undirected Mermaid diagram)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -2637,7 +2793,8 @@ const formatMermaidNode = (
  * //   1 ---|"colleagues"| 2
  * ```
  *
- * @example
+ * **Example** (Customizing Mermaid node shapes)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -2688,7 +2845,8 @@ const formatMermaidNode = (
  * //   2 --> 3
  * ```
  *
- * @example
+ * **Example** (Visualizing dependency graphs)
+ *
  * ```ts
  * import * as Graph from "effect/Graph"
  *
@@ -2753,8 +2911,8 @@ const formatMermaidNode = (
  * @param options - Optional configuration for the Mermaid output
  * @returns Mermaid diagram syntax as a string
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const toMermaid: {
   /**
@@ -2765,7 +2923,8 @@ export const toMermaid: {
    * structures to valid Mermaid syntax for use in documentation, web applications,
    * and visualization tools.
    *
-   * @example
+   * **Example** (Exporting a directed Mermaid diagram)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2788,7 +2947,8 @@ export const toMermaid: {
    * //   0 -->|"2"| 2
    * ```
    *
-   * @example
+   * **Example** (Exporting an undirected Mermaid diagram)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2815,7 +2975,8 @@ export const toMermaid: {
    * //   1 ---|"colleagues"| 2
    * ```
    *
-   * @example
+   * **Example** (Customizing Mermaid node shapes)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2866,7 +3027,8 @@ export const toMermaid: {
    * //   2 --> 3
    * ```
    *
-   * @example
+   * **Example** (Visualizing dependency graphs)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2931,8 +3093,8 @@ export const toMermaid: {
    * @param options - Optional configuration for the Mermaid output
    * @returns Mermaid diagram syntax as a string
    *
-   * @since 4.0.0
    * @category utils
+   * @since 4.0.0
    */
   <N, E>(options?: MermaidOptions<N, E>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => string
   /**
@@ -2943,7 +3105,8 @@ export const toMermaid: {
    * structures to valid Mermaid syntax for use in documentation, web applications,
    * and visualization tools.
    *
-   * @example
+   * **Example** (Exporting a directed Mermaid diagram)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2966,7 +3129,8 @@ export const toMermaid: {
    * //   0 -->|"2"| 2
    * ```
    *
-   * @example
+   * **Example** (Exporting an undirected Mermaid diagram)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -2993,7 +3157,8 @@ export const toMermaid: {
    * //   1 ---|"colleagues"| 2
    * ```
    *
-   * @example
+   * **Example** (Customizing Mermaid node shapes)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -3044,7 +3209,8 @@ export const toMermaid: {
    * //   2 --> 3
    * ```
    *
-   * @example
+   * **Example** (Visualizing dependency graphs)
+   *
    * ```ts
    * import * as Graph from "effect/Graph"
    *
@@ -3109,8 +3275,8 @@ export const toMermaid: {
    * @param options - Optional configuration for the Mermaid output
    * @returns Mermaid diagram syntax as a string
    *
-   * @since 4.0.0
    * @category utils
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -3170,7 +3336,8 @@ export const toMermaid: {
 /**
  * Direction for graph traversal, indicating which edges to follow.
  *
- * @example
+ * **Example** (Traversing by direction)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3191,8 +3358,8 @@ export const toMermaid: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Direction = "outgoing" | "incoming"
 
@@ -3207,7 +3374,8 @@ export type Direction = "outgoing" | "incoming"
  * 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.
  *
- * @example
+ * **Example** (Checking cycles)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3231,8 +3399,8 @@ export type Direction = "outgoing" | "incoming"
  * console.log(Graph.isAcyclic(cyclic)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const isAcyclic = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
@@ -3317,7 +3485,8 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
  * such that no two vertices within the same set are adjacent. Uses BFS coloring
  * to determine bipartiteness.
  *
- * @example
+ * **Example** (Checking bipartite graphs)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3345,8 +3514,8 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
  * console.log(Graph.isBipartite(triangle)) // false
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const isBipartite = <N, E>(
   graph: Graph<N, E, "undirected"> | MutableGraph<N, E, "undirected">
@@ -3426,7 +3595,8 @@ const getUndirectedNeighbors = <N, E>(
  * Find connected components in an undirected graph.
  * Each component is represented as an array of node indices.
  *
- * @example
+ * **Example** (Finding connected components)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3443,8 +3613,8 @@ const getUndirectedNeighbors = <N, E>(
  * console.log(components) // [[0, 1], [2, 3]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const connectedComponents = <N, E>(
   graph: Graph<N, E, "undirected"> | MutableGraph<N, E, "undirected">
@@ -3484,7 +3654,8 @@ export const connectedComponents = <N, E>(
  * Find strongly connected components in a directed graph using Kosaraju's algorithm.
  * Each SCC is represented as an array of node indices.
  *
- * @example
+ * **Example** (Finding strongly connected components)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3501,8 +3672,8 @@ export const connectedComponents = <N, E>(
  * console.log(sccs) // [[0, 1, 2]]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const stronglyConnectedComponents = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
@@ -3602,10 +3773,15 @@ export const stronglyConnectedComponents = <N, E, T extends Kind = "directed">(
 // =============================================================================
 
 /**
- * Result of a shortest path computation containing the path and total distance.
+ * Result of a shortest path computation.
+ *
+ * **Details**
+ *
+ * Contains the node-index path, the total numeric distance, and the edge data
+ * encountered along the path.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface PathResult<E> {
   readonly path: Array<NodeIndex>
@@ -3614,10 +3790,15 @@ export interface PathResult<E> {
 }
 
 /**
- * Configuration for Dijkstra's algorithm.
+ * Configuration for finding a shortest path with Dijkstra's algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, plus a cost function that maps
+ * each edge's data to a non-negative numeric weight.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface DijkstraConfig<E> {
   source: NodeIndex
@@ -3626,12 +3807,17 @@ export interface DijkstraConfig<E> {
 }
 
 /**
- * Find the shortest path between two nodes using Dijkstra's algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using Dijkstra's 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.
  *
- * Dijkstra's algorithm works with non-negative edge weights and finds the shortest
- * path from a source node to a target node in O((V + E) log V) time complexity.
+ * **Example** (Finding shortest paths with Dijkstra)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3656,17 +3842,22 @@ export interface DijkstraConfig<E> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const dijkstra: {
   /**
-   * Find the shortest path between two nodes using Dijkstra's algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using Dijkstra's algorithm.
+   *
+   * **Details**
    *
-   * Dijkstra's algorithm works with non-negative edge weights and finds the shortest
-   * path from a source node to a target node in O((V + E) log V) time complexity.
+   * 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.
+   *
+   * **Example** (Finding shortest paths with Dijkstra)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -3691,17 +3882,22 @@ export const dijkstra: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <E>(config: DijkstraConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
-   * Find the shortest path between two nodes using Dijkstra's algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using Dijkstra's algorithm.
    *
-   * Dijkstra's algorithm works with non-negative edge weights and finds the shortest
-   * path from a source node to a target node in O((V + E) log V) time complexity.
+   * **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.
+   *
+   * **Example** (Finding shortest paths with Dijkstra)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -3726,8 +3922,8 @@ export const dijkstra: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: DijkstraConfig<E>): Option.Option<PathResult<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -3857,10 +4053,15 @@ export const dijkstra: {
 })
 
 /**
- * Result of all-pairs shortest path computation.
+ * Result of an all-pairs shortest path computation.
+ *
+ * **Details**
+ *
+ * Contains distance, node-path, and edge-data maps keyed by source and target
+ * node indices.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AllPairsResult<E> {
   readonly distances: Map<NodeIndex, Map<NodeIndex, number>>
@@ -3869,14 +4070,17 @@ export interface AllPairsResult<E> {
 }
 
 /**
- * Find shortest paths between all pairs of nodes using Floyd-Warshall algorithm.
+ * Finds shortest paths between all pairs of nodes using the Floyd-Warshall
+ * algorithm.
+ *
+ * **Details**
  *
- * Floyd-Warshall algorithm computes shortest paths between all pairs of nodes in O(V³) time.
- * It can handle negative edge weights and detect negative cycles.
+ * 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.
  *
- * Throws if a negative cycle is detected that affects the path to target.
+ * **Example** (Finding all-pairs shortest paths)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -3894,19 +4098,22 @@ export interface AllPairsResult<E> {
  * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const floydWarshall: {
   /**
-   * Find shortest paths between all pairs of nodes using Floyd-Warshall algorithm.
+   * Finds shortest paths between all pairs of nodes using the Floyd-Warshall
+   * algorithm.
+   *
+   * **Details**
    *
-   * Floyd-Warshall algorithm computes shortest paths between all pairs of nodes in O(V³) time.
-   * It can handle negative edge weights and detect negative cycles.
+   * 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.
    *
-   * Throws if a negative cycle is detected that affects the path to target.
+   * **Example** (Finding all-pairs shortest paths)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -3924,19 +4131,22 @@ export const floydWarshall: {
    * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <E>(cost: (edgeData: E) => number): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => AllPairsResult<E>
   /**
-   * Find shortest paths between all pairs of nodes using Floyd-Warshall algorithm.
+   * Finds shortest paths between all pairs of nodes using the Floyd-Warshall
+   * algorithm.
+   *
+   * **Details**
    *
-   * Floyd-Warshall algorithm computes shortest paths between all pairs of nodes in O(V³) time.
-   * It can handle negative edge weights and detect negative cycles.
+   * 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.
    *
-   * Throws if a negative cycle is detected that affects the path to target.
+   * **Example** (Finding all-pairs shortest paths)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -3954,8 +4164,8 @@ export const floydWarshall: {
    * const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -4073,10 +4283,15 @@ export const floydWarshall: {
 })
 
 /**
- * Configuration for A* pathfinding algorithm.
+ * Configuration for finding a shortest path with the A* algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, an edge-cost function, and a
+ * heuristic that estimates the remaining cost from a node to the target.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AstarConfig<E, N> {
   source: NodeIndex
@@ -4086,13 +4301,18 @@ export interface AstarConfig<E, N> {
 }
 
 /**
- * Find the shortest path between two nodes using A* pathfinding algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using the A* pathfinding algorithm.
+ *
+ * **Details**
+ *
+ * The edge-cost function must return non-negative weights, and the heuristic
+ * should be admissible 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.
  *
- * A* is an extension of Dijkstra's algorithm that uses a heuristic function to guide
- * the search towards the target, potentially finding paths faster than Dijkstra's.
- * The heuristic must be admissible (never overestimate the actual cost).
+ * **Example** (Finding shortest paths with A-star)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4123,18 +4343,23 @@ export interface AstarConfig<E, N> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const astar: {
   /**
-   * Find the shortest path between two nodes using A* pathfinding algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using the A* pathfinding algorithm.
+   *
+   * **Details**
    *
-   * A* is an extension of Dijkstra's algorithm that uses a heuristic function to guide
-   * the search towards the target, potentially finding paths faster than Dijkstra's.
-   * The heuristic must be admissible (never overestimate the actual cost).
+   * The edge-cost function must return non-negative weights, and the heuristic
+   * should be admissible 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.
+   *
+   * **Example** (Finding shortest paths with A-star)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4165,18 +4390,23 @@ export const astar: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <E, N>(config: AstarConfig<E, N>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
-   * Find the shortest path between two nodes using A* pathfinding algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using the A* pathfinding algorithm.
+   *
+   * **Details**
    *
-   * A* is an extension of Dijkstra's algorithm that uses a heuristic function to guide
-   * the search towards the target, potentially finding paths faster than Dijkstra's.
-   * The heuristic must be admissible (never overestimate the actual cost).
+   * The edge-cost function must return non-negative weights, and the heuristic
+   * should be admissible 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.
+   *
+   * **Example** (Finding shortest paths with A-star)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4207,8 +4437,8 @@ export const astar: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: AstarConfig<E, N>): Option.Option<PathResult<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
@@ -4362,10 +4592,15 @@ export const astar: {
 })
 
 /**
- * Configuration for Bellman-Ford algorithm.
+ * Configuration for finding a shortest path with the Bellman-Ford algorithm.
+ *
+ * **Details**
+ *
+ * Specifies the source and target node indices, plus a cost function that maps
+ * each edge's data to a numeric weight.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BellmanFordConfig<E> {
   source: NodeIndex
@@ -4374,13 +4609,17 @@ export interface BellmanFordConfig<E> {
 }
 
 /**
- * Find the shortest path between two nodes using Bellman-Ford algorithm.
+ * Finds the shortest path from the configured source node to the target node
+ * using the Bellman-Ford algorithm.
+ *
+ * **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.
  *
- * Bellman-Ford algorithm can handle negative edge weights and detects negative cycles.
- * It has O(VE) time complexity, slower than Dijkstra's but more versatile.
- * Returns Option.none() if a negative cycle is detected that affects the path.
+ * **Example** (Finding shortest paths with Bellman-Ford)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4405,18 +4644,22 @@ export interface BellmanFordConfig<E> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category algorithms
+ * @since 4.0.0
  */
 export const bellmanFord: {
   /**
-   * Find the shortest path between two nodes using Bellman-Ford algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using the Bellman-Ford algorithm.
+   *
+   * **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.
    *
-   * Bellman-Ford algorithm can handle negative edge weights and detects negative cycles.
-   * It has O(VE) time complexity, slower than Dijkstra's but more versatile.
-   * Returns Option.none() if a negative cycle is detected that affects the path.
+   * **Example** (Finding shortest paths with Bellman-Ford)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4441,18 +4684,22 @@ export const bellmanFord: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <E>(config: BellmanFordConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
-   * Find the shortest path between two nodes using Bellman-Ford algorithm.
+   * Finds the shortest path from the configured source node to the target node
+   * using the Bellman-Ford algorithm.
+   *
+   * **Details**
    *
-   * Bellman-Ford algorithm can handle negative edge weights and detects negative cycles.
-   * It has O(VE) time complexity, slower than Dijkstra's but more versatile.
-   * Returns Option.none() if a negative cycle is detected that affects the path.
+   * 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.
+   *
+   * **Example** (Finding shortest paths with Bellman-Ford)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4477,8 +4724,8 @@ export const bellmanFord: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category algorithms
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
@@ -4614,13 +4861,16 @@ export const bellmanFord: {
 })
 
 /**
- * Concrete class for iterables that produce [NodeIndex, NodeData] tuples.
+ * Iterable wrapper used by graph traversal and listing APIs.
+ *
+ * **Details**
  *
- * This class provides a common abstraction for all iterables that return node data,
- * including traversal iterators (DFS, BFS, etc.) and element iterators (nodes, externals).
- * It uses a mapEntry function pattern for flexible iteration and transformation.
+ * A `Walker` yields `[index, data]` pairs lazily and can be viewed as just the
+ * indices, just the values, or mapped entries with `indices`, `values`,
+ * `entries`, and `visit`.
+ *
+ * **Example** (Working with node walkers)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4644,8 +4894,8 @@ export const bellmanFord: {
  * const nodeEntries = Array.from(Graph.entries(allNodes)) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Walker<T, N> implements Iterable<[T, N]> {
   // @ts-ignore
@@ -4658,7 +4908,8 @@ export class Walker<T, N> implements Iterable<[T, N]> {
    * and returns an iterable of the mapped values. Skips elements that
    * no longer exist in the graph.
    *
-   * @example
+   * **Example** (Visiting walker elements)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4681,8 +4932,8 @@ export class Walker<T, N> implements Iterable<[T, N]> {
    * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   readonly visit: <U>(f: (index: T, data: N) => U) => Iterable<U>
 
@@ -4694,7 +4945,8 @@ export class Walker<T, N> implements Iterable<[T, N]> {
      * and returns an iterable of the mapped values. Skips elements that
      * no longer exist in the graph.
      *
-     * @example
+     * **Example** (Visiting walker elements)
+     *
      * ```ts
      * import { Graph } from "effect"
      *
@@ -4717,8 +4969,8 @@ export class Walker<T, N> implements Iterable<[T, N]> {
      * console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
      * ```
      *
-     * @since 4.0.0
      * @category iterators
+     * @since 4.0.0
      */
     visit: <U>(f: (index: T, data: N) => U) => Iterable<U>
   ) {
@@ -4731,8 +4983,8 @@ export class Walker<T, N> implements Iterable<[T, N]> {
  * Type alias for node iteration using Walker.
  * NodeWalker is represented as Walker<NodeIndex, N>.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type NodeWalker<N> = Walker<NodeIndex, N>
 
@@ -4740,15 +4992,16 @@ export type NodeWalker<N> = Walker<NodeIndex, N>
  * Type alias for edge iteration using Walker.
  * EdgeWalker is represented as Walker<EdgeIndex, Edge<E>>.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type EdgeWalker<E> = Walker<EdgeIndex, Edge<E>>
 
 /**
  * Returns an iterator over the indices in the walker.
  *
- * @example
+ * **Example** (Iterating walker indices)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4763,15 +5016,16 @@ export type EdgeWalker<E> = Walker<EdgeIndex, Edge<E>>
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const indices = <T, N>(walker: Walker<T, N>): Iterable<T> => walker.visit((index, _) => index)
 
 /**
  * Returns an iterator over the values (data) in the walker.
  *
- * @example
+ * **Example** (Iterating walker values)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4786,15 +5040,16 @@ export const indices = <T, N>(walker: Walker<T, N>): Iterable<T> => walker.visit
  * console.log(values) // ["A", "B"]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const values = <T, N>(walker: Walker<T, N>): Iterable<N> => walker.visit((_, data) => data)
 
 /**
  * Returns an iterator over [index, data] entries in the walker.
  *
- * @example
+ * **Example** (Iterating walker entries)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4809,17 +5064,23 @@ export const values = <T, N>(walker: Walker<T, N>): Iterable<N> => walker.visit(
  * console.log(entries) // [[0, "A"], [1, "B"]]
  * ```
  *
- * @since 4.0.0
  * @category utilities
+ * @since 4.0.0
  */
 export const entries = <T, N>(walker: Walker<T, N>): Iterable<[T, N]> =>
   walker.visit((index, data) => [index, data] as [T, N])
 
 /**
- * Configuration options for search iterators.
+ * Configuration for DFS, BFS, and postorder graph traversals.
+ *
+ * **Details**
+ *
+ * `start` supplies the node indices where traversal begins. If it is omitted,
+ * the iterator is empty. `direction` chooses whether traversal follows
+ * outgoing or incoming edges.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SearchConfig {
   readonly start?: Array<NodeIndex>
@@ -4827,12 +5088,17 @@ export interface SearchConfig {
 }
 
 /**
- * Creates a new DFS iterator with optional configuration.
+ * Creates a lazy depth-first traversal iterator from the configured start
+ * nodes.
  *
- * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the depth-first search.
+ * **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`
+ * if any configured start node does not exist.
+ *
+ * **Example** (Traversing depth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -4855,17 +5121,22 @@ export interface SearchConfig {
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const dfs: {
   /**
-   * Creates a new DFS iterator with optional configuration.
+   * Creates a lazy depth-first traversal iterator from the configured start
+   * nodes.
+   *
+   * **Details**
    *
-   * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
-   * It provides lazy evaluation of the depth-first search.
+   * If no start nodes are supplied, the iterator is empty. The `direction` option
+   * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+   * if any configured start node does not exist.
+   *
+   * **Example** (Traversing depth-first)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4888,17 +5159,22 @@ export const dfs: {
    * // Can be used programmatically
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>
   /**
-   * Creates a new DFS iterator with optional configuration.
+   * Creates a lazy depth-first traversal iterator from the configured start
+   * nodes.
+   *
+   * **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`
+   * if any configured start node does not exist.
    *
-   * The iterator maintains a stack of nodes to visit and tracks discovered nodes.
-   * It provides lazy evaluation of the depth-first search.
+   * **Example** (Traversing depth-first)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -4921,8 +5197,8 @@ export const dfs: {
    * // Can be used programmatically
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>
 } = dual((args) => isGraph(args[0]), <N, E, T extends Kind = "directed">(
@@ -4979,12 +5255,17 @@ export const dfs: {
 })
 
 /**
- * Creates a new BFS iterator with optional configuration.
+ * Creates a lazy breadth-first traversal iterator from the configured start
+ * nodes.
+ *
+ * **Details**
  *
- * The iterator maintains a queue of nodes to visit and tracks discovered nodes.
- * It provides lazy evaluation of the breadth-first search.
+ * If no start nodes are supplied, the iterator is empty. The `direction` option
+ * chooses whether to follow outgoing or incoming edges. Throws a `GraphError`
+ * if any configured start node does not exist.
+ *
+ * **Example** (Traversing breadth-first)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5007,17 +5288,22 @@ export const dfs: {
  * // Can be used programmatically
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const bfs: {
   /**
-   * Creates a new BFS iterator with optional configuration.
+   * Creates a lazy breadth-first traversal iterator from the configured start
+   * nodes.
    *
-   * The iterator maintains a queue of nodes to visit and tracks discovered nodes.
-   * It provides lazy evaluation of the breadth-first search.
+   * **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`
+   * if any configured start node does not exist.
+   *
+   * **Example** (Traversing breadth-first)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5040,17 +5326,22 @@ export const bfs: {
    * // Can be used programmatically
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>
   /**
-   * Creates a new BFS iterator with optional configuration.
+   * Creates a lazy breadth-first traversal iterator from the configured start
+   * nodes.
    *
-   * The iterator maintains a queue of nodes to visit and tracks discovered nodes.
-   * It provides lazy evaluation of the breadth-first search.
+   * **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`
+   * if any configured start node does not exist.
+   *
+   * **Example** (Traversing breadth-first)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5073,8 +5364,8 @@ export const bfs: {
    * // Can be used programmatically
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>
 } = dual((args) => isGraph(args[0]), <N, E, T extends Kind = "directed">(
@@ -5127,10 +5418,16 @@ export const bfs: {
 })
 
 /**
- * Configuration options for topological sort iterator.
+ * Configuration for the topological sort iterator.
+ *
+ * **Details**
+ *
+ * `initials` optionally supplies the node indices used as initial queue
+ * entries. When omitted, topological sorting starts from all nodes with zero
+ * in-degree.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TopoConfig {
   readonly initials?: Array<NodeIndex>
@@ -5142,7 +5439,8 @@ export interface TopoConfig {
  * The iterator uses Kahn's algorithm to lazily produce nodes in topological order.
  * Throws an error if the graph contains cycles.
  *
- * @example
+ * **Example** (Sorting topologically)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5163,7 +5461,7 @@ export interface TopoConfig {
  * // With initial nodes
  * const topo2 = Graph.topo(graph, { initials: [0] })
  *
- * // Throws error for cyclic graph
+ * // Check before sorting a cyclic graph
  * const cyclicGraph = Graph.directed<string, number>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
  *   const b = Graph.addNode(mutable, "B")
@@ -5171,15 +5469,13 @@ export interface TopoConfig {
  *   Graph.addEdge(mutable, b, a, 2) // Creates cycle
  * })
  *
- * try {
- *   Graph.topo(cyclicGraph) // Throws: "Cannot perform topological sort on cyclic graph"
- * } catch (error) {
- *   console.log((error as Error).message)
+ * if (!Graph.isAcyclic(cyclicGraph)) {
+ *   console.log("cyclic graph") // cyclic graph
  * }
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const topo: {
   /**
@@ -5188,7 +5484,8 @@ export const topo: {
    * The iterator uses Kahn's algorithm to lazily produce nodes in topological order.
    * Throws an error if the graph contains cycles.
    *
-   * @example
+   * **Example** (Sorting topologically)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5209,7 +5506,7 @@ export const topo: {
    * // With initial nodes
    * const topo2 = Graph.topo(graph, { initials: [0] })
    *
-   * // Throws error for cyclic graph
+   * // Check before sorting a cyclic graph
    * const cyclicGraph = Graph.directed<string, number>((mutable) => {
    *   const a = Graph.addNode(mutable, "A")
    *   const b = Graph.addNode(mutable, "B")
@@ -5217,15 +5514,13 @@ export const topo: {
    *   Graph.addEdge(mutable, b, a, 2) // Creates cycle
    * })
    *
-   * try {
-   *   Graph.topo(cyclicGraph) // Throws: "Cannot perform topological sort on cyclic graph"
-   * } catch (error) {
-   *   console.log((error as Error).message)
+   * if (!Graph.isAcyclic(cyclicGraph)) {
+   *   console.log("cyclic graph") // cyclic graph
    * }
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   (config?: TopoConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>
   /**
@@ -5234,7 +5529,8 @@ export const topo: {
    * The iterator uses Kahn's algorithm to lazily produce nodes in topological order.
    * Throws an error if the graph contains cycles.
    *
-   * @example
+   * **Example** (Sorting topologically)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5255,7 +5551,7 @@ export const topo: {
    * // With initial nodes
    * const topo2 = Graph.topo(graph, { initials: [0] })
    *
-   * // Throws error for cyclic graph
+   * // Check before sorting a cyclic graph
    * const cyclicGraph = Graph.directed<string, number>((mutable) => {
    *   const a = Graph.addNode(mutable, "A")
    *   const b = Graph.addNode(mutable, "B")
@@ -5263,15 +5559,13 @@ export const topo: {
    *   Graph.addEdge(mutable, b, a, 2) // Creates cycle
    * })
    *
-   * try {
-   *   Graph.topo(cyclicGraph) // Throws: "Cannot perform topological sort on cyclic graph"
-   * } catch (error) {
-   *   console.log((error as Error).message)
+   * if (!Graph.isAcyclic(cyclicGraph)) {
+   *   console.log("cyclic graph") // cyclic graph
    * }
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: TopoConfig): NodeWalker<N>
 } = dual((args) => isGraph(args[0]), <N, E, T extends Kind = "directed">(
@@ -5358,13 +5652,17 @@ export const topo: {
 })
 
 /**
- * Creates a new DFS postorder iterator with optional configuration.
+ * Creates a lazy depth-first postorder traversal iterator from the configured
+ * start nodes.
+ *
+ * **Details**
+ *
+ * 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.
  *
- * The iterator maintains a stack with visit state tracking and emits nodes
- * in postorder (after all descendants have been processed). Essential for
- * dependency resolution and tree destruction algorithms.
+ * **Example** (Traversing in postorder)
  *
- * @example
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5383,18 +5681,22 @@ export const topo: {
  * }
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const dfsPostOrder: {
   /**
-   * Creates a new DFS postorder iterator with optional configuration.
+   * Creates a lazy depth-first postorder traversal iterator from the configured
+   * start nodes.
+   *
+   * **Details**
    *
-   * The iterator maintains a stack with visit state tracking and emits nodes
-   * in postorder (after all descendants have been processed). Essential for
-   * dependency resolution and tree destruction algorithms.
+   * 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.
+   *
+   * **Example** (Traversing in postorder)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5413,18 +5715,22 @@ export const dfsPostOrder: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   (config?: SearchConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>
   /**
-   * Creates a new DFS postorder iterator with optional configuration.
+   * Creates a lazy depth-first postorder traversal iterator from the configured
+   * start nodes.
+   *
+   * **Details**
    *
-   * The iterator maintains a stack with visit state tracking and emits nodes
-   * in postorder (after all descendants have been processed). Essential for
-   * dependency resolution and tree destruction algorithms.
+   * 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.
+   *
+   * **Example** (Traversing in postorder)
    *
-   * @example
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5443,8 +5749,8 @@ export const dfsPostOrder: {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: SearchConfig): NodeWalker<N>
 } = dual((args) => isGraph(args[0]), <N, E, T extends Kind = "directed">(
@@ -5520,7 +5826,8 @@ export const dfsPostOrder: {
  * The iterator produces node indices in the order they were added to the graph.
  * This provides access to all nodes regardless of connectivity.
  *
- * @example
+ * **Example** (Iterating all nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5535,8 +5842,8 @@ export const dfsPostOrder: {
  * console.log(indices) // [0, 1, 2]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const nodes = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
@@ -5565,7 +5872,8 @@ export const nodes = <N, E, T extends Kind = "directed">(
  * The iterator produces edge indices in the order they were added to the graph.
  * This provides access to all edges regardless of connectivity.
  *
- * @example
+ * **Example** (Iterating all edges)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5581,8 +5889,8 @@ export const nodes = <N, E, T extends Kind = "directed">(
  * console.log(indices) // [0, 1]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const edges = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
@@ -5606,10 +5914,16 @@ export const edges = <N, E, T extends Kind = "directed">(
   }))
 
 /**
- * Configuration for externals iterator.
+ * Configuration for selecting external nodes.
+ *
+ * **Details**
+ *
+ * `direction` chooses which missing edge direction makes a node external:
+ * `"outgoing"` selects nodes with no outgoing edges, and `"incoming"` selects
+ * nodes with no incoming edges.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ExternalsConfig {
   readonly direction?: Direction
@@ -5622,7 +5936,8 @@ export interface ExternalsConfig {
  * no incoming edges (direction="incoming"). These are useful for finding
  * sources, sinks, or isolated nodes.
  *
- * @example
+ * **Example** (Iterating external nodes)
+ *
  * ```ts
  * import { Graph } from "effect"
  *
@@ -5649,8 +5964,8 @@ export interface ExternalsConfig {
  * console.log(sources) // [0, 3]
  * ```
  *
- * @since 4.0.0
  * @category iterators
+ * @since 4.0.0
  */
 export const externals: {
   /**
@@ -5660,7 +5975,8 @@ export const externals: {
    * no incoming edges (direction="incoming"). These are useful for finding
    * sources, sinks, or isolated nodes.
    *
-   * @example
+   * **Example** (Iterating external nodes)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5687,8 +6003,8 @@ export const externals: {
    * console.log(sources) // [0, 3]
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   (config?: ExternalsConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>
   /**
@@ -5698,7 +6014,8 @@ export const externals: {
    * no incoming edges (direction="incoming"). These are useful for finding
    * sources, sinks, or isolated nodes.
    *
-   * @example
+   * **Example** (Iterating external nodes)
+   *
    * ```ts
    * import { Graph } from "effect"
    *
@@ -5725,8 +6042,8 @@ export const externals: {
    * console.log(sources) // [0, 3]
    * ```
    *
-   * @since 4.0.0
    * @category iterators
+   * @since 4.0.0
    */
   <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: ExternalsConfig): NodeWalker<N>
 } = dual((args) => isGraph(args[0]), <N, E, T extends Kind = "directed">(