effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/Schema.ts

@@ -1,85 +1,13 @@
 /**
- * Define data shapes, validate unknown input, and transform values between formats.
- *
- * ## Mental model
- *
- * - **Schema** — a description of a data shape. Every schema carries a decoded
- *   *Type* (the value you work with) and an *Encoded* representation (the
- *   serialized form, e.g. JSON).
- * - **Decoding** — turning unknown external data (API responses, form
- *   submissions, config files) into typed, validated values.
- * - **Encoding** — turning typed values back into a serializable format.
- * - **Codec** — a schema that tracks both Type and Encoded, so it can decode
- *   *and* encode. Most concrete schemas are Codecs.
- * - **Check / Filter** — a constraint attached to a schema (e.g. `isMinLength`,
- *   `isGreaterThan`). Attach them with `.check(...)`.
- * - **Transformation** — a pair of functions (decode + encode) that convert
- *   values between two schemas. Created with {@link decodeTo} / {@link encodeTo}.
- * - **Annotation** — metadata attached to a schema (title, description, custom
- *   keys). Attach with `.annotate(...)`.
- *
- * ## Common tasks
- *
- * - Define a struct: {@link Struct}
- * - Define a union: {@link Union}, {@link TaggedUnion}, {@link Literals}
- * - Define an array: {@link ArraySchema}, {@link NonEmptyArray}
- * - Define a record: {@link Record}
- * - Define a tuple: {@link Tuple}, {@link TupleWithRest}
- * - Validate unknown data synchronously: {@link decodeUnknownSync}
- * - Validate unknown data (Effect): {@link decodeUnknownEffect}
- * - Encode a value: {@link encodeUnknownSync}, {@link encodeUnknownEffect}
- * - Type guard: {@link is}
- * - Assertion: {@link asserts}
- * - Add constraints: `.check(...)` with filters like {@link isMinLength},
- *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}, {@link isGUID}
- * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
- * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
- * - Create branded types: {@link brand}
- * - Define classes with validation: {@link Class}, {@link TaggedClass}
- * - Define error classes: {@link ErrorClass}, {@link TaggedErrorClass}
- * - Generate JSON Schema: {@link toJsonSchemaDocument}
- * - Generate test data: {@link toArbitrary}
- * - Derive equivalence: {@link toEquivalence}
- *
- * ## Gotchas
- *
- * - `Schema.optional` creates `T | undefined` (key can be missing *or*
- *   `undefined`). Use `Schema.optionalKey` for exact optional properties.
- * - `decodeTo` is curried: use `from.pipe(Schema.decodeTo(to, ...))`.
- * - `decodeUnknownSync` throws on failure. Use `decodeUnknownExit` or
- *   `decodeUnknownOption` for non-throwing alternatives.
- * - Filters do not change the TypeScript type. Use {@link refine} or
- *   {@link brand} to narrow the type.
- * - Recursive schemas require {@link suspend} to avoid infinite loops.
- *
- * ## Quickstart
- *
- * **Example** (Validate a user object)
+ * Describes data shapes and how unknown input becomes trusted values.
  *
- * ```ts
- * import { Schema } from "effect"
- *
- * const User = Schema.Struct({
- *   name: Schema.String.check(Schema.isMinLength(1)),
- *   age: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
- *   email: Schema.optionalKey(Schema.String)
- * })
- *
- * // Decode unknown input — throws on failure
- * const user = Schema.decodeUnknownSync(User)({
- *   name: "Alice",
- *   age: 30
- * })
- *
- * console.log(user)
- * // { name: "Alice", age: 30 }
- * ```
- *
- * @see {@link Schema} — type-level view tracking only the decoded Type
- * @see {@link Codec} — type-level view tracking both Type and Encoded
- * @see {@link Struct} — define object shapes
- * @see {@link decodeUnknownSync} — synchronous validation
- * @see {@link decodeTo} — schema transformations
+ * A schema can validate input, decode it into an application type, and encode
+ * that value back to another representation. This module contains the main
+ * schema, codec, decoder, and encoder APIs, together with schemas for common
+ * JavaScript values and Effect data types. It also supports refinements,
+ * transformations, defaults, classes, JSON Schema generation, test data
+ * generation, formatting, equivalence, optics, and differs derived from schema
+ * definitions.
  *
  * @since 4.0.0
  */
@@ -3197,6 +3125,9 @@ export interface encodeKeys<
   >
 {}
 
+const canonicalPropertyKey = (key: PropertyKey): string | symbol =>
+  typeof key === "symbol" ? key : globalThis.String(key)
+
 /**
  * Renames struct keys in the encoded form without changing the decoded type.
  *
@@ -3205,6 +3136,8 @@ export interface encodeKeys<
  * Takes a partial mapping `{ decodedKey: encodedKey }` and produces a
  * transformation schema that decodes from the renamed keys and encodes back to
  * the renamed keys. Keys not present in the mapping are left unchanged.
+ * If two existing fields would produce the same encoded key, construction
+ * fails.
  *
  * **Example** (Rename `name` to `full_name` in the encoded form)
  *
@@ -3229,21 +3162,29 @@ export function encodeKeys<
 >(mapping: M) {
   return function(self: S): encodeKeys<S, M> {
     const fields: any = {}
+    const appliedMapping: any = {}
     const reverseMapping: any = {}
-    for (const k in self.fields) {
+    const seenEncodedKeys = new Set<string | symbol>()
+    for (const k of Reflect.ownKeys(self.fields)) {
       const encoded = toEncoded(self.fields[k])
-      if (Object.hasOwn(mapping, k)) {
-        fields[mapping[k]!] = encoded
-        reverseMapping[mapping[k]!] = k
-      } else {
-        fields[k] = encoded
+      const hasMapping = Object.hasOwn(mapping, k)
+      const encodedKey = hasMapping ? (mapping as any)[k] as PropertyKey : k
+      const canonical = canonicalPropertyKey(encodedKey)
+      if (seenEncodedKeys.has(canonical)) {
+        throw new globalThis.Error(`Duplicate encoded keys: ${formatPropertyKey(encodedKey)}`)
+      }
+      seenEncodedKeys.add(canonical)
+      fields[encodedKey] = encoded
+      if (hasMapping) {
+        appliedMapping[k] = encodedKey
+        reverseMapping[encodedKey] = k
       }
     }
     return Struct(fields).pipe(decodeTo(
       self,
       SchemaTransformation.transform<any, any>({
         decode: Struct_.renameKeys(reverseMapping),
-        encode: Struct_.renameKeys(mapping)
+        encode: Struct_.renameKeys(appliedMapping)
       })
     )) as any
   }
@@ -6151,8 +6092,8 @@ export function isTrimmed(annotations?: Annotations.Filter) {
         _tag: "isTrimmed",
         regExp: new globalThis.RegExp(TRIMMED_PATTERN)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [TRIMMED_PATTERN]
         }
       },
@@ -6458,8 +6399,8 @@ export function isStartsWith(startsWith: string, annotations?: Annotations.Filte
         startsWith,
         regExp: new globalThis.RegExp(`^${startsWith}`)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [`^${startsWith}`]
         }
       },
@@ -6492,8 +6433,8 @@ export function isEndsWith(endsWith: string, annotations?: Annotations.Filter) {
         endsWith,
         regExp: new globalThis.RegExp(`${endsWith}$`)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [`${endsWith}$`]
         }
       },
@@ -6526,8 +6467,8 @@ export function isIncludes(includes: string, annotations?: Annotations.Filter) {
         includes,
         regExp: new globalThis.RegExp(includes)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [includes]
         }
       },
@@ -6559,8 +6500,8 @@ export function isUppercased(annotations?: Annotations.Filter) {
         _tag: "isUppercased",
         regExp: new globalThis.RegExp(UPPERCASED_PATTERN)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [UPPERCASED_PATTERN]
         }
       },
@@ -6592,8 +6533,8 @@ export function isLowercased(annotations?: Annotations.Filter) {
         _tag: "isLowercased",
         regExp: new globalThis.RegExp(LOWERCASED_PATTERN)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [LOWERCASED_PATTERN]
         }
       },
@@ -6625,8 +6566,8 @@ export function isCapitalized(annotations?: Annotations.Filter) {
         _tag: "isCapitalized",
         regExp: new globalThis.RegExp(CAPITALIZED_PATTERN)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [CAPITALIZED_PATTERN]
         }
       },
@@ -6658,8 +6599,8 @@ export function isUncapitalized(annotations?: Annotations.Filter) {
         _tag: "isUncapitalized",
         regExp: new globalThis.RegExp(UNCAPITALIZED_PATTERN)
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [UNCAPITALIZED_PATTERN]
         }
       },
@@ -6680,8 +6621,8 @@ export function isUncapitalized(annotations?: Annotations.Filter) {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies `noDefaultInfinity`
- * and `noNaN` constraints to ensure generated numbers are finite.
+ * When generating test data with fast-check, this applies `noNaN: true` and
+ * `noInfinity: true` constraints to ensure generated numbers are finite.
  *
  * @category Number checks
  * @since 4.0.0
@@ -6694,9 +6635,9 @@ export function isFinite(annotations?: Annotations.Filter) {
       meta: {
         _tag: "isFinite"
       },
-      toArbitraryConstraint: {
-        number: {
-          noDefaultInfinity: true,
+      arbitrary: {
+        constraint: {
+          noInfinity: true,
           noNaN: true
         }
       },
@@ -6724,6 +6665,15 @@ export function makeIsGreaterThan<T>(options: {
       (input) => gt(input, exclusiveMinimum),
       {
         expected: `a value greater than ${formatter(exclusiveMinimum)}`,
+        arbitrary: {
+          constraint: {
+            ordered: {
+              order: options.order,
+              minimum: exclusiveMinimum,
+              exclusiveMinimum: true
+            }
+          }
+        },
         ...options.annotate?.(exclusiveMinimum),
         ...annotations
       }
@@ -6750,6 +6700,14 @@ export function makeIsGreaterThanOrEqualTo<T>(options: {
       (input) => gte(input, minimum),
       {
         expected: `a value greater than or equal to ${formatter(minimum)}`,
+        arbitrary: {
+          constraint: {
+            ordered: {
+              order: options.order,
+              minimum
+            }
+          }
+        },
         ...options.annotate?.(minimum),
         ...annotations
       }
@@ -6776,6 +6734,15 @@ export function makeIsLessThan<T>(options: {
       (input) => lt(input, exclusiveMaximum),
       {
         expected: `a value less than ${formatter(exclusiveMaximum)}`,
+        arbitrary: {
+          constraint: {
+            ordered: {
+              order: options.order,
+              maximum: exclusiveMaximum,
+              exclusiveMaximum: true
+            }
+          }
+        },
         ...options.annotate?.(exclusiveMaximum),
         ...annotations
       }
@@ -6802,6 +6769,14 @@ export function makeIsLessThanOrEqualTo<T>(options: {
       (input) => lte(input, maximum),
       {
         expected: `a value less than or equal to ${formatter(maximum)}`,
+        arbitrary: {
+          constraint: {
+            ordered: {
+              order: options.order,
+              maximum
+            }
+          }
+        },
         ...options.annotate?.(maximum),
         ...annotations
       }
@@ -6847,6 +6822,17 @@ export function makeIsBetween<T>(deriveOptions: {
         expected: `a value between ${formatter(options.minimum)}${options.exclusiveMinimum ? " (excluded)" : ""} and ${
           formatter(options.maximum)
         }${options.exclusiveMaximum ? " (excluded)" : ""}`,
+        arbitrary: {
+          constraint: {
+            ordered: {
+              order: deriveOptions.order,
+              minimum: options.minimum,
+              maximum: options.maximum,
+              ...(options.exclusiveMinimum && { exclusiveMinimum: true }),
+              ...(options.exclusiveMaximum && { exclusiveMaximum: true })
+            }
+          }
+        },
         ...deriveOptions.annotate?.(options),
         ...annotations
       }
@@ -6891,9 +6877,9 @@ export function makeIsMultipleOf<T>(options: {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated numbers are greater than the
- * specified value.
+ * When generating test data with fast-check, this applies an
+ * `exclusiveMinimum` constraint to ensure generated numbers are greater than
+ * the specified value.
  *
  * @category Number checks
  * @since 4.0.0
@@ -6904,12 +6890,6 @@ export const isGreaterThan = makeIsGreaterThan({
     meta: {
       _tag: "isGreaterThan",
       exclusiveMinimum
-    },
-    toArbitraryConstraint: {
-      number: {
-        min: exclusiveMinimum,
-        minExcluded: true
-      }
     }
   })
 })
@@ -6926,7 +6906,7 @@ export const isGreaterThan = makeIsGreaterThan({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
+ * When generating test data with fast-check, this applies a `minimum` constraint
  * to ensure generated numbers are greater than or equal to the specified value.
  *
  * @category Number checks
@@ -6938,11 +6918,6 @@ export const isGreaterThanOrEqualTo = makeIsGreaterThanOrEqualTo({
     meta: {
       _tag: "isGreaterThanOrEqualTo",
       minimum
-    },
-    toArbitraryConstraint: {
-      number: {
-        min: minimum
-      }
     }
   })
 })
@@ -6958,8 +6933,8 @@ export const isGreaterThanOrEqualTo = makeIsGreaterThanOrEqualTo({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated numbers are less than the
+ * When generating test data with fast-check, this applies an
+ * `exclusiveMaximum` constraint to ensure generated numbers are less than the
  * specified value.
  *
  * @category Number checks
@@ -6971,12 +6946,6 @@ export const isLessThan = makeIsLessThan({
     meta: {
       _tag: "isLessThan",
       exclusiveMaximum
-    },
-    toArbitraryConstraint: {
-      number: {
-        max: exclusiveMaximum,
-        maxExcluded: true
-      }
     }
   })
 })
@@ -6993,7 +6962,7 @@ export const isLessThan = makeIsLessThan({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
+ * When generating test data with fast-check, this applies a `maximum` constraint
  * to ensure generated numbers are less than or equal to the specified value.
  *
  * @category Number checks
@@ -7005,11 +6974,6 @@ export const isLessThanOrEqualTo = makeIsLessThanOrEqualTo({
     meta: {
       _tag: "isLessThanOrEqualTo",
       maximum
-    },
-    toArbitraryConstraint: {
-      number: {
-        max: maximum
-      }
     }
   })
 })
@@ -7027,9 +6991,10 @@ export const isLessThanOrEqualTo = makeIsLessThanOrEqualTo({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies `min` and `max`
- * constraints with optional `minExcluded` and `maxExcluded` flags to ensure
- * generated numbers fall within the specified range.
+ * When generating test data with fast-check, this applies `minimum` and
+ * `maximum` constraints with optional `exclusiveMinimum` and
+ * `exclusiveMaximum` flags to ensure generated numbers fall within the
+ * specified range.
  *
  * @category Number checks
  * @since 4.0.0
@@ -7041,14 +7006,6 @@ export const isBetween = makeIsBetween({
       meta: {
         _tag: "isBetween",
         ...options
-      },
-      toArbitraryConstraint: {
-        number: {
-          min: options.minimum,
-          max: options.maximum,
-          ...(options.exclusiveMinimum && { minExcluded: true }),
-          ...(options.exclusiveMaximum && { maxExcluded: true })
-        }
       }
     }
   }
@@ -7095,7 +7052,7 @@ export const isMultipleOf = makeIsMultipleOf({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies an `isInteger: true`
+ * When generating test data with fast-check, this applies an `integer: true`
  * constraint to ensure generated numbers are integers.
  *
  * @category Integer checks
@@ -7109,9 +7066,9 @@ export function isInt(annotations?: Annotations.Filter) {
       meta: {
         _tag: "isInt"
       },
-      toArbitraryConstraint: {
-        number: {
-          isInteger: true
+      arbitrary: {
+        constraint: {
+          integer: true
         }
       },
       ...annotations
@@ -7196,7 +7153,7 @@ export function isUint32(annotations?: Annotations.Filter) {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `noInvalidDate`
+ * When generating test data with fast-check, this applies a `valid: true`
  * constraint to ensure generated Date objects are valid.
  *
  * @category Date checks
@@ -7210,9 +7167,9 @@ export function isDateValid(annotations?: Annotations.Filter) {
       meta: {
         _tag: "isDateValid"
       },
-      toArbitraryConstraint: {
-        date: {
-          noInvalidDate: true
+      arbitrary: {
+        constraint: {
+          valid: true
         }
       },
       ...annotations
@@ -7220,10 +7177,6 @@ export function isDateValid(annotations?: Annotations.Filter) {
   )
 }
 
-const nextDate = (date: globalThis.Date) => new globalThis.Date(date.getTime() + 1)
-
-const previousDate = (date: globalThis.Date) => new globalThis.Date(date.getTime() - 1)
-
 /**
  * Validates that a Date is greater than the specified value (exclusive).
  *
@@ -7244,11 +7197,6 @@ export const isGreaterThanDate = makeIsGreaterThan({
     meta: {
       _tag: "isGreaterThanDate",
       exclusiveMinimum
-    },
-    toArbitraryConstraint: {
-      date: {
-        min: nextDate(exclusiveMinimum)
-      }
     }
   })
 })
@@ -7279,11 +7227,6 @@ export const isGreaterThanOrEqualToDate = makeIsGreaterThanOrEqualTo({
     meta: {
       _tag: "isGreaterThanOrEqualToDate",
       minimum
-    },
-    toArbitraryConstraint: {
-      date: {
-        min: minimum
-      }
     }
   })
 })
@@ -7308,11 +7251,6 @@ export const isLessThanDate = makeIsLessThan({
     meta: {
       _tag: "isLessThanDate",
       exclusiveMaximum
-    },
-    toArbitraryConstraint: {
-      date: {
-        max: previousDate(exclusiveMaximum)
-      }
     }
   })
 })
@@ -7343,11 +7281,6 @@ export const isLessThanOrEqualToDate = makeIsLessThanOrEqualTo({
     meta: {
       _tag: "isLessThanOrEqualToDate",
       maximum
-    },
-    toArbitraryConstraint: {
-      date: {
-        max: maximum
-      }
     }
   })
 })
@@ -7378,20 +7311,10 @@ export const isBetweenDate = makeIsBetween({
     meta: {
       _tag: "isBetweenDate",
       ...options
-    },
-    toArbitraryConstraint: {
-      date: {
-        min: options.exclusiveMinimum ? nextDate(options.minimum) : options.minimum,
-        max: options.exclusiveMaximum ? previousDate(options.maximum) : options.maximum
-      }
     }
   })
 })
 
-const nextBigInt = (n: bigint) => n + globalThis.BigInt(1)
-
-const previousBigInt = (n: bigint) => n - globalThis.BigInt(1)
-
 /**
  * Validates that a BigInt is greater than the specified value (exclusive).
  *
@@ -7412,11 +7335,6 @@ export const isGreaterThanBigInt = makeIsGreaterThan({
     meta: {
       _tag: "isGreaterThanBigInt",
       exclusiveMinimum
-    },
-    toArbitraryConstraint: {
-      bigint: {
-        min: nextBigInt(exclusiveMinimum)
-      }
     }
   })
 })
@@ -7442,11 +7360,6 @@ export const isGreaterThanOrEqualToBigInt = makeIsGreaterThanOrEqualTo({
     meta: {
       _tag: "isGreaterThanOrEqualToBigInt",
       minimum
-    },
-    toArbitraryConstraint: {
-      bigint: {
-        min: minimum
-      }
     }
   })
 })
@@ -7471,11 +7384,6 @@ export const isLessThanBigInt = makeIsLessThan({
     meta: {
       _tag: "isLessThanBigInt",
       exclusiveMaximum
-    },
-    toArbitraryConstraint: {
-      bigint: {
-        max: previousBigInt(exclusiveMaximum)
-      }
     }
   })
 })
@@ -7501,11 +7409,6 @@ export const isLessThanOrEqualToBigInt = makeIsLessThanOrEqualTo({
     meta: {
       _tag: "isLessThanOrEqualToBigInt",
       maximum
-    },
-    toArbitraryConstraint: {
-      bigint: {
-        max: maximum
-      }
     }
   })
 })
@@ -7531,12 +7434,6 @@ export const isBetweenBigInt = makeIsBetween({
     meta: {
       _tag: "isBetweenBigInt",
       ...options
-    },
-    toArbitraryConstraint: {
-      bigint: {
-        min: options.exclusiveMinimum ? nextBigInt(options.minimum) : options.minimum,
-        max: options.exclusiveMaximum ? previousBigInt(options.maximum) : options.maximum
-      }
     }
   })
 })
@@ -7643,11 +7540,8 @@ export function isMinLength(minLength: number, annotations?: Annotations.Filter)
         minLength
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        string: {
-          minLength
-        },
-        array: {
+      arbitrary: {
+        constraint: {
           minLength
         }
       },
@@ -7710,11 +7604,8 @@ export function isMaxLength(maxLength: number, annotations?: Annotations.Filter)
         maxLength
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        string: {
-          maxLength
-        },
-        array: {
+      arbitrary: {
+        constraint: {
           maxLength
         }
       },
@@ -7758,12 +7649,8 @@ export function isLengthBetween(minimum: number, maximum: number, annotations?:
         maximum
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        string: {
-          minLength: minimum,
-          maxLength: maximum
-        },
-        array: {
+      arbitrary: {
+        constraint: {
           minLength: minimum,
           maxLength: maximum
         }
@@ -7786,9 +7673,9 @@ export function isLengthBetween(minimum: number, maximum: number, annotations?:
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `minLength`
- * constraint to the array representation to ensure generated values have at
- * least the required size.
+ * When generating test data with fast-check, this applies a node-local
+ * `minLength` constraint. Generators for values with a final `.size`, such as
+ * sets and maps, interpret it as final cardinality.
  *
  * @category Size checks
  * @since 4.0.0
@@ -7804,8 +7691,8 @@ export function isMinSize(minSize: number, annotations?: Annotations.Filter) {
         minSize
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           minLength: minSize
         }
       },
@@ -7827,9 +7714,9 @@ export function isMinSize(minSize: number, annotations?: Annotations.Filter) {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `maxLength`
- * constraint to the array representation to ensure generated values have at
- * most the required size.
+ * When generating test data with fast-check, this applies a node-local
+ * `maxLength` constraint. Generators for values with a final `.size`, such as
+ * sets and maps, interpret it as final cardinality.
  *
  * @category Size checks
  * @since 4.0.0
@@ -7845,8 +7732,8 @@ export function isMaxSize(maxSize: number, annotations?: Annotations.Filter) {
         maxSize
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           maxLength: maxSize
         }
       },
@@ -7868,9 +7755,9 @@ export function isMaxSize(maxSize: number, annotations?: Annotations.Filter) {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies `minLength` and
- * `maxLength` constraints to ensure generated values have a size within the
- * specified range.
+ * When generating test data with fast-check, this applies node-local
+ * `minLength` and `maxLength` constraints. Generators for values with a final
+ * `.size`, such as sets and maps, interpret them as final cardinality.
  *
  * @category Size checks
  * @since 4.0.0
@@ -7890,8 +7777,8 @@ export function isSizeBetween(minimum: number, maximum: number, annotations?: An
         maximum
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           minLength: minimum,
           maxLength: maximum
         }
@@ -7914,10 +7801,9 @@ export function isSizeBetween(minimum: number, maximum: number, annotations?: An
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `minLength`
- * constraint to the array of entries that is generated before being converted
- * to an object, ensuring the resulting object has at least the required number
- * of properties.
+ * When generating test data with fast-check, this applies a node-local
+ * `minLength` constraint. Object generators interpret it as the final number
+ * of own properties.
  *
  * @category Object checks
  * @since 4.0.0
@@ -7933,8 +7819,8 @@ export function isMinProperties(minProperties: number, annotations?: Annotations
         minProperties
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           minLength: minProperties
         }
       },
@@ -7955,10 +7841,9 @@ export function isMinProperties(minProperties: number, annotations?: Annotations
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `maxLength`
- * constraint to the array of entries that is generated before being converted
- * to an object, ensuring the resulting object has at most the required number
- * of properties.
+ * When generating test data with fast-check, this applies a node-local
+ * `maxLength` constraint. Object generators interpret it as the final number
+ * of own properties.
  *
  * @category Object checks
  * @since 4.0.0
@@ -7974,8 +7859,8 @@ export function isMaxProperties(maxProperties: number, annotations?: Annotations
         maxProperties
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           maxLength: maxProperties
         }
       },
@@ -7997,9 +7882,9 @@ export function isMaxProperties(maxProperties: number, annotations?: Annotations
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies `minLength` and
- * `maxLength` constraints to the array of entries that is generated before
- * being converted to an object.
+ * When generating test data with fast-check, this applies node-local
+ * `minLength` and `maxLength` constraints. Object generators interpret them as
+ * the final number of own properties.
  *
  * @category Object checks
  * @since 4.0.0
@@ -8019,8 +7904,8 @@ export function isPropertiesLengthBetween(minimum: number, maximum: number, anno
         maximum
       },
       [SchemaAST.STRUCTURAL_ANNOTATION_KEY]: true,
-      toArbitraryConstraint: {
-        array: {
+      arbitrary: {
+        constraint: {
           minLength: minimum,
           maxLength: maximum
         }
@@ -8086,8 +7971,9 @@ export function isPropertyNames(keySchema: Top, annotations?: Annotations.Filter
  * This check corresponds to the `uniqueItems: true` constraint in JSON Schema.
  *
  * Arbitrary:
- * When generating test data with fast-check, this applies a comparator based on
- * Effect equality to ensure generated arrays contain only unique items.
+ * When generating test data with fast-check, this applies a node-local
+ * `unique: true` constraint. Array generators translate it to `fast-check`
+ * `uniqueArray` using Effect equality.
  *
  * @category Array checks
  * @since 4.0.0
@@ -8101,9 +7987,9 @@ export function isUnique<T>(annotations?: Annotations.Filter) {
       meta: {
         _tag: "isUnique"
       },
-      toArbitraryConstraint: {
-        array: {
-          comparator: equivalence
+      arbitrary: {
+        constraint: {
+          unique: true
         }
       },
       ...annotations
@@ -8249,11 +8135,12 @@ export function Option<A extends Top>(value: A): Option<A> {
           })
         ),
       toArbitrary: ([value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "Option" } : {},
-          fc.constant(Option_.none()),
-          value.map(Option_.some)
+        const terminal = fc.constant(Option_.none())
+        const arbitrary = fc.oneof(
+          terminal,
+          value.arbitrary.map(Option_.some)
         )
+        return withRecursion(fc, ctx, terminal, arbitrary)
       },
       toEquivalence: ([value]) => Option_.makeEquivalence(value),
       toFormatter: ([value]) =>
@@ -8556,11 +8443,16 @@ export function Result<A extends Top, E extends Top>(
           })
         ),
       toArbitrary: ([success, failure]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "Result" } : {},
-          success.map(Result_.succeed),
-          failure.map(Result_.fail)
+        const terminal = oneOfArbitraries(
+          fc,
+          success.terminal?.map((a): Result_.Result<A["Type"], E["Type"]> => Result_.succeed(a)),
+          failure.terminal?.map((e): Result_.Result<A["Type"], E["Type"]> => Result_.fail(e))
         )
+        const arbitrary = fc.oneof(
+          success.arbitrary.map((a): Result_.Result<A["Type"], E["Type"]> => Result_.succeed(a)),
+          failure.arbitrary.map((e): Result_.Result<A["Type"], E["Type"]> => Result_.fail(e))
+        )
+        return withRecursion(fc, ctx, terminal, arbitrary)
       },
       toEquivalence: ([success, failure]) => Result_.makeEquivalence(success, failure),
       toFormatter: ([success, failure]) =>
@@ -8673,7 +8565,10 @@ export function Redacted<S extends Top>(value: S, options?: {
               SchemaGetter.transform(Redacted_.value)
           }
         ),
-      toArbitrary: ([value]) => () => value.map((a) => Redacted_.make(a, { label: options?.label })),
+      toArbitrary: ([value]) => () => ({
+        arbitrary: value.arbitrary.map((a) => Redacted_.make(a, { label: options?.label })),
+        terminal: value.terminal?.map((a) => Redacted_.make(a, { label: options?.label }))
+      }),
       toFormatter: () => globalThis.String,
       toEquivalence: ([value]) => Redacted_.makeEquivalence(value)
     }
@@ -8865,15 +8760,19 @@ export function CauseReason<E extends Top, D extends Top>(error: E, defect: D):
   return make(schema.ast, { error, defect })
 }
 
-function causeReasonToArbitrary<E, D>(error: FastCheck.Arbitrary<E>, defect: FastCheck.Arbitrary<D>) {
-  return (fc: typeof FastCheck, ctx: Annotations.ToArbitrary.Context | undefined) => {
-    return fc.oneof(
-      ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "Cause.Failure" } : {},
-      fc.constant(Cause_.makeInterruptReason()),
+function causeReasonToArbitrary<E, D>(
+  error: Annotations.ToArbitrary.TypeParameter<E>,
+  defect: Annotations.ToArbitrary.TypeParameter<D>
+) {
+  return (fc: typeof FastCheck, ctx: Annotations.ToArbitrary.Context) => {
+    const terminal = fc.constant(Cause_.makeInterruptReason())
+    const arbitrary = fc.oneof(
+      terminal,
       fc.integer({ min: 1 }).map(Cause_.makeInterruptReason),
-      error.map((e) => Cause_.makeFailReason(e)),
-      defect.map((d) => Cause_.makeDieReason(d))
+      error.arbitrary.map((e) => Cause_.makeFailReason(e)),
+      defect.arbitrary.map((d) => Cause_.makeDieReason(d))
     )
+    return withRecursion(fc, ctx, terminal, arbitrary)
   }
 }
 
@@ -9003,9 +8902,15 @@ export function Cause<E extends Top, D extends Top>(error: E, defect: D): Cause<
   return make(schema.ast, { error, defect })
 }
 
-function causeToArbitrary<E, D>(error: FastCheck.Arbitrary<E>, defect: FastCheck.Arbitrary<D>) {
-  return (fc: typeof FastCheck, ctx: Annotations.ToArbitrary.Context | undefined) => {
-    return fc.array(causeReasonToArbitrary(error, defect)(fc, ctx)).map(Cause_.fromReasons)
+function causeToArbitrary<E, D>(
+  error: Annotations.ToArbitrary.TypeParameter<E>,
+  defect: Annotations.ToArbitrary.TypeParameter<D>
+) {
+  return (fc: typeof FastCheck, ctx: Annotations.ToArbitrary.Context) => {
+    const reason = causeReasonToArbitrary(error, defect)(fc, ctx)
+    const terminal = fc.constant(Cause_.empty)
+    const arbitrary = fc.array(reason.arbitrary).map(Cause_.fromReasons)
+    return withRecursion(fc, ctx, terminal, arbitrary)
   }
 }
 
@@ -9286,12 +9191,19 @@ export function Exit<A extends Top, E extends Top, D extends Top>(value: A, erro
                 : { _tag: "Failure", cause: exit.cause } as const
           })
         ),
-      toArbitrary: ([value, error, defect]) => (fc, ctx) =>
-        fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "Exit" } : {},
-          value.map((v) => Exit_.succeed(v)),
-          causeToArbitrary(error, defect)(fc, ctx).map((cause) => Exit_.failCause(cause))
-        ),
+      toArbitrary: ([value, error, defect]) => (fc, ctx) => {
+        const cause = causeToArbitrary(error, defect)(fc, ctx)
+        const terminal = oneOfArbitraries(
+          fc,
+          value.terminal?.map((v): Exit_.Exit<A["Type"], E["Type"]> => Exit_.succeed(v)),
+          cause.terminal?.map((cause): Exit_.Exit<A["Type"], E["Type"]> => Exit_.failCause(cause))
+        )
+        const arbitrary = fc.oneof(
+          value.arbitrary.map((v): Exit_.Exit<A["Type"], E["Type"]> => Exit_.succeed(v)),
+          cause.arbitrary.map((cause): Exit_.Exit<A["Type"], E["Type"]> => Exit_.failCause(cause))
+        )
+        return withRecursion(fc, ctx, terminal, arbitrary)
+      },
       toEquivalence: ([value, error, defect]) => {
         const cause = causeToEquivalence(error, defect)
         return (a, b) => {
@@ -9348,6 +9260,96 @@ export interface $ReadonlyMap<Key extends Top, Value extends Top> extends
  */
 export type ReadonlyMapIso<Key extends Top, Value extends Top> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>
 
+function oneOfArbitraries<T>(
+  fc: typeof FastCheck,
+  a: FastCheck.Arbitrary<T> | undefined,
+  b: FastCheck.Arbitrary<T> | undefined
+) {
+  return a === undefined ? b : b === undefined ? a : fc.oneof(a, b)
+}
+
+function withRecursion<T>(
+  fc: typeof FastCheck,
+  ctx: Annotations.ToArbitrary.Context,
+  terminal: FastCheck.Arbitrary<T> | undefined,
+  arbitrary: FastCheck.Arbitrary<T>
+) {
+  return {
+    arbitrary: terminal === undefined || ctx.recursion === undefined
+      ? arbitrary
+      : fc.oneof(ctx.recursion, terminal, arbitrary),
+    terminal
+  }
+}
+
+function arrayFromItems<T>(
+  fc: typeof FastCheck,
+  item: FastCheck.Arbitrary<T>,
+  constraints: FastCheck.ArrayConstraints | undefined,
+  comparator?: ((a: T, b: T) => boolean) | undefined
+) {
+  return comparator === undefined
+    ? fc.array(item, constraints)
+    : fc.uniqueArray(item, { ...constraints, comparator })
+}
+
+function collectionArbitrary<T, Out>(
+  fc: typeof FastCheck,
+  ctx: Annotations.ToArbitrary.Context,
+  item: FastCheck.Arbitrary<T>,
+  terminalItem: FastCheck.Arbitrary<T> | undefined,
+  fromIterable: (items: Array<T>) => Out,
+  comparator?: ((a: T, b: T) => boolean) | undefined
+) {
+  const constraint = ctx.constraint
+  const constraints = constraint === undefined ||
+      (constraint.minLength === undefined && constraint.maxLength === undefined)
+    ? undefined
+    : {
+      ...(constraint.minLength !== undefined ? { minLength: constraint.minLength } : {}),
+      ...(constraint.maxLength !== undefined ? { maxLength: constraint.maxLength } : {})
+    }
+  if (
+    constraints?.minLength !== undefined && constraints.maxLength !== undefined &&
+    constraints.minLength > constraints.maxLength
+  ) {
+    throw new globalThis.Error("Unable to derive an arbitrary for size constraints")
+  }
+  const minLength = constraints?.minLength ?? 0
+  const terminal = minLength === 0
+    ? fc.constant<Array<T>>([])
+    : terminalItem === undefined
+    ? undefined
+    : arrayFromItems(fc, terminalItem, { ...constraints, maxLength: minLength }, comparator)
+  const arrays = withRecursion(
+    fc,
+    ctx,
+    terminal,
+    arrayFromItems(fc, item, constraints, comparator)
+  )
+  return {
+    arbitrary: arrays.arbitrary.map(fromIterable),
+    terminal: arrays.terminal?.map(fromIterable)
+  }
+}
+
+function entriesArbitrary<K, V, Out>(
+  fc: typeof FastCheck,
+  ctx: Annotations.ToArbitrary.Context,
+  key: Annotations.ToArbitrary.TypeParameter<K>,
+  value: Annotations.ToArbitrary.TypeParameter<V>,
+  fromIterable: (items: Array<[K, V]>) => Out
+) {
+  return collectionArbitrary(
+    fc,
+    ctx,
+    fc.tuple(key.arbitrary, value.arbitrary),
+    key.terminal === undefined || value.terminal === undefined ? undefined : fc.tuple(key.terminal, value.terminal),
+    fromIterable,
+    ([a], [b]) => Equal.equals(a, b)
+  )
+}
+
 /**
  * Schema for readonly maps whose keys and values conform to the provided
  * schemas.
@@ -9395,13 +9397,7 @@ export function ReadonlyMap<Key extends Top, Value extends Top>(key: Key, value:
             encode: (map) => [...map.entries()]
           })
         ),
-      toArbitrary: ([key, value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "ReadonlyMap" } : {},
-          fc.constant([]),
-          fc.array(fc.tuple(key, value), ctx?.constraints?.array)
-        ).map((as) => new globalThis.Map(as))
-      },
+      toArbitrary: ([key, value]) => (fc, ctx) => entriesArbitrary(fc, ctx, key, value, (as) => new globalThis.Map(as)),
       toEquivalence: ([key, value]) => Equal.makeCompareMap(key, value),
       toFormatter: ([key, value]) => (t) => {
         const size = t.size
@@ -9491,13 +9487,7 @@ export function HashMap<Key extends Top, Value extends Top>(key: Key, value: Val
             encode: HashMap_.toEntries
           })
         ),
-      toArbitrary: ([key, value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "HashMap" } : {},
-          fc.constant([]),
-          fc.array(fc.tuple(key, value), ctx?.constraints?.array)
-        ).map(HashMap_.fromIterable)
-      },
+      toArbitrary: ([key, value]) => (fc, ctx) => entriesArbitrary(fc, ctx, key, value, HashMap_.fromIterable),
       toEquivalence: ([key, value]) => Equal.makeCompareMap(key, value),
       toFormatter: ([key, value]) => (t) => {
         const size = HashMap_.size(t)
@@ -9585,13 +9575,8 @@ export function ReadonlySet<Value extends Top>(value: Value): $ReadonlySet<Value
             encode: (set) => [...set.values()]
           })
         ),
-      toArbitrary: ([value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "ReadonlySet" } : {},
-          fc.constant([]),
-          fc.array(value, ctx?.constraints?.array)
-        ).map((as) => new globalThis.Set(as))
-      },
+      toArbitrary: ([value]) => (fc, ctx) =>
+        collectionArbitrary(fc, ctx, value.arbitrary, value.terminal, (as) => new globalThis.Set(as), Equal.equals),
       toEquivalence: ([value]) => Equal.makeCompareSet(value),
       toFormatter: ([value]) => (t) => {
         const size = t.size
@@ -9679,13 +9664,8 @@ export function HashSet<Value extends Top>(value: Value): HashSet<Value> {
             encode: Arr.fromIterable
           })
         ),
-      toArbitrary: ([value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "HashSet" } : {},
-          fc.constant([]),
-          fc.array(value, ctx?.constraints?.array)
-        ).map(HashSet_.fromIterable)
-      },
+      toArbitrary: ([value]) => (fc, ctx) =>
+        collectionArbitrary(fc, ctx, value.arbitrary, value.terminal, HashSet_.fromIterable, Equal.equals),
       toEquivalence: ([value]) => Equal.makeCompareSet(value),
       toFormatter: ([value]) => (t) => {
         const size = HashSet_.size(t)
@@ -9780,13 +9760,8 @@ export function Chunk<Value extends Top>(value: Value): Chunk<Value> {
             encode: Arr.fromIterable
           })
         ),
-      toArbitrary: ([value]) => (fc, ctx) => {
-        return fc.oneof(
-          ctx?.isSuspend ? { maxDepth: 2, depthIdentifier: "Chunk" } : {},
-          fc.constant([]),
-          fc.array(value, ctx?.constraints?.array)
-        ).map(Chunk_.fromIterable)
-      },
+      toArbitrary: ([value]) => (fc, ctx) =>
+        collectionArbitrary(fc, ctx, value.arbitrary, value.terminal, Chunk_.fromIterable),
       toEquivalence: ([value]) => Chunk_.makeEquivalence(value),
       toFormatter: ([value]) => (t) => {
         const size = Chunk_.size(t)
@@ -9958,6 +9933,38 @@ export interface Date extends instanceOf<globalThis.Date> {
   readonly "Rebuild": Date
 }
 
+type DateArbitraryConstraints = FastCheck.DateConstraints & {
+  readonly valid?: boolean | undefined
+}
+
+function dateArbitraryConstraints<T = globalThis.Date>(
+  constraint: Annotations.ToArbitrary.Constraint | undefined,
+  ordered: Annotations.ToArbitrary.OrderedConstraint<T> | undefined,
+  base?: DateArbitraryConstraints | undefined,
+  toDate?: (value: T) => globalThis.Date
+): FastCheck.DateConstraints {
+  const out: FastCheck.DateConstraints = { ...base }
+  delete (out as any).valid
+  if (base?.valid || constraint?.valid) {
+    out.noInvalidDate = true
+  }
+  if (ordered?.minimum !== undefined) {
+    const minimum = toDate === undefined ? ordered.minimum as globalThis.Date : toDate(ordered.minimum)
+    const nextMin = ordered.exclusiveMinimum ? new globalThis.Date(minimum.getTime() + 1) : minimum
+    if (out.min === undefined || nextMin.getTime() > out.min.getTime()) {
+      out.min = nextMin
+    }
+  }
+  if (ordered?.maximum !== undefined) {
+    const maximum = toDate === undefined ? ordered.maximum as globalThis.Date : toDate(ordered.maximum)
+    const nextMax = ordered.exclusiveMaximum ? new globalThis.Date(maximum.getTime() - 1) : maximum
+    if (out.max === undefined || nextMax.getTime() < out.max.getTime()) {
+      out.max = nextMax
+    }
+  }
+  return out
+}
+
 const DateString = String.annotate({ expected: "a string in ISO 8601 format that will be decoded as a Date" })
 
 /**
@@ -10004,7 +10011,11 @@ export const Date: Date = instanceOf(
         DateString,
         SchemaTransformation.dateFromString
       ),
-    toArbitrary: () => (fc, ctx) => fc.date(ctx?.constraints?.date)
+    toArbitrary: () => (fc, ctx) =>
+      fc.date(dateArbitraryConstraints(
+        ctx?.constraint,
+        ctx?.constraint?.ordered?.order === Order.Date ? ctx.constraint.ordered : undefined
+      ))
   }
 )
 
@@ -10268,6 +10279,81 @@ export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
 
 const BigDecimalString = String.annotate({ expected: "a string that will be decoded as a BigDecimal" })
 
+const bigDecimalDefaultMaxScale = 20
+const bigDecimalInvalidOrderedConstraintsError = "Unable to derive an arbitrary for the ordered BigDecimal constraints"
+
+function bigDecimalScaleValueAtScale(bd: BigDecimal_.BigDecimal, scale: number): bigint {
+  return BigDecimal_.scale(bd, scale).value
+}
+
+function bigDecimalMinValueAtScale(
+  minimum: BigDecimal_.BigDecimal,
+  scale: number,
+  excluded: boolean
+): bigint {
+  return excluded
+    ? bigDecimalScaleValueAtScale(BigDecimal_.floor(minimum, scale), scale) + globalThis.BigInt(1)
+    : bigDecimalScaleValueAtScale(BigDecimal_.ceil(minimum, scale), scale)
+}
+
+function bigDecimalMaxValueAtScale(
+  maximum: BigDecimal_.BigDecimal,
+  scale: number,
+  excluded: boolean
+): bigint {
+  return excluded
+    ? bigDecimalScaleValueAtScale(BigDecimal_.ceil(maximum, scale), scale) - globalThis.BigInt(1)
+    : bigDecimalScaleValueAtScale(BigDecimal_.floor(maximum, scale), scale)
+}
+
+function bigDecimalMaxScale(ordered: Annotations.ToArbitrary.OrderedConstraint<BigDecimal_.BigDecimal>): number {
+  return Math.max(
+    bigDecimalDefaultMaxScale,
+    ordered.minimum?.scale ?? 0,
+    ordered.maximum?.scale ?? 0,
+    ordered.exclusiveMinimum && ordered.minimum !== undefined ? ordered.minimum.scale + 1 : 0,
+    ordered.exclusiveMaximum && ordered.maximum !== undefined ? ordered.maximum.scale + 1 : 0
+  )
+}
+
+function bigDecimalValueConstraintsAtScale(
+  ordered: Annotations.ToArbitrary.OrderedConstraint<BigDecimal_.BigDecimal>,
+  scale: number
+): FastCheck.BigIntConstraints | undefined {
+  const constraints: FastCheck.BigIntConstraints = {}
+  if (ordered.minimum !== undefined) {
+    constraints.min = bigDecimalMinValueAtScale(ordered.minimum, scale, ordered.exclusiveMinimum === true)
+  }
+  if (ordered.maximum !== undefined) {
+    constraints.max = bigDecimalMaxValueAtScale(ordered.maximum, scale, ordered.exclusiveMaximum === true)
+  }
+  if (constraints.min !== undefined && constraints.max !== undefined && constraints.min > constraints.max) {
+    return undefined
+  }
+  return constraints
+}
+
+function bigDecimalScaleConstraints(
+  ordered: Annotations.ToArbitrary.OrderedConstraint<BigDecimal_.BigDecimal>
+): FastCheck.IntegerConstraints {
+  const max = bigDecimalMaxScale(ordered)
+  if (bigDecimalValueConstraintsAtScale(ordered, max) === undefined) {
+    throw new globalThis.Error(bigDecimalInvalidOrderedConstraintsError)
+  }
+
+  let min = 0
+  let high = max
+  while (min < high) {
+    const scale = min + Math.floor((high - min) / 2)
+    if (bigDecimalValueConstraintsAtScale(ordered, scale) === undefined) {
+      min = scale + 1
+    } else {
+      high = scale
+    }
+  }
+  return { min, max }
+}
+
 /**
  * Schema for `BigDecimal` values.
  *
@@ -10304,9 +10390,23 @@ export const BigDecimal: BigDecimal = declare(
         BigDecimalString,
         SchemaTransformation.bigDecimalFromString
       ),
-    toArbitrary: () => (fc) =>
-      fc.tuple(fc.bigInt(), fc.integer({ min: 0, max: 20 }))
-        .map(([value, scale]) => BigDecimal_.make(value, scale)),
+    toArbitrary: () => (fc, ctx) => {
+      const ordered = ctx.constraint?.ordered?.order === BigDecimal_.Order
+        ? ctx.constraint.ordered as Annotations.ToArbitrary.OrderedConstraint<BigDecimal_.BigDecimal>
+        : undefined
+      if (ordered === undefined) {
+        return fc.tuple(fc.bigInt(), fc.integer({ min: 0, max: bigDecimalDefaultMaxScale }))
+          .map(([value, scale]) => BigDecimal_.make(value, scale))
+      }
+
+      return fc.integer(bigDecimalScaleConstraints(ordered)).chain((scale) => {
+        const constraints = bigDecimalValueConstraintsAtScale(ordered, scale)
+        if (constraints === undefined) {
+          throw new globalThis.Error(bigDecimalInvalidOrderedConstraintsError)
+        }
+        return fc.bigInt(constraints).map((value) => BigDecimal_.make(value, scale))
+      })
+    },
     toFormatter: () => (bd) => BigDecimal_.format(bd),
     toEquivalence: () => BigDecimal_.Equivalence
   }
@@ -11427,7 +11527,13 @@ export const DateTimeUtc: DateTimeUtc = declare(
         SchemaTransformation.dateTimeUtcFromString
       ),
     toArbitrary: () => (fc, ctx) =>
-      fc.date({ noInvalidDate: true, ...ctx?.constraints?.date }).map((date) => DateTime.fromDateUnsafe(date)),
+      fc.date(dateArbitraryConstraints(
+        ctx?.constraint,
+        ctx?.constraint?.ordered?.order === DateTime.Order ? ctx.constraint.ordered : undefined,
+        { valid: true },
+        DateTime.toDateUtc
+      ))
+        .map((date) => DateTime.fromDateUnsafe(date)),
     toFormatter: () => (utc) => utc.toString(),
     toEquivalence: () => DateTime.Equivalence
   }
@@ -11801,12 +11907,16 @@ export const DateTimeZoned: DateTimeZoned = declare(
       ),
     toArbitrary: () => (fc, ctx) =>
       fc.tuple(
-        fc.date({
-          noInvalidDate: true,
-          min: new globalThis.Date(-8640000000000000 + 14 * 60 * 60 * 1000),
-          max: new globalThis.Date(8640000000000000 - 14 * 60 * 60 * 1000),
-          ...ctx?.constraints?.date
-        }),
+        fc.date(dateArbitraryConstraints(
+          ctx?.constraint,
+          ctx?.constraint?.ordered?.order === DateTime.Order ? ctx.constraint.ordered : undefined,
+          {
+            max: new globalThis.Date(8640000000000000 - 14 * 60 * 60 * 1000),
+            min: new globalThis.Date(-8640000000000000 + 14 * 60 * 60 * 1000),
+            valid: true
+          },
+          DateTime.toDateUtc
+        )),
         fc.constantFrom("UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney")
       ).map(([date, zone]) => DateTime.makeZonedUnsafe(date, { timeZone: zone })),
     toFormatter: () => (zoned) => DateTime.formatIsoZoned(zoned),
@@ -12046,8 +12156,10 @@ function getClassSchemaFactory<S extends Top>(
             identifier,
             [SchemaAST.ClassTypeId]: ([from]: readonly [SchemaAST.AST]) => new SchemaAST.Link(from, transformation),
             toCodec: ([from]: readonly [Codec<S["Encoded"]>]) => new SchemaAST.Link(from.ast, transformation),
-            toArbitrary: ([from]: readonly [FastCheck.Arbitrary<S["Type"]>]) => () =>
-              from.map((args) => new self(args)),
+            toArbitrary: ([from]: readonly [Annotations.ToArbitrary.TypeParameter<S["Type"]>]) => () => ({
+              arbitrary: from.arbitrary.map((args: S["Type"]) => new self(args)),
+              terminal: from.terminal?.map((args: S["Type"]) => new self(args))
+            }),
             toFormatter: ([from]: readonly [Formatter<S["Type"]>]) => (t: Self) => `${self.identifier}(${from(t)})`,
             "~sentinels": SchemaAST.collectSentinels(from.ast),
             ...annotations
@@ -12766,7 +12878,10 @@ export type LazyArbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>
  *
  * **Details**
  *
- * Prefer {@link toArbitrary} when you just need the arbitrary directly.
+ * Prefer {@link toArbitrary} when you need the arbitrary directly, or when you
+ * want derivation diagnostics via `{ report: true }`. Unsupported schema
+ * nodes, impossible constraints, invalid candidates, and recursive schemas
+ * without a finite terminal path fail immediately.
  *
  * @category Arbitrary
  * @since 4.0.0
@@ -12780,6 +12895,13 @@ export function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary<S["Type
  * Derives a `fast-check` `Arbitrary` from a schema for property-based
  * testing. The derived arbitrary generates values that satisfy the schema.
  *
+ * **Details**
+ *
+ * Constraints refine base generators; candidates add weighted sources while
+ * filters still validate every value. `{ report: true }` returns warnings such
+ * as `OpaqueFilter`, while derivation errors remain fail-fast. Recursive
+ * schemas use terminal branches and fail when no finite terminal path exists.
+ *
  * **Example** (Generating arbitrary values)
  *
  * ```ts
@@ -12798,7 +12920,24 @@ export function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary<S["Type
  * @category Arbitrary
  * @since 4.0.0
  */
-export function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Type"]> {
+export function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Type"]>
+export function toArbitrary<S extends Top>(
+  schema: S,
+  options: { readonly report: true }
+): Annotations.ToArbitrary.WithReport<FastCheck.Arbitrary<S["Type"]>>
+export function toArbitrary<S extends Top>(
+  schema: S,
+  options?: { readonly report?: boolean }
+): FastCheck.Arbitrary<S["Type"]> | Annotations.ToArbitrary.WithReport<FastCheck.Arbitrary<S["Type"]>> {
+  if (options?.report === true) {
+    const lawc = InternalArbitrary.memoized(schema.ast)
+    const report = InternalArbitrary.makeReport()
+    InternalArbitrary.collectReport(schema.ast, report)
+    return {
+      value: lawc(FastCheck, {}),
+      report: InternalArbitrary.toReport(report)
+    }
+  }
   return toArbitraryLazy(schema)(FastCheck)
 }
 
@@ -13193,7 +13332,8 @@ function toCodecJsonBase(ast: SchemaAST.AST, recur: (ast: SchemaAST.AST) => Sche
           ast.annotations,
           ast.checks,
           ast.encoding,
-          ast.context
+          ast.context,
+          ast.encodingChecks
         ).recur(recur)
       }
       return ast.recur(recur)
@@ -13472,7 +13612,8 @@ function serializerTree(
           ast.annotations,
           ast.checks,
           ast.encoding,
-          ast.context
+          ast.context,
+          ast.encodingChecks
         ).recur(recur)
       }
       return ast.recur(recur)
@@ -13865,7 +14006,7 @@ export function resolveAnnotationsKey<S extends Top>(schema: S): Annotations.Key
  * Use {@link resolveAnnotations} to read the annotations attached to a schema at
  * runtime.
  *
- * @since 3.10.0
+ * @since 4.0.0
  */
 export declare namespace Annotations {
   /**
@@ -13909,7 +14050,7 @@ export declare namespace Annotations {
    * ```
    *
    * @category models
-   * @since 3.10.0
+   * @since 4.0.0
    */
   export interface Annotations {
     readonly [x: string]: unknown
@@ -14038,7 +14179,7 @@ export declare namespace Annotations {
      * values.
      *
      * @category utility types
-     * @since 3.10.0
+     * @since 4.0.0
      */
     export type Type<TypeParameters extends ReadonlyArray<Top>> = {
       readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"]>
@@ -14047,7 +14188,7 @@ export declare namespace Annotations {
      * Maps declaration type-parameter schemas to codecs for their `Encoded` values.
      *
      * @category utility types
-     * @since 3.10.0
+     * @since 4.0.0
      */
     export type Encoded<TypeParameters extends ReadonlyArray<Top>> = {
       readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Encoded"]>
@@ -14103,7 +14244,7 @@ export declare namespace Annotations {
    * Filters are intentionally non-parametric to keep them covariant.
    *
    * @category models
-   * @since 3.10.0
+   * @since 4.0.0
    */
   export interface Filter extends Augment {
     /**
@@ -14130,8 +14271,17 @@ export declare namespace Annotations {
      * Optional metadata used to identify or extend the filter with custom data.
      */
     readonly meta?: Meta | undefined
-    readonly toArbitraryConstraint?:
-      | ToArbitrary.Constraint
+    /**
+     * Optional hints used by arbitrary derivation for this filter.
+     *
+     * **Details**
+     *
+     * The same annotation can be attached to a single filter or a
+     * `FilterGroup`. Group hints apply to the same schema node while child
+     * filters are still collected and checked normally.
+     */
+    readonly arbitrary?:
+      | ToArbitrary.Filter
       | undefined
     /**
      * Marks the filter as *structural*, meaning it applies to the shape or
@@ -14147,111 +14297,261 @@ export declare namespace Annotations {
 
   /**
    * Types used by arbitrary-derivation annotations to configure `toArbitrary`
-   * hooks and carry merged fast-check constraints.
+   * hooks, filter hints, candidate sources, diagnostics, and merged generation
+   * constraints.
    *
    * @since 4.0.0
    */
   export namespace ToArbitrary {
     /**
-     * fast-check string constraints plus optional regular-expression pattern strings
-     * used when deriving string arbitraries from schema checks.
+     * Arbitrary-generation hints attached to a filter or filter group.
+     *
+     * **Details**
+     *
+     * `constraint` refines the schema node's base generator. `candidate` adds a
+     * weighted source before all filters run. If neither hint is provided, the
+     * filter does not guide generation; generated values are still checked by
+     * the filter predicate. With `{ report: true }`, this is reported as
+     * `OpaqueFilter`.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export interface Filter {
+      readonly constraint?: Constraint | undefined
+      readonly candidate?: Candidate | undefined
+    }
+
+    /**
+     * Additional arbitrary source used before final filter checks run.
+     *
+     * **Details**
+     *
+     * The base generator keeps weight `1`; candidates default to weight `1`
+     * and must use a positive integer weight. `make` receives the merged
+     * constraint for the current node and may return `undefined` to opt out,
+     * including for recursive terminal branches. Candidate values are still
+     * checked by every schema filter, so invalid candidates affect efficiency but
+     * not validity.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface StringConstraints extends FastCheck.StringSharedConstraints {
-      readonly patterns?: readonly [string, ...Array<string>]
+    export interface Candidate {
+      readonly weight?: number | undefined
+      readonly make: (
+        fc: typeof FastCheck,
+        context: Context
+      ) => FastCheck.Arbitrary<unknown> | undefined
     }
 
     /**
-     * fast-check floating-point constraints plus `isInteger`, which switches
-     * derived number arbitraries to integer generation.
+     * Ordered constraint accumulated from range checks.
+     *
+     * **Details**
+     *
+     * Generators consume these constraints only when they recognize `order`,
+     * such as `Order.Number`, `Order.BigInt`, DateTime, or BigDecimal. Merging
+     * constraints with different `Order` instances fails fast.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface NumberConstraints extends FastCheck.FloatConstraints {
-      readonly isInteger?: boolean
+    export interface OrderedConstraint<T> {
+      readonly order: Order.Order<T>
+      readonly minimum?: T | undefined
+      readonly exclusiveMinimum?: boolean | undefined
+      readonly maximum?: T | undefined
+      readonly exclusiveMaximum?: boolean | undefined
     }
 
     /**
-     * fast-check bigint constraints used when deriving arbitraries for bigint
-     * schemas.
+     * Node-local arbitrary-generation constraint accumulated from schema checks.
+     *
+     * **Details**
+     *
+     * `Constraint` is a generation hint for the current schema AST node, not a
+     * self-describing validation contract. Each generator consumes the fields it
+     * understands for the current node and ignores the rest; final schema
+     * filters still validate every generated value.
+     *
+     * `minLength` and `maxLength` represent node-local cardinality: string
+     * length for strings, array length for arrays, final own-property count for
+     * objects, and final size/cardinality for sets, maps, hash collections, and
+     * chunks. `patterns` are concatenated and used by string generators.
+     * `integer`, `noNaN`, `noInfinity`, `valid`, and `unique` are true when any
+     * contributing filter sets them. Range bounds live in `ordered` so ordered
+     * values can share the same representation.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface BigIntConstraints extends FastCheck.BigIntConstraints {}
+    export interface Constraint {
+      readonly minLength?: number | undefined
+      readonly maxLength?: number | undefined
+      readonly patterns?: readonly [string, ...Array<string>]
+      readonly integer?: boolean | undefined
+      readonly noInfinity?: boolean | undefined
+      readonly noNaN?: boolean | undefined
+      readonly valid?: boolean | undefined
+      readonly unique?: boolean | undefined
+      readonly ordered?: OrderedConstraint<any> | undefined
+    }
 
     /**
-     * fast-check array constraints plus an optional comparator used when deriving
-     * unique-array arbitraries.
+     * Recursion budget passed to arbitrary-derivation hooks.
+     *
+     * **Details**
+     *
+     * Pass this object to `fc.oneof` when combining terminal and recursive
+     * branches. Put the terminal branch first because fast-check uses only the
+     * first branch once `maxDepth` is reached for `depthIdentifier`.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface ArrayConstraints extends FastCheck.ArrayConstraints {
-      readonly comparator?: (a: any, b: any) => boolean
+    export interface Recursion {
+      readonly maxDepth: number
+      readonly depthIdentifier: FastCheck.DepthIdentifier | string
     }
 
     /**
-     * fast-check date constraints used when deriving arbitraries for `Date` and
-     * DateTime schemas.
+     * Context passed to arbitrary-derivation hooks and candidate factories.
+     *
+     * **Details**
+     *
+     * `constraint` contains the merged constraint for the current schema
+     * node. `recursion` is present while deriving through a suspended schema;
+     * hooks that build recursive alternatives should pass it to `fc.oneof` with
+     * the finite branch first.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface DateConstraints extends FastCheck.DateConstraints {}
+    export interface Context {
+      readonly constraint?: ToArbitrary.Constraint | undefined
+      readonly recursion?: ToArbitrary.Recursion | undefined
+    }
 
     /**
-     * Grouped arbitrary-generation constraints accumulated from schema checks and
-     * passed to `toArbitrary` derivation.
+     * Arbitrary generators derived for a declaration type parameter.
+     *
+     * **Details**
+     *
+     * `arbitrary` is the normal generator. `terminal` is the finite generator
+     * used while building recursive terminal branches and is `undefined` when
+     * no finite path is known. Optional containers can ignore it; non-empty
+     * containers need it for their terminal branch.
      *
      * @category models
      * @since 4.0.0
      */
-    export interface Constraint {
-      readonly string?: StringConstraints | undefined
-      readonly number?: NumberConstraints | undefined
-      readonly bigint?: BigIntConstraints | undefined
-      readonly array?: ArrayConstraints | undefined
-      readonly date?: DateConstraints | undefined
+    export interface TypeParameter<T> {
+      readonly arbitrary: FastCheck.Arbitrary<T>
+      readonly terminal: FastCheck.Arbitrary<T> | undefined
     }
 
     /**
-     * Context passed to arbitrary-derivation hooks, including accumulated
-     * constraints and an `isSuspend` flag used to limit recursion for suspended
-     * schemas.
+     * Arbitrary derivation returned by declaration hooks.
+     *
+     * **Details**
+     *
+     * `arbitrary` is the normal generator. `terminal` is an optional finite
+     * branch for recursive schemas. If omitted, it defaults to `arbitrary` only
+     * for declarations without type parameters.
      *
      * @category models
-     * @since 3.10.0
+     * @since 4.0.0
      */
-    export interface Context {
-      /**
-       * This flag is set to `true` when the current schema is a suspend. The goal
-       * is to avoid infinite recursion when generating arbitrary values for
-       * suspends, so implementations should try to avoid excessive recursion.
-       */
-      readonly isSuspend?: boolean | undefined
-      readonly constraints?: ToArbitrary.Constraint | undefined
+    export interface Derivation<T> {
+      readonly arbitrary: FastCheck.Arbitrary<T>
+      readonly terminal?: FastCheck.Arbitrary<T> | undefined
     }
 
+    /**
+     * Output accepted from declaration arbitrary hooks.
+     *
+     * **Details**
+     *
+     * A bare fast-check arbitrary is shorthand for `{ arbitrary }`, useful for
+     * atomic declarations such as URLs. Generic declarations that need precise
+     * recursive behavior should return a {@link Derivation} with `terminal`.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export type Output<T> = FastCheck.Arbitrary<T> | Derivation<T>
+
     /**
      * Hook signature for declaration schema arbitrary annotations.
      *
      * **Details**
      *
-     * Given arbitraries for any type parameters, returns a function that receives the
-     * fast-check module and derivation context and produces an arbitrary for `T`.
+     * Type parameters expose normal and terminal generators. A declaration with
+     * no type parameters can return a bare arbitrary; a generic declaration
+     * must return `terminal` explicitly when it has a finite branch depending on
+     * parameters.
      *
      * @category models
      * @since 4.0.0
      */
     export interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
       (
-        /* Arbitraries for any type parameters of the schema (if present) */
-        typeParameters: { readonly [K in keyof TypeParameters]: FastCheck.Arbitrary<TypeParameters[K]["Type"]> }
-      ): (fc: typeof FastCheck, context: Context) => FastCheck.Arbitrary<T>
+        /* Arbitrary derivations for any type parameters of the schema (if present) */
+        typeParameters: { readonly [K in keyof TypeParameters]: TypeParameter<TypeParameters[K]["Type"]> }
+      ): (fc: typeof FastCheck, context: Context) => Output<T>
+    }
+
+    /**
+     * Wraps a derived value together with arbitrary-derivation diagnostics.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export interface WithReport<A> {
+      readonly value: A
+      readonly report: Report
+    }
+
+    /**
+     * Diagnostics collected while deriving an arbitrary.
+     *
+     * **Details**
+     *
+     * Reports contain warnings only. Unsupported schema nodes, impossible
+     * constraints, invalid candidate weights, and throwing candidate factories
+     * fail immediately.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export interface Report {
+      readonly warnings: ReadonlyArray<Warning>
+    }
+
+    /**
+     * Non-fatal arbitrary-derivation warning.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export type Warning = OpaqueFilterWarning
+
+    /**
+     * Warning emitted when a filter is handled only by the final `.filter`.
+     *
+     * **Details**
+     *
+     * The filter is still enforced. The warning means it did not contribute
+     * a constraint or candidate, so generation may rely on fast-check discards.
+     *
+     * @category models
+     * @since 4.0.0
+     */
+    export interface OpaqueFilterWarning {
+      readonly _tag: "OpaqueFilter"
+      readonly path: ReadonlyArray<PropertyKey>
+      readonly description?: string | undefined
     }
   }