effect 4.0.0-beta.3 → 4.0.0-beta.31

package/dist/Schema.js

@@ -1,18 +1,104 @@
 /**
+ * Define data shapes, validate unknown input, and transform values between formats.
+ *
+ * ## Mental model
+ *
+ * - **Schema** — a description of a data shape. Every schema carries a decoded
+ *   *Type* (the value you work with) and an *Encoded* representation (the
+ *   serialized form, e.g. JSON).
+ * - **Decoding** — turning unknown external data (API responses, form
+ *   submissions, config files) into typed, validated values.
+ * - **Encoding** — turning typed values back into a serializable format.
+ * - **Codec** — a schema that tracks both Type and Encoded, so it can decode
+ *   *and* encode. Most concrete schemas are Codecs.
+ * - **Check / Filter** — a constraint attached to a schema (e.g. `isMinLength`,
+ *   `isGreaterThan`). Attach them with `.check(...)`.
+ * - **Transformation** — a pair of functions (decode + encode) that convert
+ *   values between two schemas. Created with {@link decodeTo} / {@link encodeTo}.
+ * - **Annotation** — metadata attached to a schema (title, description, custom
+ *   keys). Attach with `.annotate(...)`.
+ *
+ * ## Common tasks
+ *
+ * - Define a struct: {@link Struct}
+ * - Define a union: {@link Union}, {@link TaggedUnion}, {@link Literals}
+ * - Define an array: {@link Array}, {@link NonEmptyArray}
+ * - Define a record: {@link Record}
+ * - Define a tuple: {@link Tuple}, {@link TupleWithRest}
+ * - Validate unknown data synchronously: {@link decodeUnknownSync}
+ * - Validate unknown data (Effect): {@link decodeUnknownEffect}
+ * - Encode a value: {@link encodeUnknownSync}, {@link encodeUnknownEffect}
+ * - Type guard: {@link is}
+ * - Assertion: {@link asserts}
+ * - Add constraints: `.check(...)` with filters like {@link isMinLength},
+ *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}
+ * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
+ * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
+ * - Create branded types: {@link brand}
+ * - Define classes with validation: {@link Class}, {@link TaggedClass}
+ * - Define error classes: {@link ErrorClass}, {@link TaggedErrorClass}
+ * - Generate JSON Schema: {@link toJsonSchemaDocument}
+ * - Generate test data: {@link toArbitrary}
+ * - Derive equivalence: {@link toEquivalence}
+ *
+ * ## Gotchas
+ *
+ * - `Schema.optional` creates `T | undefined` (key can be missing *or*
+ *   `undefined`). Use `Schema.optionalKey` for exact optional properties.
+ * - `decodeTo` is curried: use `from.pipe(Schema.decodeTo(to, ...))`.
+ * - `decodeUnknownSync` throws on failure. Use `decodeUnknownExit` or
+ *   `decodeUnknownOption` for non-throwing alternatives.
+ * - Filters do not change the TypeScript type. Use {@link refine} or
+ *   {@link brand} to narrow the type.
+ * - Recursive schemas require {@link suspend} to avoid infinite loops.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Validate a user object)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const User = Schema.Struct({
+ *   name: Schema.String.check(Schema.isMinLength(1)),
+ *   age: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // Decode unknown input — throws on failure
+ * const user = Schema.decodeUnknownSync(User)({
+ *   name: "Alice",
+ *   age: 30
+ * })
+ *
+ * console.log(user)
+ * // { name: "Alice", age: 30 }
+ * ```
+ *
+ * @see {@link Schema} — type-level view tracking only the decoded Type
+ * @see {@link Codec} — type-level view tracking both Type and Encoded
+ * @see {@link Struct} — define object shapes
+ * @see {@link decodeUnknownSync} — synchronous validation
+ * @see {@link decodeTo} — schema transformations
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.js";
+import * as BigDecimal_ from "./BigDecimal.js";
 import * as Cause_ from "./Cause.js";
+import * as Chunk_ from "./Chunk.js";
 import * as Data from "./Data.js";
 import * as DateTime from "./DateTime.js";
 import * as Duration_ from "./Duration.js";
 import * as Effect from "./Effect.js";
-import * as Base64 from "./encoding/Base64.js";
+import * as Encoding from "./Encoding.js";
 import * as Equal from "./Equal.js";
 import * as Equivalence from "./Equivalence.js";
 import * as Exit_ from "./Exit.js";
 import { format, formatDate, formatPropertyKey } from "./Formatter.js";
 import { identity } from "./Function.js";
+import * as HashMap_ from "./HashMap.js";
+import * as HashSet_ from "./HashSet.js";
 import * as core from "./internal/core.js";
 import * as InternalAnnotations from "./internal/schema/annotations.js";
 import * as InternalArbitrary from "./internal/schema/arbitrary.js";
@@ -41,9 +127,51 @@ import * as Struct_ from "./Struct.js";
 import * as FastCheck from "./testing/FastCheck.js";
 const TypeId = InternalSchema.TypeId;
 /**
- * An API for creating schemas for parametric types.
+ * Creates a schema for a **parametric** type (a generic container such as
+ * `Array<A>`, `Option<A>`, etc.) by accepting a list of type-parameter schemas
+ * and a decoder factory.
+ *
+ * The outer call `declareConstructor<T, E, Iso>()` fixes the decoded type `T`,
+ * the encoded type `E`, and the optional iso type. The inner call receives:
+ * - `typeParameters` — the concrete schemas for each type variable
+ * - `run` — a factory that, given resolved codecs for each type parameter,
+ *   returns a parsing function `(u, ast, options) => Effect<T, Issue>`
+ * - `annotations` — optional metadata
+ *
+ * @see {@link declare} for creating schemas for non-parametric types.
+ *
+ * **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"
  *
- * @see {@link declare} for creating schemas for non parametric types.
+ * interface Box<A> {
+ *   readonly value: A
+ * }
+ *
+ * const isBox = (u: unknown): u is Box<unknown> =>
+ *   typeof u === "object" && u !== null && "value" in u
+ *
+ * const Box = <A extends Schema.Top>(item: A) =>
+ *   Schema.declareConstructor<Box<A["Type"]>, Box<A["Encoded"]>>()(
+ *     [item],
+ *     ([itemCodec]) =>
+ *       (u, ast, options) => {
+ *         if (!isBox(u)) {
+ *           return Effect.fail(new Issue.InvalidType(ast, Option.some(u)))
+ *         }
+ *         return Effect.map(
+ *           SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options),
+ *           (value) => ({ value })
+ *         )
+ *       }
+ *   )
+ *
+ * const schema = Box(Schema.Number)
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -54,18 +182,60 @@ export function declareConstructor() {
   };
 }
 /**
- * An API for creating schemas for non parametric types.
+ * Creates a schema for a **non-parametric** opaque type using a type-guard
+ * function. The schema accepts any unknown value and succeeds when `is` returns
+ * `true`, failing with an `InvalidType` issue otherwise.
+ *
+ * Use this when the type has no type parameters. For parametric types such as
+ * `Option<A>` or `Array<A>`, use {@link declareConstructor} instead.
+ *
+ * **Example** (Schema for a custom `UserId` branded type)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * type UserId = string & { readonly _tag: "UserId" }
+ *
+ * const isUserId = (u: unknown): u is UserId =>
+ *   typeof u === "string" && u.startsWith("user_")
+ *
+ * const UserId = Schema.declare<UserId>(isUserId, {
+ *   title: "UserId",
+ *   description: "A user identifier starting with 'user_'"
+ * })
+ * ```
  *
  * @see {@link declareConstructor} for creating schemas for parametric types.
  *
+ * @category Constructors
  * @since 4.0.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);
 }
 /**
- * Reveals the complete Bottom interface type of a schema, exposing all 14 type
- * parameters.
+ * Widens a schema's type to the fully-parameterized {@link Bottom} interface,
+ * making all 14 type parameters visible to TypeScript.
+ *
+ * Normally, concrete schema interfaces (e.g. `Schema<string>`) hide most type
+ * parameters. `revealBottom` is useful when writing generic utilities that need
+ * to inspect or propagate the complete set of type parameters.
+ *
+ * **Example** (Inspecting all type parameters of a schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.String
+ *
+ * // Widen to Bottom to access all 14 type parameters
+ * const bottom = Schema.revealBottom(schema)
+ *
+ * // `bottom` now exposes Type, Encoded, DecodingServices, EncodingServices,
+ * // ast, ~rebuild.out, ~type.make.in, Iso, ~type.parameters, etc.
+ * type T = typeof bottom["Type"]     // string
+ * type E = typeof bottom["Encoded"]  // string
+ * ```
  *
  * @since 4.0.0
  */
@@ -74,8 +244,24 @@ export function revealBottom(bottom) {
 }
 /**
  * Adds metadata annotations to a schema without changing its runtime behavior.
- * Annotations are used to provide additional context for documentation,
- * JSON schema generation, error formatting, and other tooling.
+ * This is the pipeable (curried) counterpart of the `.annotate` method.
+ *
+ * Annotations provide extra context used by documentation generators, JSON
+ * Schema converters, error formatters, and other tooling. Common keys include
+ * `title`, `description`, `examples`, `message`, and `identifier`.
+ *
+ * **Example** (Adding a title and description)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Age = Schema.Number.pipe(
+ *   Schema.annotate({
+ *     title: "Age",
+ *     description: "A non-negative integer representing age in years"
+ *   })
+ * )
+ * ```
  *
  * @category Annotations
  * @since 4.0.0
@@ -86,9 +272,29 @@ export function annotate(annotations) {
   };
 }
 /**
- * Adds key-specific annotations to a schema field. This is useful for providing
- * custom error messages and documentation for individual fields within
- * structures.
+ * Adds key-level annotations to a schema field. This is the pipeable
+ * (curried) counterpart of the `.annotateKey` method.
+ *
+ * Key annotations apply to a field's position inside a `Struct` or `Tuple`
+ * rather than to the field's value type. They can carry a
+ * `messageMissingKey` to customise the error shown when the field is absent,
+ * as well as standard documentation fields such as `title`, `description`,
+ * and `examples`.
+ *
+ * **Example** (Custom missing-key message for a required field)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Struct({
+ *   username: Schema.String.pipe(
+ *     Schema.annotateKey({
+ *       description: "The username used to log in",
+ *       messageMissingKey: "Username is required"
+ *     })
+ *   )
+ * })
+ * ```
  *
  * @category Annotations
  * @since 4.0.0
@@ -99,6 +305,25 @@ export function annotateKey(annotations) {
   };
 }
 /**
+ * Identity function that widens a value to the full {@link Codec} interface,
+ * prompting TypeScript to infer all four type parameters (`T`, `E`, `RD`, `RE`).
+ *
+ * When a schema is stored in a variable typed as `Schema<T>` or `Top`, the
+ * encoded type and service requirements are erased. Passing the value through
+ * `revealCodec` recovers those parameters without any runtime cost.
+ *
+ * **Example** (Recovering encoded type from a schema variable)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema: Schema.Schema<number> = Schema.NumberFromString
+ *
+ * // Without revealCodec, Encoded is unknown
+ * const codec = Schema.revealCodec(schema)
+ * type Enc = typeof codec["Encoded"] // string
+ * ```
+ *
  * @since 4.0.0
  */
 export function revealCodec(codec) {
@@ -106,12 +331,30 @@ export function revealCodec(codec) {
 }
 const SchemaErrorTypeId = "~effect/Schema/SchemaError";
 /**
- * A `SchemaError` is returned when schema decoding or encoding fails.
+ * Error thrown (or returned as the error channel value) when schema decoding
+ * or encoding fails.
  *
- * This error extends `Data.TaggedError` and contains detailed information about
- * what went wrong during schema processing. The error includes an `issue` field
- * that provides comprehensive details about the validation failure, including
- * the path to the problematic data, expected types, and actual values.
+ * The `issue` field contains a structured {@link Issue.Issue} tree describing
+ * every validation failure, including the path to the problematic value,
+ * expected types, and actual values received. `message` renders the issue tree
+ * as a human-readable string.
+ *
+ * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
+ *
+ * **Example** (Catching a SchemaError)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("not a number")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err.message)
+ *     // Expected number, actual "not a number"
+ *   }
+ * }
+ * ```
  *
  * @since 4.0.0
  */
@@ -131,6 +374,22 @@ export class SchemaError {
   }
 }
 /**
+ * Returns `true` if `u` is a {@link SchemaError}.
+ *
+ * **Example** (Type guard in a catch block)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("oops")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err._tag) // "SchemaError"
+ *   }
+ * }
+ * ```
+ *
  * @since 4.0.0
  */
 export function isSchemaError(u) {
@@ -370,6 +629,11 @@ export const is = Parser.is;
  */
 export const asserts = Parser.asserts;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Effect` that
+ * 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.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -380,11 +644,22 @@ export function decodeUnknownEffect(schema) {
   };
 }
 /**
+ * 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}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeEffect = decodeUnknownEffect;
 /**
+ * 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.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -395,41 +670,110 @@ export function decodeUnknownExit(schema) {
   };
 }
 /**
+ * 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}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeExit = decodeUnknownExit;
 /**
+ * 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}.
+ *
  * @category Decoding
  * @since 4.0.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}.
+ *
  * @category Decoding
  * @since 4.0.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}.
+ *
  * @category Decoding
  * @since 4.0.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}.
+ *
  * @category Decoding
  * @since 4.0.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}.
+ *
+ * **Example** (Decoding with a transformation schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * console.log(Schema.decodeUnknownSync(NumberFromString)("42"))
+ * // Output: 42
+ *
+ * Schema.decodeUnknownSync(NumberFromString)("not a number")
+ * // throws SchemaError: NumberFromString
+ * //   └─ Encoded side transformation failure
+ * //      └─ NumberFromString
+ * //         └─ Expected a numeric string, actual "not a number"
+ * ```
+ *
  * @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}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeSync = Parser.decodeSync;
 /**
+ * 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`.
+ *
+ * **Example** (Encoding a value to a string)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * Effect.runPromise(Schema.encodeUnknownEffect(NumberFromString)(42)).then(console.log)
+ * // Output: "42"
+ * ```
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -440,11 +784,22 @@ export function encodeUnknownEffect(schema) {
   };
 }
 /**
+ * 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}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeEffect = encodeUnknownEffect;
 /**
+ * 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`.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -455,36 +810,72 @@ export function encodeUnknownExit(schema) {
   };
 }
 /**
+ * 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}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeExit = encodeUnknownExit;
 /**
+ * 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}.
+ *
  * @category Encoding
  * @since 4.0.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}.
+ *
  * @category Encoding
  * @since 4.0.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}.
+ *
  * @category Encoding
  * @since 4.0.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}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodePromise = Parser.encodePromise;
 /**
+ * Encodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to serialize data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link encodeUnknownOption},
+ * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
+ * use {@link encodeSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 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}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -539,57 +930,74 @@ export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.option
   schema
 }));
 /**
+ * Reverses {@link optionalKey}, returning the inner required schema. Only
+ * applicable to schemas already wrapped with `optionalKey`.
+ *
  * @since 4.0.0
  */
 export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
 /**
- * Creates an optional schema field that allows both the specified type and
+ * Marks a struct field as optional, allowing the key to be absent or
  * `undefined`.
  *
- * This is equivalent to `optionalKey(UndefinedOr(schema))`, creating a field
- * that:
- * - Can be omitted from the object entirely
- * - Can be explicitly set to `undefined`
- * - Can contain the specified schema type
+ * explicitly set to `undefined`. Equivalent to `optionalKey(UndefinedOr(S))`.
+ *
+ * Use {@link optionalKey} instead if you want exact optional semantics (absent
+ * only, not `undefined`).
  *
- * **Example** (Creating a struct with optional)
+ * **Example** (Optional field accepting undefined)
  *
  * ```ts
  * import { Schema } from "effect"
  *
  * const schema = Schema.Struct({
  *   name: Schema.String,
- *   age: Schema.optionalKey(Schema.Number)
+ *   age: Schema.optional(Schema.Number)
  * })
  *
- * // Type: { readonly name: string; readonly age?: number | undefined }
- * type Person = typeof schema["Type"]
+ * // { readonly name: string; readonly age?: number | undefined }
+ * type Person = typeof schema.Type
  * ```
  *
  * @since 4.0.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
  */
 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.
+ *
  * @since 4.0.0
  */
 export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutableKey(schema.ast), {
   schema
 }));
 /**
+ * Reverses {@link mutableKey}, returning the inner schema as readonly again.
+ * Only applicable to schemas already wrapped with `mutableKey`.
+ *
  * @since 4.0.0
  */
 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.
+ *
  * @since 4.0.0
  */
 export const toType = /*#__PURE__*/Struct_.lambda(schema => make(AST.toType(schema.ast), {
   schema
 }));
 /**
+ * Extracts the encoded-side schema: sets `Type` to equal the `Encoded`,
+ * discarding the decoding transformation path.
+ *
  * @since 4.0.0
  */
 export const toEncoded = /*#__PURE__*/Struct_.lambda(schema => make(AST.toEncoded(schema.ast), {
@@ -609,6 +1017,16 @@ 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"
+ *
+ * const schema = Schema.Literal("hello")
+ * // Type: Schema.Literal<"hello">
+ * ```
+ *
  * @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.
@@ -630,6 +1048,18 @@ function templateLiteralFromParts(parts) {
   return new AST.TemplateLiteral(parts.map(part => isSchema(part) ? part.ast : new AST.Literal(part)));
 }
 /**
+ * Creates a schema that validates strings matching a template literal pattern. Each part can be
+ * 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"
+ *
+ * const schema = Schema.TemplateLiteral(["/user/", Schema.Number])
+ * // matches strings like "/user/123", "/user/42", etc.
+ * ```
+ *
+ * @see {@link TemplateLiteralParser} for a schema that also parses matched parts into a tuple.
  * @since 4.0.0
  */
 export function TemplateLiteral(parts) {
@@ -638,6 +1068,18 @@ export function TemplateLiteral(parts) {
   });
 }
 /**
+ * Like {@link TemplateLiteral} but decodes the matched string into a readonly tuple of typed values,
+ * one element per schema part.
+ *
+ * **Example** (Parse path parameters)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.TemplateLiteralParser(["/user/", Schema.NumberFromString])
+ * // decodes "/user/42" => readonly ["/user/", 42]
+ * ```
+ *
+ * @see {@link TemplateLiteral} for a validation-only version that keeps the string encoded.
  * @since 4.0.0
  */
 export function TemplateLiteralParser(parts) {
@@ -646,6 +1088,21 @@ 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"
+ *
+ * enum Direction {
+ *   Up = "Up",
+ *   Down = "Down"
+ * }
+ *
+ * const schema = Schema.Enum(Direction)
+ * // accepts "Up" or "Down"
+ * ```
+ *
  * @since 4.0.0
  */
 export function Enum(enums) {
@@ -654,84 +1111,102 @@ export function Enum(enums) {
   });
 }
 /**
+ * Schema for the `never` type. Always fails validation — no value satisfies it.
+ *
  * @since 4.0.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
  */
 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
  */
 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
  */
 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
  */
 export const Undefined = /*#__PURE__*/make(AST.undefined);
 /**
- * A schema for all strings.
+ * Schema for `string` values. Validates that the input is `typeof` `"string"`.
  *
  * @since 4.0.0
  */
 export const String = /*#__PURE__*/make(AST.string);
 /**
- * A schema for all numbers, including `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for `number` values, including `NaN`, `Infinity`, and `-Infinity`.
  *
  * **Default Json Serializer**
  *
- * - If the number is finite, it is serialized as a number.
- * - Otherwise, it is serialized as a string ("NaN", "Infinity", or "-Infinity").
+ * - Finite numbers are serialized as numbers.
+ * - Non-finite values are serialized as strings (`"NaN"`, `"Infinity"`, `"-Infinity"`).
  *
+ * @see {@link Finite} for a schema that excludes non-finite values.
  * @since 4.0.0
  */
 export const Number = /*#__PURE__*/make(AST.number);
 /**
- * A schema for all booleans.
+ * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
  * @category Boolean
  * @since 4.0.0
  */
 export const Boolean = /*#__PURE__*/make(AST.boolean);
 /**
- * A schema for all symbols.
+ * Schema for `symbol` values. Validates that the input is `typeof` `"symbol"`.
  *
+ * @see {@link UniqueSymbol} for a schema that matches a specific symbol.
  * @since 4.0.0
  */
 export const Symbol = /*#__PURE__*/make(AST.symbol);
 /**
- * A schema for all bigints.
+ * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
  * @since 4.0.0
  */
 export const BigInt = /*#__PURE__*/make(AST.bigInt);
 /**
- * A schema for the `void` type.
+ * Schema for the `void` type. Accepts `undefined` as the encoded value.
  *
  * @since 4.0.0
  */
 export const Void = /*#__PURE__*/make(AST.void);
 /**
- * A schema for the `object` type.
+ * 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"`).
  *
  * @since 4.0.0
  */
 export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
 /**
- * A schema for unique symbols.
- *
- * **Example**
+ * Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.
  *
+ * **Example** (Specific symbol)
  * ```ts
  * import { Schema } from "effect"
  *
- * const a = Symbol.for("a")
- * const schema = Schema.UniqueSymbol(a)
+ * const mySymbol = Symbol.for("mySymbol")
+ * const schema = Schema.UniqueSymbol(mySymbol)
  * ```
+ *
+ * @see {@link Symbol} for a schema that accepts any symbol.
  * @since 4.0.0
  */
 export function UniqueSymbol(symbol) {
@@ -747,6 +1222,34 @@ function makeStruct(ast, fields) {
   });
 }
 /**
+ * Defines a struct schema from a map of field schemas.
+ *
+ * Each field value is a schema. Use {@link optionalKey} or {@link optional} to
+ * mark fields as optional, and {@link mutableKey} to mark them as mutable.
+ *
+ * The resulting schema's `Type` is a readonly object type with the fields'
+ * decoded types. The `Encoded` form mirrors the field schemas' encoded types.
+ *
+ * **Example** (Basic struct)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   age: Schema.Number,
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // { readonly name: string; readonly age: number; readonly email?: string }
+ * type Person = typeof Person.Type
+ *
+ * const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Struct(fields) {
@@ -774,6 +1277,26 @@ export function fieldsAssign(fields) {
   return Struct_.lambda(struct => struct.mapFields(Struct_.assign(fields)));
 }
 /**
+ * Renames struct keys in the encoded form without changing the decoded type.
+ *
+ * Takes a partial mapping `{ decodedKey: encodedKey }` and produces a
+ * transformation schema that decodes from the renamed keys and encodes back to
+ * the renamed keys. Keys not present in the mapping are left unchanged.
+ *
+ * **Example** (Rename `name` to `full_name` in the encoded form)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * const Encoded = Person.pipe(Schema.encodeKeys({ name: "full_name" }))
+ *
+ * // Decodes { full_name: "Alice", age: 30 } → { name: "Alice", age: 30 }
+ * const alice = Schema.decodeUnknownSync(Encoded)({ full_name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
  * @category Struct transformations
  * @since 4.0.0
  */
@@ -782,11 +1305,12 @@ export function encodeKeys(mapping) {
     const fields = {};
     const reverseMapping = {};
     for (const k in self.fields) {
+      const encoded = toEncoded(self.fields[k]);
       if (Object.hasOwn(mapping, k)) {
-        fields[mapping[k]] = toEncoded(self.fields[k]);
+        fields[mapping[k]] = encoded;
         reverseMapping[mapping[k]] = k;
       } else {
-        fields[k] = self.fields[k];
+        fields[k] = encoded;
       }
     }
     return Struct(fields).pipe(decodeTo(self, Transformation.transform({
@@ -796,6 +1320,31 @@ export function encodeKeys(mapping) {
   };
 }
 /**
+ * Adds derived fields to a struct schema during decoding.
+ *
+ * Each new field is derived from the decoded struct value via a function that
+ * returns `Option`. On encoding the derived fields are stripped. This allows
+ * computed or enriched fields to live in the decoded type without appearing in
+ * the encoded form.
+ *
+ * **Example** (Add a computed `fullName` field)
+ *
+ * ```ts
+ * import { Option, Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ first: Schema.String, last: Schema.String })
+ * const Extended = Person.pipe(
+ *   Schema.extendTo(
+ *     { fullName: Schema.String },
+ *     { fullName: (p) => Option.some(`${p.first} ${p.last}`) }
+ *   )
+ * )
+ *
+ * const alice = Schema.decodeUnknownSync(Extended)({ first: "Alice", last: "Smith" })
+ * console.log(alice.fullName)
+ * // Alice Smith
+ * ```
+ *
  * @since 4.0.0
  * @experimental
  */
@@ -835,6 +1384,24 @@ derive) {
   };
 }
 /**
+ * Defines a record (dictionary) schema with typed keys and values.
+ *
+ * **Example** (String-keyed record of numbers)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Record(Schema.String, Schema.Number)
+ *
+ * // { readonly [x: string]: number }
+ * type R = typeof schema.Type
+ *
+ * const result = Schema.decodeUnknownSync(schema)({ a: 1, b: 2 })
+ * console.log(result)
+ * // { a: 1, b: 2 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Record(key, value, options) {
@@ -845,6 +1412,24 @@ export function Record(key, value, options) {
   });
 }
 /**
+ * Extends a struct schema with one or more record (index-signature) schemas,
+ * producing a schema whose decoded type intersects the struct and all records.
+ *
+ * **Example** (Struct with string-indexed extra keys)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.StructWithRest(
+ *   Schema.Struct({ id: Schema.Number }),
+ *   [Schema.Record(Schema.String, Schema.String)]
+ * )
+ *
+ * // { readonly id: number } & { readonly [x: string]: string }
+ * type T = typeof schema.Type
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function StructWithRest(schema, records) {
@@ -863,6 +1448,20 @@ function makeTuple(ast, elements) {
   });
 }
 /**
+ * Defines a fixed-length tuple schema from an array of element schemas.
+ *
+ * **Example** (Pair of string and number)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Tuple([Schema.String, Schema.Number])
+ *
+ * const pair = Schema.decodeUnknownSync(schema)(["hello", 42])
+ * console.log(pair)
+ * // [ 'hello', 42 ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -870,6 +1469,26 @@ 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.
+ *
+ * **Example** (Tuple with rest)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // [string, number, ...boolean[]]
+ * const schema = Schema.TupleWithRest(
+ *   Schema.Tuple([Schema.String, Schema.Number]),
+ *   [Schema.Boolean]
+ * )
+ *
+ * const result = Schema.decodeUnknownSync(schema)(["hello", 1, true, false])
+ * console.log(result)
+ * // [ 'hello', 1, true, false ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -880,6 +1499,20 @@ export function TupleWithRest(schema, rest) {
   });
 }
 /**
+ * Defines a `ReadonlyArray` schema for a given element schema.
+ *
+ * **Example** (Array of strings)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Array(Schema.String)
+ *
+ * const result = Schema.decodeUnknownSync(schema)(["a", "b", "c"])
+ * console.log(result)
+ * // [ 'a', 'b', 'c' ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -887,6 +1520,20 @@ export const Array = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(f
   schema
 }));
 /**
+ * Defines a non-empty `ReadonlyArray` schema — at least one element required.
+ * Type is `readonly [T, ...T[]]`.
+ *
+ * **Example** (Non-empty array of numbers)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.NonEmptyArray(Schema.Number)
+ *
+ * Schema.decodeUnknownSync(schema)([1, 2, 3])  // ok
+ * Schema.decodeUnknownSync(schema)([])          // throws
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -906,7 +1553,18 @@ export function UniqueArray(item) {
   return Array(item).check(isUnique());
 }
 /**
- * Makes arrays or tuples mutable.
+ * Makes an array or tuple schema mutable, removing the `readonly` modifier.
+ *
+ * **Example** (Mutable array)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.mutable(Schema.Array(Schema.Number))
+ *
+ * // number[]   (mutable)
+ * type T = typeof schema.Type
+ * ```
  *
  * @since 4.0.0
  */
@@ -925,12 +1583,23 @@ function makeUnion(ast, members) {
   });
 }
 /**
- * Creates a schema that represents a union of multiple schemas. Members are checked in order, and the first match is returned.
+ * Creates a union schema from an array of member schemas. Members are tested in
+ * order; the first match is returned.
+ *
+ * Optionally, specify `mode`:
+ * - `"anyOf"` (default) — matches if any member matches.
+ * - `"oneOf"` — matches if exactly one member matches.
+ *
+ * **Example** (String or number union)
+ *
+ * ```ts
+ * import { Schema } from "effect"
  *
- * Optionally, you can specify the `mode` to be `"anyOf"` or `"oneOf"`.
+ * const schema = Schema.Union([Schema.String, Schema.Number])
  *
- * - `"anyOf"` - The union matches if any member matches.
- * - `"oneOf"` - The union matches if exactly one member matches.
+ * Schema.decodeUnknownSync(schema)("hello") // "hello"
+ * Schema.decodeUnknownSync(schema)(42)       // 42
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -939,6 +1608,16 @@ export function Union(members, options) {
   return makeUnion(AST.union(members, options?.mode ?? "anyOf", undefined), members);
 }
 /**
+ * Creates a union schema from an array of literal values.
+ *
+ * **Example** (Status codes)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Literals(["active", "inactive", "pending"])
+ * // accepts "active", "inactive", or "pending"
+ * ```
+ *
  * @see {@link Literal} for a schema that represents a single literal.
  * @category Constructors
  * @since 4.0.0
@@ -960,16 +1639,21 @@ export function Literals(literals) {
   });
 }
 /**
+ * Creates a union schema of `S | null`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const NullOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null]));
 /**
+ * Creates a union schema of `S | undefined`.
+ *
  * @category Constructors
  * @since 4.0.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
  */
@@ -979,6 +1663,21 @@ export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null,
  * essential for creating recursive schemas where a schema references itself,
  * preventing infinite recursion during schema definition.
  *
+ * **Example** (Recursive tree schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * interface Tree {
+ *   readonly value: number
+ *   readonly children: ReadonlyArray<Tree>
+ * }
+ *
+ * const Tree = Schema.Struct({
+ *   value: Schema.Number,
+ *   children: Schema.Array(Schema.suspend((): Schema.Codec<Tree> => Tree))
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -986,6 +1685,18 @@ export function suspend(f) {
   return make(new AST.Suspend(() => f().ast));
 }
 /**
+ * Pipeable function that attaches one or more filter checks to a schema without
+ * changing the TypeScript type.
+ *
+ * **Example** (Adding checks to a schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const AgeSchema = Schema.Number.pipe(
+ *   Schema.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(120))
+ * )
+ * ```
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -993,6 +1704,9 @@ export function check(...checks) {
   return self => self.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
  */
@@ -1002,7 +1716,8 @@ export function refine(refinement, annotations) {
   });
 }
 /**
- * Adds a brand to a schema.
+ * 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
@@ -1014,7 +1729,10 @@ export function brand(identifier) {
   });
 }
 /**
- * @category Constructors
+ * 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
  */
 export function fromBrand(identifier, ctor) {
@@ -1023,6 +1741,25 @@ export function fromBrand(identifier, ctor) {
   };
 }
 /**
+ * Intercepts the decoding pipeline of a schema.
+ *
+ * The provided function receives the current decoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RD`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging decode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareDecoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("decode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchDecoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareDecoding(decode) {
@@ -1031,6 +1768,25 @@ export function middlewareDecoding(decode) {
   });
 }
 /**
+ * Intercepts the encoding pipeline of a schema.
+ *
+ * The provided function receives the current encoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RE`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging encode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareEncoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("encode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchEncoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareEncoding(encode) {
@@ -1039,24 +1795,50 @@ export function middlewareEncoding(encode) {
   });
 }
 /**
+ * Recovers from a decoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * **Example** (Returning a default on decode failure)
+ *
+ * ```ts
+ * import { Effect, Option, Schema } from "effect"
+ *
+ * const schema = Schema.Number.pipe(
+ *   Schema.catchDecoding((_issue) => Effect.succeed(Option.some(0)))
+ * )
+ * ```
+ *
+ * @see {@link catchDecodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchDecoding(f) {
   return catchDecodingWithContext(f);
 }
 /**
+ * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchDecodingWithContext(f) {
   return self => self.pipe(middlewareDecoding(Effect.catchEager(f)));
 }
 /**
+ * Recovers from an encoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * @see {@link catchEncodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchEncoding(f) {
   return catchEncodingWithContext(f);
 }
 /**
+ * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchEncodingWithContext(f) {
@@ -1118,6 +1900,25 @@ export function encodeTo(to, transformation) {
   };
 }
 /**
+ * Applies a transformation to a schema's encoded type, creating a new schema where encoding/decoding
+ * operate on `S["Encoded"]` rather than `S["Type"]`.
+ *
+ * The `decode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during decoding),
+ * and the `encode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during encoding).
+ *
+ * **Example** (Upper-casing encoded strings)
+ *
+ * ```ts
+ * import { Schema, SchemaGetter } from "effect"
+ *
+ * const UpperFromLower = Schema.String.pipe(
+ *   Schema.encode({
+ *     decode: SchemaGetter.transform((s: string) => s.toLowerCase()),
+ *     encode: SchemaGetter.transform((s: string) => s.toUpperCase())
+ *   })
+ * )
+ * ```
+ *
  * @since 4.0.0
  */
 export function encode(transformation) {
@@ -1126,6 +1927,32 @@ export function encode(transformation) {
   };
 }
 /**
+ * Attaches a constructor default value to a schema field.
+ *
+ * The `defaultValue` function receives `Option.some(undefined)` when the field is
+ * explicitly set to `undefined`, or `Option.none()` when the field is absent.
+ * Return `Option.some(value)` to supply a default, or `Option.none()` to leave the
+ * field required. An `Effect` may be returned for async or service-dependent defaults.
+ *
+ * Constructor defaults are applied only during `makeUnsafe` / `make`, not during
+ * decoding or encoding.
+ *
+ * **Example** (Optional field with a static default)
+ *
+ * ```ts
+ * import { Option, Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(
+ *     Schema.optionalKey,
+ *     Schema.withConstructorDefault(() => Option.some("anonymous"))
+ *   )
+ * })
+ *
+ * const value = MySchema.makeUnsafe({})
+ * // value: { name: "anonymous" }
+ * ```
+ *
  * @since 4.0.0
  */
 export function withConstructorDefault(defaultValue) {
@@ -1142,6 +1969,27 @@ export function withConstructorDefault(defaultValue) {
  *   - `passthrough`: (default) Pass the default value through to the output.
  *   - `omit`: Omit the value from the output.
  *
+ * Provides a default value for a missing key during decoding.
+ *
+ * When the key is absent from the input, `defaultValue()` is called to supply a value.
+ * During encoding, the behavior is controlled by `options.encodingStrategy`:
+ * - `"passthrough"` (default): include the value in the output
+ * - `"omit"`: omit the key from the output
+ *
+ * **Example** (Default for a missing struct key)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.withDecodingDefaultKey(() => "anonymous"))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({})
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefault} for the `optional` (value-level) variant
  * @since 4.0.0
  */
 export function withDecodingDefaultKey(defaultValue, options) {
@@ -1160,6 +2008,30 @@ export function withDecodingDefaultKey(defaultValue, options) {
  *   - `passthrough`: (default) Pass the default value through to the output.
  *   - `omit`: Omit the value from the output.
  *
+ * Provides a default value for an `optional` field during decoding.
+ *
+ * Similar to {@link withDecodingDefaultKey} but works on `optional` (value-level optional)
+ * rather than `optionalKey` (key-level optional).
+ *
+ * When the value is `undefined` or absent, `defaultValue()` is called to supply a value.
+ * During encoding, the behavior is controlled by `options.encodingStrategy`:
+ * - `"passthrough"` (default): include the value in the output
+ * - `"omit"`: omit the value from the output
+ *
+ * **Example** (Default for an optional field value)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.optional, Schema.withDecodingDefault(() => "anonymous"))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({ name: undefined })
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefaultKey} for the key-level variant
  * @since 4.0.0
  */
 export function withDecodingDefault(defaultValue, options) {
@@ -1172,23 +2044,50 @@ export function withDecodingDefault(defaultValue, options) {
   };
 }
 /**
- * Creates a schema for a literal value and automatically provides itself as a
- * default.
+ * Combines a {@link Literal} schema with {@link withConstructorDefault}, making it ideal
+ * for discriminator fields in tagged unions. When constructing via `makeUnsafe`, the
+ * `_tag` field can be omitted and will be filled automatically.
  *
- * The `tag` function combines a literal schema with a constructor default,
- * making it perfect for discriminated unions and tagged data structures. The
- * tag value is automatically provided when the field is missing during
- * construction.
+ * **Example** (Discriminated union tag)
  *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
+ *
+ * // _tag is optional in makeUnsafe, auto-filled to "A"
+ * const a = A.makeUnsafe({ value: 42 })
+ * // a: { _tag: "A", value: 42 }
+ * ```
+ *
+ * @see {@link tagDefaultOmit} to also omit the tag during encoding
+ * @see {@link TaggedStruct} for a shorthand that adds `_tag` automatically
  * @since 4.0.0
  */
 export function tag(literal) {
   return Literal(literal).pipe(withConstructorDefault(() => Option_.some(literal)));
 }
 /**
- * Similar to `tag`, but provides itself as a default when decoding and omits
- * the value from the output when encoding.
+ * Like {@link tag}, but additionally omits the tag field from the encoded output.
+ * Useful when the encoded form (e.g. JSON) does not include the discriminator key,
+ * but the decoded type and constructor still need it.
+ *
+ * **Example** (Tag omitted during encoding)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.Struct({
+ *   _tag: Schema.tagDefaultOmit("A"),
+ *   value: Schema.Number
+ * })
+ *
+ * // Encode strips the _tag field
+ * const encoded = Schema.encodeUnknownSync(A)({ _tag: "A", value: 1 })
+ * // encoded: { value: 1 }
+ * ```
  *
+ * @see {@link tag} for the variant that keeps the tag during encoding
  * @since 4.0.0
  */
 export function tagDefaultOmit(literal) {
@@ -1244,18 +2143,27 @@ export function TaggedStruct(value, fields) {
     ...fields
   });
 }
-/** @internal */
-export function _getTagValueIfPropertyKey(tag, ast) {
-  const ps = ast.propertySignatures.find(p => p.name === tag);
-  if (ps) {
-    if (AST.isLiteral(ps.type) && Predicate.isPropertyKey(ps.type.literal)) {
-      return ps.type.literal;
-    } else if (AST.isUniqueSymbol(ps.type)) {
-      return ps.type.symbol;
-    }
-  }
-}
 /**
+ * Augments an existing {@link Union} of tagged structs with utility methods keyed by the discriminant field.
+ *
+ * **Example** (Adding tagged-union utilities to an existing union)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.TaggedStruct("A", { value: Schema.Number })
+ * const B = Schema.TaggedStruct("B", { name: Schema.String })
+ *
+ * const MyUnion = Schema.Union([A, B]).pipe(Schema.toTaggedUnion("_tag"))
+ *
+ * // Pattern-match on the union
+ * const result = MyUnion.match({ _tag: "A", value: 1 }, {
+ *   A: (a) => `number: ${a.value}`,
+ *   B: (b) => `name: ${b.name}`
+ * })
+ * ```
+ *
+ * @see {@link TaggedUnion} for a shorthand that builds the union from scratch
  * @since 4.0.0
  * @experimental
  */
@@ -1276,15 +2184,16 @@ export function toTaggedUnion(tag) {
       if (AST.isUnion(ast) && "members" in schema && globalThis.Array.isArray(schema.members) && schema.members.every(isSchema)) {
         return schema.members.forEach(walk);
       }
-      if (AST.isObjects(ast)) {
-        const key = _getTagValueIfPropertyKey(tag, ast);
-        if (key !== undefined) {
-          cases[key] = schema;
-          guards[key] = is(toType(schema));
+      const sentinels = AST.collectSentinels(ast);
+      if (sentinels.length > 0) {
+        const literal = sentinels.find(s => s.key === tag)?.literal;
+        if (Predicate.isPropertyKey(literal)) {
+          cases[literal] = schema;
+          guards[literal] = is(toType(schema));
           return;
         }
       }
-      throw new globalThis.Error("No literal found");
+      throw new globalThis.Error("No literal or unique symbol found");
     }
     function match() {
       if (arguments.length === 1) {
@@ -1300,6 +2209,28 @@ export function toTaggedUnion(tag) {
   };
 }
 /**
+ * Builds a discriminated union from a record of field sets, one per variant.
+ * Each key becomes the `_tag` literal and the value is passed to {@link TaggedStruct}.
+ * The result includes `cases`, `guards`, `isAnyOf`, and `match` utilities.
+ *
+ * **Example** (Discriminated union with pattern matching)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Shape = Schema.TaggedUnion({
+ *   Circle: { radius: Schema.Number },
+ *   Rectangle: { width: Schema.Number, height: Schema.Number }
+ * })
+ *
+ * // Pattern-match on a decoded value
+ * const area = Shape.match({ _tag: "Circle", radius: 5 }, {
+ *   Circle: (c) => Math.PI * c.radius ** 2,
+ *   Rectangle: (r) => r.width * r.height
+ * })
+ * ```
+ *
+ * @see {@link toTaggedUnion} to augment an existing union instead
  * @category Constructors
  * @since 4.0.0
  */
@@ -1323,6 +2254,23 @@ export function TaggedUnion(casesByTag) {
   });
 }
 /**
+ * Wraps a schema so that its decoded `Type` becomes a nominally distinct type `Self`.
+ * Useful for creating opaque types that are structurally identical to a base schema
+ * but type-incompatible with it.
+ *
+ * **Example** (Opaque user ID)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * type UserId = string & { readonly _tag: "UserId" }
+ * const UserId = Schema.Opaque<UserId>()(Schema.String)
+ *
+ * // Decoded value is UserId, not plain string
+ * const id = Schema.decodeUnknownSync(UserId)("abc")
+ * // id: UserId
+ * ```
+ *
  * @since 4.0.0
  */
 export function Opaque() {
@@ -1334,7 +2282,19 @@ export function Opaque() {
   };
 }
 /**
- * Creates a schema that validates an instance of a specific class constructor.
+ * Creates a schema that validates values using `instanceof`.
+ * Decoding and encoding pass the value through unchanged.
+ *
+ * **Example** (Schema for a built-in class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const DateSchema = Schema.instanceOf(Date)
+ *
+ * const decoded = Schema.decodeUnknownSync(DateSchema)(new Date("2024-01-01"))
+ * // decoded: Date
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -1343,6 +2303,9 @@ export function instanceOf(constructor, annotations) {
   return declare(u => u 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.
+ *
  * @since 4.0.0
  * @experimental
  */
@@ -1355,11 +2318,30 @@ 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
+ * `true`/`undefined` on success or a failure description on error.
+ *
+ * **Example** (Custom filter check)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // Check that a number is even
+ * const isEven = Schema.makeFilter(
+ *   (n: number) => n % 2 === 0 || "expected an even number"
+ * )
+ *
+ * const EvenNumber = Schema.Number.check(isEven)
+ * ```
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
 export const makeFilter = AST.makeFilter;
 /**
+ * Groups multiple checks into a single {@link AST.FilterGroup}, applying
+ * optional shared annotations to the group as a whole.
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
@@ -1847,6 +2829,9 @@ export function isFinite(annotations) {
   });
 }
 /**
+ * Generic factory for creating a "greater than" (`>`) check for any ordered
+ * type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1862,6 +2847,9 @@ export function makeIsGreaterThan(options) {
   };
 }
 /**
+ * Generic factory for creating a ">=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1877,6 +2865,9 @@ export function makeIsGreaterThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating a "<" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1892,6 +2883,9 @@ export function makeIsLessThan(options) {
   };
 }
 /**
+ * Generic factory for creating a "<=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1907,6 +2901,9 @@ export function makeIsLessThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating an inclusive/exclusive range check for any
+ * ordered type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1927,6 +2924,9 @@ export function makeIsBetween(deriveOptions) {
   };
 }
 /**
+ * Generic factory for creating a divisibility check for any numeric type by
+ * supplying a remainder function and a zero value.
+ *
  * @category Numeric checks
  * @since 4.0.0
  */
@@ -2528,6 +3528,58 @@ export const isBetweenBigInt = /*#__PURE__*/makeIsBetween({
     }
   })
 });
+/**
+ * Validates that a BigDecimal is greater than the specified value (exclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export const isGreaterThanBigDecimal = /*#__PURE__*/makeIsGreaterThan({
+  order: BigDecimal_.Order,
+  formatter: bd => BigDecimal_.format(bd)
+});
+/**
+ * Validates that a BigDecimal is greater than or equal to the specified value
+ * (inclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export const isGreaterThanOrEqualToBigDecimal = /*#__PURE__*/makeIsGreaterThanOrEqualTo({
+  order: BigDecimal_.Order,
+  formatter: bd => BigDecimal_.format(bd)
+});
+/**
+ * Validates that a BigDecimal is less than the specified value (exclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export const isLessThanBigDecimal = /*#__PURE__*/makeIsLessThan({
+  order: BigDecimal_.Order,
+  formatter: bd => BigDecimal_.format(bd)
+});
+/**
+ * Validates that a BigDecimal is less than or equal to the specified value
+ * (inclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export const isLessThanOrEqualToBigDecimal = /*#__PURE__*/makeIsLessThanOrEqualTo({
+  order: BigDecimal_.Order,
+  formatter: bd => BigDecimal_.format(bd)
+});
+/**
+ * Validates that a BigDecimal is within a specified range.
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export const isBetweenBigDecimal = /*#__PURE__*/makeIsBetween({
+  order: BigDecimal_.Order,
+  formatter: bd => BigDecimal_.format(bd)
+});
 /**
  * Validates that a value has at least the specified length. Works with strings
  * and arrays.
@@ -2543,6 +3595,14 @@ export const isBetweenBigInt = /*#__PURE__*/makeIsBetween({
  * constraint to ensure generated strings or arrays have at least the required
  * length.
  *
+ * **Example** (Minimum length check)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NonEmptyStringSchema = Schema.String.check(Schema.isMinLength(1))
+ * const NonEmptyArraySchema = Schema.Array(Schema.Number).check(Schema.isMinLength(1))
+ * ```
+ *
  * @category Length checks
  * @since 4.0.0
  */
@@ -2935,6 +3995,7 @@ export function isPropertyNames(keySchema, annotations) {
  * constraint using the provided equivalence function to ensure generated arrays
  * contain only unique items.
  *
+ * @category Array checks
  * @since 4.0.0
  */
 export function isUnique(annotations) {
@@ -2969,6 +4030,8 @@ export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty(
  */
 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
  */
@@ -3041,6 +4104,40 @@ export function Option(value) {
 export function OptionFromNullOr(schema) {
   return NullOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullOr()));
 }
+/**
+ * Decodes an undefined-or value `T` to a required `Option<T>` value.
+ *
+ * Decoding:
+ * - `undefined` is decoded as `None`
+ * - other values are decoded as `Some`
+ *
+ * Encoding:
+ * - `None` is encoded as `undefined`
+ * - `Some` is encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromUndefinedOr(schema) {
+  return UndefinedOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromUndefinedOr()));
+}
+/**
+ * Decodes a nullish value `T` to a required `Option<T>` value.
+ *
+ * Decoding:
+ * - `null` and `undefined` are decoded as `None`
+ * - other values are decoded as `Some`
+ *
+ * Encoding:
+ * - `None` is encoded as `null` or `undefined` depending on the provided `options.onNoneEncoding` (defaults to `undefined`)
+ * - `Some` is encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromNullishOr(schema, options) {
+  return NullishOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullishOr(options)));
+}
 /**
  * Decodes an optional value `A` to a required `Option<A>` value.
  *
@@ -3078,6 +4175,8 @@ export function OptionFromOptional(schema) {
   return optional(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromOptional()));
 }
 /**
+ * Creates a schema for `Result<A, E>`. See {@link Result} for details.
+ *
  * @category Result
  * @since 4.0.0
  */
@@ -3206,6 +4305,9 @@ export function Redacted(value, options) {
   });
 }
 /**
+ * Middleware that wraps decoded errors in `Redacted`, preventing sensitive
+ * schema details from leaking in error messages.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3213,6 +4315,10 @@ export function redact(schema) {
   return schema.pipe(middlewareDecoding(Effect.mapErrorEager(Issue.redact)));
 }
 /**
+ * Decodes a value and wraps it in `Redacted<A>`. Unlike {@link Redacted} which
+ * expects the input to already be a `Redacted` instance, this schema decodes
+ * the raw value and wraps it.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3225,10 +4331,12 @@ export function RedactedFromValue(value, options) {
   }));
 }
 /**
- * @category CauseFailure
+ * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ *
+ * @category CauseReason
  * @since 4.0.0
  */
-export function CauseFailure(error, defect) {
+export function CauseReason(error, defect) {
   const schema = declareConstructor()([error, defect], ([error, defect]) => (input, ast, options) => {
     if (!Cause_.isReason(input)) {
       return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
@@ -3252,7 +4360,7 @@ export function CauseFailure(error, defect) {
       _tag: "effect/Cause/Failure"
     },
     generation: {
-      runtime: `Schema.CauseFailure(?, ?)`,
+      runtime: `Schema.CauseReason(?, ?)`,
       Type: `Cause.Failure<?, ?>`,
       importDeclaration: `import * as Cause from "effect/Cause"`
     },
@@ -3279,16 +4387,16 @@ export function CauseFailure(error, defect) {
       },
       encode: identity
     })),
-    toArbitrary: ([error, defect]) => causeFailureToArbitrary(error, defect),
-    toEquivalence: ([error, defect]) => causeFailureToEquivalence(error, defect),
-    toFormatter: ([error, defect]) => causeFailureToFormatter(error, defect)
+    toArbitrary: ([error, defect]) => causeReasonToArbitrary(error, defect),
+    toEquivalence: ([error, defect]) => causeReasonToEquivalence(error, defect),
+    toFormatter: ([error, defect]) => causeReasonToFormatter(error, defect)
   });
   return make(schema.ast, {
     error,
     defect
   });
 }
-function causeFailureToArbitrary(error, defect) {
+function causeReasonToArbitrary(error, defect) {
   return (fc, ctx) => {
     return fc.oneof(ctx?.isSuspend ? {
       maxDepth: 2,
@@ -3298,7 +4406,7 @@ function causeFailureToArbitrary(error, defect) {
     }).map(Cause_.makeInterruptReason), error.map(e => Cause_.makeFailReason(e)), defect.map(d => Cause_.makeDieReason(d)));
   };
 }
-function causeFailureToEquivalence(error, defect) {
+function causeReasonToEquivalence(error, defect) {
   return (a, b) => {
     if (a._tag !== b._tag) return false;
     switch (a._tag) {
@@ -3311,7 +4419,7 @@ function causeFailureToEquivalence(error, defect) {
     }
   };
 }
-function causeFailureToFormatter(error, defect) {
+function causeReasonToFormatter(error, defect) {
   return t => {
     switch (t._tag) {
       case "Fail":
@@ -3324,19 +4432,23 @@ function causeFailureToFormatter(error, defect) {
   };
 }
 /**
+ * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ *
  * @category Cause
  * @since 4.0.0
  */
 export function Cause(error, defect) {
-  const schema = declareConstructor()([error, defect], ([error, defect]) => (input, ast, options) => {
-    if (!Cause_.isCause(input)) {
-      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
-    }
-    const failures = Array(CauseFailure(error, defect));
-    return Effect.mapBothEager(Parser.decodeUnknownEffect(failures)(input.reasons, options), {
-      onSuccess: Cause_.fromReasons,
-      onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["failures"], issue)])
-    });
+  const schema = declareConstructor()([error, defect], ([error, defect]) => {
+    const failures = Array(CauseReason(error, defect));
+    return (input, ast, options) => {
+      if (!Cause_.isCause(input)) {
+        return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+      }
+      return Effect.mapBothEager(Parser.decodeUnknownEffect(failures)(input.reasons, options), {
+        onSuccess: Cause_.fromReasons,
+        onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["failures"], issue)])
+      });
+    };
   }, {
     typeConstructor: {
       _tag: "effect/Cause"
@@ -3347,7 +4459,7 @@ export function Cause(error, defect) {
       importDeclaration: `import * as Cause from "effect/Cause"`
     },
     expected: "Cause",
-    toCodec: ([error, defect]) => link()(Array(CauseFailure(error, defect)), Transformation.transform({
+    toCodec: ([error, defect]) => link()(Array(CauseReason(error, defect)), Transformation.transform({
       decode: Cause_.fromReasons,
       encode: ({
         reasons: failures
@@ -3364,16 +4476,16 @@ export function Cause(error, defect) {
 }
 function causeToArbitrary(error, defect) {
   return (fc, ctx) => {
-    return fc.array(causeFailureToArbitrary(error, defect)(fc, ctx)).map(Cause_.fromReasons);
+    return fc.array(causeReasonToArbitrary(error, defect)(fc, ctx)).map(Cause_.fromReasons);
   };
 }
 function causeToEquivalence(error, defect) {
-  const failures = Equivalence.Array(causeFailureToEquivalence(error, defect));
+  const failures = Equivalence.Array(causeReasonToEquivalence(error, defect));
   return (a, b) => failures(a.reasons, b.reasons);
 }
 function causeToFormatter(error, defect) {
-  const causeFailure = causeFailureToFormatter(error, defect);
-  return t => `Cause([${t.reasons.map(causeFailure).join(", ")}])`;
+  const causeReason = causeReasonToFormatter(error, defect);
+  return t => `Cause([${t.reasons.map(causeReason).join(", ")}])`;
 }
 const ErrorJsonEncoded = /*#__PURE__*/Struct({
   message: String,
@@ -3455,27 +4567,31 @@ export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
+ * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ *
  * @category Exit
  * @since 4.0.0
  */
 export function Exit(value, error, defect) {
-  const schema = declareConstructor()([value, error, defect], ([value, error, defect]) => (input, ast, options) => {
-    if (!Exit_.isExit(input)) {
-      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
-    }
+  const schema = declareConstructor()([value, error, defect], ([value, error, defect]) => {
     const cause = Cause(error, defect);
-    switch (input._tag) {
-      case "Success":
-        return Effect.mapBothEager(Parser.decodeUnknownEffect(value)(input.value, options), {
-          onSuccess: Exit_.succeed,
-          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["value"], issue)])
-        });
-      case "Failure":
-        return Effect.mapBothEager(Parser.decodeUnknownEffect(cause)(input.cause, options), {
-          onSuccess: Exit_.failCause,
-          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["cause"], issue)])
-        });
-    }
+    return (input, ast, options) => {
+      if (!Exit_.isExit(input)) {
+        return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+      }
+      switch (input._tag) {
+        case "Success":
+          return Effect.mapBothEager(Parser.decodeUnknownEffect(value)(input.value, options), {
+            onSuccess: Exit_.succeed,
+            onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["value"], issue)])
+          });
+        case "Failure":
+          return Effect.mapBothEager(Parser.decodeUnknownEffect(cause)(input.cause, options), {
+            onSuccess: Exit_.failCause,
+            onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["cause"], issue)])
+          });
+      }
+    };
   }, {
     typeConstructor: {
       _tag: "effect/Exit"
@@ -3543,91 +4659,253 @@ export function Exit(value, error, defect) {
  * @category ReadonlyMap
  * @since 4.0.0
  */
-export function ReadonlyMap(key, value) {
-  const schema = declareConstructor()([key, value], ([key, value]) => (input, ast, options) => {
-    if (input instanceof globalThis.Map) {
-      const array = Array(Tuple([key, value]));
-      return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
-        onSuccess: array => new globalThis.Map(array),
-        onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["entries"], issue)])
-      });
-    }
-    return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+export function ReadonlyMap(key, value) {
+  const schema = declareConstructor()([key, value], ([key, value]) => {
+    const array = Array(Tuple([key, value]));
+    return (input, ast, options) => {
+      if (input instanceof globalThis.Map) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
+          onSuccess: array => new globalThis.Map(array),
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["entries"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
+  }, {
+    typeConstructor: {
+      _tag: "ReadonlyMap"
+    },
+    generation: {
+      runtime: `Schema.ReadonlyMap(?, ?)`,
+      Type: `globalThis.ReadonlyMap<?, ?>`
+    },
+    expected: "ReadonlyMap",
+    toCodec: ([key, value]) => link()(Array(Tuple([key, value])), Transformation.transform({
+      decode: e => new globalThis.Map(e),
+      encode: map => [...map.entries()]
+    })),
+    toArbitrary: ([key, value]) => (fc, ctx) => {
+      return fc.oneof(ctx?.isSuspend ? {
+        maxDepth: 2,
+        depthIdentifier: "ReadonlyMap"
+      } : {}, fc.constant([]), fc.array(fc.tuple(key, value), ctx?.constraints?.array)).map(as => new globalThis.Map(as));
+    },
+    toEquivalence: ([key, value]) => Equal.makeCompareMap(key, value),
+    toFormatter: ([key, value]) => t => {
+      const size = t.size;
+      if (size === 0) {
+        return "ReadonlyMap(0) {}";
+      }
+      const entries = globalThis.Array.from(t.entries()).sort().map(([k, v]) => `${key(k)} => ${value(v)}`);
+      return `ReadonlyMap(${size}) { ${entries.join(", ")} }`;
+    }
+  });
+  return make(schema.ast, {
+    key,
+    value
+  });
+}
+/**
+ * Creates a schema that validates a `HashMap` where keys and values must
+ * conform to the provided schemas.
+ *
+ * @category HashMap
+ * @since 4.0.0
+ */
+export function HashMap(key, value) {
+  const schema = declareConstructor()([key, value], ([key, value]) => {
+    const entries = Array(Tuple([key, value]));
+    return (input, ast, options) => {
+      if (HashMap_.isHashMap(input)) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(entries)(HashMap_.toEntries(input), options), {
+          onSuccess: HashMap_.fromIterable,
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["entries"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
+  }, {
+    typeConstructor: {
+      _tag: "effect/HashMap"
+    },
+    generation: {
+      runtime: `Schema.HashMap(?, ?)`,
+      Type: `HashMap.HashMap<?, ?>`,
+      importDeclaration: `import * as HashMap from "effect/HashMap"`
+    },
+    expected: "HashMap",
+    toCodec: ([key, value]) => link()(Array(Tuple([key, value])), Transformation.transform({
+      decode: HashMap_.fromIterable,
+      encode: HashMap_.toEntries
+    })),
+    toArbitrary: ([key, value]) => (fc, ctx) => {
+      return fc.oneof(ctx?.isSuspend ? {
+        maxDepth: 2,
+        depthIdentifier: "HashMap"
+      } : {}, fc.constant([]), fc.array(fc.tuple(key, value), ctx?.constraints?.array)).map(HashMap_.fromIterable);
+    },
+    toEquivalence: ([key, value]) => Equal.makeCompareMap(key, value),
+    toFormatter: ([key, value]) => t => {
+      const size = HashMap_.size(t);
+      if (size === 0) {
+        return "HashMap(0) {}";
+      }
+      const entries = HashMap_.toEntries(t).sort().map(([k, v]) => `${key(k)} => ${value(v)}`);
+      return `HashMap(${size}) { ${entries.join(", ")} }`;
+    }
+  });
+  return make(schema.ast, {
+    key,
+    value
+  });
+}
+/**
+ * @category ReadonlySet
+ * @since 4.0.0
+ */
+export function ReadonlySet(value) {
+  const schema = declareConstructor()([value], ([value]) => {
+    const array = Array(value);
+    return (input, ast, options) => {
+      if (input instanceof globalThis.Set) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
+          onSuccess: array => new globalThis.Set(array),
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["values"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
+  }, {
+    typeConstructor: {
+      _tag: "ReadonlySet"
+    },
+    generation: {
+      runtime: `Schema.ReadonlySet(?)`,
+      Type: `globalThis.ReadonlySet<?>`
+    },
+    expected: "ReadonlySet",
+    toCodec: ([value]) => link()(Array(value), Transformation.transform({
+      decode: e => new globalThis.Set(e),
+      encode: set => [...set.values()]
+    })),
+    toArbitrary: ([value]) => (fc, ctx) => {
+      return fc.oneof(ctx?.isSuspend ? {
+        maxDepth: 2,
+        depthIdentifier: "ReadonlySet"
+      } : {}, fc.constant([]), fc.array(value, ctx?.constraints?.array)).map(as => new globalThis.Set(as));
+    },
+    toEquivalence: ([value]) => Equal.makeCompareSet(value),
+    toFormatter: ([value]) => t => {
+      const size = t.size;
+      if (size === 0) {
+        return "ReadonlySet(0) {}";
+      }
+      const values = globalThis.Array.from(t.values()).sort().map(v => `${value(v)}`);
+      return `ReadonlySet(${size}) { ${values.join(", ")} }`;
+    }
+  });
+  return make(schema.ast, {
+    value
+  });
+}
+/**
+ * Creates a schema that validates a `HashSet` where values must conform to the
+ * provided schema.
+ *
+ * @category HashSet
+ * @since 4.0.0
+ */
+export function HashSet(value) {
+  const schema = declareConstructor()([value], ([value]) => {
+    const values = Array(value);
+    return (input, ast, options) => {
+      if (HashSet_.isHashSet(input)) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
+          onSuccess: HashSet_.fromIterable,
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["values"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
   }, {
     typeConstructor: {
-      _tag: "ReadonlyMap"
+      _tag: "effect/HashSet"
     },
     generation: {
-      runtime: `Schema.ReadonlyMap(?, ?)`,
-      Type: `globalThis.ReadonlyMap<?, ?>`
+      runtime: `Schema.HashSet(?)`,
+      Type: `HashSet.HashSet<?>`
     },
-    expected: "ReadonlyMap",
-    toCodec: ([key, value]) => link()(Array(Tuple([key, value])), Transformation.transform({
-      decode: e => new globalThis.Map(e),
-      encode: map => [...map.entries()]
+    expected: "HashSet",
+    toCodec: ([value]) => link()(Array(value), Transformation.transform({
+      decode: HashSet_.fromIterable,
+      encode: Arr.fromIterable
     })),
-    toArbitrary: ([key, value]) => (fc, ctx) => {
+    toArbitrary: ([value]) => (fc, ctx) => {
       return fc.oneof(ctx?.isSuspend ? {
         maxDepth: 2,
-        depthIdentifier: "ReadonlyMap"
-      } : {}, fc.constant([]), fc.array(fc.tuple(key, value), ctx?.constraints?.array)).map(as => new globalThis.Map(as));
+        depthIdentifier: "HashSet"
+      } : {}, fc.constant([]), fc.array(value, ctx?.constraints?.array)).map(HashSet_.fromIterable);
     },
-    toEquivalence: ([key, value]) => Equal.makeCompareMap(key, value),
-    toFormatter: ([key, value]) => t => {
-      const size = t.size;
+    toEquivalence: ([value]) => Equal.makeCompareSet(value),
+    toFormatter: ([value]) => t => {
+      const size = HashSet_.size(t);
       if (size === 0) {
-        return "ReadonlyMap(0) {}";
+        return "HashSet(0) {}";
       }
-      const entries = globalThis.Array.from(t.entries()).sort().map(([k, v]) => `${key(k)} => ${value(v)}`);
-      return `ReadonlyMap(${size}) { ${entries.join(", ")} }`;
+      const values = globalThis.Array.from(t).sort().map(v => `${value(v)}`);
+      return `HashSet(${size}) { ${values.join(", ")} }`;
     }
   });
   return make(schema.ast, {
-    key,
     value
   });
 }
 /**
- * @category ReadonlySet
+ * Creates a schema that validates a `Chunk` where values must conform to the
+ * provided schema.
+ *
+ * @category Chunk
  * @since 4.0.0
  */
-export function ReadonlySet(value) {
-  const schema = declareConstructor()([value], ([value]) => (input, ast, options) => {
-    if (input instanceof globalThis.Set) {
-      const array = Array(value);
-      return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
-        onSuccess: array => new globalThis.Set(array),
-        onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["values"], issue)])
-      });
-    }
-    return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+export function Chunk(value) {
+  const schema = declareConstructor()([value], ([value]) => {
+    const values = Array(value);
+    return (input, ast, options) => {
+      if (Chunk_.isChunk(input)) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
+          onSuccess: Chunk_.fromIterable,
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["values"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
   }, {
     typeConstructor: {
-      _tag: "ReadonlySet"
+      _tag: "effect/Chunk"
     },
     generation: {
-      runtime: `Schema.ReadonlySet(?)`,
-      Type: `globalThis.ReadonlySet<?>`
+      runtime: `Schema.Chunk(?)`,
+      Type: `Chunk.Chunk<?>`
     },
-    expected: "ReadonlySet",
+    expected: "Chunk",
     toCodec: ([value]) => link()(Array(value), Transformation.transform({
-      decode: e => new globalThis.Set(e),
-      encode: set => [...set.values()]
+      decode: Chunk_.fromIterable,
+      encode: Arr.fromIterable
     })),
     toArbitrary: ([value]) => (fc, ctx) => {
       return fc.oneof(ctx?.isSuspend ? {
         maxDepth: 2,
-        depthIdentifier: "ReadonlySet"
-      } : {}, fc.constant([]), fc.array(value, ctx?.constraints?.array)).map(as => new globalThis.Set(as));
+        depthIdentifier: "Chunk"
+      } : {}, fc.constant([]), fc.array(value, ctx?.constraints?.array)).map(Chunk_.fromIterable);
     },
-    toEquivalence: ([value]) => Equal.makeCompareSet(value),
+    toEquivalence: ([value]) => Chunk_.makeEquivalence(value),
     toFormatter: ([value]) => t => {
-      const size = t.size;
+      const size = Chunk_.size(t);
       if (size === 0) {
-        return "ReadonlySet(0) {}";
+        return "Chunk(0) {}";
       }
-      const values = globalThis.Array.from(t.values()).sort().map(v => `${value(v)}`);
-      return `ReadonlySet(${size}) { ${values.join(", ")} }`;
+      const values = globalThis.Array.from(t).sort().map(v => `${value(v)}`);
+      return `Chunk(${size}) { ${values.join(", ")} }`;
     }
   });
   return make(schema.ast, {
@@ -3635,6 +4913,11 @@ export function ReadonlySet(value) {
   });
 }
 /**
+ * Schema for JavaScript `RegExp` objects.
+ *
+ * The default JSON serializer encodes a `RegExp` as `{ source, flags }`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
@@ -3712,8 +4995,19 @@ export const URLFromString = /*#__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 `ValidDate` instead.
+ * Date("invalid")`). For validating only valid dates, use {@link DateValid}
+ * instead. The default JSON serializer encodes `Date` as an ISO 8601 string.
  *
+ * **Example** (Date schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * Schema.decodeUnknownSync(Schema.Date)(new Date("2024-01-01"))
+ * // => Date { 2024-01-01T00:00:00.000Z }
+ * ```
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
@@ -3745,9 +5039,20 @@ export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
 /**
  * A schema for `Duration` values.
  *
- * **Default JSON serializer**
+ * The default JSON serializer encodes `Duration` as a tagged object with the
+ * duration type and value.
  *
- * - encodes `Duration` as a `string`
+ * **Example** (Duration schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Duration } from "effect"
+ *
+ * Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(5))
+ * // => Duration(5s)
+ * ```
+ *
+ * @category Duration
  *
  * @since 4.0.0
  */
@@ -3842,6 +5147,35 @@ export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualT
  * @since 4.0.0
  */
 export const DurationFromMillis = /*#__PURE__*/Number.check(isGreaterThanOrEqualTo(0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromMillis));
+/**
+ * A schema for `BigDecimal` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `BigDecimal` as a `string`
+ *
+ * @since 4.0.0
+ */
+export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
+  typeConstructor: {
+    _tag: "effect/BigDecimal"
+  },
+  generation: {
+    runtime: `Schema.BigDecimal`,
+    Type: `BigDecimal.BigDecimal`,
+    importDeclaration: `import * as BigDecimal from "effect/BigDecimal"`
+  },
+  expected: "BigDecimal",
+  toCodecJson: () => link()(String.annotate({
+    expected: "a string that will be decoded as a BigDecimal"
+  }), Transformation.bigDecimalFromString),
+  toArbitrary: () => fc => fc.tuple(fc.bigInt(), fc.integer({
+    min: 0,
+    max: 20
+  })).map(([value, scale]) => BigDecimal_.make(value, scale)),
+  toFormatter: () => bd => BigDecimal_.format(bd),
+  toEquivalence: () => BigDecimal_.Equivalence
+});
 /**
  * A transformation schema that decodes a JSON-encoded string into an `unknown` value.
  *
@@ -3936,6 +5270,12 @@ export function fromJsonString(schema) {
   }).pipe(decodeTo(schema, Transformation.fromJsonString));
 }
 /**
+ * Schema for JavaScript `File` objects.
+ *
+ * The default JSON serializer encodes a `File` as `{ data, type, name, lastModified }`
+ * where `data` is base64-encoded.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const File = /*#__PURE__*/instanceOf(globalThis.File, {
@@ -3953,7 +5293,7 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
     name: String,
     lastModified: Number
   }), Transformation.transformOrFail({
-    decode: e => Result_.match(Base64.decode(e.data), {
+    decode: e => Result_.match(Encoding.decodeBase64(e.data), {
       onFailure: error => Effect.fail(new Issue.InvalidValue(Option_.some(e.data), {
         message: error.message
       })),
@@ -3969,7 +5309,7 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
       try: async () => {
         const bytes = new globalThis.Uint8Array(await file.arrayBuffer());
         return {
-          data: Base64.encode(bytes),
+          data: Encoding.encodeBase64(bytes),
           type: file.type,
           name: file.name,
           lastModified: file.lastModified
@@ -3982,6 +5322,12 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
   }))
 });
 /**
+ * Schema for JavaScript `FormData` objects.
+ *
+ * The default JSON serializer encodes a `FormData` as an array of `[key, entry]`
+ * pairs where each entry is tagged as `"String"` or `"File"`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
@@ -4111,6 +5457,11 @@ export function fromFormData(schema) {
   return FormData.pipe(decodeTo(schema, Transformation.fromFormData));
 }
 /**
+ * Schema for JavaScript `URLSearchParams` objects.
+ *
+ * The default JSON serializer encodes a `URLSearchParams` as a query string.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const URLSearchParams = /*#__PURE__*/instanceOf(globalThis.URLSearchParams, {
@@ -4268,6 +5619,9 @@ export const Trim = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a trimmed string"
 }).pipe(/*#__PURE__*/decodeTo(Trimmed, /*#__PURE__*/Transformation.trim()));
 /**
+ * A union schema for JavaScript property keys: `number | symbol | string`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const PropertyKey = /*#__PURE__*/Union([Finite, Symbol, String]);
@@ -4383,7 +5737,7 @@ export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
  */
 export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isUtc(u), {
   typeConstructor: {
-    _tag: "DateTime.Utc"
+    _tag: "effect/DateTime.Utc"
   },
   generation: {
     runtime: `Schema.DateTimeUtc`,
@@ -4391,10 +5745,7 @@ export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && D
     importDeclaration: `import * as DateTime from "effect/DateTime"`
   },
   expected: "DateTime.Utc",
-  toCodecJson: () => link()(String, {
-    decode: Getter.dateTimeUtcFromInput(),
-    encode: Getter.transform(DateTime.formatIso)
-  }),
+  toCodecJson: () => link()(String, Transformation.dateTimeUtcFromString),
   toArbitrary: () => (fc, ctx) => fc.date({
     noInvalidDate: true,
     ...ctx?.constraints?.date
@@ -4434,10 +5785,7 @@ export const DateTimeUtcFromDate = /*#__PURE__*/DateValid.pipe(/*#__PURE__*/deco
  */
 export const DateTimeUtcFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a DateTime.Utc"
-}).pipe(/*#__PURE__*/decodeTo(DateTimeUtc, /*#__PURE__*/Transformation.transform({
-  decode: DateTime.makeUnsafe,
-  encode: DateTime.formatIso
-})));
+}).pipe(/*#__PURE__*/decodeTo(DateTimeUtc, Transformation.dateTimeUtcFromString));
 /**
  * A transformation schema that decodes a number into a `DateTime.Utc`.
  *
@@ -4454,18 +5802,140 @@ export const DateTimeUtcFromMillis = /*#__PURE__*/Number.pipe(/*#__PURE__*/decod
   decode: /*#__PURE__*/Getter.dateTimeUtcFromInput(),
   encode: /*#__PURE__*/Getter.transform(DateTime.toEpochMillis)
 }));
+/**
+ * A schema for `DateTime.TimeZone.Offset` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `DateTime.TimeZone.Offset` as a number (offset in milliseconds)
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const TimeZoneOffset = /*#__PURE__*/declare(DateTime.isTimeZoneOffset, {
+  typeConstructor: {
+    _tag: "effect/DateTime.TimeZone.Offset"
+  },
+  generation: {
+    runtime: `Schema.TimeZoneOffset`,
+    Type: `DateTime.TimeZone.Offset`,
+    importDeclaration: `import * as DateTime from "effect/DateTime"`
+  },
+  expected: "DateTime.TimeZone.Offset",
+  toCodecJson: () => link()(Number, Transformation.timeZoneOffsetFromNumber),
+  toArbitrary: () => fc => fc.integer({
+    min: -12 * 60 * 60 * 1000,
+    max: 14 * 60 * 60 * 1000
+  }).map(n => DateTime.zoneMakeOffset(n)),
+  toFormatter: () => tz => DateTime.zoneToString(tz),
+  toEquivalence: () => (a, b) => a.offset === b.offset
+});
+/**
+ * A schema for `DateTime.TimeZone.Named` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `DateTime.TimeZone.Named` as a string (IANA time zone identifier)
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
+  typeConstructor: {
+    _tag: "effect/DateTime.TimeZone.Named"
+  },
+  generation: {
+    runtime: `Schema.TimeZoneNamed`,
+    Type: `DateTime.TimeZone.Named`,
+    importDeclaration: `import * as DateTime from "effect/DateTime"`
+  },
+  expected: "DateTime.TimeZone.Named",
+  toCodecJson: () => link()(String.annotate({
+    expected: "an IANA time zone identifier"
+  }), Transformation.timeZoneNamedFromString),
+  toArbitrary: () => fc => fc.constantFrom(...["UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney"].map(DateTime.zoneMakeNamedUnsafe)),
+  toFormatter: () => tz => DateTime.zoneToString(tz),
+  toEquivalence: () => (a, b) => a.id === b.id
+});
+/**
+ * A schema for `DateTime.TimeZone` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `DateTime.TimeZone` as a string (IANA identifier or offset like
+ *   `+03:00`)
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
+  typeConstructor: {
+    _tag: "effect/DateTime.TimeZone"
+  },
+  generation: {
+    runtime: `Schema.TimeZone`,
+    Type: `DateTime.TimeZone`,
+    importDeclaration: `import * as DateTime from "effect/DateTime"`
+  },
+  expected: "DateTime.TimeZone",
+  toCodecJson: () => link()(String.annotate({
+    expected: "a time zone string (IANA identifier or offset like +03:00)"
+  }), Transformation.timeZoneFromString),
+  toArbitrary: () => fc => fc.oneof(fc.integer({
+    min: -12 * 60 * 60 * 1000,
+    max: 14 * 60 * 60 * 1000
+  }).map(n => DateTime.zoneMakeOffset(n)), fc.constantFrom(...["UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney"].map(DateTime.zoneMakeNamedUnsafe))),
+  toFormatter: () => tz => DateTime.zoneToString(tz),
+  toEquivalence: () => (a, b) => DateTime.zoneToString(a) === DateTime.zoneToString(b)
+});
+/**
+ * A schema for `DateTime.Zoned` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `DateTime.Zoned` as a string in the format
+ *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isZoned(u), {
+  typeConstructor: {
+    _tag: "effect/DateTime.Zoned"
+  },
+  generation: {
+    runtime: `Schema.DateTimeZoned`,
+    Type: `DateTime.Zoned`,
+    importDeclaration: `import * as DateTime from "effect/DateTime"`
+  },
+  expected: "DateTime.Zoned",
+  toCodecJson: () => link()(String.annotate({
+    expected: "a zoned DateTime string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London])"
+  }), Transformation.dateTimeZonedFromString),
+  toArbitrary: () => (fc, ctx) => fc.tuple(fc.date({
+    noInvalidDate: true,
+    min: new globalThis.Date(-8640000000000000 + 14 * 60 * 60 * 1000),
+    max: new globalThis.Date(8640000000000000 - 14 * 60 * 60 * 1000),
+    ...ctx?.constraints?.date
+  }), fc.constantFrom("UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney")).map(([date, zone]) => DateTime.makeZonedUnsafe(date, {
+    timeZone: zone
+  })),
+  toFormatter: () => zoned => DateTime.formatIsoZoned(zoned),
+  toEquivalence: () => DateTime.Equivalence
+});
 const immerable = /*#__PURE__*/globalThis.Symbol.for("immer-draftable");
 function makeClass(Inherited, identifier, struct, annotations) {
   const getClassSchema = getClassSchemaFactory(struct, identifier, annotations);
   const ClassTypeId = getClassTypeId(identifier); // HMR support
   return class extends Inherited {
     constructor(...[input, options]) {
+      const props = input ?? {};
       if (options?.disableValidation) {
-        super(input, options);
+        super(props, options);
       } else {
-        const validated = struct.makeUnsafe(input, options);
+        const validated = struct.makeUnsafe(props, options);
         super({
-          ...input,
+          ...props,
           ...validated
         }, {
           ...options,
@@ -4497,6 +5967,9 @@ function makeClass(Inherited, identifier, struct, annotations) {
     static makeUnsafe(input, options) {
       return new this(input, options);
     }
+    static makeOption(input, options) {
+      return Parser.makeOption(getClassSchema(this))(input, options);
+    }
     static annotate(annotations) {
       return this.rebuild(AST.annotate(this.ast, annotations));
     }
@@ -4541,6 +6014,7 @@ function getClassSchemaFactory(from, identifier, annotations) {
         toCodec: ([from]) => new AST.Link(from.ast, transformation),
         toArbitrary: ([from]) => () => from.map(args => new self(args)),
         toFormatter: ([from]) => t => `${self.identifier}(${from(t)})`,
+        "~sentinels": AST.collectSentinels(from.ast),
         ...annotations
       }));
       memo = from.pipe(decodeTo(to, transformation));
@@ -4552,6 +6026,46 @@ function isStruct(schema) {
   return isSchema(schema);
 }
 /**
+ * Creates a schema-backed class whose constructor validates input against a
+ * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
+ * input (unless `disableValidation` is set in the options).
+ *
+ * Pass the desired class type as the first type parameter. The second optional
+ * type parameter can be used to add nominal brands.
+ *
+ * **Example** (Basic class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Person extends Schema.Class<Person>("Person")({
+ *   name: Schema.String,
+ *   age: Schema.Number
+ * }) {}
+ *
+ * const alice = new Person({ name: "Alice", age: 30 })
+ * console.log(alice.name) // "Alice"
+ * console.log(`${alice}`) // "Person({ name: Alice, age: 30 })"
+ * ```
+ *
+ * **Example** (Extending a class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Animal extends Schema.Class<Animal>("Animal")({
+ *   name: Schema.String
+ * }) {}
+ *
+ * class Dog extends Animal.extend<Dog>("Dog")({
+ *   breed: Schema.String
+ * }) {}
+ *
+ * const dog = new Dog({ name: "Rex", breed: "Labrador" })
+ * console.log(dog.name) // "Rex"
+ * console.log(dog.breed) // "Labrador"
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4560,6 +6074,27 @@ export const Class = identifier => (schema, annotations) => {
   return makeClass(Data.Class, identifier, struct, annotations);
 };
 /**
+ * Like {@link Class} but automatically adds a `_tag` literal field set to the
+ * given `tag` value. This makes instances compatible with tagged union
+ * discrimination patterns.
+ *
+ * The optional `identifier` parameter overrides the schema identifier;
+ * it defaults to the `tag` value.
+ *
+ * **Example** (Tagged class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Circle extends Schema.TaggedClass<Circle>()("Circle", {
+ *   radius: Schema.Number
+ * }) {}
+ *
+ * const c = new Circle({ radius: 5 })
+ * console.log(c._tag) // "Circle"
+ * console.log(c.radius) // 5
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4574,14 +6109,53 @@ export const TaggedClass = identifier => {
   };
 };
 /**
+ * Creates a schema-backed error class that can be used as a typed,
+ * yieldable error in Effect programs. Combines {@link Class} validation with
+ * the `YieldableError` interface so instances can be yielded directly inside
+ * `Effect.gen`.
+ *
+ * **Example** (Schema-backed error)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 1 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const ErrorClass = identifier => (schema, annotations) => {
   const struct = isStruct(schema) ? schema : Struct(schema);
-  return makeClass(core.Error, identifier, struct, annotations);
+  const self = makeClass(core.Error, identifier, struct, annotations);
+  self.prototype.name = identifier;
+  return self;
 };
 /**
+ * Like {@link ErrorClass} but automatically adds a `_tag` literal field. The
+ * resulting class is both a schema-validated, yieldable error and a tagged
+ * union member.
+ *
+ * **Example** (Tagged error class)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 42 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4596,6 +6170,11 @@ export const TaggedErrorClass = identifier => {
   };
 };
 /**
+ * Derives a {@link LazyArbitrary} from a schema. The result is memoized so
+ * repeated calls with the same schema are cheap.
+ *
+ * Prefer {@link toArbitrary} when you just need the arbitrary directly.
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -4604,6 +6183,24 @@ export function toArbitraryLazy(schema) {
   return fc => lawc(fc, {});
 }
 /**
+ * Derives a `fast-check` `Arbitrary` from a schema for property-based
+ * testing. The derived arbitrary generates values that satisfy the schema.
+ *
+ * **Example** (Generating arbitrary values)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import * as FastCheck from "fast-check"
+ *
+ * const PersonArb = Schema.toArbitrary(
+ *   Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * )
+ *
+ * // Sample a random value
+ * const sample = FastCheck.sample(PersonArb, 1)[0]
+ * console.log(typeof sample.name) // "string"
+ * ```
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -4630,6 +6227,13 @@ export function overrideToFormatter(toFormatter) {
   };
 }
 /**
+ * Derives a string formatter function from a schema. The formatter converts
+ * a value to its human-readable string representation, recursing into structs,
+ * arrays, and unions.
+ *
+ * The optional `onBefore` hook lets you intercept specific AST nodes before
+ * the default formatting logic runs.
+ *
  * @category Formatter
  * @since 4.0.0
  */
@@ -4768,10 +6372,9 @@ export function toFormatter(schema, options) {
 // Equivalence
 // -----------------------------------------------------------------------------
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it would make
- * the schema invariant.
+ * Overrides the equivalence derivation for a schema by supplying a custom
+ * `Equivalence`. Use this when the default structural equivalence derived by
+ * {@link toEquivalence} is not appropriate for a type.
  *
  * @category Equivalence
  * @since 4.0.0
@@ -4782,6 +6385,21 @@ export function overrideToEquivalence(toEquivalence) {
   });
 }
 /**
+ * Derives an `Equivalence` from a schema. Two values are considered equal when
+ * every field (and nested field) compares equal according to the schema
+ * structure.
+ *
+ * **Example** (Struct equivalence)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const eq = Schema.toEquivalence(Schema.Struct({ id: Schema.Number, name: Schema.String }))
+ *
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 1, name: "Alice" })) // true
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 2, name: "Alice" })) // false
+ * ```
+ *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -4792,6 +6410,10 @@ export function toEquivalence(schema) {
 // Representation
 // -----------------------------------------------------------------------------
 /**
+ * Derives an intermediate `SchemaRepresentation.Document` from a schema. This
+ * document is used internally by {@link toJsonSchemaDocument} and related
+ * functions to produce JSON Schema output.
+ *
  * @category Representation
  * @since 4.0.0
  */
@@ -4816,17 +6438,23 @@ export function toJsonSchemaDocument(schema, options) {
   };
 }
 // -----------------------------------------------------------------------------
-// Serializer
+// Canonical Codecs
 // -----------------------------------------------------------------------------
 /**
- * @category Serializer
+ * Derives a canonical JSON codec from a schema. The encoded form is `unknown`
+ * (any JSON-compatible value), decoded to the schema's `Type`.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toCodecJson(schema) {
   return make(InternalToCodec.toCodecJson(schema.ast));
 }
 /**
- * @category Serializer
+ * Derives an isomorphism codec from a schema. The encoded form is the
+ * schema's `Iso` type — the intermediate representation used for round-tripping.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toCodecIso(schema) {
@@ -4840,7 +6468,11 @@ export function toCodecStringTree(schema, options) {
   }
 }
 /**
- * @category Serializer
+ * 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.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toEncoderXml(codec, options) {
@@ -4956,8 +6588,6 @@ function getStringTreePriority(ast) {
 const treeReorder = /*#__PURE__*/InternalToCodec.makeReorder(getStringTreePriority);
 function serializerTree(ast, recur, onMissingAnnotation) {
   switch (ast._tag) {
-    case "Unknown":
-    case "ObjectKeyword":
     case "Declaration":
       {
         const getLink = ast.annotations?.toCodecJson ?? ast.annotations?.toCodec;
@@ -4973,6 +6603,9 @@ function serializerTree(ast, recur, onMissingAnnotation) {
       return AST.replaceEncoding(ast, [nullToString]);
     case "Boolean":
       return AST.replaceEncoding(ast, [booleanToString]);
+    case "Unknown":
+    case "ObjectKeyword":
+      return AST.replaceEncoding(ast, [AST.unknownToStringTree]);
     case "Enum":
     case "Number":
     case "Literal":
@@ -5051,6 +6684,9 @@ function onSerializerEnsureArray(ast) {
 // Optic APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives an `Iso` optic from a schema that isomorphically converts between
+ * the schema's `Type` and its `Iso` (intermediate / serialized form).
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5059,6 +6695,8 @@ export function toIso(schema) {
   return Optic_.makeIso(Parser.encodeSync(serializer), Parser.decodeSync(serializer));
 }
 /**
+ * Returns an identity `Iso` over the schema's source (`Type`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5066,6 +6704,8 @@ export function toIsoSource(_) {
   return Optic_.id();
 }
 /**
+ * Returns an identity `Iso` over the schema's focus (`Iso`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5073,10 +6713,11 @@ export function toIsoFocus(_) {
   return Optic_.id();
 }
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it changes
- * the schema type.
+ * Overrides the ISO codec derivation for a schema by providing a target codec
+ * and explicit `decode`/`encode` getters. The resulting schema carries a
+ * custom `Iso` type, which changes the schema's type parameter — use
+ * {@link overrideToCodecIso} when the default ISO transformation is not
+ * appropriate.
  *
  * @category Optic
  * @since 4.0.0
@@ -5094,11 +6735,15 @@ export function overrideToCodecIso(to, transformation) {
 // Differ APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives a JSON Patch differ from a codec. Serializes values to JSON (via
+ * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
+ * and new values, and can apply patches back to the typed value.
+ *
  * @category JsonPatch
  * @since 4.0.0
  */
 export function toDifferJsonPatch(schema) {
-  const serializer = toCodecJson(schema); // TODO: remove this cast
+  const serializer = toCodecJson(schema);
   const get = Parser.encodeSync(serializer);
   const set = Parser.decodeSync(serializer);
   return {
@@ -5113,6 +6758,10 @@ export function toDifferJsonPatch(schema) {
   };
 }
 /**
+ * Creates a recursive schema for a {@link Tree} of values described by `node`.
+ * The resulting schema accepts a single node value, an array of trees, or an
+ * object whose values are trees.
+ *
  * @category Tree
  * @since 4.0.0
  */
@@ -5122,24 +6771,29 @@ export function Tree(node) {
   return Tree;
 }
 /**
- * @category Tree
- * @since 4.0.0
- */
-export function MutableTree(node) {
-  const MutableTree$ref = suspend(() => MutableTree);
-  const MutableTree = Union([node, mutable(Array(MutableTree$ref)), Record(String, mutableKey(MutableTree$ref))]);
-  return MutableTree;
-}
-/**
+ * Schema that accepts and validates any immutable JSON-compatible value.
+ *
+ * **Example** (Validating a JSON value)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const result = Schema.decodeUnknownOption(Schema.Json)({ key: [1, true, null] })
+ * console.log(result._tag) // "Some"
+ * ```
+ *
  * @category JSON
  * @since 4.0.0
  */
-export const Json = /*#__PURE__*/Tree(/*#__PURE__*/Union([Null, Number, Boolean, String]));
+export const Json = /*#__PURE__*/make(AST.Json);
 /**
+ * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
+ * the immutable variant.
+ *
  * @category JSON
  * @since 4.0.0
  */
-export const MutableJson = /*#__PURE__*/MutableTree(/*#__PURE__*/Union([Null, Number, Boolean, String]));
+export const MutableJson = /*#__PURE__*/make(AST.MutableJson);
 // -----------------------------------------------------------------------------
 // Annotations
 // -----------------------------------------------------------------------------