effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/Schema.ts

@@ -251,6 +251,8 @@ export interface Bottom<
   check(...checks: readonly [AST.Check<this["Type"]>, ...Array<AST.Check<this["Type"]>>]): this["Rebuild"]
   rebuild(ast: this["ast"]): this["Rebuild"]
   /**
+   * Constructs a value from the make input representation.
+   *
    * @throws {Error} The issue is contained in the error cause.
    */
   make(input: this["~type.make.in"], options?: MakeOptions): this["Type"]
@@ -1137,12 +1139,14 @@ export const asserts = Parser.asserts
  * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link decodeEffect} when
  * the input is already typed as the schema's `Encoded` type.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
-export function decodeUnknownEffect<S extends Top>(schema: S) {
-  const parser = Parser.decodeUnknownEffect(schema)
+export function decodeUnknownEffect<S extends Top>(schema: S, options?: AST.ParseOptions) {
+  const parser = Parser.decodeUnknownEffect(schema, options)
   return (input: unknown, options?: AST.ParseOptions): Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]> => {
     return Effect.mapErrorEager(parser(input, options), (issue) => new SchemaError(issue))
   }
@@ -1153,12 +1157,15 @@ export function decodeUnknownEffect<S extends Top>(schema: S) {
  * returning an `Effect` that succeeds with the decoded value or fails with a
  * {@link SchemaError}. Use this when the input is already typed; for `unknown`
  * input use {@link decodeUnknownEffect}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeEffect: <S extends Top>(
-  schema: S
+  schema: S,
+  options?: AST.ParseOptions
 ) => (input: S["Encoded"], options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]> =
   decodeUnknownEffect
 
@@ -1168,12 +1175,14 @@ export const decodeEffect: <S extends Top>(
  * a {@link SchemaError}. Only usable with schemas that have no
  * `DecodingServices` requirement. Prefer {@link decodeExit} when the input is
  * already typed as the schema's `Encoded` type.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
-export function decodeUnknownExit<S extends Decoder<unknown>>(schema: S) {
-  const parser = Parser.decodeUnknownExit(schema)
+export function decodeUnknownExit<S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) {
+  const parser = Parser.decodeUnknownExit(schema, options)
   return (input: unknown, options?: AST.ParseOptions): Exit_.Exit<S["Type"], SchemaError> => {
     return Exit_.mapError(parser(input, options), (issue) => new SchemaError(issue))
   }
@@ -1185,12 +1194,15 @@ export function decodeUnknownExit<S extends Decoder<unknown>>(schema: S) {
  * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
  * schemas that have no `DecodingServices` requirement. For `unknown` input use
  * {@link decodeUnknownExit}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeExit: <S extends Decoder<unknown>>(
-  schema: S
+  schema: S,
+  options?: AST.ParseOptions
 ) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError> = decodeUnknownExit
 
 /**
@@ -1199,6 +1211,8 @@ export const decodeExit: <S extends Decoder<unknown>>(
  * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
  * need to know whether decoding succeeded and don't need error details. For
  * typed input use {@link decodeOption}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -1209,6 +1223,8 @@ export const decodeUnknownOption = Parser.decodeUnknownOption
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Option` that is `Some` with the decoded value on success or
  * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -1216,10 +1232,11 @@ export const decodeUnknownOption = Parser.decodeUnknownOption
 export const decodeOption = Parser.decodeOption
 
 /**
- * Decodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link decodePromise}.
+ * Decodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the decoded value or fails with a schema issue. For typed input
+ * use {@link decodeResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -1227,12 +1244,25 @@ export const decodeOption = Parser.decodeOption
 export const decodeUnknownResult = Parser.decodeUnknownResult
 
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Result` that succeeds with the decoded value or fails with a
+ * schema issue. For `unknown` input use {@link decodeUnknownResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeResult = Parser.decodeResult
 
 /**
+ * Decodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the decoded value or rejects with a schema issue. Useful for
+ * integrating with Promise-based APIs. For typed input use
+ * {@link decodePromise}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -1241,7 +1271,11 @@ export const decodeUnknownPromise = Parser.decodeUnknownPromise
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning a `Promise` that resolves with the decoded value or rejects with a
- * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ * schema issue. For `unknown` input use `decodeUnknownPromise`.
+ *
+ * **Details**
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -1249,12 +1283,16 @@ export const decodeUnknownPromise = Parser.decodeUnknownPromise
 export const decodePromise = Parser.decodePromise
 
 /**
- * Decodes an `unknown` input against a schema synchronously, throwing a
- * {@link SchemaError} on failure. Use this when you want to validate data at a
- * boundary and treat a schema mismatch as an unrecoverable error. For
- * non-throwing alternatives see {@link decodeUnknownOption},
- * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
- * use {@link decodeSync}.
+ * Decodes an `unknown` input against a schema synchronously, returning the
+ * decoded value or throwing an `Error` whose cause contains the schema issue.
+ * Use this when you want to validate data at a boundary and treat a schema
+ * mismatch as an exception. For typed input use `decodeSync`.
+ *
+ * **Details**
+ * Only service-free schemas can be decoded synchronously. For non-throwing
+ * alternatives see `decodeUnknownOption`, `decodeUnknownExit`, or
+ * `decodeUnknownEffect`. Options may be provided either when creating the
+ * decoder or when applying it; application options override creation options.
  *
  * **Example** (Decoding with a transformation schema)
  *
@@ -1280,8 +1318,13 @@ export const decodeUnknownSync = Parser.decodeUnknownSync
 
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
- * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
- * use {@link decodeUnknownSync}.
+ * synchronously, returning the decoded value or throwing an `Error` whose cause
+ * contains the schema issue. For `unknown` input use `decodeUnknownSync`.
+ *
+ * **Details**
+ * Only service-free schemas can be decoded synchronously. Options may be
+ * provided either when creating the decoder or when applying it; application
+ * options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -1293,6 +1336,8 @@ export const decodeSync = Parser.decodeSync
  * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link encodeEffect} when
  * the input is already typed as the schema's `Type`.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * **Example** (Encoding a value to a string)
  *
@@ -1308,8 +1353,8 @@ export const decodeSync = Parser.decodeSync
  * @category Encoding
  * @since 4.0.0
  */
-export function encodeUnknownEffect<S extends Top>(schema: S) {
-  const parser = Parser.encodeUnknownEffect(schema)
+export function encodeUnknownEffect<S extends Top>(schema: S, options?: AST.ParseOptions) {
+  const parser = Parser.encodeUnknownEffect(schema, options)
   return (
     input: unknown,
     options?: AST.ParseOptions
@@ -1323,12 +1368,15 @@ export function encodeUnknownEffect<S extends Top>(schema: S) {
  * `Effect` that succeeds with the encoded value or fails with a
  * {@link SchemaError}. Use this when the input is already typed; for `unknown`
  * input use {@link encodeUnknownEffect}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeEffect: <S extends Top>(
-  schema: S
+  schema: S,
+  options?: AST.ParseOptions
 ) => (input: S["Type"], options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]> =
   encodeUnknownEffect
 
@@ -1338,12 +1386,14 @@ export const encodeEffect: <S extends Top>(
  * a {@link SchemaError}. Only usable with schemas that have no
  * `EncodingServices` requirement. Prefer {@link encodeExit} when the input is
  * already typed as the schema's `Type`.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
-export function encodeUnknownExit<S extends Encoder<unknown>>(schema: S) {
-  const parser = Parser.encodeUnknownExit(schema)
+export function encodeUnknownExit<S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) {
+  const parser = Parser.encodeUnknownExit(schema, options)
   return (input: unknown, options?: AST.ParseOptions): Exit_.Exit<S["Encoded"], SchemaError> => {
     return Exit_.mapError(parser(input, options), (issue) => new SchemaError(issue))
   }
@@ -1355,12 +1405,15 @@ export function encodeUnknownExit<S extends Encoder<unknown>>(schema: S) {
  * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
  * `EncodingServices` requirement. For `unknown` input use
  * {@link encodeUnknownExit}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeExit: <S extends Encoder<unknown>>(
-  schema: S
+  schema: S,
+  options?: AST.ParseOptions
 ) => (input: S["Type"], options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError> = encodeUnknownExit
 
 /**
@@ -1369,6 +1422,8 @@ export const encodeExit: <S extends Encoder<unknown>>(
  * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
  * need to know whether encoding succeeded and don't need error details. For
  * typed input use {@link encodeOption}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1379,6 +1434,8 @@ export const encodeUnknownOption = Parser.encodeUnknownOption
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `Option` that is `Some` with the encoded value on success or `None` on
  * failure. For `unknown` input use {@link encodeUnknownOption}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1386,10 +1443,11 @@ export const encodeUnknownOption = Parser.encodeUnknownOption
 export const encodeOption = Parser.encodeOption
 
 /**
- * Encodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link encodePromise}.
+ * Encodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the encoded value or fails with a schema issue. For typed input
+ * use {@link encodeResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1397,12 +1455,25 @@ export const encodeOption = Parser.encodeOption
 export const encodeUnknownResult = Parser.encodeUnknownResult
 
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Result` that succeeds with the encoded value or fails with a schema issue.
+ * For `unknown` input use {@link encodeUnknownResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeResult = Parser.encodeResult
 
 /**
+ * Encodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the encoded value or rejects with a schema issue. Useful for
+ * integrating with Promise-based APIs. For typed input use
+ * {@link encodePromise}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -1412,6 +1483,8 @@ export const encodeUnknownPromise = Parser.encodeUnknownPromise
  * Encodes a typed input (the schema's `Type`) against a schema, returning a
  * `Promise` that resolves with the encoded value or rejects with a
  * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1425,6 +1498,8 @@ export const encodePromise = Parser.encodePromise
  * non-throwing alternatives see {@link encodeUnknownOption},
  * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
  * use {@link encodeSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1435,6 +1510,8 @@ export const encodeUnknownSync = Parser.encodeUnknownSync
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
  * throwing a {@link SchemaError} on failure. For `unknown` input use
  * {@link encodeUnknownSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1860,6 +1937,12 @@ export function Literal<L extends AST.LiteralValue>(literal: L): Literal<L> {
  */
 export declare namespace TemplateLiteral {
   /**
+   * Constraint for schema parts that can appear inside a `TemplateLiteral`.
+   *
+   * **Details**
+   * The schema's encoded value must be a `string`, `number`, or `bigint` so it can
+   * be converted into a template literal string segment.
+   *
    * @since 4.0.0
    */
   export interface SchemaPart extends Top {
@@ -1867,16 +1950,23 @@ export declare namespace TemplateLiteral {
   }
 
   /**
+   * Literal value that can be used directly as a part of a `TemplateLiteral`.
+   *
    * @since 4.0.0
    */
   export type LiteralPart = string | number | bigint
 
   /**
+   * A single part of a `TemplateLiteral`, either an interpolated schema part or a
+   * literal `string`, `number`, or `bigint`.
+   *
    * @since 4.0.0
    */
   export type Part = SchemaPart | LiteralPart
 
   /**
+   * Ordered list of parts used to construct a `TemplateLiteral` schema.
+   *
    * @since 4.0.0
    */
   export type Parts = ReadonlyArray<Part>
@@ -1889,6 +1979,9 @@ export declare namespace TemplateLiteral {
     : never
 
   /**
+   * Computes the encoded string literal type produced by concatenating the encoded
+   * forms of all template literal parts.
+   *
    * @since 4.0.0
    */
   export type Encoded<Parts> = Parts extends readonly [...infer Init, infer Last] ? AppendType<Encoded<Init>, Last>
@@ -1945,6 +2038,12 @@ export function TemplateLiteral<const Parts extends TemplateLiteral.Parts>(parts
  */
 export declare namespace TemplateLiteralParser {
   /**
+   * Computes the decoded tuple type produced by `TemplateLiteralParser`.
+   *
+   * **Details**
+   * Literal parts contribute their literal value to the tuple. Schema parts
+   * contribute their decoded `Type`.
+   *
    * @since 4.0.0
    */
   export type Type<Parts> = Parts extends readonly [infer Head, ...infer Tail] ? readonly [
@@ -1998,8 +2097,8 @@ export function TemplateLiteralParser<const Parts extends TemplateLiteral.Parts>
 }
 
 /**
- * Represents a schema derived from a TypeScript `const enum` or a plain enum object,
- * accepting any of its values.
+ * Represents a schema derived from a TypeScript enum object or an enum-like
+ * `as const` object, accepting any of its values.
  *
  * @see {@link Enum} for the constructor function.
  * @since 4.0.0
@@ -2298,12 +2397,18 @@ export declare namespace Struct {
     O extends keyof F = TypeOptionalKeys<F>,
     M extends keyof F = TypeMutableKeys<F>
   > =
-    & { readonly [K in Exclude<keyof F, M | O>]: F[K]["Type"] }
-    & { readonly [K in Exclude<O, M>]?: F[K]["Type"] }
-    & { [K in Exclude<M, O>]: F[K]["Type"] }
-    & { [K in M & O]?: F[K]["Type"] }
+    & { readonly [K in keyof F as K extends M | O ? never : K]: F[K]["Type"] }
+    & { readonly [K in keyof F as K extends O ? K extends M ? never : K : never]?: F[K]["Type"] }
+    & { -readonly [K in keyof F as K extends M ? K extends O ? never : K : never]: F[K]["Type"] }
+    & { -readonly [K in keyof F as K extends M & O ? K : never]?: F[K]["Type"] }
 
   /**
+   * Computes the decoded object type for a struct field map.
+   *
+   * **Details**
+   * Field schemas contribute their decoded `Type`. `optionalKey` and `optional`
+   * produce optional properties, while `mutableKey` produces writable properties.
+   *
    * @since 4.0.0
    */
   export type Type<F extends Fields> = Simplify<Type_<F>>
@@ -2313,12 +2418,19 @@ export declare namespace Struct {
     O extends keyof F = TypeOptionalKeys<F>,
     M extends keyof F = TypeMutableKeys<F>
   > =
-    & { readonly [K in Exclude<keyof F, M | O>]: F[K]["Iso"] }
-    & { readonly [K in Exclude<O, M>]?: F[K]["Iso"] }
-    & { [K in Exclude<M, O>]: F[K]["Iso"] }
-    & { [K in M & O]?: F[K]["Iso"] }
+    & { readonly [K in keyof F as K extends M | O ? never : K]: F[K]["Iso"] }
+    & { readonly [K in keyof F as K extends O ? K extends M ? never : K : never]?: F[K]["Iso"] }
+    & { -readonly [K in keyof F as K extends M ? K extends O ? never : K : never]: F[K]["Iso"] }
+    & { -readonly [K in keyof F as K extends M & O ? K : never]?: F[K]["Iso"] }
 
   /**
+   * Computes the iso object type for a struct field map from each field schema's
+   * `Iso` type.
+   *
+   * **Details**
+   * The resulting property optionality and mutability follow the same field
+   * modifiers used by `Struct.Type`.
+   *
    * @since 4.0.0
    */
   export type Iso<F extends Fields> = Simplify<Iso_<F>>
@@ -2338,22 +2450,35 @@ export declare namespace Struct {
     O extends keyof F = EncodedOptionalKeys<F>,
     M extends keyof F = EncodedMutableKeys<F>
   > =
-    & { readonly [K in Exclude<keyof F, M | O>]: F[K]["Encoded"] }
-    & { readonly [K in Exclude<O, M>]?: F[K]["Encoded"] }
-    & { [K in Exclude<M, O>]: F[K]["Encoded"] }
-    & { [K in M & O]?: F[K]["Encoded"] }
+    & { readonly [K in keyof F as K extends M | O ? never : K]: F[K]["Encoded"] }
+    & { readonly [K in keyof F as K extends O ? K extends M ? never : K : never]?: F[K]["Encoded"] }
+    & { -readonly [K in keyof F as K extends M ? K extends O ? never : K : never]: F[K]["Encoded"] }
+    & { -readonly [K in keyof F as K extends M & O ? K : never]?: F[K]["Encoded"] }
 
   /**
+   * Computes the encoded object type for a struct field map.
+   *
+   * **Details**
+   * Field schemas contribute their `Encoded` type. Encoded-side optionality and
+   * mutability modifiers determine whether properties are optional or writable in
+   * the encoded shape.
+   *
    * @since 4.0.0
    */
   export type Encoded<F extends Fields> = Simplify<Encoded_<F>>
 
   /**
+   * Union of all decoding service requirements needed by the schemas in a struct
+   * field map.
+   *
    * @since 4.0.0
    */
   export type DecodingServices<F extends Fields> = { readonly [K in keyof F]: F[K]["DecodingServices"] }[keyof F]
 
   /**
+   * Union of all encoding service requirements needed by the schemas in a struct
+   * field map.
+   *
    * @since 4.0.0
    */
   export type EncodingServices<F extends Fields> = { readonly [K in keyof F]: F[K]["EncodingServices"] }[keyof F]
@@ -2371,12 +2496,25 @@ export declare namespace Struct {
     & { readonly [K in keyof F as K extends O ? K : never]?: F[K]["~type.make"] }
 
   /**
+   * Computes the input object type accepted when constructing a struct value.
+   *
+   * **Details**
+   * Required fields use each field schema's `~type.make` input. Fields marked
+   * optional or with a constructor default may be omitted.
+   *
    * @since 4.0.0
    */
   export type MakeIn<F extends Fields> = Simplify<MakeIn_<F>>
 }
 
 /**
+ * Schema type returned by `Schema.Struct` for an object with a fixed set of
+ * schema-defined fields.
+ *
+ * **Details**
+ * The `fields` property exposes the original field map for reuse, and
+ * `mapFields` creates a new struct schema by transforming that field map.
+ *
  * @since 4.0.0
  */
 export interface Struct<Fields extends Struct.Fields> extends
@@ -2666,6 +2804,12 @@ export function extendTo<S extends Struct<Struct.Fields>, const Fields extends S
  */
 export declare namespace Record {
   /**
+   * Constraint for schemas that can be used as record keys.
+   *
+   * **Details**
+   * The key schema must decode and encode property keys (`string`, `number`, or
+   * `symbol`) so it can describe object property names.
+   *
    * @since 4.0.0
    */
   export interface Key extends Codec<PropertyKey, PropertyKey, unknown, unknown> {
@@ -2674,6 +2818,14 @@ export declare namespace Record {
   }
 
   /**
+   * Computes the decoded object type for a record schema from its key and value
+   * schemas.
+   *
+   * **Details**
+   * The key schema supplies the property keys and the value schema supplies each
+   * property's decoded `Type`. Optional and mutable value schemas affect the
+   * resulting property optionality and writability.
+   *
    * @since 4.0.0
    */
   export type Type<Key extends Record.Key, Value extends Top> = Value extends
@@ -2684,6 +2836,9 @@ export declare namespace Record {
     : { readonly [P in Key["Type"]]: Value["Type"] }
 
   /**
+   * Computes the iso object type for a record schema from the key schema's `Iso`
+   * keys and the value schema's `Iso` values.
+   *
    * @since 4.0.0
    */
   export type Iso<Key extends Record.Key, Value extends Top> = Value extends
@@ -2694,6 +2849,13 @@ export declare namespace Record {
     : { readonly [P in Key["Iso"]]: Value["Iso"] }
 
   /**
+   * Computes the encoded object type for a record schema from the key and value
+   * schemas' encoded types.
+   *
+   * **Details**
+   * Encoded-side optionality and mutability on the value schema determine whether
+   * the encoded record properties are optional or writable.
+   *
    * @since 4.0.0
    */
   export type Encoded<Key extends Record.Key, Value extends Top> = Value extends
@@ -2704,6 +2866,9 @@ export declare namespace Record {
     : { readonly [P in Key["Encoded"]]: Value["Encoded"] }
 
   /**
+   * Union of the decoding service requirements of a record's key schema and value
+   * schema.
+   *
    * @since 4.0.0
    */
   export type DecodingServices<Key extends Record.Key, Value extends Top> =
@@ -2711,6 +2876,9 @@ export declare namespace Record {
     | Value["DecodingServices"]
 
   /**
+   * Union of the encoding service requirements of a record's key schema and value
+   * schema.
+   *
    * @since 4.0.0
    */
   export type EncodingServices<Key extends Record.Key, Value extends Top> =
@@ -2718,6 +2886,13 @@ export declare namespace Record {
     | Value["EncodingServices"]
 
   /**
+   * Computes the input object type accepted when constructing a record value.
+   *
+   * **Details**
+   * Keys use the key schema's `~type.make` type and values use the value schema's
+   * `~type.make` type. Value optionality and mutability determine whether
+   * properties are optional or writable.
+   *
    * @since 4.0.0
    */
   export type MakeIn<Key extends Record.Key, Value extends Top> = Value extends
@@ -2797,11 +2972,17 @@ export function Record<Key extends Record.Key, Value extends Top>(
  */
 export declare namespace StructWithRest {
   /**
+   * Constraint for object-like schemas that can be used as the fixed portion of a
+   * `StructWithRest` schema.
+   *
    * @since 4.0.0
    */
   export type Objects = Top & { readonly ast: AST.Objects }
 
   /**
+   * Readonly list of record schemas that provide the additional index signatures
+   * for a `StructWithRest` schema.
+   *
    * @since 4.0.0
    */
   export type Records = ReadonlyArray<$Record<Record.Key, Top>>
@@ -2811,6 +2992,9 @@ export declare namespace StructWithRest {
     : {}
 
   /**
+   * Computes the decoded type for `StructWithRest` by intersecting the base object
+   * schema's decoded `Type` with the decoded types of all rest record schemas.
+   *
    * @since 4.0.0
    */
   export type Type<S extends Objects, Records extends StructWithRest.Records> =
@@ -2818,6 +3002,9 @@ export declare namespace StructWithRest {
     & MergeTuple<{ readonly [K in keyof Records]: Records[K]["Type"] }>
 
   /**
+   * Computes the iso type for `StructWithRest` by intersecting the base object
+   * schema's `Iso` type with the `Iso` types of all rest record schemas.
+   *
    * @since 4.0.0
    */
   export type Iso<S extends Objects, Records extends StructWithRest.Records> =
@@ -2825,6 +3012,9 @@ export declare namespace StructWithRest {
     & MergeTuple<{ readonly [K in keyof Records]: Records[K]["Iso"] }>
 
   /**
+   * Computes the encoded type for `StructWithRest` by intersecting the base object
+   * schema's encoded type with the encoded types of all rest record schemas.
+   *
    * @since 4.0.0
    */
   export type Encoded<S extends Objects, Records extends StructWithRest.Records> =
@@ -2832,6 +3022,9 @@ export declare namespace StructWithRest {
     & MergeTuple<{ readonly [K in keyof Records]: Records[K]["Encoded"] }>
 
   /**
+   * Union of the decoding service requirements of the base object schema and all
+   * rest record schemas.
+   *
    * @since 4.0.0
    */
   export type DecodingServices<S extends Objects, Records extends StructWithRest.Records> =
@@ -2839,6 +3032,9 @@ export declare namespace StructWithRest {
     | { [K in keyof Records]: Records[K]["DecodingServices"] }[number]
 
   /**
+   * Union of the encoding service requirements of the base object schema and all
+   * rest record schemas.
+   *
    * @since 4.0.0
    */
   export type EncodingServices<S extends Objects, Records extends StructWithRest.Records> =
@@ -2846,6 +3042,10 @@ export declare namespace StructWithRest {
     | { [K in keyof Records]: Records[K]["EncodingServices"] }[number]
 
   /**
+   * Computes the input type accepted when constructing a `StructWithRest` value by
+   * intersecting the base object's make input with the make inputs of all rest
+   * record schemas.
+   *
    * @since 4.0.0
    */
   export type MakeIn<S extends Objects, Records extends StructWithRest.Records> =
@@ -2921,6 +3121,9 @@ export function StructWithRest<
  */
 export declare namespace Tuple {
   /**
+   * Constraint for the readonly array of element schemas used to define a
+   * fixed-length `Tuple` schema.
+   *
    * @since 4.0.0
    */
   export type Elements = ReadonlyArray<Top>
@@ -2936,6 +3139,12 @@ export declare namespace Tuple {
     : Out
 
   /**
+   * Computes the decoded tuple type for a tuple element schema array.
+   *
+   * **Details**
+   * Each element contributes its decoded `Type`; optional element schemas produce
+   * optional tuple positions.
+   *
    * @since 4.0.0
    */
   export type Type<E extends Elements> = Type_<E>
@@ -2951,6 +3160,9 @@ export declare namespace Tuple {
     : Out
 
   /**
+   * Computes the iso tuple type for a tuple element schema array from each
+   * element schema's `Iso` type.
+   *
    * @since 4.0.0
    */
   export type Iso<E extends Elements> = Iso_<E>
@@ -2966,16 +3178,28 @@ export declare namespace Tuple {
     : Out
 
   /**
+   * Computes the encoded tuple type for a tuple element schema array.
+   *
+   * **Details**
+   * Each element contributes its `Encoded` type; encoded-side optional element
+   * schemas produce optional tuple positions.
+   *
    * @since 4.0.0
    */
   export type Encoded<E extends Elements> = Encoded_<E>
 
   /**
+   * Union of all decoding service requirements needed by the tuple element
+   * schemas.
+   *
    * @since 4.0.0
    */
   export type DecodingServices<E extends Elements> = E[number]["DecodingServices"]
 
   /**
+   * Union of all encoding service requirements needed by the tuple element
+   * schemas.
+   *
    * @since 4.0.0
    */
   export type EncodingServices<E extends Elements> = E[number]["EncodingServices"]
@@ -2993,6 +3217,12 @@ export declare namespace Tuple {
     Out
 
   /**
+   * Computes the input tuple type accepted when constructing a tuple value.
+   *
+   * **Details**
+   * Each element uses its `~type.make` input type. Optional elements and elements
+   * with constructor defaults produce optional tuple positions.
+   *
    * @since 4.0.0
    */
   export type MakeIn<E extends Elements> = MakeIn_<E>
@@ -3088,6 +3318,9 @@ export function Tuple<const Elements extends ReadonlyArray<Top>>(elements: Eleme
  */
 export declare namespace TupleWithRest {
   /**
+   * Constraint for tuple-like schemas that can be used as the fixed leading
+   * portion of a `TupleWithRest` schema.
+   *
    * @since 4.0.0
    */
   export type TupleType = Top & {
@@ -3099,11 +3332,24 @@ export declare namespace TupleWithRest {
   }
 
   /**
+   * Non-empty list of schemas used for the rest portion of a `TupleWithRest`.
+   *
+   * **Details**
+   * The first schema describes the repeated rest element. Additional schemas, when
+   * present, describe trailing tuple elements after the repeated rest segment.
+   *
    * @since 4.0.0
    */
   export type Rest = readonly [Top, ...Array<Top>]
 
   /**
+   * Computes the decoded tuple type for a `TupleWithRest`.
+   *
+   * **Details**
+   * The output starts with the fixed tuple elements, continues with zero or more
+   * values decoded by the first rest schema, and includes any trailing rest schemas
+   * as fixed tuple positions.
+   *
    * @since 4.0.0
    */
   export type Type<T extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends
@@ -3115,6 +3361,13 @@ export declare namespace TupleWithRest {
     T
 
   /**
+   * Computes the iso tuple type for a `TupleWithRest`.
+   *
+   * **Details**
+   * The output starts with the fixed tuple's `Iso` elements, continues with zero
+   * or more values using the first rest schema's `Iso`, and includes any trailing
+   * rest schemas as fixed tuple positions.
+   *
    * @since 4.0.0
    */
   export type Iso<T extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends
@@ -3126,6 +3379,13 @@ export declare namespace TupleWithRest {
     T
 
   /**
+   * Computes the encoded tuple type for `TupleWithRest`.
+   *
+   * **Details**
+   * The leading tuple's encoded elements are kept first. The encoded type of the
+   * first rest schema may repeat zero or more times, and the encoded types of any
+   * additional rest schemas become required trailing tuple elements.
+   *
    * @since 4.0.0
    */
   export type Encoded<E extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends
@@ -3137,6 +3397,13 @@ export declare namespace TupleWithRest {
     E
 
   /**
+   * Computes the constructor input tuple type for `TupleWithRest`.
+   *
+   * **Details**
+   * The leading tuple's make input elements are kept first. The make input type of
+   * the first rest schema may repeat zero or more times, and the make input types
+   * of any additional rest schemas become required trailing tuple elements.
+   *
    * @since 4.0.0
    */
   export type MakeIn<M extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends
@@ -3174,9 +3441,14 @@ export interface TupleWithRest<
 }
 
 /**
- * Extends a fixed-length tuple schema with rest elements, creating a variadic
- * tuple that starts with the fixed elements and ends with zero or more rest
- * elements.
+ * Extends a fixed-length tuple schema with a variadic rest segment.
+ *
+ * **Details**
+ * The resulting tuple starts with the fixed elements from `schema`. The first
+ * schema in `rest` is the repeatable element schema, and any additional schemas
+ * in `rest` are required trailing tuple elements after the variadic segment. For
+ * example, `[Schema.Boolean, Schema.String]` represents zero or more booleans
+ * followed by a final string.
  *
  * **Example** (Tuple with rest)
  *
@@ -3205,7 +3477,12 @@ export function TupleWithRest<S extends Tuple<Tuple.Elements>, const Rest extend
 }
 
 /**
- * Companion type for a `ReadonlyArray`. Produced by {@link ArraySchema}.
+ * Schema interface produced by `Schema.Array` for readonly arrays.
+ *
+ * **Details**
+ * The decoded type is `ReadonlyArray<S["Type"]>`, the encoded type is
+ * `ReadonlyArray<S["Encoded"]>`, and the element schema is available as
+ * `schema`.
  *
  * @since 4.0.0
  */
@@ -3305,6 +3582,13 @@ export const NonEmptyArray = Struct_.lambda<NonEmptyArrayLambda>((schema) =>
 )
 
 /**
+ * Schema interface returned by `ArrayEnsure`, which normalizes a single item or
+ * an array of items into a readonly array.
+ *
+ * **Details**
+ * The schema decodes from `S` or `Schema.Array(S)` and produces
+ * `ReadonlyArray<S["Type"]>`.
+ *
  * @category Arrays
  * @since 4.0.0
  */
@@ -3313,15 +3597,16 @@ export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>,
 }
 
 /**
- * Decodes a single value or an array of values into an array.
+ * Creates a schema that accepts either a value decoded by `schema` or an array
+ * decoded by `Schema.Array(schema)`, then returns an array.
  *
- * Decoding:
- * - a single value is decoded as a one-element array
- * - an array is decoded as-is
+ * **Details**
+ * The single-value branch is tried before the array branch. If `schema` itself
+ * accepts arrays, an array input can be treated as one value and wrapped in a
+ * one-element array.
  *
- * Encoding:
- * - a one-element array is encoded as a single value
- * - arrays with more than one element are encoded as arrays
+ * During encoding, one-element arrays are encoded as the single element. Empty
+ * arrays and arrays with two or more elements are encoded as arrays.
  *
  * @category Arrays
  * @since 4.0.0
@@ -3731,6 +4016,12 @@ export interface refine<T extends S["Type"], S extends Top> extends
  * Narrows the TypeScript type of a schema's output via a type guard predicate,
  * attaching the guard as a runtime filter check.
  *
+ * The `annotations` parameter annotates the filter created by the refinement.
+ * With the default formatter, failed refinements use `message` first,
+ * `expected` second, and `<filter>` when neither is provided. `identifier`
+ * names type-level failures before the refinement runs; it does not name the
+ * failed refinement itself.
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -3997,10 +4288,13 @@ export function catchEncodingWithContext<S extends Top, R = never>(
 }
 
 /**
- * The type produced by {@link decodeTo} when a custom transformation is provided.
+ * Schema type produced by `decodeTo` when a custom transformation composes a
+ * `From` schema with a `To` schema.
  *
- * - `Type` is `To["Type"]`, `Encoded` is `From["Encoded"]`
- * - Decoding services from both `from` and `to` are combined
+ * **Details**
+ * `Type` is `To["Type"]` and `Encoded` is `From["Encoded"]`. Decoding services
+ * are `To["DecodingServices"] | From["DecodingServices"] | RD`; encoding
+ * services are `To["EncodingServices"] | From["EncodingServices"] | RE`.
  *
  * @see {@link compose} for the passthrough (no transformation) variant
  * @since 4.0.0
@@ -4246,7 +4540,14 @@ export interface WithoutConstructorDefault {
 }
 
 /**
- * The type produced by {@link withConstructorDefault} — a schema with `"~type.constructor.default": "with-default"`.
+ * Schema type returned by `withConstructorDefault` after attaching a default used
+ * by constructor helpers.
+ *
+ * **Details**
+ * The default affects `make` and related constructor helpers only; decoding and
+ * encoding still use the original schema behavior. The schema is marked as
+ * already having a constructor default so another constructor default cannot be
+ * added.
  *
  * @see {@link withConstructorDefault} for the constructor
  * @since 4.0.0
@@ -4300,10 +4601,10 @@ export interface withConstructorDefault<S extends Top & WithoutConstructorDefaul
 export function withConstructorDefault<S extends Top & WithoutConstructorDefault>(
   // `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
   // it makes easier to define the default value if there are nested defaults
-  defaultValue: Effect.Effect<S["~type.make.in"]>
+  defaultValue: Effect.Effect<S["~type.make.in"], SchemaError>
 ) {
   return (schema: S): withConstructorDefault<S> =>
-    make(AST.withConstructorDefault(schema.ast, defaultValue), { schema })
+    make(AST.withConstructorDefault(schema.ast, Effect.mapErrorEager(defaultValue, (e) => e.issue)), { schema })
 }
 
 /**
@@ -4313,8 +4614,8 @@ export function withConstructorDefault<S extends Top & WithoutConstructorDefault
  * @see {@link withDecodingDefaultKey} for the constructor
  * @since 4.0.0
  */
-export interface withDecodingDefaultKey<S extends Top> extends decodeTo<S, optionalKey<toEncoded<S>>> {
-  readonly "Rebuild": withDecodingDefaultKey<S>
+export interface withDecodingDefaultKey<S extends Top, R = never> extends decodeTo<S, optionalKey<toEncoded<S>>, R> {
+  readonly "Rebuild": withDecodingDefaultKey<S, R>
 }
 
 /**
@@ -4361,14 +4662,14 @@ export type DecodingDefaultOptions = {
  * @see {@link withDecodingDefaultTypeKey} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
-export function withDecodingDefaultKey<S extends Top>(
-  defaultValue: Effect.Effect<S["Encoded"]>,
+export function withDecodingDefaultKey<S extends Top, R = never>(
+  defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>,
   options?: DecodingDefaultOptions
 ) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough()
-  return (self: S): withDecodingDefaultKey<S> => {
+  return (self: S): withDecodingDefaultKey<S, R> => {
     return optionalKey(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, (e) => e.issue)),
       encode
     }))
   }
@@ -4382,10 +4683,10 @@ export function withDecodingDefaultKey<S extends Top>(
  * @see {@link withDecodingDefaultTypeKey} for the constructor
  * @since 4.0.0
  */
-export interface withDecodingDefaultTypeKey<S extends Top>
-  extends decodeTo<withDecodingDefaultKey<toType<S>>, optionalKey<S>>
+export interface withDecodingDefaultTypeKey<S extends Top, R = never>
+  extends decodeTo<withDecodingDefaultKey<toType<S>, R>, optionalKey<S>>
 {
-  readonly "Rebuild": withDecodingDefaultTypeKey<S>
+  readonly "Rebuild": withDecodingDefaultTypeKey<S, R>
 }
 
 /**
@@ -4407,13 +4708,13 @@ export interface withDecodingDefaultTypeKey<S extends Top>
  * @see {@link withDecodingDefaultType} for the value-level variant
  * @since 4.0.0
  */
-export function withDecodingDefaultTypeKey<S extends Top>(
-  defaultValue: Effect.Effect<S["Type"]>,
+export function withDecodingDefaultTypeKey<S extends Top, R = never>(
+  defaultValue: Effect.Effect<S["Type"], SchemaError, R>,
   options?: DecodingDefaultOptions
 ) {
-  return (self: S): withDecodingDefaultTypeKey<S> => {
+  return (self: S): withDecodingDefaultTypeKey<S, R> => {
     return toType(self).pipe(
-      withDecodingDefaultKey<toType<S>>(defaultValue, options),
+      withDecodingDefaultKey<toType<S>, R>(defaultValue, options),
       encodeTo(optionalKey(self))
     )
   }
@@ -4426,8 +4727,8 @@ export function withDecodingDefaultTypeKey<S extends Top>(
  * @see {@link withDecodingDefault} for the constructor
  * @since 4.0.0
  */
-export interface withDecodingDefault<S extends Top> extends decodeTo<S, optional<toEncoded<S>>> {
-  readonly "Rebuild": withDecodingDefault<S>
+export interface withDecodingDefault<S extends Top, R = never> extends decodeTo<S, optional<toEncoded<S>>, R> {
+  readonly "Rebuild": withDecodingDefault<S, R>
 }
 
 /**
@@ -4461,14 +4762,14 @@ export interface withDecodingDefault<S extends Top> extends decodeTo<S, optional
  * @see {@link withDecodingDefaultType} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
-export function withDecodingDefault<S extends Top>(
-  defaultValue: Effect.Effect<S["Encoded"]>,
+export function withDecodingDefault<S extends Top, R = never>(
+  defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>,
   options?: DecodingDefaultOptions
 ) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough()
-  return (self: S): withDecodingDefault<S> => {
+  return (self: S): withDecodingDefault<S, R> => {
     return optional(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, (e) => e.issue)),
       encode
     }))
   }
@@ -4482,8 +4783,10 @@ export function withDecodingDefault<S extends Top>(
  * @see {@link withDecodingDefaultType} for the constructor
  * @since 4.0.0
  */
-export interface withDecodingDefaultType<S extends Top> extends decodeTo<withDecodingDefault<toType<S>>, optional<S>> {
-  readonly "Rebuild": withDecodingDefaultType<S>
+export interface withDecodingDefaultType<S extends Top, R = never>
+  extends decodeTo<withDecodingDefault<toType<S>, R>, optional<S>>
+{
+  readonly "Rebuild": withDecodingDefaultType<S, R>
 }
 
 /**
@@ -4505,13 +4808,13 @@ export interface withDecodingDefaultType<S extends Top> extends decodeTo<withDec
  * @see {@link withDecodingDefaultTypeKey} for the key-level variant
  * @since 4.0.0
  */
-export function withDecodingDefaultType<S extends Top>(
-  defaultValue: Effect.Effect<S["Type"]>,
+export function withDecodingDefaultType<S extends Top, R = never>(
+  defaultValue: Effect.Effect<S["Type"], SchemaError, R>,
   options?: DecodingDefaultOptions
 ) {
-  return (self: S): withDecodingDefaultType<S> => {
+  return (self: S): withDecodingDefaultType<S, R> => {
     return toType(self).pipe(
-      withDecodingDefault<toType<S>>(defaultValue, options),
+      withDecodingDefault<toType<S>, R>(defaultValue, options),
       encodeTo(optional(self))
     )
   }
@@ -4953,9 +5256,17 @@ export function link<T>() {
 // -----------------------------------------------------------------------------
 
 /**
- * Creates a custom filter check from a predicate function. The predicate
- * receives the input value, the schema's AST, and parse options, and returns
- * a value of type {@link FilterOutput}.
+ * Creates a custom validation filter from a predicate function.
+ *
+ * **Details**
+ * The predicate receives the decoded input value, the schema AST, and parse
+ * options, and returns a `FilterOutput`. Non-success outputs are normalized into
+ * schema issues. The `annotations` parameter annotates the filter itself; with
+ * the default formatter, failures use `message` first, `expected` second, and
+ * `<filter>` when neither is provided.
+ *
+ * When `abort` is `true`, parsing stops after this filter fails instead of
+ * collecting later check failures.
  *
  * **Example** (Failure at a nested path)
  *
@@ -5143,17 +5454,17 @@ export const isPattern: (regExp: globalThis.RegExp, annotations?: Annotations.Fi
 export const isStringFinite: (annotations?: Annotations.Filter) => AST.Filter<string> = AST.isStringFinite
 
 /**
- * Validates that a string represents a valid BigInt (can be parsed as a BigInt).
+ * Validates that a string is a signed base-10 integer literal for Effect's
+ * BigInt string encoding.
  *
- * **JSON Schema**
+ * **Details**
+ * The check uses the pattern `^-?\d+$`. It does not accept leading `+`, decimal
+ * points, exponent notation, separators, or non-decimal inputs such as
+ * hexadecimal strings.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing BigInt values.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the BigInt string pattern.
+ * **JSON Schema**
+ * This check corresponds to a `pattern` constraint with the same signed
+ * base-10 integer pattern.
  *
  * @category String checks
  * @since 4.0.0
@@ -5161,17 +5472,12 @@ export const isStringFinite: (annotations?: Annotations.Filter) => AST.Filter<st
 export const isStringBigInt: (annotations?: Annotations.Filter) => AST.Filter<string> = AST.isStringBigInt
 
 /**
- * Validates that a string represents a valid Symbol (can be parsed as a Symbol).
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing Symbol values.
- *
- * **Arbitrary**
+ * Validates that a string has the `Symbol(description)` format used by Effect's
+ * symbol string encoding.
  *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the Symbol string pattern.
+ * **Details**
+ * The check uses the pattern `^Symbol\((.*)\)$`. It is not a general test for
+ * whether a string can be passed to JavaScript's `Symbol()` function.
  *
  * @category String checks
  * @since 4.0.0
@@ -5321,17 +5627,12 @@ export function isBase64Url(annotations?: Annotations.Filter) {
 }
 
 /**
- * Validates that a string starts with the specified prefix.
+ * Validates at runtime that a string starts with the specified literal prefix.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings starting with the specified prefix.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings start with the required prefix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `^${startsWith}` without
+ * escaping regexp metacharacters. If the prefix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `startsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -5358,17 +5659,12 @@ export function isStartsWith(startsWith: string, annotations?: Annotations.Filte
 }
 
 /**
- * Validates that a string ends with the specified suffix.
+ * Validates at runtime that a string ends with the specified literal suffix.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings ending with the specified suffix.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings end with the required suffix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `${endsWith}$` without
+ * escaping regexp metacharacters. If the suffix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `endsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -5395,17 +5691,12 @@ export function isEndsWith(endsWith: string, annotations?: Annotations.Filter) {
 }
 
 /**
- * Validates that a string contains the specified substring.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings containing the specified substring.
- *
- * **Arbitrary**
+ * Validates at runtime that a string contains the specified literal substring.
  *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain the required substring.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata use the substring as a raw regexp
+ * pattern. If the substring contains regexp syntax, generated patterns may not be
+ * equivalent to the runtime `includes` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -5434,17 +5725,12 @@ export function isIncludes(includes: string, annotations?: Annotations.Filter) {
 const UPPERCASED_PATTERN = "^[^a-z]*$"
 
 /**
- * Validates that a string contains only uppercase characters.
+ * Validates that a string is unchanged by JavaScript's `toUpperCase()`.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only uppercase characters.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain only uppercase characters.
+ * **Details**
+ * This accepts empty strings and characters that do not have lowercase forms,
+ * such as digits, punctuation, and whitespace. It rejects strings that would
+ * change when uppercased.
  *
  * @category String checks
  * @since 4.0.0
@@ -5471,17 +5757,12 @@ export function isUppercased(annotations?: Annotations.Filter) {
 const LOWERCASED_PATTERN = "^[^A-Z]*$"
 
 /**
- * Validates that a string contains only lowercase characters.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only lowercase characters.
+ * Validates that a string is unchanged by JavaScript's `toLowerCase()`.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain only lowercase characters.
+ * **Details**
+ * This accepts empty strings and characters that do not have uppercase forms,
+ * such as digits, punctuation, and whitespace. It rejects strings that would
+ * change when lowercased.
  *
  * @category String checks
  * @since 4.0.0
@@ -5508,17 +5789,12 @@ export function isLowercased(annotations?: Annotations.Filter) {
 const CAPITALIZED_PATTERN = "^[^a-z]?.*$"
 
 /**
- * Validates that a string has its first character in uppercase.
- *
- * **JSON Schema**
+ * Validates that the first character of a string is unchanged by
+ * `toUpperCase()`.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with the first character in uppercase.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings have the first character in uppercase.
+ * **Details**
+ * Empty strings pass. Strings whose first character has no lowercase form, such
+ * as a digit, punctuation mark, or whitespace, also pass.
  *
  * @category String checks
  * @since 4.0.0
@@ -5545,17 +5821,12 @@ export function isCapitalized(annotations?: Annotations.Filter) {
 const UNCAPITALIZED_PATTERN = "^[^A-Z]?.*$"
 
 /**
- * Validates that a string has its first character in lowercase.
- *
- * **JSON Schema**
+ * Validates that the first character of a string is unchanged by
+ * `toLowerCase()`.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with the first character in lowercase.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings have the first character in lowercase.
+ * **Details**
+ * Empty strings pass. Strings whose first character has no uppercase form, such
+ * as a digit, punctuation mark, or whitespace, also pass.
  *
  * @category String checks
  * @since 4.0.0
@@ -6452,7 +6723,11 @@ export const isLessThanOrEqualToBigDecimal = makeIsLessThanOrEqualTo({
 })
 
 /**
- * Validates that a BigDecimal is within a specified range.
+ * Validates that a `BigDecimal` is within a specified range.
+ *
+ * **Details**
+ * The minimum and maximum boundaries are inclusive by default. Pass
+ * `exclusiveMinimum` or `exclusiveMaximum` to exclude either boundary.
  *
  * @category BigDecimal checks
  * @since 4.0.0
@@ -6869,12 +7144,16 @@ export function isPropertiesLengthBetween(minimum: number, maximum: number, anno
 }
 
 /**
- * Validates that all property names in an object satisfy the provided key
- * schema (encoded side of the schema).
+ * Validates that every own property key of an object satisfies the encoded side
+ * of the provided key schema.
  *
- * **JSON Schema**
+ * **Details**
+ * This check uses `Reflect.ownKeys`, so symbol keys are validated in addition to
+ * string property names.
  *
- * This check corresponds to the `propertyNames` constraint in JSON Schema.
+ * **JSON Schema**
+ * For string property names, this corresponds to the `propertyNames` constraint
+ * in JSON Schema.
  *
  * @category Object checks
  * @since 4.0.0
@@ -6911,18 +7190,14 @@ export function isPropertyNames(keySchema: Top, annotations?: Annotations.Filter
 }
 
 /**
- * Validates that all items in an array are unique according to the provided
- * equivalence function.
+ * Validates that all items in an array are unique according to Effect equality.
  *
  * **JSON Schema**
- *
  * This check corresponds to the `uniqueItems: true` constraint in JSON Schema.
  *
  * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `comparator`
- * constraint using the provided equivalence function to ensure generated arrays
- * contain only unique items.
+ * When generating test data with fast-check, this applies a comparator based on
+ * Effect equality to ensure generated arrays contain only unique items.
  *
  * @category Array checks
  * @since 4.0.0
@@ -6951,7 +7226,8 @@ export function isUnique<T>(annotations?: Annotations.Filter) {
 // -----------------------------------------------------------------------------
 
 /**
- * Companion type for {@link NonEmptyString}.
+ * Type-level representation of the `NonEmptyString` schema, which validates
+ * strings with a length of at least one.
  *
  * @category String
  * @since 4.0.0
@@ -6970,7 +7246,8 @@ export interface NonEmptyString extends String {
 export const NonEmptyString: NonEmptyString = String.check(isNonEmpty())
 
 /**
- * Companion type for {@link Char}.
+ * Type-level representation of the `Char` schema, which validates strings whose
+ * length is exactly one.
  *
  * @category String
  * @since 4.0.0
@@ -7021,6 +7298,12 @@ export interface Option<A extends Top> extends
 }
 
 /**
+ * Iso representation used for `Option` schemas.
+ *
+ * **Details**
+ * `None` is represented as `{ _tag: "None" }`, while `Some` is represented as
+ * `{ _tag: "Some", value }` using the wrapped schema's `Iso` type.
+ *
  * @category Option
  * @since 4.0.0
  */
@@ -7096,7 +7379,8 @@ export function Option<A extends Top>(value: A): Option<A> {
 }
 
 /**
- * Companion type for {@link OptionFromNullOr}.
+ * Type-level representation of a schema that decodes `null` as `None` and all
+ * other values as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7127,7 +7411,8 @@ export function OptionFromNullOr<S extends Top>(schema: S): OptionFromNullOr<S>
 }
 
 /**
- * Companion type for {@link OptionFromUndefinedOr}.
+ * Type-level representation of a schema that decodes `undefined` as `None` and
+ * all other values as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7158,7 +7443,8 @@ export function OptionFromUndefinedOr<S extends Top>(schema: S): OptionFromUndef
 }
 
 /**
- * Companion type for {@link OptionFromNullishOr}.
+ * Type-level representation of a schema that decodes `null` or `undefined` as
+ * `None` and all other values as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7194,7 +7480,8 @@ export function OptionFromNullishOr<S extends Top>(
 }
 
 /**
- * Companion type for {@link OptionFromOptionalKey}.
+ * Type-level representation of a schema that decodes a missing object key as
+ * `None` and a present key as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7225,7 +7512,8 @@ export function OptionFromOptionalKey<S extends Top>(schema: S): OptionFromOptio
 }
 
 /**
- * Companion type for {@link OptionFromOptional}.
+ * Type-level representation of a schema that decodes a missing key or
+ * `undefined` value as `None` and other present values as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7258,7 +7546,8 @@ export function OptionFromOptional<S extends Top>(schema: S): OptionFromOptional
 }
 
 /**
- * Companion type for {@link OptionFromOptionalNullOr}.
+ * Type-level representation of a schema that decodes a missing key, `undefined`,
+ * or `null` as `None` and all other present values as `Some`.
  *
  * @category Option
  * @since 4.0.0
@@ -7328,6 +7617,12 @@ export interface Result<A extends Top, E extends Top> extends
 }
 
 /**
+ * Iso representation used for `Result` schemas.
+ *
+ * **Details**
+ * Successful results are represented as `{ _tag: "Success", success }`, while
+ * failed results are represented as `{ _tag: "Failure", failure }`.
+ *
  * @category Result
  * @since 4.0.0
  */
@@ -7517,7 +7812,8 @@ export function Redacted<S extends Top>(value: S, options?: {
 }
 
 /**
- * Companion type for {@link RedactedFromValue}.
+ * Type-level representation of a schema that decodes a raw value with the
+ * provided schema and wraps the result in `Redacted`.
  *
  * @category Redacted
  * @since 4.0.0
@@ -7562,10 +7858,14 @@ export function RedactedFromValue<S extends Top>(value: S, options?: {
 }
 
 /**
- * Schema for a single `Cause.Reason<E>`, representing one reason a fiber may
- * fail: a typed error (`Fail`), an unexpected defect (`Die`), or an interrupt
+ * Schema for a single `Cause.Reason`, representing one reason a fiber may fail:
+ * a typed error (`Fail`), an unexpected defect (`Die`), or an interrupt
  * (`Interrupt`).
  *
+ * **Details**
+ * The `error` schema validates typed failures and the `defect` schema validates
+ * unexpected defects.
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -7583,6 +7883,12 @@ export interface CauseReason<E extends Top, D extends Top> extends
 }
 
 /**
+ * Iso representation used for `CauseReason` schemas.
+ *
+ * **Details**
+ * Failures are represented with a `Fail` tag and encoded error, defects with a
+ * `Die` tag and encoded defect, and interrupts with an optional `fiberId`.
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -7598,7 +7904,8 @@ export type CauseReasonIso<E extends Top, D extends Top> = {
 }
 
 /**
- * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ * Creates a schema for `Cause.Reason` values using separate schemas for typed
+ * failures and unexpected defects.
  *
  * @category CauseReason
  * @since 4.0.0
@@ -7711,8 +8018,12 @@ function causeReasonToFormatter<E>(error: Formatter<E>, defect: Formatter<unknow
 }
 
 /**
- * Schema for `Cause<E>`, an ordered collection of reasons a fiber failed,
- * combining typed errors, defects, and interrupts.
+ * Schema for `Cause` values, represented as an ordered collection of failure
+ * reasons combining typed errors, defects, and interrupts.
+ *
+ * **Details**
+ * The `error` schema validates typed failures and the `defect` schema validates
+ * unexpected defects.
  *
  * @category Cause
  * @since 4.0.0
@@ -7731,13 +8042,17 @@ export interface Cause<E extends Top, D extends Top> extends
 }
 
 /**
+ * Iso representation used for `Cause` schemas: an ordered array of
+ * `CauseReasonIso` values.
+ *
  * @category Cause
  * @since 4.0.0
  */
 export type CauseIso<E extends Top, D extends Top> = ReadonlyArray<CauseReasonIso<E, D>>
 
 /**
- * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ * Creates a schema for `Cause` values using separate schemas for typed failures
+ * and unexpected defects.
  *
  * @category Cause
  * @since 4.0.0
@@ -7800,7 +8115,7 @@ function causeToFormatter<E>(error: Formatter<E>, defect: Formatter<unknown>) {
 }
 
 /**
- * Companion type for {@link Error}.
+ * Type-level representation of the schema for JavaScript `Error` instances.
  *
  * @category Error
  * @since 4.0.0
@@ -7816,10 +8131,12 @@ const ErrorJsonEncoded = Struct({
 })
 
 /**
- * A schema that represents `Error` objects.
+ * A schema for JavaScript `Error` objects.
  *
- * The default json serializer decodes to a struct with `name` and `message`
- * properties (stack is omitted for security).
+ * **Default JSON serializer**
+ * Encodes an `Error` as an object with `message` and optional `name` properties,
+ * and decodes that object back into an `Error`. The stack trace is omitted from
+ * the encoded form for security.
  *
  * @category Schemas
  * @since 4.0.0
@@ -7838,10 +8155,12 @@ export const Error: Error = instanceOf(globalThis.Error, {
 })
 
 /**
- * A schema that represents `Error` objects.
+ * A schema for JavaScript `Error` objects that preserves stack traces in the JSON
+ * encoded form.
  *
- * The default json serializer decodes to a struct with `name`, `message` and
- * `stack` properties.
+ * **Default JSON serializer**
+ * Encodes an `Error` as an object with `message`, optional `name`, and optional
+ * `stack` properties, and decodes that object back into an `Error`.
  *
  * @category Schemas
  * @since 4.0.0
@@ -7866,7 +8185,8 @@ export const ErrorWithStack: Error = instanceOf(globalThis.Error, {
 })
 
 /**
- * Companion type for {@link Defect}.
+ * Type-level representation of the `Defect` schema, which accepts JavaScript
+ * `Error` values and arbitrary unknown defect values.
  *
  * @category Defect
  * @since 4.0.0
@@ -7901,7 +8221,12 @@ const defectTransformation = new Transformation.Transformation(
 )
 
 /**
- * A schema that represents defects.
+ * A schema for defect values, accepting either JavaScript `Error` values encoded
+ * with `message` and optional `name`, or arbitrary unknown defect values.
+ *
+ * **Default JSON serializer**
+ * Unknown defects are serialized with `JSON.stringify` when possible and fall
+ * back to Effect's formatted representation when JSON serialization fails.
  *
  * @category Constructors
  * @since 4.0.0
@@ -7941,8 +8266,8 @@ export const DefectWithStack: Defect = Union([
 ])
 
 /**
- * Schema for `Exit<A, E>`, representing the result of a fiber execution —
- * either a success with value `A` or a failure with `Cause<E>`.
+ * Schema for `Exit` values, representing either a success with value `A` or a
+ * failure with a `Cause` containing typed errors and defects.
  *
  * @category Exit
  * @since 4.0.0
@@ -7962,6 +8287,12 @@ export interface Exit<A extends Top, E extends Top, D extends Top> extends
 }
 
 /**
+ * Iso representation used for `Exit` schemas.
+ *
+ * **Details**
+ * Successful exits are represented as `{ _tag: "Success", value }`, while failed
+ * exits are represented as `{ _tag: "Failure", cause }`.
+ *
  * @category Exit
  * @since 4.0.0
  */
@@ -7974,7 +8305,8 @@ export type ExitIso<A extends Top, E extends Top, D extends Top> = {
 }
 
 /**
- * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ * Creates a schema for `Exit` values using schemas for the success value, typed
+ * failure, and unexpected defect channels.
  *
  * @category Exit
  * @since 4.0.0
@@ -8074,7 +8406,8 @@ export function Exit<A extends Top, E extends Top, D extends Top>(value: A, erro
 }
 
 /**
- * Companion type for {@link ReadonlyMap}.
+ * Type-level representation of a `ReadonlyMap` schema whose keys and values are
+ * validated by the provided schemas.
  *
  * @category ReadonlyMap
  * @since 4.0.0
@@ -8093,6 +8426,9 @@ export interface $ReadonlyMap<Key extends Top, Value extends Top> extends
 }
 
 /**
+ * Iso representation used for `ReadonlyMap` schemas: an array of readonly
+ * `[key, value]` tuples using each entry schema's `Iso` type.
+ *
  * @category ReadonlyMap
  * @since 4.0.0
  */
@@ -8187,6 +8523,9 @@ export interface HashMap<Key extends Top, Value extends Top> extends
 }
 
 /**
+ * Iso representation used for `HashMap` schemas: an array of readonly
+ * `[key, value]` tuples using each entry schema's `Iso` type.
+ *
  * @category HashMap
  * @since 4.0.0
  */
@@ -8262,7 +8601,8 @@ export function HashMap<Key extends Top, Value extends Top>(key: Key, value: Val
 }
 
 /**
- * Companion type for {@link ReadonlySet}.
+ * Type-level representation of a `ReadonlySet` schema whose values are validated
+ * by the provided element schema.
  *
  * @category ReadonlySet
  * @since 4.0.0
@@ -8280,12 +8620,18 @@ export interface $ReadonlySet<Value extends Top> extends
 }
 
 /**
+ * Iso representation used for `ReadonlySet` schemas: an array of element values
+ * using the element schema's `Iso` type.
+ *
  * @category ReadonlySet
  * @since 4.0.0
  */
 export type ReadonlySetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>
 
 /**
+ * Creates a schema that validates a `ReadonlySet` whose values conform to the
+ * provided element schema.
+ *
  * @category ReadonlySet
  * @since 4.0.0
  */
@@ -8370,6 +8716,9 @@ export interface HashSet<Value extends Top> extends
 }
 
 /**
+ * Iso representation used for `HashSet` schemas: an array of element values
+ * using the element schema's `Iso` type.
+ *
  * @category HashSet
  * @since 4.0.0
  */
@@ -8463,6 +8812,9 @@ export interface Chunk<Value extends Top> extends
 }
 
 /**
+ * Iso representation used for `Chunk` schemas: an array of element values using
+ * the element schema's `Iso` type.
+ *
  * @category Chunk
  * @since 4.0.0
  */
@@ -8537,7 +8889,7 @@ export function Chunk<Value extends Top>(value: Value): Chunk<Value> {
 }
 
 /**
- * Companion type for {@link RegExp}.
+ * Type-level representation of the schema for JavaScript `RegExp` instances.
  *
  * @category RegExp
  * @since 4.0.0
@@ -8611,7 +8963,7 @@ export const RegExp: RegExp = instanceOf(
 )
 
 /**
- * Companion type for {@link URL}.
+ * Type-level representation of the schema for JavaScript `URL` instances.
  *
  * @category URL
  * @since 4.0.0
@@ -8629,8 +8981,8 @@ const URLString = String.annotate({ expected: "a string that will be decoded as
  *
  * - encodes `URL` as a `string`
  *
- * @since 4.0.0
  * @category URL
+ * @since 4.0.0
  */
 export const URL: URL = instanceOf(
   globalThis.URL,
@@ -8654,7 +9006,8 @@ export const URL: URL = instanceOf(
 )
 
 /**
- * Companion type for {@link URLFromString}.
+ * Type-level representation of a transformation schema that decodes valid URL
+ * strings into JavaScript `URL` instances.
  *
  * @category URL
  * @since 4.0.0
@@ -8678,7 +9031,8 @@ export interface URLFromString extends decodeTo<URL, String> {
 export const URLFromString: URLFromString = URLString.pipe(decodeTo(URL, Transformation.urlFromString))
 
 /**
- * Companion type for {@link Date}.
+ * Type-level representation of the schema for JavaScript `Date` instances,
+ * including invalid dates.
  *
  * @category Date
  * @since 4.0.0
@@ -8692,9 +9046,10 @@ const DateString = String.annotate({ expected: "a string in ISO 8601 format that
 /**
  * A schema for JavaScript `Date` objects.
  *
- * This schema accepts any `Date` instance, including invalid dates (e.g., `new
- * Date("invalid")`). For validating only valid dates, use {@link DateValid}
- * instead. The default JSON serializer encodes `Date` as an ISO 8601 string.
+ * This schema accepts any `Date` instance, including invalid dates. For
+ * validating only valid dates, use `DateValid` instead. The default JSON
+ * serializer encodes valid dates as ISO 8601 strings; invalid dates encode as
+ * `"Invalid Date"`.
  *
  * **Example** (Date schema)
  *
@@ -8729,7 +9084,8 @@ export const Date: Date = instanceOf(
 )
 
 /**
- * Companion type for {@link DateFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * JavaScript `Date` instances.
  *
  * @category Date
  * @since 4.0.0
@@ -8739,13 +9095,15 @@ export interface DateFromString extends decodeTo<Date, String> {
 }
 
 /**
- * A transformation schema that parses an ISO 8601 string into a `Date`.
+ * A transformation schema that decodes a string into a JavaScript `Date`.
  *
- * Decoding:
- * - A `string` is decoded as a `Date`.
+ * **Decoding**
+ * The string is passed to JavaScript `Date` construction and may decode to an
+ * invalid `Date`. Compose with `DateValid` when invalid dates should be rejected.
  *
- * Encoding:
- * - A `Date` is encoded as a `string`.
+ * **Encoding**
+ * A valid `Date` is encoded as an ISO string; an invalid `Date` is encoded as
+ * `"Invalid Date"`.
  *
  * @category Date
  * @since 4.0.0
@@ -8753,7 +9111,8 @@ export interface DateFromString extends decodeTo<Date, String> {
 export const DateFromString: DateFromString = DateString.pipe(decodeTo(Date, Transformation.dateFromString))
 
 /**
- * Companion type for {@link DateValid}.
+ * Type-level representation of the `DateValid` schema, which accepts only valid
+ * JavaScript `Date` instances.
  *
  * @category Date
  * @since 4.0.0
@@ -8774,7 +9133,7 @@ export interface DateValid extends Date {
 export const DateValid: DateValid = Date.check(isDateValid())
 
 /**
- * Companion type for {@link Duration}.
+ * Type-level representation of the schema for Effect `Duration` values.
  *
  * @category Duration
  * @since 4.0.0
@@ -8865,7 +9224,8 @@ export const Duration: Duration = declare(
 const DurationString = String.annotate({ expected: "a string that will be decoded as a Duration" })
 
 /**
- * Companion type for {@link DurationFromString}.
+ * Type-level representation of a transformation schema that decodes strings
+ * accepted by `Duration.fromInput` into `Duration` values.
  *
  * @category Duration
  * @since 4.0.0
@@ -8892,7 +9252,8 @@ export const DurationFromString: DurationFromString = DurationString.pipe(
 )
 
 /**
- * Companion type for {@link DurationFromNanos}.
+ * Type-level representation of a transformation schema that decodes non-negative
+ * nanosecond `bigint` values into `Duration` values.
  *
  * @category Duration
  * @since 4.0.0
@@ -8905,13 +9266,15 @@ const bigint0 = globalThis.BigInt(0)
 
 /**
  * A transformation schema that decodes a non-negative `bigint` into a
- * `Duration`, treating the `bigint` value as the duration in nanoseconds.
+ * `Duration`, treating the bigint as nanoseconds.
  *
- * Decoding:
- * - A non-negative `bigint` representing nanoseconds is decoded as a `Duration`
+ * **Decoding**
+ * A non-negative `bigint` representing nanoseconds is decoded as a `Duration`.
  *
- * Encoding:
- * - A `Duration` is encoded to a non-negative `bigint` representing nanoseconds
+ * **Encoding**
+ * Finite durations are encoded as a non-negative `bigint` number of nanoseconds.
+ * Encoding fails when the duration cannot be represented as nanoseconds, such as
+ * `Duration.infinity`.
  *
  * @category Duration
  * @since 4.0.0
@@ -8921,7 +9284,8 @@ export const DurationFromNanos: DurationFromNanos = BigInt.check(isGreaterThanOr
 )
 
 /**
- * Companion type for {@link DurationFromMillis}.
+ * Type-level representation of a transformation schema that decodes
+ * non-negative millisecond numbers into `Duration` values.
  *
  * @category Duration
  * @since 4.0.0
@@ -8951,7 +9315,7 @@ export const DurationFromMillis: DurationFromMillis = Number.check(isGreaterThan
 )
 
 /**
- * Companion type for {@link BigDecimal}.
+ * Type-level representation of the schema for Effect `BigDecimal` values.
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -8998,7 +9362,8 @@ export const BigDecimal: BigDecimal = declare(
 )
 
 /**
- * Companion type for {@link BigDecimalFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * `BigDecimal` values.
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -9024,7 +9389,8 @@ export const BigDecimalFromString: BigDecimalFromString = BigDecimalString.pipe(
 )
 
 /**
- * Companion type for {@link UnknownFromJsonString}.
+ * Type-level representation of a transformation schema that decodes
+ * JSON-encoded strings into `unknown` values.
  *
  * @category JSON
  * @since 4.0.0
@@ -9059,7 +9425,8 @@ export interface UnknownFromJsonString extends fromJsonString<Unknown> {
 export const UnknownFromJsonString: UnknownFromJsonString = fromJsonString(Unknown)
 
 /**
- * Companion type for {@link fromJsonString}.
+ * Type-level representation of a schema that parses a JSON string and then
+ * decodes the parsed value with the provided schema.
  *
  * @category JSON
  * @since 4.0.0
@@ -9141,7 +9508,7 @@ export function fromJsonString<S extends Top>(schema: S): fromJsonString<S> {
 }
 
 /**
- * Companion type for {@link File}.
+ * Type-level representation of the schema for JavaScript `File` instances.
  *
  * @category File
  * @since 4.0.0
@@ -9213,7 +9580,7 @@ export const File: File = instanceOf(globalThis.File, {
 })
 
 /**
- * Companion type for {@link FormData}.
+ * Type-level representation of the schema for JavaScript `FormData` instances.
  *
  * @category FormData
  * @since 4.0.0
@@ -9275,7 +9642,8 @@ export const FormData: FormData = instanceOf(globalThis.FormData, {
 })
 
 /**
- * Companion type for {@link fromFormData}.
+ * Type-level representation of a schema that parses `FormData` into a tree
+ * record and then decodes it with the provided schema.
  *
  * @category FormData
  * @since 4.0.0
@@ -9372,7 +9740,8 @@ export function fromFormData<S extends Top>(schema: S): fromFormData<S> {
 }
 
 /**
- * Companion type for {@link URLSearchParams}.
+ * Type-level representation of the schema for JavaScript `URLSearchParams`
+ * instances.
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -9409,7 +9778,8 @@ export const URLSearchParams: URLSearchParams = instanceOf(globalThis.URLSearchP
 })
 
 /**
- * Companion type for {@link fromURLSearchParams}.
+ * Type-level representation of a schema that parses `URLSearchParams` into a
+ * tree record and then decodes it with the provided schema.
  *
  * @category URLSearchParams
  * @since 4.0.0
@@ -9497,7 +9867,8 @@ export function fromURLSearchParams<S extends Top>(schema: S): fromURLSearchPara
 }
 
 /**
- * Companion type for {@link Finite}.
+ * Type-level representation of the `Finite` number schema, which rejects `NaN`,
+ * `Infinity`, and `-Infinity`.
  *
  * @category Number
  * @since 4.0.0
@@ -9515,7 +9886,8 @@ export interface Finite extends Number {
 export const Finite: Finite = Number.check(isFinite())
 
 /**
- * Companion type for {@link Int}.
+ * Type-level representation of the `Int` schema, which accepts only finite
+ * integer numbers.
  *
  * @category Number
  * @since 4.0.0
@@ -9533,7 +9905,8 @@ export interface Int extends Number {
 export const Int: Int = Number.check(isInt())
 
 /**
- * Companion type for {@link NumberFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * numbers using JavaScript number coercion.
  *
  * @category Number
  * @since 4.0.0
@@ -9543,13 +9916,16 @@ export interface NumberFromString extends decodeTo<Finite, String> {
 }
 
 /**
- * A transformation schema that parses a string into a number.
+ * A transformation schema that parses a string into a `number` using JavaScript
+ * number coercion.
  *
- * Decoding:
- * - A `string` is decoded as a finite number.
+ * **Decoding**
+ * A `string` is decoded as a number, including possible non-finite values such as
+ * `NaN`, `Infinity`, and `-Infinity`. Use `FiniteFromString` to reject non-finite
+ * numbers.
  *
- * Encoding:
- * - A number is encoded as a `string`.
+ * **Encoding**
+ * A number is encoded as a `string`.
  *
  * @category Number
  * @since 4.0.0
@@ -9559,7 +9935,8 @@ export const NumberFromString: NumberFromString = String.annotate({
 }).pipe(decodeTo(Number, Transformation.numberFromString))
 
 /**
- * Companion type for {@link FiniteFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * finite numbers.
  *
  * @category Number
  * @since 4.0.0
@@ -9586,7 +9963,8 @@ export const FiniteFromString: FiniteFromString = String.annotate({
 }).pipe(decodeTo(Finite, Transformation.numberFromString))
 
 /**
- * Companion type for {@link BigIntFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * `bigint` values.
  *
  * @category BigInt
  * @since 4.0.0
@@ -9612,7 +9990,8 @@ export const BigIntFromString: BigIntFromString = make<String>(AST.bigIntString)
 )
 
 /**
- * Companion type for {@link Trimmed}.
+ * Schema interface for `Trimmed`, representing strings with no leading or
+ * trailing whitespace.
  *
  * @category String
  * @since 4.0.0
@@ -9630,7 +10009,8 @@ export interface Trimmed extends String {
 export const Trimmed: Trimmed = String.check(isTrimmed())
 
 /**
- * Companion type for {@link Trim}.
+ * Schema interface for `Trim`, a transformation that trims leading and trailing
+ * whitespace while decoding and encodes the trimmed string unchanged.
  *
  * @category String
  * @since 4.0.0
@@ -9656,7 +10036,8 @@ export const Trim: Trim = String.annotate({
 }).pipe(decodeTo(Trimmed, Transformation.trim()))
 
 /**
- * Companion type for {@link StringFromBase64}.
+ * Schema interface for `StringFromBase64`, a transformation between RFC4648
+ * base64-encoded strings and UTF-8 strings.
  *
  * @category String
  * @since 4.0.0
@@ -9684,7 +10065,8 @@ export const StringFromBase64: StringFromBase64 = String.annotate({
 )
 
 /**
- * Companion type for {@link StringFromBase64Url}.
+ * Schema interface for `StringFromBase64Url`, a transformation between URL-safe
+ * base64-encoded strings and UTF-8 strings.
  *
  * @category String
  * @since 4.0.0
@@ -9712,7 +10094,8 @@ export const StringFromBase64Url: StringFromBase64Url = String.annotate({
 )
 
 /**
- * Companion type for {@link StringFromHex}.
+ * Schema interface for `StringFromHex`, a transformation between hex-encoded
+ * strings and UTF-8 strings.
  *
  * @category String
  * @since 4.0.0
@@ -9740,7 +10123,8 @@ export const StringFromHex: StringFromHex = String.annotate({
 )
 
 /**
- * Companion type for {@link StringFromUriComponent}.
+ * Schema interface for `StringFromUriComponent`, a transformation between
+ * URI-component encoded strings and UTF-8 strings.
  *
  * @category String
  * @since 4.0.0
@@ -9787,7 +10171,8 @@ export const StringFromUriComponent: StringFromUriComponent = String.annotate({
 )
 
 /**
- * A union schema for JavaScript property keys: `number | symbol | string`.
+ * A union schema for property keys accepted by Effect schemas: finite `number`,
+ * `symbol`, or `string`.
  *
  * @category PropertyKey
  * @since 4.0.0
@@ -9795,6 +10180,11 @@ export const StringFromUriComponent: StringFromUriComponent = String.annotate({
 export const PropertyKey = Union([Finite, Symbol, String])
 
 /**
+ * Schema for a Standard Schema v1 failure result.
+ *
+ * The result contains an `issues` array where each issue has a message and an
+ * optional path made of property keys or keyed path segments.
+ *
  * @category StandardSchema
  * @since 4.0.0
  */
@@ -9806,7 +10196,8 @@ export const StandardSchemaV1FailureResult = Struct({
 })
 
 /**
- * Companion type for {@link BooleanFromBit}.
+ * Schema interface for `BooleanFromBit`, a transformation between bit literals
+ * `0 | 1` and boolean values.
  *
  * @category Boolean
  * @since 4.0.0
@@ -9832,7 +10223,8 @@ export const BooleanFromBit: BooleanFromBit = Literals([0, 1]).pipe(
 )
 
 /**
- * Companion type for {@link Uint8Array}.
+ * Schema interface for `Uint8Array`, representing JavaScript `Uint8Array`
+ * instances with base64 JSON encoding.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -9875,7 +10267,8 @@ export const Uint8Array: Uint8Array = instanceOf(globalThis.Uint8Array<ArrayBuff
 })
 
 /**
- * Companion type for {@link Uint8ArrayFromBase64}.
+ * Schema interface for `Uint8ArrayFromBase64`, a transformation between
+ * base64-encoded strings and `Uint8Array` values.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -9902,7 +10295,8 @@ export const Uint8ArrayFromBase64: Uint8ArrayFromBase64 = Base64String.pipe(
 )
 
 /**
- * Companion type for {@link Uint8ArrayFromBase64Url}.
+ * Schema interface for `Uint8ArrayFromBase64Url`, a transformation between
+ * URL-safe base64-encoded strings and `Uint8Array` values.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -9934,7 +10328,8 @@ export const Uint8ArrayFromBase64Url: Uint8ArrayFromBase64Url = String.annotate(
 )
 
 /**
- * Companion type for {@link Uint8ArrayFromHex}.
+ * Schema interface for `Uint8ArrayFromHex`, a transformation between
+ * hex-encoded strings and `Uint8Array` values.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -9966,7 +10361,8 @@ export const Uint8ArrayFromHex: Uint8ArrayFromHex = String.annotate({
 )
 
 /**
- * Companion type for {@link DateTimeUtc}.
+ * Schema interface for `DateTimeUtc`, representing `DateTime.Utc` values with
+ * UTC ISO string JSON encoding.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10010,7 +10406,8 @@ export const DateTimeUtc: DateTimeUtc = declare(
 )
 
 /**
- * Companion type for {@link DateTimeUtcFromDate}.
+ * Schema interface for `DateTimeUtcFromDate`, a transformation from valid
+ * JavaScript `Date` values to `DateTime.Utc`.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10039,7 +10436,8 @@ export const DateTimeUtcFromDate: DateTimeUtcFromDate = DateValid.pipe(
 )
 
 /**
- * Companion type for {@link DateTimeUtcFromString}.
+ * Schema interface for `DateTimeUtcFromString`, a transformation from date-time
+ * strings to `DateTime.Utc`.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10049,15 +10447,16 @@ export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
 }
 
 /**
- * A transformation schema that decodes a string into a `DateTime.Utc`.
+ * A transformation schema that decodes a date-time string into a `DateTime.Utc`.
  *
  * Decoding:
- * - A `string` that can be parsed by `Date.parse` is decoded as a
- *   `DateTime.Utc`
+ *
+ * - A string accepted by `DateTime.make` is parsed and normalized to UTC. Strings
+ *   without an explicit zone are interpreted as UTC.
  *
  * Encoding:
- * - A `DateTime.Utc` is encoded as a `string` in ISO 8601 format, ignoring any
- *   time zone.
+ *
+ * - A `DateTime.Utc` is encoded as a UTC ISO 8601 string.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10072,7 +10471,8 @@ export const DateTimeUtcFromString: DateTimeUtcFromString = String.annotate({
 )
 
 /**
- * Companion type for {@link DateTimeUtcFromMillis}.
+ * Schema interface for `DateTimeUtcFromMillis`, a transformation between epoch
+ * milliseconds and `DateTime.Utc` values.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10101,7 +10501,8 @@ export const DateTimeUtcFromMillis: DateTimeUtcFromMillis = Number.pipe(
 )
 
 /**
- * Companion type for {@link TimeZoneOffset}.
+ * Schema interface for `TimeZoneOffset`, representing
+ * `DateTime.TimeZone.Offset` values encoded as offset milliseconds.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10145,7 +10546,8 @@ export const TimeZoneOffset: TimeZoneOffset = declare(
 )
 
 /**
- * Companion type for {@link TimeZoneNamed}.
+ * Schema interface for `TimeZoneNamed`, representing
+ * `DateTime.TimeZone.Named` values encoded as IANA time zone identifiers.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10195,7 +10597,8 @@ export const TimeZoneNamed: TimeZoneNamed = declare(
 )
 
 /**
- * Companion type for {@link TimeZoneNamedFromString}.
+ * Schema interface for `TimeZoneNamedFromString`, a transformation between IANA
+ * time zone identifier strings and `DateTime.TimeZone.Named` values.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10221,7 +10624,8 @@ export const TimeZoneNamedFromString: TimeZoneNamedFromString = TimeZoneNamedStr
 )
 
 /**
- * Companion type for {@link TimeZone}.
+ * Schema interface for `TimeZone`, representing `DateTime.TimeZone` values
+ * encoded as either IANA identifiers or numeric offset strings.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10277,7 +10681,8 @@ export const TimeZone: TimeZone = declare(
 )
 
 /**
- * Companion type for {@link TimeZoneFromString}.
+ * Schema interface for `TimeZoneFromString`, a transformation from IANA
+ * identifier or offset strings to `DateTime.TimeZone` values.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10303,7 +10708,8 @@ export const TimeZoneFromString: TimeZoneFromString = TimeZoneString.pipe(
 )
 
 /**
- * Companion type for {@link DateTimeZoned}.
+ * Schema interface for `DateTimeZoned`, representing `DateTime.Zoned` values
+ * with ISO offset or named-zone string JSON encoding.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10321,7 +10727,9 @@ const DateTimeZonedString = String.annotate({
  *
  * **Default JSON serializer**
  *
- * - encodes `DateTime.Zoned` as a string in the format
+ * - encodes offset zones as an ISO date-time with a numeric offset, such as
+ *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`
+ * - encodes named zones by appending the IANA identifier in brackets, such as
  *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`
  *
  * @category DateTime
@@ -10360,7 +10768,8 @@ export const DateTimeZoned: DateTimeZoned = declare(
 )
 
 /**
- * Companion type for {@link DateTimeZonedFromString}.
+ * Schema interface for `DateTimeZonedFromString`, a transformation between
+ * zoned date-time strings and `DateTime.Zoned` values.
  *
  * @category DateTime
  * @since 4.0.0
@@ -10512,10 +10921,7 @@ function makeClass<
       return Parser.makeOption(getClassSchema(this) as any)(input ?? {}, options) as any
     }
     static makeEffect(input: S["~type.make.in"], options?: MakeOptions): Effect.Effect<Self, SchemaError> {
-      return Effect.mapErrorEager(
-        Parser.makeEffect(getClassSchema(this) as any)(input ?? {}, options),
-        (issue) => new SchemaError(issue)
-      ) as any
+      return (getClassSchema(this) as any).makeEffect(input ?? {}, options)
     }
     static annotate(annotations: Annotations.Declaration<Self, readonly [S]>) {
       return this.rebuild(AST.annotate(this.ast, annotations))
@@ -10942,13 +11348,14 @@ export const TaggedClass: {
     schema: Struct.Fields | Struct<Struct.Fields>,
     annotations?: Annotations.Declaration<any, readonly [Struct<Struct.Fields>]>
   ): any => {
+    const struct = isStruct(schema) ?
+      schema.mapFields((fields) => ({ _tag: tag(tagValue), ...fields }), {
+        unsafePreserveChecks: true
+      }) :
+      TaggedStruct(tagValue, schema)
     return Class<any, {}>(identifier ?? tagValue)(
-      isStruct(schema) ?
-        schema.mapFields((fields) => ({ _tag: tag(tagValue), ...fields }), {
-          unsafePreserveChecks: true
-        }) :
-        TaggedStruct(tagValue, schema),
-      annotations
+      struct,
+      annotations as Annotations.Declaration<any, readonly [typeof struct]>
     )
   }
 }
@@ -11186,13 +11593,14 @@ export const TaggedErrorClass: {
     schema: Struct.Fields | Struct<Struct.Fields>,
     annotations?: Annotations.Declaration<any, readonly [Struct<Struct.Fields>]>
   ): any => {
+    const struct = isStruct(schema) ?
+      schema.mapFields((fields) => ({ _tag: tag(tagValue), ...fields }), {
+        unsafePreserveChecks: true
+      }) :
+      TaggedStruct(tagValue, schema)
     return ErrorClass<any, {}>(identifier ?? tagValue)(
-      isStruct(schema) ?
-        schema.mapFields((fields) => ({ _tag: tag(tagValue), ...fields }), {
-          unsafePreserveChecks: true
-        }) :
-        TaggedStruct(tagValue, schema),
-      annotations
+      struct,
+      annotations as Annotations.Declaration<any, readonly [typeof struct]>
     )
   }
 }
@@ -11256,10 +11664,11 @@ export function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Ty
 // -----------------------------------------------------------------------------
 
 /**
- * **Technical Note**
+ * Annotates a schema with a custom formatter used by `toFormatter`.
  *
- * This annotation cannot be added to `Annotations.Bottom` because it would make
- * the schema invariant.
+ * Use this when the formatter derived from the schema structure is not suitable.
+ * The annotation is applied through this helper because adding it directly to
+ * `Annotations.Bottom` would make schemas invariant.
  *
  * @category Formatter
  * @since 4.0.0
@@ -11500,9 +11909,11 @@ export interface ToJsonSchemaOptions {
 }
 
 /**
- * Returns a JSON Schema Document (draft-2020-12).
+ * Returns a JSON Schema document using draft 2020-12.
  *
- * You can use the `options` parameter to return a different target JSON Schema.
+ * The `options` parameter controls generation details such as additional
+ * properties and synthesized check descriptions; it does not change the draft
+ * target.
  *
  * @category JsonSchema
  * @since 4.0.0
@@ -11522,8 +11933,8 @@ export function toJsonSchemaDocument(schema: Top, options?: ToJsonSchemaOptions)
 // -----------------------------------------------------------------------------
 
 /**
- * Derives a canonical JSON codec from a schema. The encoded form is `unknown`
- * (any JSON-compatible value), decoded to the schema's `Type`.
+ * Derives a canonical JSON codec from a schema. The encoded form is `Json`, and
+ * decoding produces the schema's `Type`.
  *
  * @category Canonical Codecs
  * @since 4.0.0
@@ -11686,9 +12097,11 @@ type XmlEncoderOptions = {
 }
 
 /**
- * Derives an XML encoder from a codec. Encodes a value to an XML string by
- * first converting it through {@link toCodecStringTree}, then serializing the
- * resulting tree to XML.
+ * Derives an XML encoder from a codec.
+ *
+ * The returned function encodes a value through `toCodecStringTree` and returns
+ * an `Effect` that succeeds with the XML string or fails with `SchemaError` if
+ * codec encoding fails.
  *
  * @category Canonical Codecs
  * @since 4.0.0
@@ -12066,6 +12479,9 @@ export function toDifferJsonPatch<T, E>(schema: Codec<T, E>): Differ<T, JsonPatc
 }
 
 /**
+ * Recursive tree type whose leaves are `Node` values and whose branches are
+ * readonly arrays or string-keyed records of child trees.
+ *
  * @category Tree
  * @since 4.0.0
  */
@@ -12152,6 +12568,9 @@ export interface JsonObject {
 export const Json: Codec<Json> = make(AST.Json)
 
 /**
+ * Recursive TypeScript type for mutable JSON values: `null`, `number`,
+ * `boolean`, `string`, mutable arrays, or mutable string-keyed records.
+ *
  * @category JSON
  * @since 4.0.0
  */
@@ -12278,6 +12697,15 @@ export declare namespace Annotations {
    * @since 4.0.0
    */
   export interface Augment extends Annotations {
+    /**
+     * Human-readable description of what a value is expected to satisfy.
+     *
+     * For filter and refinement failures, the default formatter uses
+     * `message` first, then `expected`, and finally falls back to `<filter>`.
+     *
+     * Use this to name a failed filter in the default message:
+     * `Expected <expected>, got <actual>`.
+     */
     readonly expected?: string | undefined
     readonly title?: string | undefined
     readonly description?: string | undefined
@@ -12325,13 +12753,31 @@ export declare namespace Annotations {
    */
   export interface Bottom<T, TypeParameters extends ReadonlyArray<Top>> extends Documentation<T> {
     /**
-     * The message to use when the value is invalid.
+     * Complete message to use when this schema node reports an issue.
+     *
+     * This replaces the default message for matching issue types instead of
+     * only changing the expected label. For a filter or refinement failure,
+     * annotate the filter with `message` to replace the whole filter failure
+     * message, or `expected` to keep the default
+     * `Expected <expected>, got <actual>` shape.
      */
     readonly message?: string | undefined
     /**
      * The message to use when a key is unexpected.
      */
     readonly messageUnexpectedKey?: string | undefined
+    /**
+     * Stable identifier for this schema node.
+     *
+     * Identifiers are used by schema tooling, including JSON Schema
+     * generation, to name references. The default formatter also uses
+     * `identifier` as the expected label for type-level failures, such as
+     * `Expected UserId, got null`.
+     *
+     * `identifier` does not name a failed filter or refinement. If the base
+     * type matches and a filter fails, put `expected` or `message` on the
+     * filter/refinement instead.
+     */
     readonly identifier?: string | undefined
     readonly parseOptions?: AST.ParseOptions | undefined
     /**
@@ -12348,16 +12794,24 @@ export declare namespace Annotations {
   }
 
   /**
+   * Helpers for projecting declaration type-parameter schemas into decoded or
+   * encoded codec arrays used by annotation hooks.
+   *
    * @since 4.0.0
    */
   export namespace TypeParameters {
     /**
+     * Maps declaration type-parameter schemas to codecs for their decoded `Type`
+     * values.
+     *
      * @since 4.0.0
      */
     export type Type<TypeParameters extends ReadonlyArray<Top>> = {
       readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"]>
     }
     /**
+     * Maps declaration type-parameter schemas to codecs for their `Encoded` values.
+     *
      * @since 4.0.0
      */
     export type Encoded<TypeParameters extends ReadonlyArray<Top>> = {
@@ -12416,7 +12870,21 @@ export declare namespace Annotations {
    * @since 4.0.0
    */
   export interface Filter extends Augment {
+    /**
+     * Complete message to use when this filter or refinement fails.
+     *
+     * The default formatter checks filter annotations in this order:
+     * `message`, then `expected`, then `<filter>`.
+     */
     readonly message?: string | undefined
+    /**
+     * Stable identifier for the schema after this filter is attached.
+     *
+     * This can affect schema tooling such as JSON Schema generation and
+     * type-level failures before the filter runs, but it does not name the
+     * failed filter itself. For filter failure messages, use `expected` or
+     * `message`.
+     */
     readonly identifier?: string | undefined
     /**
      * Optional metadata used to identify or extend the filter with custom data.
@@ -12436,10 +12904,16 @@ export declare namespace Annotations {
   }
 
   /**
+   * Types used by arbitrary-derivation annotations to configure `toArbitrary`
+   * hooks and carry merged fast-check 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.
+     *
      * @since 4.0.0
      */
     export interface StringConstraints extends FastCheck.StringSharedConstraints {
@@ -12447,6 +12921,9 @@ export declare namespace Annotations {
     }
 
     /**
+     * fast-check floating-point constraints plus `isInteger`, which switches
+     * derived number arbitraries to integer generation.
+     *
      * @since 4.0.0
      */
     export interface NumberConstraints extends FastCheck.FloatConstraints {
@@ -12454,11 +12931,17 @@ export declare namespace Annotations {
     }
 
     /**
+     * fast-check bigint constraints used when deriving arbitraries for bigint
+     * schemas.
+     *
      * @since 4.0.0
      */
     export interface BigIntConstraints extends FastCheck.BigIntConstraints {}
 
     /**
+     * fast-check array constraints plus an optional comparator used when deriving
+     * unique-array arbitraries.
+     *
      * @since 4.0.0
      */
     export interface ArrayConstraints extends FastCheck.ArrayConstraints {
@@ -12466,11 +12949,17 @@ export declare namespace Annotations {
     }
 
     /**
+     * fast-check date constraints used when deriving arbitraries for `Date` and
+     * DateTime schemas.
+     *
      * @since 4.0.0
      */
     export interface DateConstraints extends FastCheck.DateConstraints {}
 
     /**
+     * Grouped arbitrary-generation constraints accumulated from schema checks and
+     * passed to `toArbitrary` derivation.
+     *
      * @since 4.0.0
      */
     export interface Constraint {
@@ -12482,6 +12971,10 @@ export declare namespace Annotations {
     }
 
     /**
+     * Context passed to arbitrary-derivation hooks, including accumulated
+     * constraints and an `isSuspend` flag used to limit recursion for suspended
+     * schemas.
+     *
      * @since 4.0.0
      */
     export interface Context {
@@ -12495,6 +12988,11 @@ export declare namespace Annotations {
     }
 
     /**
+     * Hook signature for declaration schema arbitrary annotations.
+     *
+     * Given arbitraries for any type parameters, returns a function that receives the
+     * fast-check module and derivation context and produces an arbitrary for `T`.
+     *
      * @since 4.0.0
      */
     export interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -12506,10 +13004,17 @@ export declare namespace Annotations {
   }
 
   /**
+   * Types used by formatter annotations to customize formatter derivation for
+   * declaration schemas.
+   *
    * @since 4.0.0
    */
   export namespace ToFormatter {
     /**
+     * Hook signature for declaration schema formatter annotations.
+     *
+     * Given formatters for any type parameters, returns a formatter for `T`.
+     *
      * @since 4.0.0
      */
     export interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -12521,10 +13026,17 @@ export declare namespace Annotations {
   }
 
   /**
+   * Types used by equivalence annotations to customize equivalence derivation for
+   * declaration schemas.
+   *
    * @since 4.0.0
    */
   export namespace ToEquivalence {
     /**
+     * Hook signature for declaration schema equivalence annotations.
+     *
+     * Given equivalences for any type parameters, returns an `Equivalence` for `T`.
+     *
      * @since 4.0.0
      */
     export interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -12536,6 +13048,10 @@ export declare namespace Annotations {
   }
 
   /**
+   * Annotations that can be attached to schema issues.
+   *
+   * The optional `message` field overrides the default issue message.
+   *
    * @category Model
    * @since 4.0.0
    */
@@ -12544,7 +13060,10 @@ export declare namespace Annotations {
   }
 
   /**
-   * This MUST NOT be extended with custom meta.
+   * Registry of metadata payloads emitted by built-in schema filters and checks.
+   *
+   * Do not augment this interface with custom metadata; extend `MetaDefinitions`
+   * instead.
    *
    * @since 4.0.0
    */
@@ -12755,18 +13274,25 @@ export declare namespace Annotations {
   }
 
   /**
+   * Union of all metadata payloads defined by `BuiltInMetaDefinitions`.
+   *
    * @since 4.0.0
    */
   export type BuiltInMeta = BuiltInMetaDefinitions[keyof BuiltInMetaDefinitions]
 
   /**
-   * This MAY be extended with custom meta.
+   * Augmentable registry of schema filter metadata payloads.
+   *
+   * Extend this interface to add custom values accepted by annotation `meta`
+   * fields.
    *
    * @since 4.0.0
    */
   export interface MetaDefinitions extends BuiltInMetaDefinitions {}
 
   /**
+   * Union of built-in and user-augmented schema filter metadata payloads.
+   *
    * @since 4.0.0
    */
   export type Meta = MetaDefinitions[keyof MetaDefinitions]