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

package/dist/Schema.d.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
  */
@@ -2538,6 +2466,8 @@ export interface encodeKeys<S extends Top & {
  * 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)
  *
@@ -4977,8 +4907,8 @@ export declare function isUncapitalized(annotations?: Annotations.Filter): Schem
  *
  * 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
@@ -5078,9 +5008,9 @@ export declare 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
@@ -5098,7 +5028,7 @@ export declare const isGreaterThan: (exclusiveMinimum: number, annotations?: Ann
  *
  * 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
@@ -5116,8 +5046,8 @@ export declare const isGreaterThanOrEqualTo: (minimum: number, annotations?: Ann
  *
  * 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
@@ -5136,7 +5066,7 @@ export declare const isLessThan: (exclusiveMaximum: number, annotations?: Annota
  *
  * 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
@@ -5156,9 +5086,10 @@ export declare const isLessThanOrEqualTo: (maximum: number, annotations?: Annota
  *
  * 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
@@ -5199,7 +5130,7 @@ export declare const isMultipleOf: (divisor: number, annotations?: Annotations.F
  *
  * 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
@@ -5259,7 +5190,7 @@ export declare function isUint32(annotations?: Annotations.Filter): SchemaAST.Fi
  *
  * 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
@@ -5607,9 +5538,9 @@ export declare function isLengthBetween(minimum: number, maximum: number, annota
  *
  * 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
@@ -5630,9 +5561,9 @@ export declare function isMinSize(minSize: number, annotations?: Annotations.Fil
  *
  * 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
@@ -5653,9 +5584,9 @@ export declare function isMaxSize(maxSize: number, annotations?: Annotations.Fil
  *
  * 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
@@ -5676,10 +5607,9 @@ export declare function isSizeBetween(minimum: number, maximum: number, annotati
  *
  * 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
@@ -5697,10 +5627,9 @@ export declare function isMinProperties(minProperties: number, annotations?: Ann
  *
  * 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
@@ -5719,9 +5648,9 @@ export declare function isMaxProperties(maxProperties: number, annotations?: Ann
  *
  * 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
@@ -5753,8 +5682,9 @@ export declare function isPropertyNames(keySchema: Top, annotations?: Annotation
  * 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
@@ -8501,7 +8431,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
@@ -8511,6 +8444,13 @@ export declare function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary
  * 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
@@ -8530,6 +8470,9 @@ export declare function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary
  * @since 4.0.0
  */
 export declare function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Type"]>;
+export declare function toArbitrary<S extends Top>(schema: S, options: {
+    readonly report: true;
+}): Annotations.ToArbitrary.WithReport<FastCheck.Arbitrary<S["Type"]>>;
 /**
  * Attaches a custom formatter used by `toFormatter`.
  *
@@ -8953,7 +8896,7 @@ export declare function resolveAnnotationsKey<S extends Top>(schema: S): Annotat
  * 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 {
     /**
@@ -8997,7 +8940,7 @@ export declare namespace Annotations {
      * ```
      *
      * @category models
-     * @since 3.10.0
+     * @since 4.0.0
      */
     interface Annotations {
         readonly [x: string]: unknown;
@@ -9119,7 +9062,7 @@ export declare namespace Annotations {
          * values.
          *
          * @category utility types
-         * @since 3.10.0
+         * @since 4.0.0
          */
         type Type<TypeParameters extends ReadonlyArray<Top>> = {
             readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"]>;
@@ -9128,7 +9071,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
          */
         type Encoded<TypeParameters extends ReadonlyArray<Top>> = {
             readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Encoded"]>;
@@ -9168,7 +9111,7 @@ export declare namespace Annotations {
      * Filters are intentionally non-parametric to keep them covariant.
      *
      * @category models
-     * @since 3.10.0
+     * @since 4.0.0
      */
     interface Filter extends Augment {
         /**
@@ -9195,7 +9138,16 @@ export declare namespace Annotations {
          * Optional metadata used to identify or extend the filter with custom data.
          */
         readonly meta?: Meta | undefined;
-        readonly toArbitraryConstraint?: ToArbitrary.Constraint | undefined;
+        /**
+         * 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
          * structure of the container (e.g., array length, object keys) rather than
@@ -9209,105 +9161,244 @@ 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
      */
     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
+         */
+        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
          */
-        interface StringConstraints extends FastCheck.StringSharedConstraints {
-            readonly patterns?: readonly [string, ...Array<string>];
+        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
          */
-        interface NumberConstraints extends FastCheck.FloatConstraints {
-            readonly isInteger?: boolean;
+        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
          */
-        interface BigIntConstraints extends FastCheck.BigIntConstraints {
+        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
          */
-        interface ArrayConstraints extends FastCheck.ArrayConstraints {
-            readonly comparator?: (a: any, b: any) => boolean;
+        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
          */
-        interface DateConstraints extends FastCheck.DateConstraints {
+        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
          */
-        interface Constraint {
-            readonly string?: StringConstraints | undefined;
-            readonly number?: NumberConstraints | undefined;
-            readonly bigint?: BigIntConstraints | undefined;
-            readonly array?: ArrayConstraints | undefined;
-            readonly date?: DateConstraints | undefined;
+        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
          */
-        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;
+        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
+         */
+        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
          */
         interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
             (typeParameters: {
-                readonly [K in keyof TypeParameters]: FastCheck.Arbitrary<TypeParameters[K]["Type"]>;
-            }): (fc: typeof FastCheck, context: Context) => FastCheck.Arbitrary<T>;
+                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
+         */
+        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
+         */
+        interface Report {
+            readonly warnings: ReadonlyArray<Warning>;
+        }
+        /**
+         * Non-fatal arbitrary-derivation warning.
+         *
+         * @category models
+         * @since 4.0.0
+         */
+        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
+         */
+        interface OpaqueFilterWarning {
+            readonly _tag: "OpaqueFilter";
+            readonly path: ReadonlyArray<PropertyKey>;
+            readonly description?: string | undefined;
         }
     }
     /**