effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Schema.js

@@ -143,10 +143,7 @@ const TypeId = InternalSchema.TypeId;
  * **Example** (Schema for a parametric `Box<A>` type)
  *
  * ```ts
- * import { Effect, Schema } from "effect"
- * import * as SchemaParser from "effect/SchemaParser"
- * import * as Issue from "effect/SchemaIssue"
- * import * as Option from "effect/Option"
+ * import { Effect, Option, Schema, SchemaIssue as Issue, SchemaParser } from "effect"
  *
  * interface Box<A> {
  *   readonly value: A
@@ -173,7 +170,7 @@ const TypeId = InternalSchema.TypeId;
  * const schema = Box(Schema.Number)
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function declareConstructor() {
@@ -207,8 +204,8 @@ export function declareConstructor() {
  *
  * @see {@link declareConstructor} for creating schemas for parametric types.
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function declare(is, annotations) {
   return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new Issue.InvalidType(ast, Option_.some(input))), annotations);
@@ -237,6 +234,7 @@ export function declare(is, annotations) {
  * type E = typeof bottom["Encoded"]  // string
  * ```
  *
+ * @category utils
  * @since 4.0.0
  */
 export function revealBottom(bottom) {
@@ -265,7 +263,7 @@ export function revealBottom(bottom) {
  *
  * @see {@link annotateEncoded} to annotate the encoded side instead.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export function annotate(annotations) {
@@ -296,7 +294,7 @@ export function annotate(annotations) {
  *
  * @see {@link annotate} to annotate the type side instead.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export function annotateEncoded(annotations) {
@@ -327,7 +325,7 @@ export function annotateEncoded(annotations) {
  * })
  * ```
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export function annotateKey(annotations) {
@@ -355,6 +353,7 @@ export function annotateKey(annotations) {
  * type Enc = typeof codec["Encoded"] // string
  * ```
  *
+ * @category utils
  * @since 4.0.0
  */
 export function revealCodec(codec) {
@@ -407,6 +406,7 @@ SchemaError };
  * }
  * ```
  *
+ * @category guards
  * @since 4.0.0
  */
 export function isSchemaError(u) {
@@ -550,7 +550,6 @@ function toBaseStandardJSONSchemaV1(self, target) {
  *
  * @category Standard Schema
  * @since 4.0.0
- * @experimental
  */
 export function toStandardJSONSchemaV1(self) {
   const jsonSchema = {
@@ -604,8 +603,8 @@ export function toStandardJSONSchemaV1(self) {
  * }
  * ```
  *
- * @category Asserting
- * @since 4.0.0
+ * @category guards
+ * @since 3.10.0
  */
 export const is = Parser.is;
 /**
@@ -621,27 +620,22 @@ export const is = Parser.is;
  * ```ts
  * import { Schema } from "effect"
  *
- * const assertString: (u: unknown) => asserts u is string = Schema.asserts(
- *   Schema.String
- * )
+ * const input: unknown = "hello"
  *
- * // This will pass silently (no return value)
- * try {
- *   assertString("hello")
- *   console.log("String assertion passed")
- * } catch (error) {
- *   console.log("String assertion failed")
- * }
+ * // This will pass silently (no return value) and narrow input to string
+ * Schema.asserts(Schema.String, input)
+ * console.log(input.toUpperCase())
  *
  * // This will throw an error
  * try {
- *   assertString(123)
+ *   const invalid: unknown = 123
+ *   Schema.asserts(Schema.String, invalid)
  * } catch (error) {
  *   console.log("Non-string assertion failed as expected")
  * }
  * ```
  *
- * @category Asserting
+ * @category guards
  * @since 4.0.0
  */
 export const asserts = Parser.asserts;
@@ -650,12 +644,14 @@ export const asserts = Parser.asserts;
  * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link decodeEffect} when
  * the input is already typed as the schema's `Encoded` type.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
-export function decodeUnknownEffect(schema) {
-  const parser = Parser.decodeUnknownEffect(schema);
+export function decodeUnknownEffect(schema, options) {
+  const parser = Parser.decodeUnknownEffect(schema, options);
   return (input, options) => {
     return Effect.mapErrorEager(parser(input, options), issue => new SchemaError(issue));
   };
@@ -665,8 +661,10 @@ export function decodeUnknownEffect(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
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeEffect = decodeUnknownEffect;
@@ -676,12 +674,14 @@ export const decodeEffect = decodeUnknownEffect;
  * 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
+ * @category decoding
  * @since 4.0.0
  */
-export function decodeUnknownExit(schema) {
-  const parser = Parser.decodeUnknownExit(schema);
+export function decodeUnknownExit(schema, options) {
+  const parser = Parser.decodeUnknownExit(schema, options);
   return (input, options) => {
     return Exit_.mapError(parser(input, options), issue => new SchemaError(issue));
   };
@@ -692,8 +692,10 @@ export function decodeUnknownExit(schema) {
  * 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
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeExit = decodeUnknownExit;
@@ -703,56 +705,82 @@ export const decodeExit = decodeUnknownExit;
  * 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
+ * @category decoding
+ * @since 3.10.0
  */
 export const decodeUnknownOption = Parser.decodeUnknownOption;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Option` that is `Some` with the decoded value on success or
  * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
- * @category Decoding
- * @since 4.0.0
+ * @category decoding
+ * @since 3.10.0
  */
 export const decodeOption = Parser.decodeOption;
 /**
- * Decodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link decodePromise}.
+ * Decodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the decoded value or fails with a schema issue. For typed input
+ * use {@link decodeResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeUnknownResult = Parser.decodeUnknownResult;
 /**
- * @category Decoding
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Result` that succeeds with the decoded value or fails with a
+ * schema issue. For `unknown` input use {@link decodeUnknownResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeResult = Parser.decodeResult;
 /**
- * @category Decoding
- * @since 4.0.0
+ * 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 3.10.0
  */
 export const decodeUnknownPromise = Parser.decodeUnknownPromise;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning a `Promise` that resolves with the decoded value or rejects with a
- * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ * schema issue. For `unknown` input use `decodeUnknownPromise`.
  *
- * @category Decoding
- * @since 4.0.0
+ * **Details**
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
+ * @category decoding
+ * @since 3.10.0
  */
 export const decodePromise = Parser.decodePromise;
 /**
- * Decodes an `unknown` input against a schema synchronously, throwing a
- * {@link SchemaError} on failure. Use this when you want to validate data at a
- * boundary and treat a schema mismatch as an unrecoverable error. For
- * non-throwing alternatives see {@link decodeUnknownOption},
- * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
- * use {@link decodeSync}.
+ * Decodes an `unknown` input against a schema synchronously, returning the
+ * decoded value or throwing an `Error` whose cause contains the schema issue.
+ * Use this when you want to validate data at a boundary and treat a schema
+ * mismatch as an exception. For typed input use `decodeSync`.
+ *
+ * **Details**
+ * Only service-free schemas can be decoded synchronously. For non-throwing
+ * alternatives see `decodeUnknownOption`, `decodeUnknownExit`, or
+ * `decodeUnknownEffect`. Options may be provided either when creating the
+ * decoder or when applying it; application options override creation options.
  *
  * **Example** (Decoding with a transformation schema)
  *
@@ -771,16 +799,21 @@ export const decodePromise = Parser.decodePromise;
  * //         └─ Expected a numeric string, actual "not a number"
  * ```
  *
- * @category Decoding
+ * @category decoding
  * @since 4.0.0
  */
 export const decodeUnknownSync = Parser.decodeUnknownSync;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
- * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
- * use {@link decodeUnknownSync}.
+ * synchronously, returning the decoded value or throwing an `Error` whose cause
+ * contains the schema issue. For `unknown` input use `decodeUnknownSync`.
  *
- * @category Decoding
+ * **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 const decodeSync = Parser.decodeSync;
@@ -789,6 +822,8 @@ export const decodeSync = Parser.decodeSync;
  * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link encodeEffect} when
  * the input is already typed as the schema's `Type`.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * **Example** (Encoding a value to a string)
  *
@@ -801,11 +836,11 @@ export const decodeSync = Parser.decodeSync;
  * // Output: "42"
  * ```
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
-export function encodeUnknownEffect(schema) {
-  const parser = Parser.encodeUnknownEffect(schema);
+export function encodeUnknownEffect(schema, options) {
+  const parser = Parser.encodeUnknownEffect(schema, options);
   return (input, options) => {
     return Effect.mapErrorEager(parser(input, options), issue => new SchemaError(issue));
   };
@@ -815,8 +850,10 @@ export function encodeUnknownEffect(schema) {
  * `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
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeEffect = encodeUnknownEffect;
@@ -826,12 +863,14 @@ export const encodeEffect = encodeUnknownEffect;
  * 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
+ * @category encoding
  * @since 4.0.0
  */
-export function encodeUnknownExit(schema) {
-  const parser = Parser.encodeUnknownExit(schema);
+export function encodeUnknownExit(schema, options) {
+  const parser = Parser.encodeUnknownExit(schema, options);
   return (input, options) => {
     return Exit_.mapError(parser(input, options), issue => new SchemaError(issue));
   };
@@ -842,8 +881,10 @@ export function encodeUnknownExit(schema) {
  * `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
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeExit = encodeUnknownExit;
@@ -853,47 +894,67 @@ export const encodeExit = encodeUnknownExit;
  * 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
+ * @category encoding
+ * @since 3.10.0
  */
 export const encodeUnknownOption = Parser.encodeUnknownOption;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `Option` that is `Some` with the encoded value on success or `None` on
  * failure. For `unknown` input use {@link encodeUnknownOption}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
- * @category Encoding
- * @since 4.0.0
+ * @category encoding
+ * @since 3.10.0
  */
 export const encodeOption = Parser.encodeOption;
 /**
- * Encodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link encodePromise}.
+ * Encodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the encoded value or fails with a schema issue. For typed input
+ * use {@link encodeResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeUnknownResult = Parser.encodeUnknownResult;
 /**
- * @category Encoding
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Result` that succeeds with the encoded value or fails with a schema issue.
+ * For `unknown` input use {@link encodeUnknownResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
+ *
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeResult = Parser.encodeResult;
 /**
- * @category Encoding
- * @since 4.0.0
+ * 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 3.10.0
  */
 export const encodeUnknownPromise = Parser.encodeUnknownPromise;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning a
  * `Promise` that resolves with the encoded value or rejects with a
  * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
- * @category Encoding
- * @since 4.0.0
+ * @category encoding
+ * @since 3.10.0
  */
 export const encodePromise = Parser.encodePromise;
 /**
@@ -903,8 +964,10 @@ export const encodePromise = Parser.encodePromise;
  * non-throwing alternatives see {@link encodeUnknownOption},
  * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
  * use {@link encodeSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeUnknownSync = Parser.encodeUnknownSync;
@@ -912,8 +975,10 @@ export const encodeUnknownSync = Parser.encodeUnknownSync;
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
  * throwing a {@link SchemaError} on failure. For `unknown` input use
  * {@link encodeUnknownSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export const encodeSync = Parser.encodeSync;
@@ -929,8 +994,8 @@ export const encodeSync = Parser.encodeSync;
  * the bridge between the untyped AST representation and the strongly-typed
  * schema.
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const make = InternalSchema.make;
 /**
@@ -951,6 +1016,7 @@ export const make = InternalSchema.make;
  * // "a"
  * ```
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function asClass(schema) {
@@ -961,8 +1027,8 @@ export function asClass(schema) {
 /**
  * Tests if a value is a `Schema`.
  *
- * @category Guards
- * @since 4.0.0
+ * @category guards
+ * @since 3.10.0
  */
 export function isSchema(u) {
   return Predicate.hasProperty(u, TypeId) && u[TypeId] === TypeId;
@@ -986,6 +1052,7 @@ export function isSchema(u) {
  * type Person = typeof schema["Type"]
  * ```
  *
+ * @category combinators
  * @since 4.0.0
  */
 export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.optionalKey(schema.ast), {
@@ -995,6 +1062,7 @@ export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.option
  * Reverses {@link optionalKey}, returning the inner required schema. Only
  * applicable to schemas already wrapped with `optionalKey`.
  *
+ * @category combinators
  * @since 4.0.0
  */
 export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
@@ -1021,20 +1089,23 @@ export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
  * type Person = typeof schema.Type
  * ```
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 3.10.0
  */
 export const optional = /*#__PURE__*/Struct_.lambda(self => optionalKey(UndefinedOr(self)));
 /**
  * Reverses {@link optional}, returning the inner schema (unwrapping `UndefinedOr`).
  * Only applicable to schemas already wrapped with `optional`.
  *
- * @since 4.0.0
+ * @category combinators
+ * @since 3.10.0
  */
 export const required = /*#__PURE__*/Struct_.lambda(self => self.schema.members[0]);
 /**
  * Makes a struct field mutable (removes the `readonly` modifier on the property).
  * Use {@link readonlyKey} to reverse.
  *
+ * @category combinators
  * @since 4.0.0
  */
 export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutableKey(schema.ast), {
@@ -1044,6 +1115,7 @@ export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutable
  * Reverses {@link mutableKey}, returning the inner schema as readonly again.
  * Only applicable to schemas already wrapped with `mutableKey`.
  *
+ * @category combinators
  * @since 4.0.0
  */
 export const readonlyKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
@@ -1051,6 +1123,7 @@ export const readonlyKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
  * Extracts the type-side schema: sets `Encoded` to equal the decoded `Type`,
  * discarding the encoding transformation path.
  *
+ * @category transforming
  * @since 4.0.0
  */
 export const toType = /*#__PURE__*/Struct_.lambda(schema => make(AST.toType(schema.ast), {
@@ -1060,6 +1133,7 @@ export const toType = /*#__PURE__*/Struct_.lambda(schema => make(AST.toType(sche
  * Extracts the encoded-side schema: sets `Type` to equal the `Encoded`,
  * discarding the decoding transformation path.
  *
+ * @category transforming
  * @since 4.0.0
  */
 export const toEncoded = /*#__PURE__*/Struct_.lambda(schema => make(AST.toEncoded(schema.ast), {
@@ -1082,6 +1156,7 @@ export function flip(schema) {
  * Creates a schema for a single literal value (string, number, bigint, boolean, or null).
  *
  * **Example** (String literal)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1092,7 +1167,8 @@ export function flip(schema) {
  * @see {@link Literals} for a schema that represents a union of literals.
  * @see {@link tag} for a schema that represents a literal value that can be
  * used as a discriminator field in tagged unions and has a constructor default.
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function Literal(literal) {
   const out = make(new AST.Literal(literal), {
@@ -1114,6 +1190,7 @@ function templateLiteralFromParts(parts) {
  * a literal string/number/bigint or a schema whose encoded type is a string, number, or bigint.
  *
  * **Example** (URL path pattern)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1122,7 +1199,8 @@ function templateLiteralFromParts(parts) {
  * ```
  *
  * @see {@link TemplateLiteralParser} for a schema that also parses matched parts into a tuple.
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function TemplateLiteral(parts) {
   return make(templateLiteralFromParts(parts), {
@@ -1134,6 +1212,7 @@ export function TemplateLiteral(parts) {
  * one element per schema part.
  *
  * **Example** (Parse path parameters)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1142,7 +1221,8 @@ export function TemplateLiteral(parts) {
  * ```
  *
  * @see {@link TemplateLiteral} for a validation-only version that keeps the string encoded.
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function TemplateLiteralParser(parts) {
   return make(templateLiteralFromParts(parts).asTemplateLiteralParser(), {
@@ -1153,6 +1233,7 @@ export function TemplateLiteralParser(parts) {
  * Creates a schema from a TypeScript enum object. Validates that the input is one of the enum's values.
  *
  * **Example** (Direction enum)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1165,6 +1246,7 @@ export function TemplateLiteralParser(parts) {
  * // accepts "Up" or "Down"
  * ```
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function Enum(enums) {
@@ -1175,40 +1257,46 @@ export function Enum(enums) {
 /**
  * Schema for the `never` type. Always fails validation — no value satisfies it.
  *
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Never = /*#__PURE__*/make(AST.never);
 /**
  * Schema for the `any` type. Accepts any value without validation.
  *
  * @see {@link Unknown} for a safer alternative that uses `unknown`.
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Any = /*#__PURE__*/make(AST.any);
 /**
  * Schema for the `unknown` type. Accepts any value without validation.
  *
  * @see {@link Any} for the `any` variant.
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Unknown = /*#__PURE__*/make(AST.unknown);
 /**
  * Schema for the `null` literal. Validates that the input is strictly `null`.
  *
  * @see {@link NullOr} for a union with another schema.
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Null = /*#__PURE__*/make(AST.null);
 /**
  * Schema for the `undefined` literal. Validates that the input is strictly `undefined`.
  *
  * @see {@link UndefinedOr} for a union with another schema.
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Undefined = /*#__PURE__*/make(AST.undefined);
 /**
  * Schema for `string` values. Validates that the input is `typeof` `"string"`.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const String = /*#__PURE__*/make(AST.string);
@@ -1221,6 +1309,7 @@ export const String = /*#__PURE__*/make(AST.string);
  * - Non-finite values are serialized as strings (`"NaN"`, `"Infinity"`, `"-Infinity"`).
  *
  * @see {@link Finite} for a schema that excludes non-finite values.
+ * @category schemas
  * @since 4.0.0
  */
 export const Number = /*#__PURE__*/make(AST.number);
@@ -1235,25 +1324,29 @@ export const Boolean = /*#__PURE__*/make(AST.boolean);
  * Schema for `symbol` values. Validates that the input is `typeof` `"symbol"`.
  *
  * @see {@link UniqueSymbol} for a schema that matches a specific symbol.
+ * @category schemas
  * @since 4.0.0
  */
 export const Symbol = /*#__PURE__*/make(AST.symbol);
 /**
  * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const BigInt = /*#__PURE__*/make(AST.bigInt);
 /**
  * Schema for the `void` type. Accepts `undefined` as the encoded value.
  *
- * @since 4.0.0
+ * @category schemas
+ * @since 3.10.0
  */
 export const Void = /*#__PURE__*/make(AST.void);
 /**
  * Schema for the `object` type. Validates that the input is a non-null object or function
  * (i.e. `typeof value === "object" && value !== null || typeof value === "function"`).
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
@@ -1261,6 +1354,7 @@ export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
  * Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.
  *
  * **Example** (Specific symbol)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1269,6 +1363,7 @@ export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
  * ```
  *
  * @see {@link Symbol} for a schema that accepts any symbol.
+ * @category constructors
  * @since 4.0.0
  */
 export function UniqueSymbol(symbol) {
@@ -1311,8 +1406,8 @@ function makeStruct(ast, fields) {
  * // { name: 'Alice', age: 30 }
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function Struct(fields) {
   return makeStruct(AST.struct(fields, undefined), fields);
@@ -1333,6 +1428,7 @@ export function Struct(fields) {
  * ]).mapMembers(Tuple.map(Schema.fieldsAssign({ c: Schema.Number })))
  * ```
  *
+ * @category combinators
  * @since 4.0.0
  */
 export function fieldsAssign(fields) {
@@ -1359,7 +1455,7 @@ export function fieldsAssign(fields) {
  * // { name: 'Alice', age: 30 }
  * ```
  *
- * @category Struct transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function encodeKeys(mapping) {
@@ -1407,8 +1503,8 @@ export function encodeKeys(mapping) {
  * // Alice Smith
  * ```
  *
+ * @category transforming
  * @since 4.0.0
- * @experimental
  */
 export function extendTo(/** The new fields to add */
 fields, /** A function per field to derive its value from the original input */
@@ -1463,8 +1559,8 @@ derive) {
  * // { a: 1, b: 2 }
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function Record(key, value, options) {
   const keyValueCombiner = options?.keyValueCombiner?.decode || options?.keyValueCombiner?.encode ? new AST.KeyValueCombiner(options.keyValueCombiner.decode, options.keyValueCombiner.encode) : undefined;
@@ -1491,7 +1587,7 @@ export function Record(key, value, options) {
  * type T = typeof schema.Type
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function StructWithRest(schema, records) {
@@ -1524,16 +1620,21 @@ function makeTuple(ast, elements) {
  * // [ 'hello', 42 ]
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function Tuple(elements) {
   return makeTuple(AST.tuple(elements), elements);
 }
 /**
- * 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)
  *
@@ -1551,7 +1652,7 @@ export function Tuple(elements) {
  * // [ 'hello', 1, true, false ]
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function TupleWithRest(schema, rest) {
@@ -1561,7 +1662,7 @@ export function TupleWithRest(schema, rest) {
   });
 }
 /**
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 const ArraySchema = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [], [schema.ast]), {
@@ -1583,7 +1684,7 @@ export {
  * // [ 'a', 'b', 'c' ]
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 ArraySchema as Array };
@@ -1602,25 +1703,26 @@ ArraySchema as Array };
  * Schema.decodeUnknownSync(schema)([])          // throws
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const NonEmptyArray = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [schema.ast], [schema.ast]), {
   schema
 }));
 /**
- * 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
+ * @since 3.10.0
  */
 export function ArrayEnsure(schema) {
   return Union([schema, ArraySchema(schema)]).pipe(decodeTo(ArraySchema(toType(schema)), Transformation.transform({
@@ -1634,7 +1736,7 @@ export function ArrayEnsure(schema) {
  * The equivalence used to determine uniqueness is the one provided by
  * `Schema.toEquivalence(item)`.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function UniqueArray(item) {
@@ -1654,7 +1756,8 @@ export function UniqueArray(item) {
  * type T = typeof schema.Type
  * ```
  *
- * @since 4.0.0
+ * @category transforming
+ * @since 3.10.0
  */
 export const mutable = /*#__PURE__*/Struct_.lambda(schema => {
   return make(new AST.Arrays(true, schema.ast.elements, schema.ast.rest), {
@@ -1689,8 +1792,8 @@ function makeUnion(ast, members) {
  * Schema.decodeUnknownSync(schema)(42)       // 42
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function Union(members, options) {
   return makeUnion(AST.union(members, options?.mode ?? "anyOf", undefined), members);
@@ -1699,6 +1802,7 @@ export function Union(members, options) {
  * Creates a union schema from an array of literal values.
  *
  * **Example** (Status codes)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1707,7 +1811,7 @@ export function Union(members, options) {
  * ```
  *
  * @see {@link Literal} for a schema that represents a single literal.
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function Literals(literals) {
@@ -1729,21 +1833,21 @@ export function Literals(literals) {
 /**
  * Creates a union schema of `S | null`.
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const NullOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null]));
 /**
  * Creates a union schema of `S | undefined`.
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const UndefinedOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Undefined]));
 /**
  * Creates a union schema of `S | null | undefined`.
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null, Undefined]));
 /**
@@ -1752,6 +1856,7 @@ export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null,
  * preventing infinite recursion during schema definition.
  *
  * **Example** (Recursive tree schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1766,8 +1871,8 @@ export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null,
  * })
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function suspend(f) {
   return make(new AST.Suspend(() => f().ast));
@@ -1777,6 +1882,7 @@ export function suspend(f) {
  * changing the TypeScript type.
  *
  * **Example** (Adding checks to a schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -1785,7 +1891,7 @@ export function suspend(f) {
  * )
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export function check(...checks) {
@@ -1795,8 +1901,14 @@ export function check(...checks) {
  * Narrows the TypeScript type of a schema's output via a type guard predicate,
  * attaching the guard as a runtime filter check.
  *
- * @category Filtering
- * @since 4.0.0
+ * 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 3.10.0
  */
 export function refine(refinement, annotations) {
   return schema => make(AST.appendChecks(schema.ast, [AST.makeFilterByGuard(refinement, annotations)]), {
@@ -1807,8 +1919,8 @@ export function refine(refinement, annotations) {
  * Adds a nominal brand to a schema, intersecting the output type with
  * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
- * @category Branding
- * @since 4.0.0
+ * @category branding
+ * @since 3.10.0
  */
 export function brand(identifier) {
   return schema => make(AST.brand(schema.ast, identifier), {
@@ -1820,8 +1932,8 @@ export function brand(identifier) {
  * Creates a branded schema from a {@link Brand.Constructor}, applying the
  * constructor's checks and brand tag to the underlying schema.
  *
- * @category Branding
- * @since 4.0.0
+ * @category branding
+ * @since 3.10.0
  */
 export function fromBrand(identifier, ctor) {
   return self => {
@@ -1848,6 +1960,7 @@ export function fromBrand(identifier, ctor) {
  * ```
  *
  * @see {@link catchDecoding} for a simpler error-recovery variant
+ * @category decoding
  * @since 4.0.0
  */
 export function middlewareDecoding(decode) {
@@ -1875,6 +1988,7 @@ export function middlewareDecoding(decode) {
  * ```
  *
  * @see {@link catchEncoding} for a simpler error-recovery variant
+ * @category encoding
  * @since 4.0.0
  */
 export function middlewareEncoding(encode) {
@@ -1899,6 +2013,7 @@ export function middlewareEncoding(encode) {
  * ```
  *
  * @see {@link catchDecodingWithContext} to add service requirements to the handler
+ * @category error handling
  * @since 4.0.0
  */
 export function catchDecoding(f) {
@@ -1907,6 +2022,7 @@ export function catchDecoding(f) {
 /**
  * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
  *
+ * @category error handling
  * @since 4.0.0
  */
 export function catchDecodingWithContext(f) {
@@ -1919,6 +2035,7 @@ export function catchDecodingWithContext(f) {
  * succeeds with a fallback value or re-fails with a (possibly different) issue.
  *
  * @see {@link catchEncodingWithContext} to add service requirements to the handler
+ * @category error handling
  * @since 4.0.0
  */
 export function catchEncoding(f) {
@@ -1927,6 +2044,7 @@ export function catchEncoding(f) {
 /**
  * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
  *
+ * @category error handling
  * @since 4.0.0
  */
 export function catchEncodingWithContext(f) {
@@ -1975,7 +2093,8 @@ export function decodeTo(to, transformation) {
  * // result: "hello"
  * ```
  *
- * @since 4.0.0
+ * @category transforming
+ * @since 3.10.0
  */
 export function decode(transformation) {
   return self => {
@@ -2007,7 +2126,8 @@ export function encodeTo(to, transformation) {
  * )
  * ```
  *
- * @since 4.0.0
+ * @category transforming
+ * @since 3.10.0
  */
 export function encode(transformation) {
   return self => {
@@ -2036,13 +2156,14 @@ export function encode(transformation) {
  * // value: { name: "anonymous" }
  * ```
  *
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function withConstructorDefault(
 // `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
 // it makes easier to define the default value if there are nested defaults
 defaultValue) {
-  return schema => make(AST.withConstructorDefault(schema.ast, defaultValue), {
+  return schema => make(AST.withConstructorDefault(schema.ast, Effect.mapErrorEager(defaultValue, e => e.issue)), {
     schema
   });
 }
@@ -2075,13 +2196,14 @@ defaultValue) {
  *
  * @see {@link withDecodingDefault} for the value-level variant (key absent **or** `undefined`)
  * @see {@link withDecodingDefaultTypeKey} for the variant where the default is a `Type` value
+ * @category decoding
  * @since 4.0.0
  */
 export function withDecodingDefaultKey(defaultValue, options) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough();
   return self => {
     return optionalKey(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, e => e.issue)),
       encode
     }));
   };
@@ -2103,6 +2225,7 @@ export function withDecodingDefaultKey(defaultValue, options) {
  *
  * @see {@link withDecodingDefaultKey} for the variant where the default is an `Encoded` value
  * @see {@link withDecodingDefaultType} for the value-level variant
+ * @category decoding
  * @since 4.0.0
  */
 export function withDecodingDefaultTypeKey(defaultValue, options) {
@@ -2139,13 +2262,14 @@ export function withDecodingDefaultTypeKey(defaultValue, options) {
  *
  * @see {@link withDecodingDefaultKey} for the key-level variant (key absent only, not `undefined`)
  * @see {@link withDecodingDefaultType} for the variant where the default is a `Type` value
- * @since 4.0.0
+ * @category decoding
+ * @since 3.10.0
  */
 export function withDecodingDefault(defaultValue, options) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough();
   return self => {
     return optional(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, e => e.issue)),
       encode
     }));
   };
@@ -2167,6 +2291,7 @@ export function withDecodingDefault(defaultValue, options) {
  *
  * @see {@link withDecodingDefault} for the variant where the default is an `Encoded` value
  * @see {@link withDecodingDefaultTypeKey} for the key-level variant
+ * @category decoding
  * @since 4.0.0
  */
 export function withDecodingDefaultType(defaultValue, options) {
@@ -2193,7 +2318,8 @@ export function withDecodingDefaultType(defaultValue, options) {
  *
  * @see {@link tagDefaultOmit} to also omit the tag during encoding
  * @see {@link TaggedStruct} for a shorthand that adds `_tag` automatically
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function tag(literal) {
   return Literal(literal).pipe(withConstructorDefault(Effect.succeed(literal)));
@@ -2219,6 +2345,7 @@ export function tag(literal) {
  * ```
  *
  * @see {@link tag} for the variant that keeps the tag during encoding
+ * @category constructors
  * @since 4.0.0
  */
 export function tagDefaultOmit(literal) {
@@ -2265,8 +2392,8 @@ export function tagDefaultOmit(literal) {
  * const literal = tagged.fields._tag.schema.literal
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function TaggedStruct(value, fields) {
   return Struct({
@@ -2295,8 +2422,8 @@ export function TaggedStruct(value, fields) {
  * ```
  *
  * @see {@link TaggedUnion} for a shorthand that builds the union from scratch
+ * @category combinators
  * @since 4.0.0
- * @experimental
  */
 export function toTaggedUnion(tag) {
   return self => {
@@ -2362,7 +2489,7 @@ export function toTaggedUnion(tag) {
  * ```
  *
  * @see {@link toTaggedUnion} to augment an existing union instead
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export function TaggedUnion(casesByTag) {
@@ -2405,6 +2532,7 @@ export function TaggedUnion(casesByTag) {
  * // person: Person
  * ```
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function Opaque() {
@@ -2429,8 +2557,8 @@ export function Opaque() {
  * // decoded: Date
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export function instanceOf(constructor, annotations) {
   return declare(u => u instanceof constructor, annotations);
@@ -2439,6 +2567,7 @@ export function instanceOf(constructor, annotations) {
  * Constructs an `AST.Link` that describes how a value of type `T` encodes to and decodes from a `To` schema.
  * Used when building low-level AST transformations that bridge two schema types.
  *
+ * @category transforming
  * @since 4.0.0
  */
 export function link() {
@@ -2450,9 +2579,17 @@ export function link() {
 // Checks
 // -----------------------------------------------------------------------------
 /**
- * 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)
  *
@@ -2575,34 +2712,29 @@ export const isPattern = AST.isPattern;
  */
 export const isStringFinite = AST.isStringFinite;
 /**
- * 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.
+ * **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.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the BigInt string pattern.
+ * **JSON Schema**
+ * This check corresponds to a `pattern` constraint with the same signed
+ * base-10 integer pattern.
  *
  * @category String checks
  * @since 4.0.0
  */
 export const isStringBigInt = AST.isStringBigInt;
 /**
- * Validates that a string represents a valid Symbol (can be parsed as a Symbol).
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing Symbol values.
- *
- * **Arbitrary**
+ * Validates that a string has the `Symbol(description)` format used by Effect's
+ * symbol string encoding.
  *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the Symbol string pattern.
+ * **Details**
+ * The check uses the pattern `^Symbol\((.*)\)$`. It is not a general test for
+ * whether a string can be passed to JavaScript's `Symbol()` function.
  *
  * @category String checks
  * @since 4.0.0
@@ -2732,17 +2864,12 @@ export function isBase64Url(annotations) {
   });
 }
 /**
- * Validates that a string starts with the specified prefix.
- *
- * **JSON Schema**
+ * Validates at runtime that a string starts with the specified literal prefix.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings starting with the specified prefix.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings start with the required prefix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `^${startsWith}` without
+ * escaping regexp metacharacters. If the prefix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `startsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -2765,17 +2892,12 @@ export function isStartsWith(startsWith, annotations) {
   });
 }
 /**
- * Validates that a string ends with the specified suffix.
- *
- * **JSON Schema**
+ * Validates at runtime that a string ends with the specified literal suffix.
  *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings ending with the specified suffix.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings end with the required suffix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `${endsWith}$` without
+ * escaping regexp metacharacters. If the suffix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `endsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -2798,17 +2920,12 @@ export function isEndsWith(endsWith, annotations) {
   });
 }
 /**
- * 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.
+ * Validates at runtime that a string contains the specified literal substring.
  *
- * **Arbitrary**
- *
- * 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
@@ -2832,17 +2949,12 @@ export function isIncludes(includes, annotations) {
 }
 const UPPERCASED_PATTERN = "^[^a-z]*$";
 /**
- * Validates that a string contains only uppercase characters.
+ * Validates that a string is unchanged by JavaScript's `toUpperCase()`.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only uppercase characters.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain only uppercase characters.
+ * **Details**
+ * This accepts empty strings and characters that do not have lowercase forms,
+ * such as digits, punctuation, and whitespace. It rejects strings that would
+ * change when uppercased.
  *
  * @category String checks
  * @since 4.0.0
@@ -2864,17 +2976,12 @@ export function isUppercased(annotations) {
 }
 const LOWERCASED_PATTERN = "^[^A-Z]*$";
 /**
- * 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
@@ -2896,17 +3003,12 @@ export function isLowercased(annotations) {
 }
 const CAPITALIZED_PATTERN = "^[^a-z]?.*$";
 /**
- * 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
@@ -2928,17 +3030,12 @@ export function isCapitalized(annotations) {
 }
 const UNCAPITALIZED_PATTERN = "^[^A-Z]?.*$";
 /**
- * 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
@@ -3732,7 +3829,11 @@ export const isLessThanOrEqualToBigDecimal = /*#__PURE__*/makeIsLessThanOrEqualT
   formatter: bd => BigDecimal_.format(bd)
 });
 /**
- * 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
@@ -3757,6 +3858,7 @@ export const isBetweenBigDecimal = /*#__PURE__*/makeIsBetween({
  * length.
  *
  * **Example** (Minimum length check)
+ *
  * ```ts
  * import { Schema } from "effect"
  *
@@ -4105,12 +4207,16 @@ export function isPropertiesLengthBetween(minimum, maximum, annotations) {
   });
 }
 /**
- * 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
@@ -4143,18 +4249,14 @@ export function isPropertyNames(keySchema, annotations) {
   });
 }
 /**
- * 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
@@ -4179,21 +4281,21 @@ export function isUnique(annotations) {
  * character.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty());
 /**
  * A schema representing a single character.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Char = /*#__PURE__*/String.check(/*#__PURE__*/isLengthBetween(1, 1));
 /**
  * Creates a schema for `Option<A>`. See {@link Option} for details.
  *
  * @category Option
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function Option(value) {
   const schema = declareConstructor()([value], ([value]) => (input, ast, options) => {
@@ -4259,7 +4361,7 @@ export function Option(value) {
  * - `Some` is encoded as the value
  *
  * @category Option
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function OptionFromNullOr(schema) {
   return NullOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullOr()));
@@ -4276,7 +4378,7 @@ export function OptionFromNullOr(schema) {
  * - `Some` is encoded as the value
  *
  * @category Option
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function OptionFromUndefinedOr(schema) {
   return UndefinedOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromUndefinedOr()));
@@ -4293,7 +4395,7 @@ export function OptionFromUndefinedOr(schema) {
  * - `Some` is encoded as the value
  *
  * @category Option
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function OptionFromNullishOr(schema, options) {
   return NullishOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullishOr(options)));
@@ -4448,7 +4550,7 @@ export function Result(success, failure) {
  * but it will deserialize a value into a `Redacted` instance.
  *
  * @category Redacted
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function Redacted(value, options) {
   const decodeLabel = typeof options?.label === "string" ? Parser.decodeUnknownEffect(Literal(options.label)) : undefined;
@@ -4518,7 +4620,8 @@ export function RedactedFromValue(value, options) {
   }));
 }
 /**
- * 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
@@ -4619,10 +4722,11 @@ function causeReasonToFormatter(error, defect) {
   };
 }
 /**
- * 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
+ * @since 3.10.0
  */
 export function Cause(error, defect) {
   const schema = declareConstructor()([error, defect], ([error, defect]) => {
@@ -4680,12 +4784,14 @@ const ErrorJsonEncoded = /*#__PURE__*/Struct({
   stack: /*#__PURE__*/optionalKey(String)
 });
 /**
- * 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
+ * @category schemas
  * @since 4.0.0
  */
 export const Error = /*#__PURE__*/instanceOf(globalThis.Error, {
@@ -4701,12 +4807,14 @@ export const Error = /*#__PURE__*/instanceOf(globalThis.Error, {
   toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
 });
 /**
- * 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
+ * @category schemas
  * @since 4.0.0
  */
 export const ErrorWithStack = /*#__PURE__*/instanceOf(globalThis.Error, {
@@ -4731,10 +4839,15 @@ const defectTransformation = /*#__PURE__*/new Transformation.Transformation(/*#_
   }
 }));
 /**
- * A schema that represents defects.
+ * A schema for defect values, accepting either JavaScript `Error` values encoded
+ * with `message` and optional `name`, or arbitrary unknown defect values.
  *
- * @category Constructors
- * @since 4.0.0
+ * **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 3.10.0
  */
 export const Defect = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#__PURE__*/decodeTo(Error, /*#__PURE__*/Transformation.errorFromErrorJsonEncoded())), /*#__PURE__*/Any.pipe(/*#__PURE__*/decodeTo(/*#__PURE__*/Unknown.annotate({
   toCodecJson: () => link()(Any, defectTransformation),
@@ -4754,10 +4867,11 @@ export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
- * 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
+ * @since 3.10.0
  */
 export function Exit(value, error, defect) {
   const schema = declareConstructor()([value, error, defect], ([value, error, defect]) => {
@@ -4844,7 +4958,7 @@ export function Exit(value, error, defect) {
  * conform to the provided schemas.
  *
  * @category ReadonlyMap
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function ReadonlyMap(key, value) {
   const schema = declareConstructor()([key, value], ([key, value]) => {
@@ -4897,7 +5011,7 @@ export function ReadonlyMap(key, value) {
  * conform to the provided schemas.
  *
  * @category HashMap
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function HashMap(key, value) {
   const schema = declareConstructor()([key, value], ([key, value]) => {
@@ -4947,8 +5061,11 @@ export function HashMap(key, value) {
   });
 }
 /**
+ * Creates a schema that validates a `ReadonlySet` whose values conform to the
+ * provided element schema.
+ *
  * @category ReadonlySet
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function ReadonlySet(value) {
   const schema = declareConstructor()([value], ([value]) => {
@@ -5000,7 +5117,7 @@ export function ReadonlySet(value) {
  * provided schema.
  *
  * @category HashSet
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function HashSet(value) {
   const schema = declareConstructor()([value], ([value]) => {
@@ -5052,7 +5169,7 @@ export function HashSet(value) {
  * provided schema.
  *
  * @category Chunk
- * @since 4.0.0
+ * @since 3.10.0
  */
 export function Chunk(value) {
   const schema = declareConstructor()([value], ([value]) => {
@@ -5148,8 +5265,8 @@ const URLString = /*#__PURE__*/String.annotate({
  *
  * - encodes `URL` as a `string`
  *
- * @since 4.0.0
  * @category URL
+ * @since 4.0.0
  */
 export const URL = /*#__PURE__*/instanceOf(globalThis.URL, {
   typeConstructor: {
@@ -5183,9 +5300,10 @@ const DateString = /*#__PURE__*/String.annotate({
 /**
  * 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)
  *
@@ -5212,16 +5330,18 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
   toArbitrary: () => (fc, ctx) => fc.date(ctx?.constraints?.date)
 });
 /**
- * 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
+ * @since 3.10.0
  */
 export const DateFromString = /*#__PURE__*/DateString.pipe(/*#__PURE__*/decodeTo(Date, Transformation.dateFromString));
 /**
@@ -5243,8 +5363,7 @@ export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
  * **Example** (Duration schema)
  *
  * ```ts
- * import { Schema } from "effect"
- * import { Duration } from "effect"
+ * import { Duration, Schema } from "effect"
  *
  * Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(5))
  * // => Duration(5s)
@@ -5252,7 +5371,7 @@ export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
  *
  * @category Duration
  *
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Duration = /*#__PURE__*/declare(Duration_.isDuration, {
   typeConstructor: {
@@ -5334,16 +5453,18 @@ export const DurationFromString = /*#__PURE__*/DurationString.pipe(/*#__PURE__*/
 const bigint0 = /*#__PURE__*/globalThis.BigInt(0);
 /**
  * A transformation schema that decodes a non-negative `bigint` into a
- * `Duration`, treating the `bigint` value as the duration in nanoseconds.
+ * `Duration`, treating the bigint as nanoseconds.
  *
- * Decoding:
- * - A non-negative `bigint` representing nanoseconds is decoded as a `Duration`
+ * **Decoding**
+ * A non-negative `bigint` representing nanoseconds is decoded as a `Duration`.
  *
- * Encoding:
- * - A `Duration` is encoded to a non-negative `bigint` representing nanoseconds
+ * **Encoding**
+ * Finite durations are encoded as a non-negative `bigint` number of nanoseconds.
+ * Encoding fails when the duration cannot be represented as nanoseconds, such as
+ * `Duration.infinity`.
  *
  * @category Duration
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualToBigInt(bigint0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromNanos));
 /**
@@ -5360,7 +5481,7 @@ export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualT
  *   representing milliseconds
  *
  * @category Duration
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const DurationFromMillis = /*#__PURE__*/Number.check(isGreaterThanOrEqualTo(0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromMillis));
 const BigDecimalString = /*#__PURE__*/String.annotate({
@@ -5374,7 +5495,7 @@ const BigDecimalString = /*#__PURE__*/String.annotate({
  * - encodes `BigDecimal` as a `string`
  *
  * @category BigDecimal
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
   typeConstructor: {
@@ -5418,7 +5539,7 @@ export const BigDecimalFromString = /*#__PURE__*/BigDecimalString.pipe(/*#__PURE
  * - Any value is encoded as a JSON string using `JSON.stringify`.
  * - If the value is not a valid JSON value, encoding fails.
  *
- * **Example**
+ * **Example** (Decoding unknown JSON strings)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -5441,7 +5562,7 @@ export const UnknownFromJsonString = /*#__PURE__*/fromJsonString(Unknown);
  * The resulting schema first parses the input string as JSON, and then runs the
  * provided schema on the parsed result.
  *
- * **Example**
+ * **Example** (Decoding JSON strings with a schema)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -5459,7 +5580,7 @@ export const UnknownFromJsonString = /*#__PURE__*/fromJsonString(Unknown);
  * resulting schema will be a JSON Schema with a `contentSchema` property that
  * contains the JSON Schema for the given schema.
  *
- * **Example**
+ * **Example** (Emitting JSON Schema for a JSON string decoder)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -5684,6 +5805,7 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
  * // Success({"a":1}) // Note: the value is a number
  * ```
  *
+ * @category decoding
  * @since 4.0.0
  */
 export function fromFormData(schema) {
@@ -5785,6 +5907,7 @@ export const URLSearchParams = /*#__PURE__*/instanceOf(globalThis.URLSearchParam
  * // Success({"a":1}) // Note: the value is a number
  * ```
  *
+ * @category decoding
  * @since 4.0.0
  */
 export function fromURLSearchParams(schema) {
@@ -5794,27 +5917,30 @@ export function fromURLSearchParams(schema) {
  * A schema for finite numbers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
  * @category Number
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Finite = /*#__PURE__*/Number.check(/*#__PURE__*/isFinite());
 /**
  * A schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
  * @category Number
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Int = /*#__PURE__*/Number.check(/*#__PURE__*/isInt());
 /**
- * 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
+ * @since 3.10.0
  */
 export const NumberFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a number"
@@ -5852,7 +5978,7 @@ export const BigIntFromString = /*#__PURE__*/make(AST.bigIntString).pipe(/*#__PU
  * A schema for strings that contains no leading or trailing whitespaces.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Trimmed = /*#__PURE__*/String.check(/*#__PURE__*/isTrimmed());
 /**
@@ -5865,7 +5991,7 @@ export const Trimmed = /*#__PURE__*/String.check(/*#__PURE__*/isTrimmed());
  * - The trimmed string is encoded as is.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Trim = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a trimmed string"
@@ -5880,7 +6006,7 @@ export const Trim = /*#__PURE__*/String.annotate({
  * - A `string` is encoded as a base64-encoded string.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const StringFromBase64 = /*#__PURE__*/String.annotate({
   expected: "a base64 encoded string that will be decoded as a UTF-8 string"
@@ -5895,7 +6021,7 @@ export const StringFromBase64 = /*#__PURE__*/String.annotate({
  * - A `string` is encoded as a base64 (URL) encoded string.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const StringFromBase64Url = /*#__PURE__*/String.annotate({
   expected: "a base64 (URL) encoded string that will be decoded as a UTF-8 string"
@@ -5910,7 +6036,7 @@ export const StringFromBase64Url = /*#__PURE__*/String.annotate({
  * - A `string` is encoded as a hex string.
  *
  * @category String
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const StringFromHex = /*#__PURE__*/String.annotate({
   expected: "a hex encoded string that will be decoded as a UTF-8 string"
@@ -5925,7 +6051,7 @@ export const StringFromHex = /*#__PURE__*/String.annotate({
  * Encoding:
  * - A `string` is encoded as a URI component encoded string.
  *
- * **Example**
+ * **Example** (Decoding URI component strings)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -5944,19 +6070,25 @@ export const StringFromHex = /*#__PURE__*/String.annotate({
  * ```
  *
  * @category String
- * @since 4.0.0
+ * @since 3.12.0
  */
 export const StringFromUriComponent = /*#__PURE__*/String.annotate({
   expected: "a URI component encoded string that will be decoded as a UTF-8 string"
 }).pipe(/*#__PURE__*/decodeTo(String, Transformation.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 const PropertyKey = /*#__PURE__*/Union([Finite, Symbol, String]);
 /**
+ * Schema for a Standard Schema v1 failure result.
+ *
+ * The result contains an `issues` array where each issue has a message and an
+ * optional path made of property keys or keyed path segments.
+ *
  * @category StandardSchema
  * @since 4.0.0
  */
@@ -6016,7 +6148,7 @@ export const Uint8Array = /*#__PURE__*/instanceOf(globalThis.Uint8Array, {
  * - A `Uint8Array` is encoded as a base64-encoded string.
  *
  * @category Uint8Array
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Uint8ArrayFromBase64 = /*#__PURE__*/Base64String.pipe(/*#__PURE__*/decodeTo(Uint8Array, Transformation.uint8ArrayFromBase64String));
 /**
@@ -6030,7 +6162,7 @@ export const Uint8ArrayFromBase64 = /*#__PURE__*/Base64String.pipe(/*#__PURE__*/
  * - A `Uint8Array` is encoded as a base64 (URL) encoded string.
  *
  * @category Uint8Array
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Uint8ArrayFromBase64Url = /*#__PURE__*/String.annotate({
   expected: "a base64 (URL) encoded string that will be decoded as a Uint8Array"
@@ -6049,7 +6181,7 @@ export const Uint8ArrayFromBase64Url = /*#__PURE__*/String.annotate({
  * - A `Uint8Array` is encoded as a hex encoded string.
  *
  * @category Uint8Array
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
   expected: "a hex encoded string that will be decoded as a Uint8Array"
@@ -6065,7 +6197,7 @@ export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
  * - encodes `DateTime.Utc` as a UTC ISO string
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isUtc(u), {
   typeConstructor: {
@@ -6095,22 +6227,23 @@ export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && D
  * - A `DateTime.Utc` is encoded as a `Date`
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.12.0
  */
 export const DateTimeUtcFromDate = /*#__PURE__*/DateValid.pipe(/*#__PURE__*/decodeTo(DateTimeUtc, {
   decode: /*#__PURE__*/Getter.dateTimeUtcFromInput(),
   encode: /*#__PURE__*/Getter.transform(DateTime.toDateUtc)
 }));
 /**
- * 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
@@ -6142,7 +6275,7 @@ export const DateTimeUtcFromMillis = /*#__PURE__*/Number.pipe(/*#__PURE__*/decod
  * - encodes `DateTime.TimeZone.Offset` as a number (offset in milliseconds)
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const TimeZoneOffset = /*#__PURE__*/declare(DateTime.isTimeZoneOffset, {
   typeConstructor: {
@@ -6173,7 +6306,7 @@ const TimeZoneNamedString = /*#__PURE__*/String.annotate({
  * - encodes `DateTime.TimeZone.Named` as a string (IANA time zone identifier)
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
   typeConstructor: {
@@ -6215,7 +6348,7 @@ const TimeZoneString = /*#__PURE__*/String.annotate({
  *   `+03:00`)
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
   typeConstructor: {
@@ -6256,11 +6389,13 @@ const DateTimeZonedString = /*#__PURE__*/String.annotate({
  *
  * **Default JSON serializer**
  *
- * - encodes `DateTime.Zoned` as a string in the format
+ * - encodes offset zones as an ISO date-time with a numeric offset, such as
+ *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`
+ * - encodes named zones by appending the IANA identifier in brackets, such as
  *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`
  *
  * @category DateTime
- * @since 4.0.0
+ * @since 3.10.0
  */
 export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isZoned(u), {
   typeConstructor: {
@@ -6336,7 +6471,7 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
       return Parser.makeOption(getClassSchema(this))(input ?? {}, options);
     }
     static makeEffect(input, options) {
-      return Effect.mapErrorEager(Parser.makeEffect(getClassSchema(this))(input ?? {}, options), issue => new SchemaError(issue));
+      return getClassSchema(this).makeEffect(input ?? {}, options);
     }
     static annotate(annotations) {
       return this.rebuild(AST.annotate(this.ast, annotations));
@@ -6438,8 +6573,8 @@ function isStruct(schema) {
  * console.log(dog.breed) // "Labrador"
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const Class = identifier => (schema, annotations) => {
   const struct = isStruct(schema) ? schema : Struct(schema);
@@ -6473,8 +6608,8 @@ export const Class = identifier => (schema, annotations) => {
  * console.log(c.radius) // 5
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const TaggedClass = identifier => {
   return (tagValue, schema, annotations) => {
@@ -6507,7 +6642,7 @@ export const TaggedClass = identifier => {
  * })
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const ErrorClass = identifier => (schema, annotations) => {
@@ -6536,8 +6671,8 @@ export const ErrorClass = identifier => (schema, annotations) => {
  * })
  * ```
  *
- * @category Constructors
- * @since 4.0.0
+ * @category constructors
+ * @since 3.10.0
  */
 export const TaggedErrorClass = identifier => {
   return (tagValue, schema, annotations) => {
@@ -6592,10 +6727,11 @@ export function toArbitrary(schema) {
 // Formatter
 // -----------------------------------------------------------------------------
 /**
- * **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
@@ -6802,9 +6938,11 @@ export function toRepresentation(schema) {
   return InternalStandard.fromAST(schema.ast);
 }
 /**
- * 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
@@ -6822,8 +6960,8 @@ export function toJsonSchemaDocument(schema, options) {
 // Canonical Codecs
 // -----------------------------------------------------------------------------
 /**
- * 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
@@ -6922,9 +7060,11 @@ export function toCodecStringTree(schema, options) {
   return make(toCodecEnsureArray(options?.keepDeclarations === true ? serializerStringTreeKeepDeclarations(schema.ast) : serializerStringTree(schema.ast)));
 }
 /**
- * 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