effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Schema.d.ts

@@ -206,6 +206,8 @@ export interface Bottom<out T, out E, out RD, out RE, out Ast extends AST.AST, o
     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"];
@@ -886,49 +888,59 @@ export declare const asserts: typeof 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 declare function decodeUnknownEffect<S extends Top>(schema: S): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
+export declare function decodeUnknownEffect<S extends Top>(schema: S, options?: AST.ParseOptions): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * 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 declare const decodeEffect: <S extends Top>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
+export declare const decodeEffect: <S extends Top>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
 /**
  * Decodes an `unknown` input against a schema synchronously, returning an
  * `Exit` that is either a `Success` with the decoded value or a `Failure` with
  * 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 declare function decodeUnknownExit<S extends Decoder<unknown>>(schema: S): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
+export declare function decodeUnknownExit<S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
  * synchronously, returning an `Exit` that is either a `Success` with the
  * 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 declare const decodeExit: <S extends Decoder<unknown>>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
+export declare const decodeExit: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
 /**
  * Decodes an `unknown` input against a schema, returning an `Option` that is
  * `Some` with the decoded value on success or `None` on failure. Prefer this
  * 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
@@ -938,27 +950,43 @@ export declare const decodeUnknownOption: typeof 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
  */
-export declare const decodeOption: <S extends Decoder<unknown>>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Option_.Option<S["Type"]>;
+export declare const decodeOption: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Option_.Option<S["Type"]>;
 /**
- * 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
  */
 export declare const decodeUnknownResult: typeof 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 declare const decodeResult: <S extends Decoder<unknown>>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Result_.Result<S["Type"], Issue.Issue>;
+export declare const decodeResult: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Result_.Result<S["Type"], Issue.Issue>;
 /**
+ * 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
  */
@@ -966,19 +994,27 @@ export declare const decodeUnknownPromise: typeof 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
  */
 export declare const decodePromise: typeof 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)
  *
@@ -1003,18 +1039,25 @@ export declare const decodePromise: typeof Parser.decodePromise;
 export declare const decodeUnknownSync: typeof 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
  */
-export declare const decodeSync: <S extends Decoder<unknown>>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => S["Type"];
+export declare const decodeSync: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => S["Type"];
 /**
  * Encodes an `unknown` input against a schema, returning an `Effect` that
  * 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)
  *
@@ -1030,45 +1073,53 @@ export declare const decodeSync: <S extends Decoder<unknown>>(schema: S) => (inp
  * @category Encoding
  * @since 4.0.0
  */
-export declare function encodeUnknownEffect<S extends Top>(schema: S): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
+export declare function encodeUnknownEffect<S extends Top>(schema: S, options?: AST.ParseOptions): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `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 declare const encodeEffect: <S extends Top>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
+export declare const encodeEffect: <S extends Top>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
 /**
  * Encodes an `unknown` input against a schema synchronously, returning an
  * `Exit` that is either a `Success` with the encoded value or a `Failure` with
  * 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 declare function encodeUnknownExit<S extends Encoder<unknown>>(schema: S): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
+export declare function encodeUnknownExit<S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
  * returning an `Exit` that is either a `Success` with the encoded value or a
  * `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 declare const encodeExit: <S extends Encoder<unknown>>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
+export declare const encodeExit: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
 /**
  * Encodes an `unknown` input against a schema, returning an `Option` that is
  * `Some` with the encoded value on success or `None` on failure. Prefer this
  * 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
@@ -1078,40 +1129,58 @@ export declare const encodeUnknownOption: typeof 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
  */
-export declare const encodeOption: <S extends Encoder<unknown>>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Option_.Option<S["Encoded"]>;
+export declare const encodeOption: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Option_.Option<S["Encoded"]>;
 /**
- * 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
  */
 export declare const encodeUnknownResult: typeof 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 declare const encodeResult: <S extends Encoder<unknown>>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Result_.Result<S["Encoded"], Issue.Issue>;
+export declare const encodeResult: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Result_.Result<S["Encoded"], Issue.Issue>;
 /**
+ * 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
  */
-export declare const encodeUnknownPromise: <S extends Encoder<unknown>>(schema: S) => (input: unknown, options?: AST.ParseOptions) => Promise<S["Encoded"]>;
+export declare const encodeUnknownPromise: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: unknown, options?: AST.ParseOptions) => Promise<S["Encoded"]>;
 /**
  * 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
  */
-export declare const encodePromise: <S extends Encoder<unknown>>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Promise<S["Encoded"]>;
+export declare const encodePromise: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Promise<S["Encoded"]>;
 /**
  * Encodes an `unknown` input against a schema synchronously, throwing a
  * {@link SchemaError} on failure. Use this when you want to serialize data at a
@@ -1119,6 +1188,8 @@ export declare const encodePromise: <S extends Encoder<unknown>>(schema: S) => (
  * 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
@@ -1128,11 +1199,13 @@ export declare const encodeUnknownSync: typeof 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
  */
-export declare const encodeSync: <S extends Encoder<unknown>>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => S["Encoded"];
+export declare const encodeSync: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => S["Encoded"];
 /**
  * Creates a schema from an AST (Abstract Syntax Tree) node.
  *
@@ -1407,25 +1480,41 @@ export declare function Literal<L extends AST.LiteralValue>(literal: L): Literal
  */
 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
      */
     interface SchemaPart extends Top {
         readonly Encoded: string | number | bigint;
     }
     /**
+     * Literal value that can be used directly as a part of a `TemplateLiteral`.
+     *
      * @since 4.0.0
      */
     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
      */
     type Part = SchemaPart | LiteralPart;
     /**
+     * Ordered list of parts used to construct a `TemplateLiteral` schema.
+     *
      * @since 4.0.0
      */
     type Parts = ReadonlyArray<Part>;
     type AppendType<Template extends string, Next> = Next extends LiteralPart ? `${Template}${Next}` : Next extends Codec<unknown, infer E extends LiteralPart, unknown, unknown> ? `${Template}${E}` : never;
     /**
+     * Computes the encoded string literal type produced by concatenating the encoded
+     * forms of all template literal parts.
+     *
      * @since 4.0.0
      */
     type Encoded<Parts> = Parts extends readonly [...infer Init, infer Last] ? AppendType<Encoded<Init>, Last> : ``;
@@ -1463,6 +1552,12 @@ export declare function TemplateLiteral<const Parts extends TemplateLiteral.Part
  */
 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
      */
     type Type<Parts> = Parts extends readonly [infer Head, ...infer Tail] ? readonly [
@@ -1497,8 +1592,8 @@ export interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> exte
  */
 export declare function TemplateLiteralParser<const Parts extends TemplateLiteral.Parts>(parts: Parts): TemplateLiteralParser<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
@@ -1777,6 +1872,12 @@ export declare namespace Struct {
         -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
      */
     type Type<F extends Fields> = Simplify<Type_<F>>;
@@ -1790,6 +1891,13 @@ export declare namespace Struct {
         -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
      */
     type Iso<F extends Fields> = Simplify<Iso_<F>>;
@@ -1813,16 +1921,29 @@ export declare namespace Struct {
         -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
      */
     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
      */
     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
      */
     type EncodingServices<F extends Fields> = {
@@ -1839,11 +1960,24 @@ 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
      */
     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 Bottom<Struct.Type<Fields>, Struct.Encoded<Fields>, Struct.DecodingServices<Fields>, Struct.EncodingServices<Fields>, AST.Objects, Struct<Fields>, Struct.MakeIn<Fields>, Struct.Iso<Fields>> {
@@ -2032,6 +2166,12 @@ derive: {
  */
 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
      */
     interface Key extends Codec<PropertyKey, PropertyKey, unknown, unknown> {
@@ -2039,6 +2179,14 @@ export declare namespace Record {
         readonly "Iso": PropertyKey;
     }
     /**
+     * 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
      */
     type Type<Key extends Record.Key, Value extends Top> = Value extends {
@@ -2057,6 +2205,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
      */
     type Iso<Key extends Record.Key, Value extends Top> = Value extends {
@@ -2075,6 +2226,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
      */
     type Encoded<Key extends Record.Key, Value extends Top> = Value extends {
@@ -2093,14 +2251,27 @@ 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
      */
     type DecodingServices<Key extends Record.Key, Value extends Top> = Key["DecodingServices"] | Value["DecodingServices"];
     /**
+     * Union of the encoding service requirements of a record's key schema and value
+     * schema.
+     *
      * @since 4.0.0
      */
     type EncodingServices<Key extends Record.Key, Value extends Top> = Key["EncodingServices"] | 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
      */
     type MakeIn<Key extends Record.Key, Value extends Top> = Value extends {
@@ -2166,47 +2337,72 @@ export declare function Record<Key extends Record.Key, Value extends Top>(key: K
  */
 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
      */
     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
      */
     type Records = ReadonlyArray<$Record<Record.Key, Top>>;
     type MergeTuple<T extends ReadonlyArray<unknown>> = T extends readonly [infer Head, ...infer Tail] ? Head & MergeTuple<Tail> : {};
     /**
+     * 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
      */
     type Type<S extends Objects, Records extends StructWithRest.Records> = S["Type"] & 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
      */
     type Iso<S extends Objects, Records extends StructWithRest.Records> = S["Iso"] & 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
      */
     type Encoded<S extends Objects, Records extends StructWithRest.Records> = S["Encoded"] & 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
      */
     type DecodingServices<S extends Objects, Records extends StructWithRest.Records> = S["DecodingServices"] | {
         [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
      */
     type EncodingServices<S extends Objects, Records extends StructWithRest.Records> = S["EncodingServices"] | {
         [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
      */
     type MakeIn<S extends Objects, Records extends StructWithRest.Records> = S["~type.make"] & MergeTuple<{
@@ -2257,6 +2453,9 @@ export declare function StructWithRest<const S extends StructWithRest.Objects, c
  */
 export declare namespace Tuple {
     /**
+     * Constraint for the readonly array of element schemas used to define a
+     * fixed-length `Tuple` schema.
+     *
      * @since 4.0.0
      */
     type Elements = ReadonlyArray<Top>;
@@ -2266,6 +2465,12 @@ export declare namespace Tuple {
         readonly "~type.optionality": "optional";
     } ? Type_<Tail, readonly [...Out, T?]> : Type_<Tail, readonly [...Out, T]> : Out : 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
      */
     type Type<E extends Elements> = Type_<E>;
@@ -2275,6 +2480,9 @@ export declare namespace Tuple {
         readonly "~type.optionality": "optional";
     } ? Iso_<Tail, readonly [...Out, T?]> : Iso_<Tail, readonly [...Out, T]> : Out : Out;
     /**
+     * Computes the iso tuple type for a tuple element schema array from each
+     * element schema's `Iso` type.
+     *
      * @since 4.0.0
      */
     type Iso<E extends Elements> = Iso_<E>;
@@ -2284,14 +2492,26 @@ export declare namespace Tuple {
         readonly "~encoded.optionality": "optional";
     } ? Encoded_<Tail, readonly [...Out, T?]> : Encoded_<Tail, readonly [...Out, T]> : Out : 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
      */
     type Encoded<E extends Elements> = Encoded_<E>;
     /**
+     * Union of all decoding service requirements needed by the tuple element
+     * schemas.
+     *
      * @since 4.0.0
      */
     type DecodingServices<E extends Elements> = E[number]["DecodingServices"];
     /**
+     * Union of all encoding service requirements needed by the tuple element
+     * schemas.
+     *
      * @since 4.0.0
      */
     type EncodingServices<E extends Elements> = E[number]["EncodingServices"];
@@ -2303,6 +2523,12 @@ export declare namespace Tuple {
         readonly "~type.constructor.default": "with-default";
     } ? MakeIn_<Tail, readonly [...Out, T?]> : MakeIn_<Tail, readonly [...Out, T]> : Out : 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
      */
     type MakeIn<E extends Elements> = MakeIn_<E>;
@@ -2363,6 +2589,9 @@ export declare function Tuple<const Elements extends ReadonlyArray<Top>>(element
  */
 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
      */
     type TupleType = Top & {
@@ -2373,10 +2602,23 @@ export declare namespace TupleWithRest {
         readonly "Iso": ReadonlyArray<unknown>;
     };
     /**
+     * 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
      */
     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
      */
     type Type<T extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends readonly [infer Head extends Top, ...infer Tail extends ReadonlyArray<Top>] ? Readonly<[
@@ -2387,6 +2629,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
      */
     type Iso<T extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends readonly [infer Head extends Top, ...infer Tail extends ReadonlyArray<Top>] ? Readonly<[
@@ -2397,6 +2646,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
      */
     type Encoded<E extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends readonly [infer Head extends Top, ...infer Tail extends ReadonlyArray<Top>] ? readonly [
@@ -2407,6 +2663,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
      */
     type MakeIn<M extends ReadonlyArray<unknown>, Rest extends TupleWithRest.Rest> = Rest extends readonly [infer Head extends Top, ...infer Tail extends ReadonlyArray<Top>] ? readonly [
@@ -2428,9 +2691,14 @@ export interface TupleWithRest<S extends TupleWithRest.TupleType, Rest extends T
     readonly rest: Rest;
 }
 /**
- * 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)
  *
@@ -2453,7 +2721,12 @@ export interface TupleWithRest<S extends TupleWithRest.TupleType, Rest extends T
  */
 export declare function TupleWithRest<S extends Tuple<Tuple.Elements>, const Rest extends TupleWithRest.Rest>(schema: S, rest: Rest): TupleWithRest<S, Rest>;
 /**
- * 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
  */
@@ -2521,6 +2794,13 @@ interface NonEmptyArrayLambda extends Lambda {
  */
 export declare const NonEmptyArray: NonEmptyArrayLambda;
 /**
+ * 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
  */
@@ -2528,15 +2808,16 @@ export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>,
     readonly "Rebuild": ArrayEnsure<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
@@ -2813,6 +3094,12 @@ export interface refine<T extends S["Type"], S extends Top> extends Bottom<T, S[
  * 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
  */
@@ -2959,10 +3246,13 @@ export declare function catchEncoding<S extends Top>(f: (issue: Issue.Issue) =>
  */
 export declare function catchEncodingWithContext<S extends Top, R = never>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue, R>): (self: S) => middlewareEncoding<S, S["EncodingServices"] | R>;
 /**
- * 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
@@ -3134,7 +3424,14 @@ export interface WithoutConstructorDefault {
     readonly "~type.constructor.default": "no-default";
 }
 /**
- * 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
@@ -3166,7 +3463,7 @@ export interface withConstructorDefault<S extends Top & WithoutConstructorDefaul
  *
  * @since 4.0.0
  */
-export declare function withConstructorDefault<S extends Top & WithoutConstructorDefault>(defaultValue: Effect.Effect<S["~type.make.in"]>): (schema: S) => withConstructorDefault<S>;
+export declare function withConstructorDefault<S extends Top & WithoutConstructorDefault>(defaultValue: Effect.Effect<S["~type.make.in"], SchemaError>): (schema: S) => withConstructorDefault<S>;
 /**
  * The type produced by {@link withDecodingDefaultKey}: a schema whose `Encoded`
  * side is `optionalKey` and that fills in a default `Encoded` value during decoding.
@@ -3174,8 +3471,8 @@ export declare function withConstructorDefault<S extends Top & WithoutConstructo
  * @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>;
 }
 /**
  * Options for {@link withDecodingDefaultKey} and {@link withDecodingDefault}.
@@ -3220,7 +3517,7 @@ export type DecodingDefaultOptions = {
  * @see {@link withDecodingDefaultTypeKey} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
-export declare function withDecodingDefaultKey<S extends Top>(defaultValue: Effect.Effect<S["Encoded"]>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultKey<S>;
+export declare function withDecodingDefaultKey<S extends Top, R = never>(defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultKey<S, R>;
 /**
  * The type produced by {@link withDecodingDefaultTypeKey}: a schema whose
  * `Encoded` side is `optionalKey` and that fills in a default `Type` value
@@ -3229,8 +3526,8 @@ export declare function withDecodingDefaultKey<S extends Top>(defaultValue: Effe
  * @see {@link withDecodingDefaultTypeKey} for the constructor
  * @since 4.0.0
  */
-export interface withDecodingDefaultTypeKey<S extends Top> extends decodeTo<withDecodingDefaultKey<toType<S>>, optionalKey<S>> {
-    readonly "Rebuild": withDecodingDefaultTypeKey<S>;
+export interface withDecodingDefaultTypeKey<S extends Top, R = never> extends decodeTo<withDecodingDefaultKey<toType<S>, R>, optionalKey<S>> {
+    readonly "Rebuild": withDecodingDefaultTypeKey<S, R>;
 }
 /**
  * Makes a struct key optional on the `Encoded` side (`optionalKey`, so the
@@ -3251,7 +3548,7 @@ export interface withDecodingDefaultTypeKey<S extends Top> extends decodeTo<with
  * @see {@link withDecodingDefaultType} for the value-level variant
  * @since 4.0.0
  */
-export declare function withDecodingDefaultTypeKey<S extends Top>(defaultValue: Effect.Effect<S["Type"]>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S>;
+export declare function withDecodingDefaultTypeKey<S extends Top, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultTypeKey<S, R>;
 /**
  * The type produced by {@link withDecodingDefault}: a schema whose `Encoded`
  * side is `optional` and that fills in a default `Encoded` value during decoding.
@@ -3259,8 +3556,8 @@ export declare function withDecodingDefaultTypeKey<S extends Top>(defaultValue:
  * @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>;
 }
 /**
  * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
@@ -3293,7 +3590,7 @@ 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 declare function withDecodingDefault<S extends Top>(defaultValue: Effect.Effect<S["Encoded"]>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefault<S>;
+export declare function withDecodingDefault<S extends Top, R = never>(defaultValue: Effect.Effect<S["Encoded"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefault<S, R>;
 /**
  * The type produced by {@link withDecodingDefaultType}: a schema whose
  * `Encoded` side is `optional` and that fills in a default `Type` value during
@@ -3302,8 +3599,8 @@ export declare function withDecodingDefault<S extends Top>(defaultValue: Effect.
  * @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>;
 }
 /**
  * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
@@ -3324,7 +3621,7 @@ export interface withDecodingDefaultType<S extends Top> extends decodeTo<withDec
  * @see {@link withDecodingDefaultTypeKey} for the key-level variant
  * @since 4.0.0
  */
-export declare function withDecodingDefaultType<S extends Top>(defaultValue: Effect.Effect<S["Type"]>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S>;
+export declare function withDecodingDefaultType<S extends Top, R = never>(defaultValue: Effect.Effect<S["Type"], SchemaError, R>, options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultType<S, R>;
 /**
  * The type produced by {@link tag} — a literal schema with a constructor default.
  *
@@ -3380,7 +3677,7 @@ export declare function tag<Tag extends AST.LiteralValue>(literal: Tag): tag<Tag
  * @see {@link tag} for the variant that keeps the tag during encoding
  * @since 4.0.0
  */
-export declare function tagDefaultOmit<Tag extends AST.LiteralValue>(literal: Tag): withDecodingDefaultKey<tag<Tag>>;
+export declare function tagDefaultOmit<Tag extends AST.LiteralValue>(literal: Tag): withDecodingDefaultKey<tag<Tag>, never>;
 /**
  * The type produced by {@link TaggedStruct} — a {@link Struct} with an extra `_tag` field of type {@link tag}.
  *
@@ -3641,9 +3938,17 @@ export declare function link<T>(): <To extends Top>(encodeTo: To, transformation
     readonly encode: Getter.Getter<NoInfer<To["Type"]>, T>;
 }) => AST.Link;
 /**
- * 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)
  *
@@ -3791,34 +4096,29 @@ export declare const isPattern: (regExp: globalThis.RegExp, annotations?: Annota
  */
 export declare const isStringFinite: (annotations?: Annotations.Filter) => AST.Filter<string>;
 /**
- * Validates that a string represents a valid BigInt (can be parsed as a BigInt).
- *
- * **JSON Schema**
+ * Validates that a string is a signed base-10 integer literal for Effect's
+ * BigInt string encoding.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing BigInt values.
- *
- * **Arbitrary**
+ * **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.
  *
- * 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
  */
 export declare const isStringBigInt: (annotations?: Annotations.Filter) => AST.Filter<string>;
 /**
- * Validates that a string represents a valid Symbol (can be parsed as a Symbol).
- *
- * **JSON Schema**
+ * Validates that a string has the `Symbol(description)` format used by Effect's
+ * symbol string encoding.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing Symbol values.
- *
- * **Arbitrary**
- *
- * 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
@@ -3897,119 +4197,84 @@ export declare function isBase64(annotations?: Annotations.Filter): AST.Filter<s
  */
 export declare function isBase64Url(annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * Validates that a string starts with the specified prefix.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings starting with the specified prefix.
- *
- * **Arbitrary**
+ * Validates at runtime that a string starts with the specified literal prefix.
  *
- * 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
  */
 export declare function isStartsWith(startsWith: string, annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * Validates that a string ends with the specified suffix.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings ending with the specified suffix.
- *
- * **Arbitrary**
+ * Validates at runtime that a string ends with the specified literal suffix.
  *
- * 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
  */
 export declare function isEndsWith(endsWith: string, annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * 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
  */
 export declare function isIncludes(includes: string, annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * 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
  */
 export declare function isUppercased(annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * Validates that a string contains only lowercase characters.
+ * Validates that a string is unchanged by JavaScript's `toLowerCase()`.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only lowercase characters.
- *
- * **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
  */
 export declare function isLowercased(annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * Validates that a string has its first character in uppercase.
+ * Validates that the first character of a string is unchanged by
+ * `toUpperCase()`.
  *
- * **JSON Schema**
- *
- * 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
  */
 export declare function isCapitalized(annotations?: Annotations.Filter): AST.Filter<string>;
 /**
- * Validates that a string has its first character in lowercase.
+ * Validates that the first character of a string is unchanged by
+ * `toLowerCase()`.
  *
- * **JSON Schema**
- *
- * 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
@@ -4485,7 +4750,11 @@ export declare const isLessThanBigDecimal: (exclusiveMaximum: BigDecimal_.BigDec
  */
 export declare const isLessThanOrEqualToBigDecimal: (maximum: BigDecimal_.BigDecimal, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
 /**
- * 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
@@ -4709,37 +4978,38 @@ export declare function isMaxProperties(maxProperties: number, annotations?: Ann
  */
 export declare function isPropertiesLengthBetween(minimum: number, maximum: number, annotations?: Annotations.Filter): AST.Filter<object>;
 /**
- * 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
  */
 export declare function isPropertyNames(keySchema: Top, annotations?: Annotations.Filter): AST.Filter<object>;
 /**
- * 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
  */
 export declare function isUnique<T>(annotations?: Annotations.Filter): AST.Filter<readonly T[]>;
 /**
- * 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
@@ -4756,7 +5026,8 @@ export interface NonEmptyString extends String {
  */
 export declare const NonEmptyString: NonEmptyString;
 /**
- * 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
@@ -4797,6 +5068,12 @@ export interface Option<A extends Top> extends declareConstructor<Option_.Option
     readonly value: A;
 }
 /**
+ * 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
  */
@@ -4814,7 +5091,8 @@ export type OptionIso<A extends Top> = {
  */
 export declare 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
@@ -4838,7 +5116,8 @@ export interface OptionFromNullOr<S extends Top> extends decodeTo<Option<toType<
  */
 export declare 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
@@ -4862,7 +5141,8 @@ export interface OptionFromUndefinedOr<S extends Top> extends decodeTo<Option<to
  */
 export declare function OptionFromUndefinedOr<S extends Top>(schema: S): OptionFromUndefinedOr<S>;
 /**
- * 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
@@ -4888,7 +5168,8 @@ export declare function OptionFromNullishOr<S extends Top>(schema: S, options?:
     onNoneEncoding: null | undefined;
 }): OptionFromNullishOr<S>;
 /**
- * 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
@@ -4912,7 +5193,8 @@ export interface OptionFromOptionalKey<S extends Top> extends decodeTo<Option<to
  */
 export declare function OptionFromOptionalKey<S extends Top>(schema: S): OptionFromOptionalKey<S>;
 /**
- * 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
@@ -4938,7 +5220,8 @@ export interface OptionFromOptional<S extends Top> extends decodeTo<Option<toTyp
  */
 export declare function OptionFromOptional<S extends Top>(schema: S): OptionFromOptional<S>;
 /**
- * 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
@@ -4981,6 +5264,12 @@ export interface Result<A extends Top, E extends Top> extends declareConstructor
     readonly failure: E;
 }
 /**
+ * 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
  */
@@ -5036,7 +5325,8 @@ export declare function Redacted<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
 }): Redacted<S>;
 /**
- * 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
@@ -5064,10 +5354,14 @@ export declare function RedactedFromValue<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
 }): RedactedFromValue<S>;
 /**
- * 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
  */
@@ -5077,6 +5371,12 @@ export interface CauseReason<E extends Top, D extends Top> extends declareConstr
     readonly defect: D;
 }
 /**
+ * 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
  */
@@ -5091,15 +5391,20 @@ export type CauseReasonIso<E extends Top, D extends Top> = {
     readonly fiberId: number | undefined;
 };
 /**
- * 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
  */
 export declare function CauseReason<E extends Top, D extends Top>(error: E, defect: D): CauseReason<E, D>;
 /**
- * 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
@@ -5110,19 +5415,23 @@ export interface Cause<E extends Top, D extends Top> extends declareConstructor<
     readonly defect: D;
 }
 /**
+ * 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
  */
 export declare function Cause<E extends Top, D extends Top>(error: E, defect: D): Cause<E, D>;
 /**
- * Companion type for {@link Error}.
+ * Type-level representation of the schema for JavaScript `Error` instances.
  *
  * @category Error
  * @since 4.0.0
@@ -5131,27 +5440,32 @@ export interface Error extends instanceOf<globalThis.Error> {
     readonly "Rebuild": Error;
 }
 /**
- * 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
  */
 export declare const Error: 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
  */
 export declare const ErrorWithStack: 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
@@ -5167,7 +5481,12 @@ export interface Defect extends Union<readonly [
     readonly "Rebuild": Defect;
 }
 /**
- * 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
@@ -5182,8 +5501,8 @@ export declare const Defect: Defect;
  */
 export declare const DefectWithStack: Defect;
 /**
- * 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
@@ -5195,6 +5514,12 @@ export interface Exit<A extends Top, E extends Top, D extends Top> extends decla
     readonly defect: D;
 }
 /**
+ * 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
  */
@@ -5206,14 +5531,16 @@ export type ExitIso<A extends Top, E extends Top, D extends Top> = {
     readonly cause: CauseIso<E, D>;
 };
 /**
- * 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
  */
 export declare function Exit<A extends Top, E extends Top, D extends Top>(value: A, error: E, defect: D): Exit<A, E, D>;
 /**
- * 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
@@ -5224,6 +5551,9 @@ export interface $ReadonlyMap<Key extends Top, Value extends Top> extends declar
     readonly value: Value;
 }
 /**
+ * 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
  */
@@ -5249,6 +5579,9 @@ export interface HashMap<Key extends Top, Value extends Top> extends declareCons
     readonly value: Value;
 }
 /**
+ * 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
  */
@@ -5262,7 +5595,8 @@ export type HashMapIso<Key extends Top, Value extends Top> = ReadonlyArray<reado
  */
 export declare function HashMap<Key extends Top, Value extends Top>(key: Key, value: Value): HashMap<Key, Value>;
 /**
- * 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
@@ -5272,11 +5606,17 @@ export interface $ReadonlySet<Value extends Top> extends declareConstructor<glob
     readonly value: Value;
 }
 /**
+ * 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
  */
@@ -5293,6 +5633,9 @@ export interface HashSet<Value extends Top> extends declareConstructor<HashSet_.
     readonly value: Value;
 }
 /**
+ * Iso representation used for `HashSet` schemas: an array of element values
+ * using the element schema's `Iso` type.
+ *
  * @category HashSet
  * @since 4.0.0
  */
@@ -5317,6 +5660,9 @@ export interface Chunk<Value extends Top> extends declareConstructor<Chunk_.Chun
     readonly value: Value;
 }
 /**
+ * Iso representation used for `Chunk` schemas: an array of element values using
+ * the element schema's `Iso` type.
+ *
  * @category Chunk
  * @since 4.0.0
  */
@@ -5330,7 +5676,7 @@ export type ChunkIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
  */
 export declare 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
@@ -5348,7 +5694,7 @@ export interface RegExp extends instanceOf<globalThis.RegExp> {
  */
 export declare const RegExp: RegExp;
 /**
- * Companion type for {@link URL}.
+ * Type-level representation of the schema for JavaScript `URL` instances.
  *
  * @category URL
  * @since 4.0.0
@@ -5363,12 +5709,13 @@ export interface URL extends instanceOf<globalThis.URL> {
  *
  * - encodes `URL` as a `string`
  *
- * @since 4.0.0
  * @category URL
+ * @since 4.0.0
  */
 export declare const URL: URL;
 /**
- * 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
@@ -5390,7 +5737,8 @@ export interface URLFromString extends decodeTo<URL, String> {
  */
 export declare const URLFromString: 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
@@ -5401,9 +5749,10 @@ export interface Date extends instanceOf<globalThis.Date> {
 /**
  * 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)
  *
@@ -5419,7 +5768,8 @@ export interface Date extends instanceOf<globalThis.Date> {
  */
 export declare const Date: Date;
 /**
- * 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
@@ -5428,20 +5778,23 @@ export interface DateFromString extends decodeTo<Date, String> {
     readonly "Rebuild": DateFromString;
 }
 /**
- * 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
  */
 export declare const DateFromString: 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
@@ -5460,7 +5813,7 @@ export interface DateValid extends Date {
  */
 export declare const DateValid: DateValid;
 /**
- * Companion type for {@link Duration}.
+ * Type-level representation of the schema for Effect `Duration` values.
  *
  * @category Duration
  * @since 4.0.0
@@ -5490,7 +5843,8 @@ export interface Duration extends declare<Duration_.Duration> {
  */
 export declare const Duration: 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
@@ -5513,7 +5867,8 @@ export interface DurationFromString extends decodeTo<Duration, String> {
  */
 export declare const DurationFromString: DurationFromString;
 /**
- * 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
@@ -5523,20 +5878,23 @@ export interface DurationFromNanos extends decodeTo<Duration, BigInt> {
 }
 /**
  * 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
  */
 export declare const DurationFromNanos: DurationFromNanos;
 /**
- * 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
@@ -5562,7 +5920,7 @@ export interface DurationFromMillis extends decodeTo<Duration, Number> {
  */
 export declare const DurationFromMillis: DurationFromMillis;
 /**
- * Companion type for {@link BigDecimal}.
+ * Type-level representation of the schema for Effect `BigDecimal` values.
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -5582,7 +5940,8 @@ export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
  */
 export declare const BigDecimal: BigDecimal;
 /**
- * Companion type for {@link BigDecimalFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * `BigDecimal` values.
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -5604,7 +5963,8 @@ export interface BigDecimalFromString extends decodeTo<BigDecimal, String> {
  */
 export declare const BigDecimalFromString: BigDecimalFromString;
 /**
- * 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
@@ -5637,7 +5997,8 @@ export interface UnknownFromJsonString extends fromJsonString<Unknown> {
  */
 export declare const UnknownFromJsonString: UnknownFromJsonString;
 /**
- * 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
@@ -5711,7 +6072,7 @@ export interface fromJsonString<S extends Top> extends decodeTo<S, String> {
  */
 export declare 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
@@ -5730,7 +6091,7 @@ export interface File extends instanceOf<globalThis.File> {
  */
 export declare const File: File;
 /**
- * Companion type for {@link FormData}.
+ * Type-level representation of the schema for JavaScript `FormData` instances.
  *
  * @category FormData
  * @since 4.0.0
@@ -5749,7 +6110,8 @@ export interface FormData extends instanceOf<globalThis.FormData> {
  */
 export declare const FormData: 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
@@ -5842,7 +6204,8 @@ export interface fromFormData<S extends Top> extends decodeTo<S, FormData> {
  */
 export declare 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
@@ -5860,7 +6223,8 @@ export interface URLSearchParams extends instanceOf<globalThis.URLSearchParams>
  */
 export declare const URLSearchParams: URLSearchParams;
 /**
- * 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
@@ -5944,7 +6308,8 @@ export interface fromURLSearchParams<S extends Top> extends decodeTo<S, URLSearc
  */
 export declare function fromURLSearchParams<S extends Top>(schema: S): fromURLSearchParams<S>;
 /**
- * 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
@@ -5960,7 +6325,8 @@ export interface Finite extends Number {
  */
 export declare const Finite: Finite;
 /**
- * Companion type for {@link Int}.
+ * Type-level representation of the `Int` schema, which accepts only finite
+ * integer numbers.
  *
  * @category Number
  * @since 4.0.0
@@ -5976,7 +6342,8 @@ export interface Int extends Number {
  */
 export declare const Int: Int;
 /**
- * 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
@@ -5985,20 +6352,24 @@ export interface NumberFromString extends decodeTo<Finite, String> {
     readonly "Rebuild": NumberFromString;
 }
 /**
- * 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
  */
 export declare const NumberFromString: 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
@@ -6021,7 +6392,8 @@ export interface FiniteFromString extends decodeTo<Finite, String> {
  */
 export declare const FiniteFromString: FiniteFromString;
 /**
- * Companion type for {@link BigIntFromString}.
+ * Type-level representation of a transformation schema that decodes strings into
+ * `bigint` values.
  *
  * @category BigInt
  * @since 4.0.0
@@ -6043,7 +6415,8 @@ export interface BigIntFromString extends decodeTo<BigInt, String> {
  */
 export declare const BigIntFromString: BigIntFromString;
 /**
- * Companion type for {@link Trimmed}.
+ * Schema interface for `Trimmed`, representing strings with no leading or
+ * trailing whitespace.
  *
  * @category String
  * @since 4.0.0
@@ -6059,7 +6432,8 @@ export interface Trimmed extends String {
  */
 export declare const Trimmed: Trimmed;
 /**
- * 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
@@ -6081,7 +6455,8 @@ export interface Trim extends decodeTo<Trimmed, String> {
  */
 export declare const Trim: 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
@@ -6103,7 +6478,8 @@ export interface StringFromBase64 extends decodeTo<String, String> {
  */
 export declare const StringFromBase64: StringFromBase64;
 /**
- * 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
@@ -6125,7 +6501,8 @@ export interface StringFromBase64Url extends decodeTo<String, String> {
  */
 export declare const StringFromBase64Url: StringFromBase64Url;
 /**
- * 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
@@ -6147,7 +6524,8 @@ export interface StringFromHex extends decodeTo<String, String> {
  */
 export declare const StringFromHex: StringFromHex;
 /**
- * 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
@@ -6188,13 +6566,19 @@ export interface StringFromUriComponent extends decodeTo<String, String> {
  */
 export declare const StringFromUriComponent: StringFromUriComponent;
 /**
- * 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
  */
 export declare const PropertyKey: Union<readonly [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
  */
@@ -6207,7 +6591,8 @@ export declare 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
@@ -6223,7 +6608,8 @@ export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0,
  */
 export declare const BooleanFromBit: BooleanFromBit;
 /**
- * Companion type for {@link Uint8Array}.
+ * Schema interface for `Uint8Array`, representing JavaScript `Uint8Array`
+ * instances with base64 JSON encoding.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -6243,7 +6629,8 @@ export interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBuffer
  */
 export declare const Uint8Array: Uint8Array;
 /**
- * Companion type for {@link Uint8ArrayFromBase64}.
+ * Schema interface for `Uint8ArrayFromBase64`, a transformation between
+ * base64-encoded strings and `Uint8Array` values.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -6266,7 +6653,8 @@ export interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromBase64: Uint8ArrayFromBase64;
 /**
- * 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
@@ -6289,7 +6677,8 @@ export interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromBase64Url: Uint8ArrayFromBase64Url;
 /**
- * Companion type for {@link Uint8ArrayFromHex}.
+ * Schema interface for `Uint8ArrayFromHex`, a transformation between
+ * hex-encoded strings and `Uint8Array` values.
  *
  * @category Uint8Array
  * @since 4.0.0
@@ -6312,7 +6701,8 @@ export interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromHex: Uint8ArrayFromHex;
 /**
- * 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
@@ -6332,7 +6722,8 @@ export interface DateTimeUtc extends declare<DateTime.Utc> {
  */
 export declare const DateTimeUtc: DateTimeUtc;
 /**
- * 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
@@ -6354,7 +6745,8 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
  */
 export declare const DateTimeUtcFromDate: DateTimeUtcFromDate;
 /**
- * Companion type for {@link DateTimeUtcFromString}.
+ * Schema interface for `DateTimeUtcFromString`, a transformation from date-time
+ * strings to `DateTime.Utc`.
  *
  * @category DateTime
  * @since 4.0.0
@@ -6363,22 +6755,24 @@ export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
     readonly "Rebuild": DateTimeUtcFromString;
 }
 /**
- * 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
  */
 export declare const DateTimeUtcFromString: DateTimeUtcFromString;
 /**
- * Companion type for {@link DateTimeUtcFromMillis}.
+ * Schema interface for `DateTimeUtcFromMillis`, a transformation between epoch
+ * milliseconds and `DateTime.Utc` values.
  *
  * @category DateTime
  * @since 4.0.0
@@ -6400,7 +6794,8 @@ export interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>
  */
 export declare const DateTimeUtcFromMillis: DateTimeUtcFromMillis;
 /**
- * Companion type for {@link TimeZoneOffset}.
+ * Schema interface for `TimeZoneOffset`, representing
+ * `DateTime.TimeZone.Offset` values encoded as offset milliseconds.
  *
  * @category DateTime
  * @since 4.0.0
@@ -6420,7 +6815,8 @@ export interface TimeZoneOffset extends declare<DateTime.TimeZone.Offset> {
  */
 export declare const TimeZoneOffset: TimeZoneOffset;
 /**
- * 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
@@ -6440,7 +6836,8 @@ export interface TimeZoneNamed extends declare<DateTime.TimeZone.Named> {
  */
 export declare const TimeZoneNamed: TimeZoneNamed;
 /**
- * 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
@@ -6462,7 +6859,8 @@ export interface TimeZoneNamedFromString extends decodeTo<TimeZoneNamed, String>
  */
 export declare const TimeZoneNamedFromString: TimeZoneNamedFromString;
 /**
- * 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
@@ -6483,7 +6881,8 @@ export interface TimeZone extends declare<DateTime.TimeZone> {
  */
 export declare const TimeZone: TimeZone;
 /**
- * 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
@@ -6505,7 +6904,8 @@ export interface TimeZoneFromString extends decodeTo<TimeZone, String> {
  */
 export declare const TimeZoneFromString: TimeZoneFromString;
 /**
- * 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
@@ -6518,7 +6918,9 @@ export interface DateTimeZoned extends declare<DateTime.Zoned> {
  *
  * **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
@@ -6526,7 +6928,8 @@ export interface DateTimeZoned extends declare<DateTime.Zoned> {
  */
 export declare const DateTimeZoned: DateTimeZoned;
 /**
- * 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
@@ -7116,10 +7519,11 @@ export declare function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary
  */
 export declare function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Type"]>;
 /**
- * **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
@@ -7200,17 +7604,19 @@ export interface ToJsonSchemaOptions {
     readonly generateDescriptions?: boolean | undefined;
 }
 /**
- * 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
  */
 export declare function toJsonSchemaDocument(schema: Top, options?: ToJsonSchemaOptions): JsonSchema.Document<"draft-2020-12">;
 /**
- * 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
@@ -7267,9 +7673,11 @@ type XmlEncoderOptions = {
     readonly sortKeys?: boolean | undefined;
 };
 /**
- * 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
@@ -7331,6 +7739,9 @@ export declare function overrideToCodecIso<S extends Top, Iso>(to: Codec<Iso>, t
  */
 export declare function toDifferJsonPatch<T, E>(schema: Codec<T, E>): Differ<T, JsonPatch.JsonPatch>;
 /**
+ * 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
  */
@@ -7398,6 +7809,9 @@ export interface JsonObject {
  */
 export declare const Json: Codec<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
  */
@@ -7508,6 +7922,15 @@ export declare namespace Annotations {
      * @since 4.0.0
      */
     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;
@@ -7552,13 +7975,31 @@ export declare namespace Annotations {
      */
     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;
         /**
@@ -7572,16 +8013,24 @@ export declare namespace Annotations {
         readonly toArbitrary?: ToArbitrary.Declaration<T, TypeParameters> | undefined;
     }
     /**
+     * Helpers for projecting declaration type-parameter schemas into decoded or
+     * encoded codec arrays used by annotation hooks.
+     *
      * @since 4.0.0
      */
     namespace TypeParameters {
         /**
+         * Maps declaration type-parameter schemas to codecs for their decoded `Type`
+         * values.
+         *
          * @since 4.0.0
          */
         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
          */
         type Encoded<TypeParameters extends ReadonlyArray<Top>> = {
@@ -7624,7 +8073,21 @@ export declare namespace Annotations {
      * @since 4.0.0
      */
     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.
@@ -7641,38 +8104,59 @@ export declare namespace Annotations {
         readonly "~structural"?: boolean | undefined;
     }
     /**
+     * Types used by arbitrary-derivation annotations to configure `toArbitrary`
+     * hooks and carry merged fast-check constraints.
+     *
      * @since 4.0.0
      */
     namespace ToArbitrary {
         /**
+         * fast-check string constraints plus optional regular-expression pattern strings
+         * used when deriving string arbitraries from schema checks.
+         *
          * @since 4.0.0
          */
         interface StringConstraints extends FastCheck.StringSharedConstraints {
             readonly patterns?: readonly [string, ...Array<string>];
         }
         /**
+         * fast-check floating-point constraints plus `isInteger`, which switches
+         * derived number arbitraries to integer generation.
+         *
          * @since 4.0.0
          */
         interface NumberConstraints extends FastCheck.FloatConstraints {
             readonly isInteger?: boolean;
         }
         /**
+         * fast-check bigint constraints used when deriving arbitraries for bigint
+         * schemas.
+         *
          * @since 4.0.0
          */
         interface BigIntConstraints extends FastCheck.BigIntConstraints {
         }
         /**
+         * fast-check array constraints plus an optional comparator used when deriving
+         * unique-array arbitraries.
+         *
          * @since 4.0.0
          */
         interface ArrayConstraints extends FastCheck.ArrayConstraints {
             readonly comparator?: (a: any, b: any) => boolean;
         }
         /**
+         * fast-check date constraints used when deriving arbitraries for `Date` and
+         * DateTime schemas.
+         *
          * @since 4.0.0
          */
         interface DateConstraints extends FastCheck.DateConstraints {
         }
         /**
+         * Grouped arbitrary-generation constraints accumulated from schema checks and
+         * passed to `toArbitrary` derivation.
+         *
          * @since 4.0.0
          */
         interface Constraint {
@@ -7683,6 +8167,10 @@ export declare namespace Annotations {
             readonly date?: DateConstraints | undefined;
         }
         /**
+         * Context passed to arbitrary-derivation hooks, including accumulated
+         * constraints and an `isSuspend` flag used to limit recursion for suspended
+         * schemas.
+         *
          * @since 4.0.0
          */
         interface Context {
@@ -7695,6 +8183,11 @@ export declare namespace Annotations {
             readonly constraints?: ToArbitrary.Constraint | undefined;
         }
         /**
+         * 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
          */
         interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -7704,10 +8197,17 @@ export declare namespace Annotations {
         }
     }
     /**
+     * Types used by formatter annotations to customize formatter derivation for
+     * declaration schemas.
+     *
      * @since 4.0.0
      */
     namespace ToFormatter {
         /**
+         * Hook signature for declaration schema formatter annotations.
+         *
+         * Given formatters for any type parameters, returns a formatter for `T`.
+         *
          * @since 4.0.0
          */
         interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -7717,10 +8217,17 @@ export declare namespace Annotations {
         }
     }
     /**
+     * Types used by equivalence annotations to customize equivalence derivation for
+     * declaration schemas.
+     *
      * @since 4.0.0
      */
     namespace ToEquivalence {
         /**
+         * Hook signature for declaration schema equivalence annotations.
+         *
+         * Given equivalences for any type parameters, returns an `Equivalence` for `T`.
+         *
          * @since 4.0.0
          */
         interface Declaration<T, TypeParameters extends ReadonlyArray<Top>> {
@@ -7730,6 +8237,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
      */
@@ -7737,7 +8248,10 @@ export declare namespace Annotations {
         readonly message?: string | undefined;
     }
     /**
-     * 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
      */
@@ -7940,17 +8454,24 @@ export declare namespace Annotations {
         };
     }
     /**
+     * Union of all metadata payloads defined by `BuiltInMetaDefinitions`.
+     *
      * @since 4.0.0
      */
     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
      */
     interface MetaDefinitions extends BuiltInMetaDefinitions {
     }
     /**
+     * Union of built-in and user-augmented schema filter metadata payloads.
+     *
      * @since 4.0.0
      */
     type Meta = MetaDefinitions[keyof MetaDefinitions];