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

package/dist/Graph.d.ts

@@ -13,6 +13,7 @@ import * as Equal from "./Equal.ts";
 import type { Inspectable } from "./Inspectable.ts";
 import * as Option from "./Option.ts";
 import type { Pipeable } from "./Pipeable.ts";
+import type { Covariant, Invariant } from "./Types.ts";
 declare const TypeId = "~effect/collections/Graph";
 /**
  * Node index for node identification using plain numbers.
@@ -97,25 +98,19 @@ export declare class Edge<E> extends Data.Class<{
  */
 export type Kind = "directed" | "undirected";
 /**
- * Common structural interface shared by immutable and mutable graphs.
+ * Common public protocol for graph values.
  *
  * **Details**
  *
- * Contains the node and edge maps, adjacency indexes, allocation counters, and
- * shared protocols used by both `Graph` and `MutableGraph`.
+ * Contains only the runtime marker and shared protocols. Graph storage is kept
+ * internal; use module functions such as `nodes`, `edges`, `getNode`, and
+ * `getEdge` to inspect graph contents.
  *
  * @category models
  * @since 3.18.0
  */
 export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>, Equal.Equal, Pipeable, Inspectable {
-    readonly [TypeId]: typeof TypeId;
-    readonly nodes: Map<NodeIndex, N>;
-    readonly edges: Map<EdgeIndex, Edge<E>>;
-    readonly adjacency: Map<NodeIndex, Array<EdgeIndex>>;
-    readonly reverseAdjacency: Map<NodeIndex, Array<EdgeIndex>>;
-    nextNodeIndex: NodeIndex;
-    nextEdgeIndex: EdgeIndex;
-    acyclic: Option.Option<boolean>;
+    readonly [TypeId]: Graph.Variance<N, E>;
 }
 /**
  * Immutable graph interface.
@@ -136,6 +131,24 @@ export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<
     readonly type: T;
     readonly mutable: false;
 }
+/**
+ * Companion namespace containing type-level metadata for immutable graphs.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export declare namespace Graph {
+    /**
+     * Type-level variance marker for immutable graphs.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface Variance<out N, out E> {
+        readonly _N: Covariant<N>;
+        readonly _E: Covariant<E>;
+    }
+}
 /**
  * Mutable graph interface.
  *
@@ -152,10 +165,29 @@ export interface Graph<out N, out E, T extends Kind = "directed"> extends Proto<
  * @category models
  * @since 3.18.0
  */
-export interface MutableGraph<out N, out E, T extends Kind = "directed"> extends Proto<N, E> {
+export interface MutableGraph<in out N, in out E, T extends Kind = "directed"> extends Iterable<readonly [NodeIndex, N]>, Equal.Equal, Pipeable, Inspectable {
+    readonly [TypeId]: MutableGraph.Variance<N, E>;
     readonly type: T;
     readonly mutable: true;
 }
+/**
+ * Companion namespace containing type-level metadata for scoped mutable graphs.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export declare namespace MutableGraph {
+    /**
+     * Type-level variance marker for scoped mutable graphs.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    interface Variance<in out N, in out E> {
+        readonly _N: Invariant<N>;
+        readonly _E: Invariant<E>;
+    }
+}
 /**
  * Immutable graph type for source-to-target relationships.
  *
@@ -251,170 +283,1063 @@ export declare class GraphError extends GraphError_base<{
 }> {
 }
 /**
- * Returns `true` if a value has the graph runtime type identifier, narrowing
- * it to a `Graph`.
- *
- * **When to use**
- *
- * Use to narrow an unknown value before treating it as a graph value.
+ * Returns `true` if a value has the graph runtime type identifier, narrowing
+ * it to an immutable or mutable graph.
+ *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a graph value.
+ *
+ * **Gotchas**
+ *
+ * This guard checks the shared graph runtime type identifier and does not
+ * distinguish immutable graphs from mutable graphs or directed graphs from
+ * undirected graphs.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isGraph: <N = unknown, E = unknown, T extends Kind = Kind, U = never>(u: U | Graph<N, E, T> | MutableGraph<N, E, T>) => u is Graph<N, E, T> | MutableGraph<N, E, T>;
+/**
+ * Creates a graph constructor for the specified graph kind.
+ *
+ * **When to use**
+ *
+ * Use when the graph kind is selected dynamically. Prefer `directed` or
+ * `undirected` when the kind is known statically.
+ *
+ * **Example** (Constructing by kind)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const makeGraph = Graph.make("directed")
+ * const graph = makeGraph<string, number>((mutable) => {
+ *   Graph.addNode(mutable, "A")
+ * })
+ *
+ * console.log(graph.type) // "directed"
+ * ```
+ *
+ * @see {@link directed} for constructing a directed graph directly
+ * @see {@link undirected} for constructing an undirected graph directly
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const make: <T extends Kind>(type: T) => <N, E>(mutate?: (mutable: MutableGraph<N, E, T>) => undefined) => Graph<N, E, T>;
+/**
+ * Creates a directed graph, optionally with initial mutations.
+ *
+ * **Example** (Creating a directed graph)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * // Directed graph with initial nodes and edges
+ * const graph = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A->B")
+ *   Graph.addEdge(mutable, b, c, "B->C")
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 3.18.0
+ */
+export declare const directed: <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) => undefined) => DirectedGraph<N, E>;
+/**
+ * Creates an undirected graph, optionally with initial mutations.
+ *
+ * **Example** (Creating an undirected graph)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * // Undirected graph with initial nodes and edges
+ * const graph = Graph.undirected<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 3.18.0
+ */
+export declare const undirected: <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>) => undefined) => UndirectedGraph<N, E>;
+/**
+ * Creates a mutable scope for safe graph mutations by copying the data structure.
+ *
+ * **Example** (Beginning a mutation scope)
+ *
+ * ```ts
+ * 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
+ * ```
+ *
+ * @category mutations
+ * @since 3.18.0
+ */
+export declare const beginMutation: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>) => MutableGraph<N, E, T>;
+/**
+ * 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
+ * import { Graph } from "effect"
+ *
+ * const graph = Graph.directed<string, number>()
+ * const mutable = Graph.beginMutation(graph)
+ * // ... perform mutations on mutable ...
+ * const newGraph = Graph.endMutation(mutable)
+ * ```
+ *
+ * @category mutations
+ * @since 3.18.0
+ */
+export declare const endMutation: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>) => Graph<N, E, T>;
+/**
+ * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+ *
+ * **Example** (Applying scoped mutations)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const graph = Graph.directed<string, number>()
+ * const newGraph = Graph.mutate(graph, (mutable) => {
+ *   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
+ * ```
+ *
+ * @category mutations
+ * @since 3.18.0
+ */
+export declare const mutate: {
+    /**
+     * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+     *
+     * **Example** (Applying scoped mutations)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const graph = Graph.directed<string, number>()
+     * const newGraph = Graph.mutate(graph, (mutable) => {
+     *   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
+     * ```
+     *
+     * @category mutations
+     * @since 3.18.0
+     */
+    <N, E, T extends Kind = "directed">(f: (mutable: MutableGraph<N, E, T>) => undefined): (graph: Graph<N, E, T>) => Graph<N, E, T>;
+    /**
+     * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+     *
+     * **Example** (Applying scoped mutations)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const graph = Graph.directed<string, number>()
+     * const newGraph = Graph.mutate(graph, (mutable) => {
+     *   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
+     * ```
+     *
+     * @category mutations
+     * @since 3.18.0
+     */
+    <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>, f: (mutable: MutableGraph<N, E, T>) => undefined): Graph<N, E, T>;
+};
+/**
+ * Configures node and edge identity for graph set operations.
+ *
+ * **Details**
+ *
+ * Both functions default to using the complete node or edge data. Edge identity
+ * also includes the identities of its endpoint nodes and the graph kind.
+ *
+ * **Gotchas**
+ *
+ * Edge identity defines set membership, not edge multiplicity. Parallel edges
+ * with the same endpoint identities and projected edge identity are treated as
+ * the same member by graph set operations.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface IdentityOptions<N, E, NI = N, EI = E> {
+    readonly nodeIdentity?: (node: N) => NI;
+    readonly edgeIdentity?: (edge: E) => EI;
+}
+/**
+ * Composes two graphs, merging nodes by identity.
+ *
+ * **Details**
+ *
+ * Nodes and edges present in both graphs use data from `that`. The result has
+ * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+ * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+ * edge data. Edge identity also includes the endpoint identities.
+ *
+ * `G1 ∪ G2 = {V1 ∪ V2, E1 ∪ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * Parallel edges with equal identities are also coalesced, with the last edge
+ * supplying the data.
+ *
+ * **Example** (Combining graphs)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<{ id: string }, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, { id: "A" })
+ *   const b = Graph.addNode(mutable, { id: "B" })
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ * })
+ *
+ * const right = Graph.directed<{ id: string }, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, { id: "B" })
+ *   const c = Graph.addNode(mutable, { id: "C" })
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const result = Graph.compose(left, right, {
+ *   nodeIdentity: (node) => node.id
+ * })
+ *
+ * console.log(Graph.nodeCount(result)) // 3
+ * console.log(Graph.edgeCount(result)) // 2
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export declare const compose: {
+    /**
+     * Composes two graphs, merging nodes by identity.
+     *
+     * **Details**
+     *
+     * Nodes and edges present in both graphs use data from `that`. The result has
+     * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+     * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+     * edge data. Edge identity also includes the endpoint identities.
+     *
+     * `G1 ∪ G2 = {V1 ∪ V2, E1 ∪ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * Parallel edges with equal identities are also coalesced, with the last edge
+     * supplying the data.
+     *
+     * **Example** (Combining graphs)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<{ id: string }, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, { id: "A" })
+     *   const b = Graph.addNode(mutable, { id: "B" })
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     * })
+     *
+     * const right = Graph.directed<{ id: string }, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, { id: "B" })
+     *   const c = Graph.addNode(mutable, { id: "C" })
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const result = Graph.compose(left, right, {
+     *   nodeIdentity: (node) => node.id
+     * })
+     *
+     * console.log(Graph.nodeCount(result)) // 3
+     * console.log(Graph.edgeCount(result)) // 2
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(that: Graph<N, E, T>, options?: IdentityOptions<N, E, NI, EI>): (self: Graph<N, E, NoInfer<T>>) => Graph<N, E, T>;
+    /**
+     * Composes two graphs, merging nodes by identity.
+     *
+     * **Details**
+     *
+     * Nodes and edges present in both graphs use data from `that`. The result has
+     * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+     * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+     * edge data. Edge identity also includes the endpoint identities.
+     *
+     * `G1 ∪ G2 = {V1 ∪ V2, E1 ∪ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * Parallel edges with equal identities are also coalesced, with the last edge
+     * supplying the data.
+     *
+     * **Example** (Combining graphs)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<{ id: string }, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, { id: "A" })
+     *   const b = Graph.addNode(mutable, { id: "B" })
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     * })
+     *
+     * const right = Graph.directed<{ id: string }, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, { id: "B" })
+     *   const c = Graph.addNode(mutable, { id: "C" })
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const result = Graph.compose(left, right, {
+     *   nodeIdentity: (node) => node.id
+     * })
+     *
+     * console.log(Graph.nodeCount(result)) // 3
+     * console.log(Graph.edgeCount(result)) // 2
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(self: Graph<N, E, T>, that: Graph<N, E, NoInfer<T>>, options?: IdentityOptions<N, E, NI, EI>): Graph<N, E, T>;
+};
+/**
+ * Returns the intersection of two graphs, matching nodes by identity.
+ *
+ * **Details**
+ *
+ * Node data comes from `self`, and edge data comes from `that`. The result has
+ * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+ * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+ * edge data. Edge identity also includes the endpoint identities.
+ *
+ * `G1 ∩ G2 = {V1 ∩ V2, E1 ∩ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * The result contains at most one edge for each shared edge identity.
+ *
+ * **Example** (Finding shared structure)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, a, b, "shared")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   Graph.addEdge(mutable, a, b, "shared")
+ * })
+ *
+ * const result = Graph.intersection(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 2
+ * console.log(Graph.edgeCount(result)) // 1
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export declare const intersection: {
+    /**
+     * Returns the intersection of two graphs, matching nodes by identity.
+     *
+     * **Details**
+     *
+     * Node data comes from `self`, and edge data comes from `that`. The result has
+     * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+     * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+     * edge data. Edge identity also includes the endpoint identities.
+     *
+     * `G1 ∩ G2 = {V1 ∩ V2, E1 ∩ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * The result contains at most one edge for each shared edge identity.
+     *
+     * **Example** (Finding shared structure)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "shared")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "shared")
+     * })
+     *
+     * const result = Graph.intersection(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 2
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(that: Graph<N, E, T>, options?: IdentityOptions<N, E, NI, EI>): (self: Graph<N, E, NoInfer<T>>) => Graph<N, E, T>;
+    /**
+     * Returns the intersection of two graphs, matching nodes by identity.
+     *
+     * **Details**
+     *
+     * Node data comes from `self`, and edge data comes from `that`. The result has
+     * the same graph kind as `self`. Throws a `GraphError` when the graph kinds do
+     * not match. `nodeIdentity` and `edgeIdentity` default to the complete node and
+     * edge data. Edge identity also includes the endpoint identities.
+     *
+     * `G1 ∩ G2 = {V1 ∩ V2, E1 ∩ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * The result contains at most one edge for each shared edge identity.
+     *
+     * **Example** (Finding shared structure)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "shared")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "shared")
+     * })
+     *
+     * const result = Graph.intersection(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 2
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(self: Graph<N, E, T>, that: Graph<N, E, NoInfer<T>>, options?: IdentityOptions<N, E, NI, EI>): Graph<N, E, T>;
+};
+/**
+ * Returns `self` without edges also present in `that`.
+ *
+ * **Details**
+ *
+ * All nodes from `self` are preserved. Edges are matched by endpoint and edge
+ * identities. The result has the same graph kind as `self`. Throws a
+ * `GraphError` when the graph kinds do not match. `nodeIdentity` and
+ * `edgeIdentity` default to the complete node and edge data.
+ *
+ * `G1 \ G2 = {V1, E1 \ E2}`
+ *
+ * **Gotchas**
+ *
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * If `that` contains an edge identity, every parallel edge with that identity
+ * is removed from `self`.
+ *
+ * **Example** (Removing shared edges)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const result = Graph.difference(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 3
+ * console.log(Graph.edgeCount(result)) // 1
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export declare const difference: {
+    /**
+     * Returns `self` without edges also present in `that`.
+     *
+     * **Details**
+     *
+     * All nodes from `self` are preserved. Edges are matched by endpoint and edge
+     * identities. The result has the same graph kind as `self`. Throws a
+     * `GraphError` when the graph kinds do not match. `nodeIdentity` and
+     * `edgeIdentity` default to the complete node and edge data.
+     *
+     * `G1 \ G2 = {V1, E1 \ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * If `that` contains an edge identity, every parallel edge with that identity
+     * is removed from `self`.
+     *
+     * **Example** (Removing shared edges)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const result = Graph.difference(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 3
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(that: Graph<N, E, T>, options?: IdentityOptions<N, E, NI, EI>): (self: Graph<N, E, NoInfer<T>>) => Graph<N, E, T>;
+    /**
+     * Returns `self` without edges also present in `that`.
+     *
+     * **Details**
+     *
+     * All nodes from `self` are preserved. Edges are matched by endpoint and edge
+     * identities. The result has the same graph kind as `self`. Throws a
+     * `GraphError` when the graph kinds do not match. `nodeIdentity` and
+     * `edgeIdentity` default to the complete node and edge data.
+     *
+     * `G1 \ G2 = {V1, E1 \ E2}`
+     *
+     * **Gotchas**
+     *
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * If `that` contains an edge identity, every parallel edge with that identity
+     * is removed from `self`.
+     *
+     * **Example** (Removing shared edges)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const result = Graph.difference(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 3
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(self: Graph<N, E, T>, that: Graph<N, E, NoInfer<T>>, options?: IdentityOptions<N, E, NI, EI>): Graph<N, E, T>;
+};
+/**
+ * Returns edges present in exactly one of two graphs.
+ *
+ * **Details**
+ *
+ * Keeps nodes from both graphs. Overlapping nodes use data from `that`. The
+ * result has the same graph kind as `self`. Throws a `GraphError` when the
+ * graph kinds do not match. `nodeIdentity` and `edgeIdentity` default to the
+ * complete node and edge data. Edge identity also includes the endpoint
+ * identities.
+ *
+ * `G1 Δ G2 = {V1 ∪ V2, (E1 ∪ E2) \ (E1 ∩ E2)}`
+ *
+ * **Gotchas**
+ *
+ * Edges with different projected identities are distinct.
+ * Nodes with equal identities in one input graph are coalesced. The last node
+ * supplies the data, and redirected edges can collapse or become self-loops.
+ * Parallel edges with equal identities are coalesced before the graphs are
+ * compared.
+ *
+ * **Example** (Finding differing edges)
+ *
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const left = Graph.directed<string, string>((mutable) => {
+ *   const a = Graph.addNode(mutable, "A")
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ * })
+ *
+ * const right = Graph.directed<string, string>((mutable) => {
+ *   const b = Graph.addNode(mutable, "B")
+ *   const c = Graph.addNode(mutable, "C")
+ *   const d = Graph.addNode(mutable, "D")
+ *   Graph.addEdge(mutable, b, c, "B-C")
+ *   Graph.addEdge(mutable, c, d, "C-D")
+ * })
+ *
+ * const result = Graph.symmetricDifference(left, right)
+ *
+ * console.log(Graph.nodeCount(result)) // 4
+ * console.log(Graph.edgeCount(result)) // 2
+ * ```
+ *
+ * @category set operations
+ * @since 4.0.0
+ */
+export declare const symmetricDifference: {
+    /**
+     * Returns edges present in exactly one of two graphs.
+     *
+     * **Details**
+     *
+     * Keeps nodes from both graphs. Overlapping nodes use data from `that`. The
+     * result has the same graph kind as `self`. Throws a `GraphError` when the
+     * graph kinds do not match. `nodeIdentity` and `edgeIdentity` default to the
+     * complete node and edge data. Edge identity also includes the endpoint
+     * identities.
+     *
+     * `G1 Δ G2 = {V1 ∪ V2, (E1 ∪ E2) \ (E1 ∩ E2)}`
+     *
+     * **Gotchas**
+     *
+     * Edges with different projected identities are distinct.
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * Parallel edges with equal identities are coalesced before the graphs are
+     * compared.
+     *
+     * **Example** (Finding differing edges)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   const d = Graph.addNode(mutable, "D")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     *   Graph.addEdge(mutable, c, d, "C-D")
+     * })
+     *
+     * const result = Graph.symmetricDifference(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 4
+     * console.log(Graph.edgeCount(result)) // 2
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(that: Graph<N, E, T>, options?: IdentityOptions<N, E, NI, EI>): (self: Graph<N, E, NoInfer<T>>) => Graph<N, E, T>;
+    /**
+     * Returns edges present in exactly one of two graphs.
+     *
+     * **Details**
+     *
+     * Keeps nodes from both graphs. Overlapping nodes use data from `that`. The
+     * result has the same graph kind as `self`. Throws a `GraphError` when the
+     * graph kinds do not match. `nodeIdentity` and `edgeIdentity` default to the
+     * complete node and edge data. Edge identity also includes the endpoint
+     * identities.
+     *
+     * `G1 Δ G2 = {V1 ∪ V2, (E1 ∪ E2) \ (E1 ∩ E2)}`
+     *
+     * **Gotchas**
+     *
+     * Edges with different projected identities are distinct.
+     * Nodes with equal identities in one input graph are coalesced. The last node
+     * supplies the data, and redirected edges can collapse or become self-loops.
+     * Parallel edges with equal identities are coalesced before the graphs are
+     * compared.
+     *
+     * **Example** (Finding differing edges)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const left = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     * })
+     *
+     * const right = Graph.directed<string, string>((mutable) => {
+     *   const b = Graph.addNode(mutable, "B")
+     *   const c = Graph.addNode(mutable, "C")
+     *   const d = Graph.addNode(mutable, "D")
+     *   Graph.addEdge(mutable, b, c, "B-C")
+     *   Graph.addEdge(mutable, c, d, "C-D")
+     * })
+     *
+     * const result = Graph.symmetricDifference(left, right)
+     *
+     * console.log(Graph.nodeCount(result)) // 4
+     * console.log(Graph.edgeCount(result)) // 2
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed", NI = N, EI = E>(self: Graph<N, E, T>, that: Graph<N, E, NoInfer<T>>, options?: IdentityOptions<N, E, NI, EI>): Graph<N, E, T>;
+};
+/**
+ * Returns the complement over the existing node set.
  *
- * **Gotchas**
+ * **Details**
  *
- * This guard checks the shared graph runtime type identifier and does not
- * distinguish immutable graphs from mutable graphs.
+ * 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`.
  *
- * @category guards
- * @since 4.0.0
- */
-export declare const isGraph: (u: unknown) => u is Graph<unknown, unknown>;
-/**
- * Creates a directed graph, optionally with initial mutations.
+ * `G' = {V, (V x V) \ E}`
  *
- * **Example** (Creating a directed graph)
+ * **Example** (Finding missing relationships)
  *
  * ```ts
  * import { Graph } from "effect"
  *
- * // Directed graph with initial nodes and edges
  * const graph = Graph.directed<string, string>((mutable) => {
  *   const a = Graph.addNode(mutable, "A")
  *   const b = Graph.addNode(mutable, "B")
- *   const c = Graph.addNode(mutable, "C")
- *   Graph.addEdge(mutable, a, b, "A->B")
- *   Graph.addEdge(mutable, b, c, "B->C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
  * })
- * ```
- *
- * @category constructors
- * @since 3.18.0
- */
-export declare const directed: <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) => void) => DirectedGraph<N, E>;
-/**
- * Creates an undirected graph, optionally with initial mutations.
- *
- * **Example** (Creating an undirected graph)
  *
- * ```ts
- * import { Graph } from "effect"
+ * const result = Graph.complement(graph, (source, target) => `${source}-${target}`)
  *
- * // Undirected graph with initial nodes and edges
- * const graph = Graph.undirected<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")
- * })
+ * console.log(Graph.edgeCount(result)) // 1
  * ```
  *
- * @category constructors
- * @since 3.18.0
+ * @category set operations
+ * @since 4.0.0
  */
-export declare const undirected: <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>) => void) => UndirectedGraph<N, E>;
+export declare const complement: {
+    /**
+     * Returns the complement over the existing node set.
+     *
+     * **Details**
+     *
+     * Adds every missing edge between distinct nodes. The `createEdge` function
+     * receives the source and target node data for each added edge. The result has
+     * the same graph kind as `self`.
+     *
+     * `G' = {V, (V x V) \ E}`
+     *
+     * **Example** (Finding missing relationships)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const graph = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     * })
+     *
+     * const result = Graph.complement(graph, (source, target) => `${source}-${target}`)
+     *
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E>(createEdge: (source: N, target: N) => E): <T extends Kind = "directed">(self: Graph<N, E, T>) => Graph<N, E, T>;
+    /**
+     * Returns the complement over the existing node set.
+     *
+     * **Details**
+     *
+     * Adds every missing edge between distinct nodes. The `createEdge` function
+     * receives the source and target node data for each added edge. The result has
+     * the same graph kind as `self`.
+     *
+     * `G' = {V, (V x V) \ E}`
+     *
+     * **Example** (Finding missing relationships)
+     *
+     * ```ts
+     * import { Graph } from "effect"
+     *
+     * const graph = Graph.directed<string, string>((mutable) => {
+     *   const a = Graph.addNode(mutable, "A")
+     *   const b = Graph.addNode(mutable, "B")
+     *   Graph.addEdge(mutable, a, b, "A-B")
+     * })
+     *
+     * const result = Graph.complement(graph, (source, target) => `${source}-${target}`)
+     *
+     * console.log(Graph.edgeCount(result)) // 1
+     * ```
+     *
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed">(self: Graph<N, E, T>, createEdge: (source: N, target: N) => E): Graph<N, E, T>;
+};
 /**
- * Creates a mutable scope for safe graph mutations by copying the data structure.
- *
- * **Example** (Beginning a mutation scope)
+ * Configuration for selecting a graph neighborhood.
  *
- * ```ts
- * import { Graph } from "effect"
+ * **Details**
  *
- * const graph = Graph.directed<string, number>()
- * const mutable = Graph.beginMutation(graph)
- * // Now mutable can be safely modified without affecting original graph
- * ```
+ * `radius` limits the edge distance from the center node and defaults to `1`.
+ * `direction` controls how directed edges are traversed and defaults to
+ * `"outgoing"`.
  *
- * @category mutations
- * @since 3.18.0
+ * @category models
+ * @since 4.0.0
  */
-export declare const beginMutation: <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>) => MutableGraph<N, E, T>;
+export interface NeighborhoodConfig {
+    readonly radius?: number;
+    readonly direction?: TraversalDirection;
+}
 /**
- * Converts a mutable graph back to an immutable graph, ending the mutation scope.
- *
- * **Example** (Ending a mutation scope)
- *
- * ```ts
- * import { Graph } from "effect"
+ * Returns the induced subgraph containing nodes within a radius of a node.
  *
- * const graph = Graph.directed<string, number>()
- * const mutable = Graph.beginMutation(graph)
- * // ... perform mutations on mutable ...
- * const newGraph = Graph.endMutation(mutable)
- * ```
+ * **Details**
  *
- * @category mutations
- * @since 3.18.0
- */
-export declare const endMutation: <N, E, T extends Kind = "directed">(mutable: MutableGraph<N, E, T>) => Graph<N, E, T>;
-/**
- * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+ * 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** (Applying scoped mutations)
+ * **Example** (Getting a local neighborhood)
  *
  * ```ts
  * import { Graph } from "effect"
  *
- * const graph = Graph.directed<string, number>()
- * const newGraph = Graph.mutate(graph, (mutable) => {
- *   const nodeA = Graph.addNode(mutable, "A")
- *   const nodeB = Graph.addNode(mutable, "B")
- *   Graph.addEdge(mutable, nodeA, nodeB, 1)
+ * 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")
  * })
  *
- * console.log(Graph.nodeCount(newGraph)) // 2
- * console.log(Graph.edgeCount(newGraph)) // 1
+ * const result = Graph.neighborhood(graph, 1, { radius: 1 })
+ *
+ * console.log(Graph.nodeCount(result)) // 2
  * ```
  *
- * @category mutations
- * @since 3.18.0
+ * @category set operations
+ * @since 4.0.0
  */
-export declare const mutate: {
+export declare const neighborhood: {
     /**
-     * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+     * Returns the induced subgraph containing nodes within a radius of a node.
      *
-     * **Example** (Applying scoped mutations)
+     * **Details**
+     *
+     * The `radius` option is the maximum edge distance from `nodeIndex` and
+     * defaults to `1`. The `direction` option controls directed graph traversal and
+     * defaults to `"outgoing"`. The result has the same graph kind as `self` and
+     * keeps all original edges whose endpoints are both reached. `"undirected"`
+     * ignores edge direction while finding reachable nodes.
+     *
+     * **Example** (Getting a local neighborhood)
      *
      * ```ts
      * import { Graph } from "effect"
      *
-     * const graph = Graph.directed<string, number>()
-     * const newGraph = Graph.mutate(graph, (mutable) => {
-     *   const nodeA = Graph.addNode(mutable, "A")
-     *   const nodeB = Graph.addNode(mutable, "B")
-     *   Graph.addEdge(mutable, nodeA, nodeB, 1)
+     * 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")
      * })
      *
-     * console.log(Graph.nodeCount(newGraph)) // 2
-     * console.log(Graph.edgeCount(newGraph)) // 1
+     * const result = Graph.neighborhood(graph, 1, { radius: 1 })
+     *
+     * console.log(Graph.nodeCount(result)) // 2
      * ```
      *
-     * @category mutations
-     * @since 3.18.0
+     * @category set operations
+     * @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>;
+    (nodeIndex: NodeIndex, options?: NeighborhoodConfig): <N, E, T extends Kind = "directed">(self: Graph<N, E, T>) => Graph<N, E, T>;
     /**
-     * Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
+     * Returns the induced subgraph containing nodes within a radius of a node.
      *
-     * **Example** (Applying scoped mutations)
+     * **Details**
+     *
+     * The `radius` option is the maximum edge distance from `nodeIndex` and
+     * defaults to `1`. The `direction` option controls directed graph traversal and
+     * defaults to `"outgoing"`. The result has the same graph kind as `self` and
+     * keeps all original edges whose endpoints are both reached. `"undirected"`
+     * ignores edge direction while finding reachable nodes.
+     *
+     * **Example** (Getting a local neighborhood)
      *
      * ```ts
      * import { Graph } from "effect"
      *
-     * const graph = Graph.directed<string, number>()
-     * const newGraph = Graph.mutate(graph, (mutable) => {
-     *   const nodeA = Graph.addNode(mutable, "A")
-     *   const nodeB = Graph.addNode(mutable, "B")
-     *   Graph.addEdge(mutable, nodeA, nodeB, 1)
+     * 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")
      * })
      *
-     * console.log(Graph.nodeCount(newGraph)) // 2
-     * console.log(Graph.edgeCount(newGraph)) // 1
+     * const result = Graph.neighborhood(graph, 1, { radius: 1 })
+     *
+     * console.log(Graph.nodeCount(result)) // 2
      * ```
      *
-     * @category mutations
-     * @since 3.18.0
+     * @category set operations
+     * @since 4.0.0
+     */
+    <N, E, T extends Kind = "directed">(self: Graph<N, E, T>, nodeIndex: NodeIndex, options?: NeighborhoodConfig): Graph<N, E, T>;
+};
+/**
+ * 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 declare const sum: {
+    /**
+     * 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
+     */
+    <N, E, T extends Kind>(that: Graph<N, E, T>): (self: Graph<N, E, NoInfer<T>>) => Graph<N, E, T>;
+    /**
+     * 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
      */
-    <N, E, T extends Kind = "directed">(graph: Graph<N, E, T>, f: (mutable: MutableGraph<N, E, T>) => void): Graph<N, E, T>;
+    <N, E, T extends Kind>(self: Graph<N, E, T>, that: Graph<N, E, NoInfer<T>>): Graph<N, E, T>;
 };
 /**
  * Adds a new node to a mutable graph and returns its index.
@@ -502,7 +1427,7 @@ export declare const getNode: {
      * @category getters
      * @since 3.18.0
      */
-    <N, E, T extends Kind = "directed">(nodeIndex: NodeIndex): (graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<N>;
+    (nodeIndex: NodeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<N>;
     /**
      * Gets the data associated with a node index safely, if it exists.
      *
@@ -1327,7 +2252,7 @@ export declare const getEdge: {
      * @category getters
      * @since 3.18.0
      */
-    <E>(edgeIndex: EdgeIndex): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<Edge<E>>;
+    (edgeIndex: EdgeIndex): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<Edge<E>>;
     /**
      * Gets the edge data associated with an edge index safely, if it exists.
      *
@@ -1887,7 +2812,7 @@ export interface GraphVizOptions<N, E> {
  *
  * const dot = Graph.toGraphViz(graph)
  * console.log(dot)
- * // digraph G {
+ * // digraph "G" {
  * //   "0" [label="Node A"];
  * //   "1" [label="Node B"];
  * //   "2" [label="Node C"];
@@ -1920,7 +2845,7 @@ export declare const toGraphViz: {
      *
      * const dot = Graph.toGraphViz(graph)
      * console.log(dot)
-     * // digraph G {
+     * // digraph "G" {
      * //   "0" [label="Node A"];
      * //   "1" [label="Node B"];
      * //   "2" [label="Node C"];
@@ -1953,7 +2878,7 @@ export declare const toGraphViz: {
      *
      * const dot = Graph.toGraphViz(graph)
      * console.log(dot)
-     * // digraph G {
+     * // digraph "G" {
      * //   "0" [label="Node A"];
      * //   "1" [label="Node B"];
      * //   "2" [label="Node C"];
@@ -2274,22 +3199,22 @@ export interface MermaidOptions<N, E> {
  *     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")
@@ -2454,22 +3379,22 @@ export declare const toMermaid: {
      *     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")
@@ -2634,22 +3559,22 @@ export declare const toMermaid: {
      *     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")
@@ -2685,7 +3610,25 @@ export declare const toMermaid: {
     <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, options?: MermaidOptions<N, E>): string;
 };
 /**
- * Direction for graph traversal, indicating which edges to follow.
+ * Direction of directed edges relative to a node.
+ *
+ * **Details**
+ *
+ * `"outgoing"` selects edges whose source is the node, while `"incoming"`
+ * selects edges whose target is the node.
+ *
+ * @category models
+ * @since 3.18.0
+ */
+export type Direction = "outgoing" | "incoming";
+/**
+ * Controls how traversal follows directed edges.
+ *
+ * **Details**
+ *
+ * `"outgoing"` follows edges from source to target, `"incoming"` follows them
+ * from target to source, and `"undirected"` allows traversal in either
+ * direction.
  *
  * **Example** (Traversing by direction)
  *
@@ -2695,24 +3638,28 @@ export declare const toMermaid: {
  * 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 c = Graph.addNode(mutable, "C")
+ *   Graph.addEdge(mutable, a, b, "A-B")
+ *   Graph.addEdge(mutable, a, c, "A-C")
  * })
  *
- * // Follow outgoing edges (normal direction)
- * const outgoingNodes = Array.from(
- *   Graph.indices(Graph.dfs(graph, { start: [0], direction: "outgoing" }))
- * )
+ * const outgoing = Array.from(
+ *   Graph.indices(Graph.bfs(graph, { start: [0], direction: "outgoing" }))
+ * ) // [0, 1, 2]
  *
- * // Follow incoming edges (reverse direction)
- * const incomingNodes = Array.from(
- *   Graph.indices(Graph.dfs(graph, { start: [1], direction: "incoming" }))
- * )
+ * const incoming = Array.from(
+ *   Graph.indices(Graph.bfs(graph, { start: [1], direction: "incoming" }))
+ * ) // [1, 0]
+ *
+ * const undirected = Array.from(
+ *   Graph.indices(Graph.bfs(graph, { start: [1], direction: "undirected" }))
+ * ) // [1, 0, 2]
  * ```
  *
  * @category models
- * @since 3.18.0
+ * @since 4.0.0
  */
-export type Direction = "outgoing" | "incoming";
+export type TraversalDirection = Direction | "undirected";
 /**
  * Checks whether the graph is acyclic (contains no cycles).
  *
@@ -2720,7 +3667,8 @@ export type Direction = "outgoing" | "incoming";
  *
  * 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)
  *
@@ -2892,12 +3840,13 @@ export interface PathResult<E> {
  * **Details**
  *
  * Specifies the source and target node indices, plus a cost function that maps
- * each edge's data to a non-negative numeric weight.
+ * each edge's data to a non-negative numeric weight. `Infinity` is allowed and
+ * behaves like an impassable edge.
  *
  * **Gotchas**
  *
  * `dijkstra` throws a `GraphError` when either endpoint does not exist or when
- * the cost function returns a negative weight.
+ * the cost function returns a negative weight or `NaN`.
  *
  * @see {@link dijkstra} for the algorithm that consumes this configuration
  * @see {@link AstarConfig} for heuristic shortest-path search
@@ -2917,9 +3866,10 @@ export interface DijkstraConfig<E> {
  *
  * **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)
  *
@@ -2957,9 +3907,10 @@ export declare const dijkstra: {
      *
      * **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)
      *
@@ -2997,9 +3948,10 @@ export declare const dijkstra: {
      *
      * **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)
      *
@@ -3064,8 +4016,9 @@ export interface AllPairsResult<E> {
  * **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)
  *
@@ -3097,8 +4050,9 @@ export declare const floydWarshall: {
      * **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)
      *
@@ -3130,8 +4084,9 @@ export declare const floydWarshall: {
      * **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)
      *
@@ -3167,8 +4122,9 @@ export declare const floydWarshall: {
  *
  * **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.
+ * Specifies the source and target node indices, an edge-cost function that maps
+ * edge data to non-negative weights, and a heuristic that estimates the
+ * remaining cost from a node to the target.
  *
  * @see {@link astar} for the algorithm that consumes this configuration
  * @see {@link DijkstraConfig} for shortest paths without a heuristic
@@ -3189,10 +4145,11 @@ export interface AstarConfig<E, N> {
  *
  * **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)
  *
@@ -3236,10 +4193,11 @@ export declare const astar: {
      *
      * **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)
      *
@@ -3283,10 +4241,11 @@ export declare const astar: {
      *
      * **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)
      *
@@ -3356,9 +4315,10 @@ export interface BellmanFordConfig<E> {
  *
  * **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)
  *
@@ -3396,9 +4356,10 @@ export declare const bellmanFord: {
      *
      * **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)
      *
@@ -3436,9 +4397,10 @@ export declare const bellmanFord: {
      *
      * **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)
      *
@@ -3698,7 +4660,8 @@ export declare const entries: <T, N>(walker: Walker<T, N>) => Iterable<[T, N]>;
  *
  * `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.
+ * outgoing edges, incoming edges, or ignores edge direction. `radius` limits
+ * traversal by edge distance from the nearest start node.
  *
  * **Gotchas**
  *
@@ -3714,7 +4677,8 @@ export declare const entries: <T, N>(walker: Walker<T, N>) => Iterable<[T, N]>;
  */
 export interface SearchConfig {
     readonly start?: Array<NodeIndex>;
-    readonly direction?: Direction;
+    readonly direction?: TraversalDirection;
+    readonly radius?: number;
 }
 /**
  * Creates a lazy depth-first traversal iterator from the configured start
@@ -3723,7 +4687,8 @@ export interface SearchConfig {
  * **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)
@@ -3761,7 +4726,8 @@ export declare const dfs: {
      * **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)
@@ -3799,7 +4765,8 @@ export declare const dfs: {
      * **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)
@@ -3838,7 +4805,8 @@ export declare const dfs: {
  * **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)
@@ -3876,7 +4844,8 @@ export declare const bfs: {
      * **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)
@@ -3914,7 +4883,8 @@ export declare const bfs: {
      * **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)
@@ -4064,7 +5034,7 @@ export declare const topo: {
      * @category iterators
      * @since 3.18.0
      */
-    (config?: TopoConfig): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeWalker<N>;
+    (config?: TopoConfig): <N, E>(graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">) => NodeWalker<N>;
     /**
      * Creates a new topological sort iterator with optional configuration.
      *
@@ -4111,7 +5081,7 @@ export declare const topo: {
      * @category iterators
      * @since 3.18.0
      */
-    <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config?: TopoConfig): NodeWalker<N>;
+    <N, E>(graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, config?: TopoConfig): NodeWalker<N>;
 };
 /**
  * Creates a lazy depth-first postorder traversal iterator from the configured
@@ -4121,7 +5091,14 @@ export declare const topo: {
  *
  * 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)
  *
@@ -4155,7 +5132,14 @@ export declare const dfsPostOrder: {
      *
      * 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)
      *
@@ -4189,7 +5173,14 @@ export declare const dfsPostOrder: {
      *
      * 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)
      *