Merge commit '36c66dd290d3ce6eb1ccd310d0c658d4a32bb8eb' as 'repos/effect'

repos/effect/migration/equality.md

@@ -0,0 +1,72 @@
+# Equality
+
+## Structural Equality by Default
+
+In v3, `Equal.equals` used **reference equality** for plain objects and arrays.
+Structural comparison was only available inside a `structuralRegion`, which
+temporarily enabled deep comparison. Outside a structural region, two distinct
+objects with identical contents were not considered equal:
+
+```ts
+// v3
+import { Equal } from "effect"
+
+Equal.equals({ a: 1 }, { a: 1 }) // false — reference equality
+Equal.equals([1, 2], [1, 2]) // false — reference equality
+```
+
+In v4, `Equal.equals` uses **structural equality** by default. Plain objects,
+arrays, `Map`s, `Set`s, `Date`s, and `RegExp`s are compared by value without
+opting in:
+
+```ts
+// v4
+import { Equal } from "effect"
+
+Equal.equals({ a: 1 }, { a: 1 }) // true
+Equal.equals([1, [2, 3]], [1, [2, 3]]) // true
+Equal.equals(new Map([["a", 1]]), new Map([["a", 1]])) // true
+Equal.equals(new Set([1, 2]), new Set([1, 2])) // true
+```
+
+Objects that implement the `Equal` interface continue to use their custom
+equality logic, same as v3.
+
+## Opting Out: `byReference`
+
+If you need reference equality for a specific object, v4 provides
+`Equal.byReference` and `Equal.byReferenceUnsafe`:
+
+```ts
+import { Equal } from "effect"
+
+const obj = Equal.byReference({ a: 1 })
+Equal.equals(obj, { a: 1 }) // false — reference equality
+```
+
+- **`byReference(obj)`** — creates a `Proxy` that uses reference equality,
+  leaving the original object unchanged.
+- **`byReferenceUnsafe(obj)`** — marks the object itself for reference
+  equality without creating a proxy. More performant but permanently changes
+  how the object is compared.
+
+## `NaN` Equality
+
+In v3, `Equal.equals(NaN, NaN)` returned `false` (following IEEE 754).
+In v4, `NaN` is considered equal to `NaN`:
+
+```ts
+Equal.equals(NaN, NaN) // v3: false, v4: true
+```
+
+## `equivalence` → `asEquivalence`
+
+The function that wraps `equals` as an `Equivalence` has been renamed:
+
+```ts
+// v3
+Equal.equivalence<number>()
+
+// v4
+Equal.asEquivalence<number>()
+```