effect 4.0.0-beta.79 → 4.0.0-beta.80

package/src/Graph.ts

@@ -1386,6 +1386,31 @@ export const mapEdges = <N, E, T extends Kind = "directed">(
   }
 }
 
+/**
+ * @internal
+ */
+const rebuildAdjacency = <N, E, T extends Kind = "directed">(
+  mutable: MutableGraph<N, E, T>
+): void => {
+  mutable.adjacency.clear()
+  mutable.reverseAdjacency.clear()
+
+  for (const nodeIndex of mutable.nodes.keys()) {
+    mutable.adjacency.set(nodeIndex, [])
+    mutable.reverseAdjacency.set(nodeIndex, [])
+  }
+
+  for (const [edgeIndex, edgeData] of mutable.edges) {
+    mutable.adjacency.get(edgeData.source)!.push(edgeIndex)
+    mutable.reverseAdjacency.get(edgeData.target)!.push(edgeIndex)
+
+    if (mutable.type === "undirected") {
+      mutable.adjacency.get(edgeData.target)!.push(edgeIndex)
+      mutable.reverseAdjacency.get(edgeData.source)!.push(edgeIndex)
+    }
+  }
+}
+
 /**
  * Swaps source and target nodes for every edge in a mutable graph.
  *
@@ -1413,6 +1438,10 @@ export const mapEdges = <N, E, T extends Kind = "directed">(
 export const reverse = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>
 ): void => {
+  if (mutable.type === "undirected") {
+    return
+  }
+
   // Reverse all edges by swapping source and target
   for (const [index, edgeData] of mutable.edges) {
     mutable.edges.set(
@@ -1425,22 +1454,7 @@ export const reverse = <N, E, T extends Kind = "directed">(
     )
   }
 
-  // Clear and rebuild adjacency lists with reversed directions
-  mutable.adjacency.clear()
-  mutable.reverseAdjacency.clear()
-
-  // Rebuild adjacency lists with reversed directions
-  for (const [edgeIndex, edgeData] of mutable.edges) {
-    // Add to forward adjacency (source -> target)
-    const sourceEdges = mutable.adjacency.get(edgeData.source) || []
-    sourceEdges.push(edgeIndex)
-    mutable.adjacency.set(edgeData.source, sourceEdges)
-
-    // Add to reverse adjacency (target <- source)
-    const targetEdges = mutable.reverseAdjacency.get(edgeData.target) || []
-    targetEdges.push(edgeIndex)
-    mutable.reverseAdjacency.set(edgeData.target, targetEdges)
-  }
+  rebuildAdjacency(mutable)
 
   // Invalidate cycle flag since edge directions changed
   mutable.acyclic = Option.none()
@@ -2131,8 +2145,11 @@ export const hasEdge: {
   // Check if any edge in the adjacency list connects to the target
   for (const edgeIndex of adjacencyList) {
     const edge = graph.edges.get(edgeIndex)
-    if (edge !== undefined && edge.target === target) {
-      return true
+    if (edge !== undefined) {
+      const neighbor = graph.type === "undirected" && edge.target === source ? edge.source : edge.target
+      if (neighbor === target) {
+        return true
+      }
     }
   }
 
@@ -2169,6 +2186,31 @@ export const edgeCount = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
 ): number => graph.edges.size
 
+const getDirectedNeighbors = <N, E>(
+  graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
+  nodeIndex: NodeIndex,
+  direction: Direction
+): Array<NodeIndex> => {
+  const adjacencyMap = direction === "incoming"
+    ? graph.reverseAdjacency
+    : graph.adjacency
+
+  const adjacencyList = adjacencyMap.get(nodeIndex)
+  if (adjacencyList === undefined) {
+    return []
+  }
+
+  const result: Array<NodeIndex> = []
+  for (const edgeIndex of adjacencyList) {
+    const edge = graph.edges.get(edgeIndex)
+    if (edge !== undefined) {
+      result.push(direction === "incoming" ? edge.source : edge.target)
+    }
+  }
+
+  return result
+}
+
 /**
  * Returns the neighboring node indices for a node.
  *
@@ -2286,24 +2328,160 @@ export const neighbors: {
     return getUndirectedNeighbors(graph as any, nodeIndex)
   }
 
-  const adjacencyList = graph.adjacency.get(nodeIndex)
-  if (adjacencyList === undefined) {
-    return []
-  }
+  return getDirectedNeighbors(graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, nodeIndex, "outgoing")
+})
 
-  const result: Array<NodeIndex> = []
-  for (const edgeIndex of adjacencyList) {
-    const edge = graph.edges.get(edgeIndex)
-    if (edge !== undefined) {
-      result.push(edge.target)
-    }
+/**
+ * Returns the outgoing neighbor node indices for a node in a directed graph.
+ *
+ * **When to use**
+ *
+ * Use when you need the nodes reached by following outgoing edges from a node in
+ * a directed graph.
+ *
+ * **Gotchas**
+ *
+ * Throws a `GraphError` when used with an undirected graph.
+ *
+ * @see {@link predecessors} for incoming neighbors in a directed graph
+ * @see {@link neighbors} for generic neighbor lookup across graph kinds
+ *
+ * @category queries
+ * @since 4.0.0
+ */
+export const successors: {
+  /**
+   * Returns the outgoing neighbor node indices for a node in a directed graph.
+   *
+   * **When to use**
+   *
+   * Use when you need the nodes reached by following outgoing edges from a node in
+   * a directed graph.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
+   *
+   * @see {@link predecessors} for incoming neighbors in a directed graph
+   * @see {@link neighbors} for generic neighbor lookup across graph kinds
+   *
+   * @category queries
+   * @since 4.0.0
+   */
+  (nodeIndex: NodeIndex): <N, E>(graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">) => Array<NodeIndex>
+  /**
+   * Returns the outgoing neighbor node indices for a node in a directed graph.
+   *
+   * **When to use**
+   *
+   * Use when you need the nodes reached by following outgoing edges from a node in
+   * a directed graph.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
+   *
+   * @see {@link predecessors} for incoming neighbors in a directed graph
+   * @see {@link neighbors} for generic neighbor lookup across graph kinds
+   *
+   * @category queries
+   * @since 4.0.0
+   */
+  <N, E>(
+    graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
+    nodeIndex: NodeIndex
+  ): Array<NodeIndex>
+} = dual(2, <N, E, T extends Kind = "directed">(
+  graph: Graph<N, E, T> | MutableGraph<N, E, T>,
+  nodeIndex: NodeIndex
+): Array<NodeIndex> => {
+  if (graph.type === "undirected") {
+    throw new GraphError({ message: "Cannot get successors of undirected graph" })
   }
+  return getDirectedNeighbors(graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, nodeIndex, "outgoing")
+})
 
-  return result
+/**
+ * Returns the incoming neighbor node indices for a node in a directed graph.
+ *
+ * **When to use**
+ *
+ * Use when you need the nodes that reach a node by following incoming edges in a
+ * directed graph.
+ *
+ * **Gotchas**
+ *
+ * Throws a `GraphError` when used with an undirected graph.
+ *
+ * @see {@link successors} for outgoing neighbors in a directed graph
+ * @see {@link neighbors} for generic neighbor lookup across graph kinds
+ *
+ * @category queries
+ * @since 4.0.0
+ */
+export const predecessors: {
+  /**
+   * Returns the incoming neighbor node indices for a node in a directed graph.
+   *
+   * **When to use**
+   *
+   * Use when you need the nodes that reach a node by following incoming edges in a
+   * directed graph.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
+   *
+   * @see {@link successors} for outgoing neighbors in a directed graph
+   * @see {@link neighbors} for generic neighbor lookup across graph kinds
+   *
+   * @category queries
+   * @since 4.0.0
+   */
+  (nodeIndex: NodeIndex): <N, E>(graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">) => Array<NodeIndex>
+  /**
+   * Returns the incoming neighbor node indices for a node in a directed graph.
+   *
+   * **When to use**
+   *
+   * Use when you need the nodes that reach a node by following incoming edges in a
+   * directed graph.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
+   *
+   * @see {@link successors} for outgoing neighbors in a directed graph
+   * @see {@link neighbors} for generic neighbor lookup across graph kinds
+   *
+   * @category queries
+   * @since 4.0.0
+   */
+  <N, E>(
+    graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
+    nodeIndex: NodeIndex
+  ): Array<NodeIndex>
+} = dual(2, <N, E, T extends Kind = "directed">(
+  graph: Graph<N, E, T> | MutableGraph<N, E, T>,
+  nodeIndex: NodeIndex
+): Array<NodeIndex> => {
+  if (graph.type === "undirected") {
+    throw new GraphError({ message: "Cannot get predecessors of undirected graph" })
+  }
+  return getDirectedNeighbors(graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, nodeIndex, "incoming")
 })
 
 /**
- * Gets neighbors of a node in a specific direction for bidirectional traversal.
+ * Gets directed neighbors of a node in a specific direction.
+ *
+ * **When to use**
+ *
+ * Use when maintaining existing code that already passes an explicit traversal
+ * direction. New code should prefer `successors` or `predecessors`.
+ *
+ * **Gotchas**
+ *
+ * Throws a `GraphError` when used with an undirected graph.
  *
  * **Example** (Traversing directed neighbors)
  *
@@ -2326,12 +2504,24 @@ export const neighbors: {
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
  * ```
  *
+ * @deprecated Use {@link successors} for outgoing neighbors or {@link predecessors} for incoming neighbors.
+ * @see {@link successors} for outgoing neighbors in a directed graph
+ * @see {@link predecessors} for incoming neighbors in a directed graph
  * @category queries
  * @since 3.18.0
  */
 export const neighborsDirected: {
   /**
-   * Gets neighbors of a node in a specific direction for bidirectional traversal.
+   * Gets directed neighbors of a node in a specific direction.
+   *
+   * **When to use**
+   *
+   * Use when maintaining existing code that already passes an explicit traversal
+   * direction. New code should prefer `successors` or `predecessors`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
    *
    * **Example** (Traversing directed neighbors)
    *
@@ -2354,12 +2544,24 @@ export const neighborsDirected: {
    * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
    * ```
    *
+   * @deprecated Use {@link successors} for outgoing neighbors or {@link predecessors} for incoming neighbors.
+   * @see {@link successors} for outgoing neighbors in a directed graph
+   * @see {@link predecessors} for incoming neighbors in a directed graph
    * @category queries
    * @since 3.18.0
    */
-  (nodeIndex: NodeIndex, direction: Direction): <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Array<NodeIndex>
+  (nodeIndex: NodeIndex, direction: Direction): <N, E>(graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">) => Array<NodeIndex>
   /**
-   * Gets neighbors of a node in a specific direction for bidirectional traversal.
+   * Gets directed neighbors of a node in a specific direction.
+   *
+   * **When to use**
+   *
+   * Use when maintaining existing code that already passes an explicit traversal
+   * direction. New code should prefer `successors` or `predecessors`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `GraphError` when used with an undirected graph.
    *
    * **Example** (Traversing directed neighbors)
    *
@@ -2382,11 +2584,14 @@ export const neighborsDirected: {
    * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
    * ```
    *
+   * @deprecated Use {@link successors} for outgoing neighbors or {@link predecessors} for incoming neighbors.
+   * @see {@link successors} for outgoing neighbors in a directed graph
+   * @see {@link predecessors} for incoming neighbors in a directed graph
    * @category queries
    * @since 3.18.0
    */
-  <N, E, T extends Kind = "directed">(
-    graph: Graph<N, E, T> | MutableGraph<N, E, T>,
+  <N, E>(
+    graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
     nodeIndex: NodeIndex,
     direction: Direction
   ): Array<NodeIndex>
@@ -2395,28 +2600,10 @@ export const neighborsDirected: {
   nodeIndex: NodeIndex,
   direction: Direction
 ): Array<NodeIndex> => {
-  const adjacencyMap = direction === "incoming"
-    ? graph.reverseAdjacency
-    : graph.adjacency
-
-  const adjacencyList = adjacencyMap.get(nodeIndex)
-  if (adjacencyList === undefined) {
-    return []
-  }
-
-  const result: Array<NodeIndex> = []
-  for (const edgeIndex of adjacencyList) {
-    const edge = graph.edges.get(edgeIndex)
-    if (edge !== undefined) {
-      // For incoming direction, we want the source node instead of target
-      const neighborNode = direction === "incoming"
-        ? edge.source
-        : edge.target
-      result.push(neighborNode)
-    }
+  if (graph.type === "undirected") {
+    throw new GraphError({ message: "Cannot get directed neighbors of undirected graph" })
   }
-
-  return result
+  return getDirectedNeighbors(graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, nodeIndex, direction)
 })
 
 // =============================================================================
@@ -3603,7 +3790,11 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
         recursionStack.add(node)
 
         // Get neighbors for this node
-        const nodeNeighbors = Array.from(neighborsDirected(graph, node, "outgoing"))
+        const nodeNeighbors = getDirectedNeighbors(
+          graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
+          node,
+          "outgoing"
+        )
         stack[stack.length - 1] = [node, nodeNeighbors, 0, false]
         continue
       }
@@ -3757,7 +3948,7 @@ const getTraversalNeighbors = <N, E, T extends Kind>(
 ): Array<NodeIndex> =>
   graph.type === "undirected"
     ? getUndirectedNeighbors(graph as any, nodeIndex)
-    : neighborsDirected(graph, nodeIndex, direction)
+    : getDirectedNeighbors(graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">, nodeIndex, direction)
 
 const getTraversableNeighbor = <E, T extends Kind>(
   graph: Graph<unknown, E, T> | MutableGraph<unknown, E, T>,
@@ -3828,6 +4019,10 @@ export const connectedComponents = <N, E>(
  * Finds strongly connected components in a directed graph using Kosaraju's algorithm.
  * Each SCC is represented as an array of node indices.
  *
+ * **Gotchas**
+ *
+ * Throws a `GraphError` when used with an undirected graph.
+ *
  * **Example** (Finding strongly connected components)
  *
  * ```ts
@@ -3849,9 +4044,13 @@ export const connectedComponents = <N, E>(
  * @category algorithms
  * @since 3.18.0
  */
-export const stronglyConnectedComponents = <N, E, T extends Kind = "directed">(
-  graph: Graph<N, E, T> | MutableGraph<N, E, T>
+export const stronglyConnectedComponents = <N, E>(
+  graph: Graph<N, E, "directed"> | MutableGraph<N, E, "directed">
 ): Array<Array<NodeIndex>> => {
+  if ((graph as Graph<N, E, Kind> | MutableGraph<N, E, Kind>).type === "undirected") {
+    throw new GraphError({ message: "Cannot find strongly connected components of undirected graph" })
+  }
+
   const visited = new Set<NodeIndex>()
   const finishOrder: Array<NodeIndex> = []
   // Iterate directly over node keys
@@ -3877,7 +4076,7 @@ export const stronglyConnectedComponents = <N, E, T extends Kind = "directed">(
         }
 
         visited.add(node)
-        const nodeNeighborsList = neighbors(graph, node)
+        const nodeNeighborsList = getDirectedNeighbors(graph, node, "outgoing")
         stack[stack.length - 1] = [node, nodeNeighborsList, 0, false]
         continue
       }
@@ -4010,6 +4209,22 @@ export interface DijkstraConfig<E> {
   cost: (edgeData: E) => number
 }
 
+const validateNonNegativeEdgeWeights = <N, E, T extends Kind = "directed">(
+  graph: Graph<N, E, T> | MutableGraph<N, E, T>,
+  cost: (edgeData: E) => number,
+  algorithm: string
+): Map<EdgeIndex, number> => {
+  const edgeWeights = new Map<EdgeIndex, number>()
+  for (const [edgeIndex, edgeData] of graph.edges) {
+    const weight = cost(edgeData.data)
+    if (weight < 0 || Number.isNaN(weight)) {
+      throw new GraphError({ message: `${algorithm} requires non-negative edge weights` })
+    }
+    edgeWeights.set(edgeIndex, weight)
+  }
+  return edgeWeights
+}
+
 /**
  * Finds the shortest path from the configured source node to the target node
  * using Dijkstra's algorithm.
@@ -4142,6 +4357,8 @@ export const dijkstra: {
     throw missingNode(config.target)
   }
 
+  const edgeWeights = validateNonNegativeEdgeWeights(graph, config.cost, "Dijkstra's algorithm")
+
   // Early return if source equals target
   if (config.source === config.target) {
     return Option.some({
@@ -4202,12 +4419,7 @@ export const dijkstra: {
         const edge = graph.edges.get(edgeIndex)
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge)
-          const cost = config.cost(edge.data)
-
-          // Validate non-negative weights
-          if (cost < 0) {
-            throw new GraphError({ message: "Dijkstra's algorithm requires non-negative edge weights" })
-          }
+          const cost = edgeWeights.get(edgeIndex)!
 
           const newDistance = currentDistance + cost
           const neighborDistance = distances.get(neighbor)!
@@ -4538,7 +4750,7 @@ export interface AstarConfig<E, N> {
  * **Details**
  *
  * The edge-cost function must return non-negative weights, and the heuristic
- * should be admissible to preserve shortest-path guarantees. Returns
+ * 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.
  *
@@ -4585,7 +4797,7 @@ export const astar: {
    * **Details**
    *
    * The edge-cost function must return non-negative weights, and the heuristic
-   * should be admissible to preserve shortest-path guarantees. Returns
+   * 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.
    *
@@ -4632,7 +4844,7 @@ export const astar: {
    * **Details**
    *
    * The edge-cost function must return non-negative weights, and the heuristic
-   * should be admissible to preserve shortest-path guarantees. Returns
+   * 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.
    *
@@ -4684,6 +4896,8 @@ export const astar: {
     throw missingNode(config.target)
   }
 
+  const edgeWeights = validateNonNegativeEdgeWeights(graph, config.cost, "A* algorithm")
+
   // Early return if source equals target
   if (config.source === config.target) {
     return Option.some({
@@ -4759,12 +4973,7 @@ export const astar: {
         const edge = graph.edges.get(edgeIndex)
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge)
-          const weight = config.cost(edge.data)
-
-          // Validate non-negative weights
-          if (weight < 0) {
-            throw new GraphError({ message: "A* algorithm requires non-negative edge weights" })
-          }
+          const weight = edgeWeights.get(edgeIndex)!
 
           const tentativeGScore = currentGScore + weight
           const neighborGScore = gScore.get(neighbor)!
@@ -5697,14 +5906,17 @@ export const bfs: {
  *
  * **When to use**
  *
- * Use to seed a topological sort with specific initial node indices instead of
- * starting from every zero in-degree node.
+ * Use to prioritize specific zero in-degree nodes in a topological sort.
  *
  * **Details**
  *
- * `initials` optionally supplies the node indices used as initial queue
- * entries. When omitted, topological sorting starts from all nodes with zero
- * in-degree.
+ * `initials` optionally supplies zero in-degree node indices used as
+ * prioritized initial queue entries. Topological sorting still includes the
+ * other zero in-degree nodes and produces a complete topological order.
+ *
+ * **Gotchas**
+ *
+ * Throws a `GraphError` when any initial node has incoming edges.
  *
  * @see {@link topo} for the iterator that consumes this configuration
  *
@@ -5882,6 +6094,7 @@ export const topo: {
     [Symbol.iterator]: () => {
       const inDegree = new Map<NodeIndex, number>()
       const remaining = new Set<NodeIndex>()
+      const initialSet = new Set(initials)
       const queue = [...initials]
 
       // Initialize in-degree counts
@@ -5896,12 +6109,16 @@ export const topo: {
         inDegree.set(edgeData.target, currentInDegree + 1)
       }
 
-      // Add nodes with zero in-degree to queue if no initials provided
-      if (initials.length === 0) {
-        for (const [nodeIndex, degree] of inDegree) {
-          if (degree === 0) {
-            queue.push(nodeIndex)
-          }
+      for (const nodeIndex of initials) {
+        if (inDegree.get(nodeIndex)! !== 0) {
+          throw new GraphError({ message: `Initial node ${nodeIndex} has incoming edges` })
+        }
+      }
+
+      // Add remaining zero in-degree nodes after prioritized initials.
+      for (const [nodeIndex, degree] of inDegree) {
+        if (degree === 0 && !initialSet.has(nodeIndex)) {
+          queue.push(nodeIndex)
         }
       }
 
@@ -5913,7 +6130,11 @@ export const topo: {
             remaining.delete(current)
 
             // Process outgoing edges, reducing in-degree of targets
-            const neighbors = neighborsDirected(graph, current, "outgoing")
+            const neighbors = getDirectedNeighbors(
+              graph as Graph<N, E, "directed"> | MutableGraph<N, E, "directed">,
+              current,
+              "outgoing"
+            )
             for (const neighbor of neighbors) {
               if (remaining.has(neighbor)) {
                 const currentInDegree = inDegree.get(neighbor) || 0

package/src/Schema.ts

@@ -13258,6 +13258,13 @@ export interface ToJsonSchemaOptions {
  * properties and synthesized check descriptions; it does not change the draft
  * target.
  *
+ * **Gotchas**
+ *
+ * JSON Schema generation is best-effort. Some Effect schema semantics cannot
+ * be represented exactly in JSON Schema, and importing an emitted JSON Schema
+ * may produce an equivalent approximation rather than the original schema
+ * shape.
+ *
  * @category converting
  * @since 4.0.0
  */

package/src/SchemaRepresentation.ts

@@ -2179,6 +2179,13 @@ export function toSchema<S extends Schema.Top = Schema.Top>(document: Document,
  * Use when you need to produce a standard JSON Schema document from a schema
  * representation `Document`.
  *
+ * **Gotchas**
+ *
+ * JSON Schema generation is best-effort. Some Effect schema representation
+ * semantics cannot be represented exactly in JSON Schema, and importing an
+ * emitted JSON Schema may produce an equivalent approximation rather than the
+ * original representation shape.
+ *
  * **Example** (Generating JSON Schema)
  *
  * ```ts
@@ -2211,6 +2218,13 @@ export const toJsonSchemaDocument: (
  * Use when you need to export related schema representation documents together
  * so shared definitions stay in multi-document JSON Schema form.
  *
+ * **Gotchas**
+ *
+ * JSON Schema generation is best-effort. Some Effect schema representation
+ * semantics cannot be represented exactly in JSON Schema, and importing an
+ * emitted JSON Schema may produce equivalent approximations rather than the
+ * original representation shapes.
+ *
  * @see {@link MultiDocument}
  * @see {@link toJsonSchemaDocument}
  * @see {@link fromJsonSchemaMultiDocument}
@@ -2962,6 +2976,11 @@ function toRuntimeRegExp(regExp: RegExp): string {
  *
  * **Gotchas**
  *
+ * JSON Schema import is best-effort. Some JSON Schema constructs do not map
+ * exactly to Effect schema representations, and importing a schema previously
+ * emitted by `toJsonSchemaDocument` may produce an equivalent approximation
+ * rather than the original representation shape.
+ *
  * This throws if a `$ref` cannot be resolved within the document's definitions.
  * Circular `$ref`s are detected and cause an error.
  *
@@ -3002,6 +3021,11 @@ export function fromJsonSchemaDocument(document: JsonSchema.Document<"draft-2020
  *
  * **Gotchas**
  *
+ * JSON Schema import is best-effort. Some JSON Schema constructs do not map
+ * exactly to Effect schema representations, and importing schemas previously
+ * emitted by `toJsonSchemaMultiDocument` may produce equivalent approximations
+ * rather than the original representation shapes.
+ *
  * This throws if a `$ref` cannot be resolved.
  *
  * @see {@link MultiDocument}

package/src/Stream.ts

@@ -1416,7 +1416,7 @@ export const fromReadableStream = <A, E>(
       scope,
       options.releaseLockOnEnd
         ? Effect.sync(() => reader.releaseLock())
-        : Effect.promise(() => reader.cancel())
+        : Effect.promise(() => reader.cancel().catch(constVoid))
     )
     return Effect.flatMap(
       Effect.tryPromise({

package/src/internal/schema/representation.ts

@@ -362,8 +362,9 @@ export function toJsonSchemaMultiDocument(
     switch (schema._tag) {
       case "Any":
       case "Unknown":
-      case "ObjectKeyword":
         return {}
+      case "ObjectKeyword":
+        return { anyOf: [{ type: "object" }, { type: "array" }] }
       case "Void":
       case "Undefined":
         return { type: "null" }