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

package/dist/Schema.d.ts

@@ -1,9 +1,94 @@
 /**
+ * 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
  */
+/** @effect-diagnostics schemaStructWithTag:skip-file */
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+import * as BigDecimal_ from "./BigDecimal.ts";
 import type * as Brand from "./Brand.ts";
 import * as Cause_ from "./Cause.ts";
+import * as Chunk_ from "./Chunk.ts";
 import type * as Combiner from "./Combiner.ts";
 import * as DateTime from "./DateTime.ts";
 import type { Differ } from "./Differ.ts";
@@ -12,6 +97,8 @@ import * as Effect from "./Effect.ts";
 import * as Equivalence from "./Equivalence.ts";
 import * as Exit_ from "./Exit.ts";
 import type { Formatter } from "./Formatter.ts";
+import * as HashMap_ from "./HashMap.ts";
+import * as HashSet_ from "./HashSet.ts";
 import * as JsonPatch from "./JsonPatch.ts";
 import * as JsonSchema from "./JsonSchema.ts";
 import * as Optic_ from "./Optic.ts";
@@ -29,28 +116,42 @@ import type { Assign, Lambda, Mutable, Simplify } from "./Struct.ts";
 import * as Struct_ from "./Struct.ts";
 import * as FastCheck from "./testing/FastCheck.ts";
 import type { UnionToIntersection } from "./Types.ts";
+import type { Unify } from "./Unify.ts";
 declare const TypeId = "~effect/Schema/Schema";
 /**
- * Is this schema required or optional?
+ * Whether a schema field is required or optional within a struct.
+ *
+ * @see {@link optionalKey} — mark a struct field as optional
+ * @see {@link optional} — mark a struct field as optional with `| undefined`
  *
  * @since 4.0.0
  */
 export type Optionality = "required" | "optional";
 /**
- * Is this schema read-only or mutable?
+ * Whether a schema field is readonly or mutable within a struct.
+ *
+ * @see {@link mutableKey} — mark a struct field as mutable
  *
  * @since 4.0.0
  */
 export type Mutability = "readonly" | "mutable";
 /**
- * Does the constructor of this schema supply a default value?
+ * Whether a schema field has a constructor default value.
+ *
+ * @see {@link withConstructorDefault} — add a default to a schema field
+ * @see {@link tag} — creates a literal field with a constructor default
  *
  * @since 4.0.0
  */
 export type ConstructorDefault = "no-default" | "with-default";
 /**
- * Configuration options for the `makeUnsafe` method, providing control over
- * parsing behavior and validation.
+ * Options for `makeUnsafe` and Class constructors.
+ *
+ * When to use:
+ * - Pass `disableValidation: true` to skip validation when you trust the data.
+ * - Pass `parseOptions` to control error reporting behavior.
+ *
+ * @see {@link Bottom.makeUnsafe}
  *
  * @since 4.0.0
  */
@@ -65,15 +166,19 @@ export interface MakeOptions {
     readonly disableValidation?: boolean | undefined;
 }
 /**
- * The base interface for all schemas in the Effect Schema library, exposing all
- * 14 type parameters that control schema behavior and type inference. Bottom
- * sits at the root of the schema type hierarchy and provides access to the
- * complete internal type information of schemas.
+ * The fully-parameterized base interface for all schemas. Exposes all 14 type
+ * parameters controlling type inference, mutability, optionality, services,
+ * and transformation behavior.
+ *
+ * When to use:
+ * - You are writing advanced generic schema utilities or performing schema
+ *   introspection.
+ * - In user code, prefer {@link Schema}, {@link Codec}, {@link Decoder}, or
+ *   {@link Encoder} instead.
  *
- * Bottom is primarily used for advanced type-level operations, schema
- * introspection, and when you need precise control over all aspects of schema
- * behavior including mutability, optionality, service dependencies, and
- * transformation characteristics.
+ * @see {@link Top} — the existential "any schema" type (erased type params)
+ * @see {@link Schema} — tracks only the decoded Type
+ * @see {@link Codec} — tracks Type + Encoded
  *
  * @since 4.0.0
  */
@@ -103,71 +208,202 @@ export interface Bottom<out T, out E, out RD, out RE, out Ast extends AST.AST, o
      * @throws {Error} The issue is contained in the error cause.
      */
     makeUnsafe(input: this["~type.make.in"], options?: MakeOptions): this["Type"];
+    makeOption(input: this["~type.make.in"], options?: MakeOptions): Option_.Option<this["Type"]>;
 }
 /**
+ * The schema type returned by {@link declareConstructor}, tracking the decoded
+ * type `T`, the encoded type `E`, and the list of type-parameter schemas
+ * `TypeParameters`.
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export interface declareConstructor<T, E, TypeParameters extends ReadonlyArray<Top>, Iso = T> extends Bottom<T, E, TypeParameters[number]["DecodingServices"], TypeParameters[number]["EncodingServices"], AST.Declaration, declareConstructor<T, E, TypeParameters, Iso>, T, Iso, TypeParameters> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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"
+ *
+ * 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 })
+ *         )
+ *       }
+ *   )
  *
- * @see {@link declare} for creating schemas for non parametric types.
+ * const schema = Box(Schema.Number)
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
  */
 export declare function declareConstructor<T, E = T, Iso = T>(): <const TypeParameters extends ReadonlyArray<Top>>(typeParameters: TypeParameters, run: (typeParameters: { readonly [K in keyof TypeParameters]: Codec<TypeParameters[K]["Type"], TypeParameters[K]["Encoded"]>; }) => (u: unknown, self: AST.Declaration, options: AST.ParseOptions) => Effect.Effect<T, Issue.Issue>, annotations?: Annotations.Declaration<T, TypeParameters>) => declareConstructor<T, E, TypeParameters, Iso>;
 /**
+ * The schema type returned by {@link declare}, representing a non-parametric
+ * opaque type `T` with no type parameters.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export interface declare<T, Iso = T> extends declareConstructor<T, T, readonly [], Iso> {
 }
 /**
- * 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 declare function declare<T, Iso = T>(is: (u: unknown) => u is T, annotations?: Annotations.Declaration<T> | undefined): declare<T, Iso>;
 /**
- * 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
  */
 export declare function revealBottom<S extends Top>(bottom: S): Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], S["~rebuild.out"], S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]>;
 /**
  * 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
  */
 export declare function annotate<S extends Top>(annotations: S["~annotate.in"]): (self: S) => S["~rebuild.out"];
 /**
- * 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
  */
 export declare function annotateKey<S extends Top>(annotations: Annotations.Key<S["Type"]>): (self: S) => S["~rebuild.out"];
 /**
- * The top (most general) type for all schema-like values in this module.
+ * The existential "any schema" type — all type parameters are erased to `unknown`.
  *
- * When to use:
- * - You are writing generic helpers and only need "some schema", without caring about its `Type` / `Encoded`.
- * - You need a common constraint for type-level utilities (for example in `Schema.Type` or `Codec.Encoded`).
+ * Use `Top` as a constraint when writing generic utilities that must accept *any*
+ * schema regardless of its `Type`, `Encoded`, or service requirements. It is the
+ * widest possible schema type and therefore gives you the least static information.
  *
- * Behavior:
- * - This is a *type-level* supertype; it does not represent a specific concrete schema.
- * - In user code, you usually want {@link Schema}, {@link Codec}, {@link Decoder}, or {@link Encoder} instead.
+ * In user code prefer the narrower interfaces:
+ * - {@link Schema}`<T>` — when you only care about the decoded type
+ * - {@link Codec}`<T, E, RD, RE>` — when you need the encoded type and service requirements
+ * - {@link Decoder}`<T, RD>` — for decode-only APIs
+ * - {@link Encoder}`<E, RE>` — for encode-only APIs
  *
  * @since 4.0.0
  */
@@ -175,24 +411,52 @@ export interface Top extends Bottom<unknown, unknown, unknown, unknown, AST.AST,
 unknown, Mutability, Optionality, ConstructorDefault, Mutability, Optionality> {
 }
 /**
+ * Namespace of type-level helpers for {@link Schema}.
+ *
  * @since 4.0.0
  */
 export declare namespace Schema {
     /**
+     * Extracts the decoded `Type` from a schema.
+     *
+     * **Example** (Extracting the decoded type)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
+     * type Person = Schema.Schema.Type<typeof Person>
+     * // { readonly name: string; readonly age: number }
+     * ```
+     *
      * @since 4.0.0
      */
-    type Type<S extends Top> = S["Type"];
+    type Type<S> = S extends Top ? S["Type"] : never;
 }
 /**
- * A typed view of a schema that tracks the decoded (output) type `T`.
+ * A typed view of a schema that tracks only the decoded (output) type `T`.
  *
- * When to use:
- * - You want to accept "any schema that decodes to `T`" in a function signature.
- * - You only care about the decoded type and do not need to talk about the encoded representation.
+ * Use `Schema<T>` as a constraint when you want to accept "any schema that
+ * decodes to `T`" and do not need to know or constrain the encoded
+ * representation, required services, or any other type parameters.
+ *
+ * This is a structural interface — concrete schema values are produced by the
+ * constructors in this module (e.g. {@link Struct}, {@link String}, {@link Number}).
+ * When you also need the encoded type or service requirements, use {@link Codec}.
+ *
+ * **Example** (Function that accepts any schema decoding to `string`)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * declare function print(schema: Schema.Schema<string>): void
+ *
+ * print(Schema.String)            // ok
+ * print(Schema.NonEmptyString)    // ok
+ * ```
  *
- * Behavior:
- * - This is a structural interface used for typing; it does not by itself construct or run validation.
- * - If you also need the encoded type (or decoding/encoding services), use {@link Codec}.
+ * @see {@link Codec} — also tracks Encoded, DecodingServices, EncodingServices
+ * @see {@link Schema.Type} — extract the decoded type at the type level
  *
  * @since 4.0.0
  */
@@ -201,22 +465,66 @@ export interface Schema<out T> extends Top {
     readonly "~rebuild.out": Schema<T>;
 }
 /**
+ * Namespace of type-level helpers for {@link Codec}.
+ *
  * @since 4.0.0
  */
 export declare namespace Codec {
     /**
+     * Extracts the encoded (`Encoded`) type from a schema.
+     *
+     * **Example** (Extracting the encoded type)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const schema = Schema.NumberFromString
+     * type Enc = Schema.Codec.Encoded<typeof schema>
+     * // string
+     * ```
+     *
      * @since 4.0.0
      */
-    type Encoded<S extends Top> = S["Encoded"];
+    type Encoded<S> = S extends Top ? S["Encoded"] : never;
     /**
+     * Extracts the Effect services required during *decoding* from a schema.
+     *
+     * **Example** (Checking decoding service requirements)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const schema = Schema.String
+     * type RD = Schema.Codec.DecodingServices<typeof schema>
+     * // never
+     * ```
+     *
      * @since 4.0.0
      */
-    type DecodingServices<S extends Top> = S["DecodingServices"];
+    type DecodingServices<S> = S extends Top ? S["DecodingServices"] : never;
     /**
+     * Extracts the Effect services required during *encoding* from a schema.
+     *
+     * **Example** (Checking encoding service requirements)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const schema = Schema.String
+     * type RE = Schema.Codec.EncodingServices<typeof schema>
+     * // never
+     * ```
+     *
      * @since 4.0.0
      */
-    type EncodingServices<S extends Top> = S["EncodingServices"];
+    type EncodingServices<S> = S extends Top ? S["EncodingServices"] : never;
     /**
+     * Converts a schema type into an assertion function signature. The resulting
+     * function narrows its argument to `I & S["Type"]`. Only schemas with
+     * `DecodingServices: never` (i.e. no required services) can be used here.
+     *
+     * Produced by {@link asserts}.
+     *
      * @since 4.0.0
      */
     type ToAsserts<S extends Top & {
@@ -224,6 +532,18 @@ export declare namespace Codec {
     }> = <I>(input: I) => asserts input is I & S["Type"];
 }
 /**
+ * A schema that additionally supports optic (lens/prism) operations.
+ *
+ * `Optic<T, Iso>` extends {@link Schema}`<T>` with an `Iso` type that
+ * describes the isomorphic counterpart used by the optic layer. Crucially,
+ * decoding and encoding require *no* Effect services (`DecodingServices` and
+ * `EncodingServices` are both `never`), which means the optic can operate
+ * purely without an Effect runtime.
+ *
+ * Most primitive schemas (e.g. `Schema.String`, `Schema.Number`) implement
+ * `Optic` automatically. You normally interact with this interface through
+ * {@link Optic_} utilities rather than constructing it directly.
+ *
  * @since 4.0.0
  */
 export interface Optic<out T, out Iso> extends Schema<T> {
@@ -233,16 +553,32 @@ export interface Optic<out T, out Iso> extends Schema<T> {
     readonly "~rebuild.out": Optic<T, Iso>;
 }
 /**
- * A schema that tracks both the decoded type `T` and the encoded representation `E`.
+ * A schema that tracks the decoded type `T`, the encoded type `E`, and the
+ * Effect services required during decoding (`RD`) and encoding (`RE`).
  *
- * When to use:
- * - You want a schema in APIs that may both decode and encode.
- * - You need to preserve/describe the encoded representation (`Encoded`) in types.
- * - You need to model required services for decoding (`RD`) and encoding (`RE`).
+ * Use `Codec<T, E, RD, RE>` when you need to preserve full type information
+ * about a schema — both what it decodes to and what it serializes from/to.
+ * Most concrete schemas produced by this module implement `Codec`.
+ *
+ * For APIs that only need one direction, prefer the narrower views:
+ * - {@link Decoder}`<T, RD>` — decode-only
+ * - {@link Encoder}`<E, RE>` — encode-only
+ * - {@link Schema}`<T>` — type-only (no encoded representation)
+ *
+ * **Example** (Accepting a codec that decodes to `number` from `string`)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * declare function serialize<T>(codec: Schema.Codec<T, string>): string
+ *
+ * serialize(Schema.NumberFromString) // ok — decodes number, encoded as string
+ * ```
  *
- * Behavior:
- * - This is a typing surface; concrete schema values are created by the various constructors in this module.
- * - For decode-only or encode-only APIs, prefer {@link Decoder} or {@link Encoder}.
+ * @see {@link Codec.Encoded} — extract the encoded type
+ * @see {@link Codec.DecodingServices} — extract required decoding services
+ * @see {@link Codec.EncodingServices} — extract required encoding services
+ * @see {@link revealCodec} — helper to make TypeScript infer the full Codec type
  *
  * @since 4.0.0
  */
@@ -253,11 +589,22 @@ export interface Codec<out T, out E = T, out RD = never, out RE = never> extends
     readonly "~rebuild.out": Codec<T, E, RD, RE>;
 }
 /**
- * A `Codec` view intended for APIs that only *decode* (parse/validate) values.
+ * A {@link Codec} view for APIs that only *decode* (parse/validate) values.
  *
- * When to use:
- * - You want to accept "anything that can decode to `T`", without requiring encoding support.
- * - You are writing helpers that should not depend on the schema’s `Encoded` representation.
+ * Use `Decoder<T, RD>` to accept "any schema that can decode to `T`" without
+ * constraining or depending on the encoded representation (`Encoded` is
+ * `unknown`) or encoding services.
+ *
+ * **Example** (Function that only needs to decode)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * declare function validate<T>(decoder: Schema.Decoder<T>): (input: unknown) => T
+ *
+ * validate(Schema.String)          // ok
+ * validate(Schema.NumberFromString) // ok
+ * ```
  *
  * @since 4.0.0
  */
@@ -265,11 +612,22 @@ export interface Decoder<out T, out RD = never> extends Codec<T, unknown, RD, un
     readonly "~rebuild.out": Decoder<T, RD>;
 }
 /**
- * A `Codec` view intended for APIs that only *encode* values.
+ * A {@link Codec} view for APIs that only *encode* values.
  *
- * When to use:
- * - You want to accept "anything that can encode to `E`", without requiring decoding support.
- * - You are writing helpers that should not depend on the schema’s decoded `Type`.
+ * Use `Encoder<E, RE>` to accept "any schema that can encode to `E`" without
+ * constraining or depending on the decoded `Type` (`Type` is `unknown`) or
+ * decoding services.
+ *
+ * **Example** (Function that only needs to encode)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * declare function serialize<E>(encoder: Schema.Encoder<E>): (value: unknown) => E
+ *
+ * serialize(Schema.String)          // ok — encodes to string
+ * serialize(Schema.NumberFromString) // ok — encodes number to string
+ * ```
  *
  * @since 4.0.0
  */
@@ -277,17 +635,54 @@ export interface Encoder<out E, out RE = never> extends Codec<unknown, E, unknow
     readonly "~rebuild.out": Encoder<E, RE>;
 }
 /**
+ * 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 declare function revealCodec<T, E, RD, RE>(codec: Codec<T, E, RD, RE>): Codec<T, E, RD, RE>;
 declare 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.
+ *
+ * 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)
  *
- * 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.
+ * ```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
  */
@@ -301,6 +696,22 @@ export declare class SchemaError {
     toString(): string;
 }
 /**
+ * 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 declare function isSchemaError(u: unknown): u is SchemaError;
@@ -450,16 +861,32 @@ export declare const is: typeof Parser.is;
  */
 export declare const asserts: typeof 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
  */
 export declare function decodeUnknownEffect<S extends Top>(schema: S): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Effect` that succeeds with the decoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link decodeUnknownEffect}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export declare const decodeEffect: <S extends Top>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Effect.Effect<S["Type"], SchemaError, S["DecodingServices"]>;
 /**
+ * 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
  */
@@ -467,6 +894,12 @@ export declare function decodeUnknownExit<S extends Top & {
     readonly DecodingServices: never;
 }>(schema: S): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, returning an `Exit` that is either a `Success` with the
+ * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
+ * schemas that have no `DecodingServices` requirement. For `unknown` input use
+ * {@link decodeUnknownExit}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -474,11 +907,21 @@ export declare const decodeExit: <S extends Top & {
     readonly DecodingServices: never;
 }>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the decoded value on success or `None` on failure. Prefer this
+ * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
+ * need to know whether decoding succeeded and don't need error details. For
+ * typed input use {@link decodeOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export declare const decodeUnknownOption: typeof Parser.decodeUnknownOption;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Option` that is `Some` with the decoded value on success or
+ * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -486,21 +929,58 @@ export declare const decodeOption: <S extends Top & {
     readonly DecodingServices: never;
 }>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => Option_.Option<S["Type"]>;
 /**
+ * Decodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link decodePromise}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export declare const decodeUnknownPromise: typeof Parser.decodeUnknownPromise;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Promise` that resolves with the decoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export declare const decodePromise: typeof Parser.decodePromise;
 /**
+ * Decodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to validate data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link decodeUnknownOption},
+ * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
+ * use {@link decodeSync}.
+ *
+ * **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 declare const decodeUnknownSync: typeof Parser.decodeUnknownSync;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
+ * use {@link decodeUnknownSync}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -508,16 +988,43 @@ export declare const decodeSync: <S extends Top & {
     readonly DecodingServices: never;
 }>(schema: S) => (input: S["Encoded"], options?: AST.ParseOptions) => S["Type"];
 /**
+ * Encodes an `unknown` input against a schema, returning an `Effect` that
+ * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
+ * when the input type is not statically known. Prefer {@link encodeEffect} when
+ * the input is already typed as the schema's `Type`.
+ *
+ * **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
  */
 export declare function encodeUnknownEffect<S extends Top>(schema: S): (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Effect` that succeeds with the encoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link encodeUnknownEffect}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export declare const encodeEffect: <S extends Top>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Effect.Effect<S["Encoded"], SchemaError, S["EncodingServices"]>;
 /**
+ * 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
  */
@@ -525,6 +1032,12 @@ export declare function encodeUnknownExit<S extends Top & {
     readonly EncodingServices: never;
 }>(schema: S): (input: unknown, options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * returning an `Exit` that is either a `Success` with the encoded value or a
+ * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
+ * `EncodingServices` requirement. For `unknown` input use
+ * {@link encodeUnknownExit}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -532,11 +1045,21 @@ export declare const encodeExit: <S extends Top & {
     readonly EncodingServices: never;
 }>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
 /**
+ * Encodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the encoded value on success or `None` on failure. Prefer this
+ * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
+ * need to know whether encoding succeeded and don't need error details. For
+ * typed input use {@link encodeOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export declare const encodeUnknownOption: typeof Parser.encodeUnknownOption;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Option` that is `Some` with the encoded value on success or `None` on
+ * failure. For `unknown` input use {@link encodeUnknownOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -544,6 +1067,11 @@ export declare const encodeOption: <S extends Top & {
     readonly EncodingServices: never;
 }>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Option_.Option<S["Encoded"]>;
 /**
+ * Encodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link encodePromise}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -551,6 +1079,10 @@ export declare const encodeUnknownPromise: <S extends Top & {
     readonly EncodingServices: never;
 }>(schema: S) => (input: unknown, options?: AST.ParseOptions) => Promise<S["Encoded"]>;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Promise` that resolves with the encoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -558,31 +1090,28 @@ export declare const encodePromise: <S extends Top & {
     readonly EncodingServices: never;
 }>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => Promise<S["Encoded"]>;
 /**
+ * Encodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to serialize data at a
+ * 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 declare const encodeUnknownSync: typeof Parser.encodeUnknownSync;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * throwing a {@link SchemaError} on failure. For `unknown` input use
+ * {@link encodeUnknownSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export declare const encodeSync: <S extends Top & {
     readonly EncodingServices: never;
-}>(schema: S) => (input: S["Type"], options
-/**
- * The top (most general) type for all schema-like values in this module.
- *
- * When to use:
- * - You are writing generic helpers and only need "some schema", without caring about its `Type` / `Encoded`.
- * - You need a common constraint for type-level utilities (for example in `Schema.Type` or `Codec.Encoded`).
- *
- * Behavior:
- * - This is a *type-level* supertype; it does not represent a specific concrete schema.
- * - In user code, you usually want {@link Schema}, {@link Codec}, {@link Decoder}, or {@link Encoder} instead.
- *
- * @since 4.0.0
- */
-?: AST.ParseOptions) => S["Encoded"];
+}>(schema: S) => (input: S["Type"], options?: AST.ParseOptions) => S["Encoded"];
 /**
  * Creates a schema from an AST (Abstract Syntax Tree) node.
  *
@@ -607,6 +1136,10 @@ export declare const make: <S extends Top>(ast: S["ast"], options?: object) => S
  */
 export declare function isSchema(u: unknown): u is Top;
 /**
+ * Schema type for an exact optional struct key. The key may be absent, but
+ * when present must match the wrapped schema (no implicit `undefined`).
+ * Produced by {@link optionalKey}.
+ *
  * @since 4.0.0
  */
 export interface optionalKey<S extends Top> extends Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], optionalKey<S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], "optional", S["~type.constructor.default"], S["~encoded.mutability"], "optional"> {
@@ -644,10 +1177,16 @@ interface requiredKeyLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends optionalKey<Top> ? this["~lambda.in"]["schema"] : "Error: schema not eligible for requiredKey";
 }
 /**
+ * Reverses {@link optionalKey}, returning the inner required schema. Only
+ * applicable to schemas already wrapped with `optionalKey`.
+ *
  * @since 4.0.0
  */
 export declare const requiredKey: requiredKeyLambda;
 /**
+ * Schema type for an optional struct key that also accepts `undefined`.
+ * Equivalent to `optionalKey<UndefinedOr<S>>`. Produced by {@link optional}.
+ *
  * @since 4.0.0
  */
 export interface optional<S extends Top> extends optionalKey<UndefinedOr<S>> {
@@ -657,27 +1196,26 @@ interface optionalLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? optional<this["~lambda.in"]> : never;
 }
 /**
- * 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
@@ -688,10 +1226,16 @@ interface requiredLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends optional<Top> ? this["~lambda.in"]["schema"]["members"][0] : "Error: schema not eligible for required";
 }
 /**
+ * Reverses {@link optional}, returning the inner schema (unwrapping `UndefinedOr`).
+ * Only applicable to schemas already wrapped with `optional`.
+ *
  * @since 4.0.0
  */
 export declare const required: requiredLambda;
 /**
+ * Schema type for a mutable struct key. The key's property is writable.
+ * Produced by {@link mutableKey}.
+ *
  * @since 4.0.0
  */
 export interface mutableKey<S extends Top> extends Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], mutableKey<S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], "mutable", S["~type.optionality"], S["~type.constructor.default"], "mutable", S["~encoded.optionality"]> {
@@ -703,6 +1247,9 @@ interface mutableKeyLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? mutableKey<this["~lambda.in"]> : never;
 }
 /**
+ * Makes a struct field mutable (removes the `readonly` modifier on the property).
+ * Use {@link readonlyKey} to reverse.
+ *
  * @since 4.0.0
  */
 export declare const mutableKey: mutableKeyLambda;
@@ -711,10 +1258,16 @@ interface readonlyKeyLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends mutableKey<Top> ? this["~lambda.in"]["schema"] : "Error: schema not eligible for readonlyKey";
 }
 /**
+ * Reverses {@link mutableKey}, returning the inner schema as readonly again.
+ * Only applicable to schemas already wrapped with `mutableKey`.
+ *
  * @since 4.0.0
  */
 export declare const readonlyKey: readonlyKeyLambda;
 /**
+ * Schema type that collapses a transformation schema to its decoded `Type` on
+ * both sides (Type = Encoded = S["Type"]). Produced by {@link toType}.
+ *
  * @since 4.0.0
  */
 export interface toType<S extends Top> extends Bottom<S["Type"], S["Type"], never, never, S["ast"], toType<S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -725,10 +1278,16 @@ interface toTypeLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? toType<this["~lambda.in"]> : never;
 }
 /**
+ * Extracts the type-side schema: sets `Encoded` to equal the decoded `Type`,
+ * discarding the encoding transformation path.
+ *
  * @since 4.0.0
  */
 export declare const toType: toTypeLambda;
 /**
+ * Schema type that collapses a transformation schema to its `Encoded` side on
+ * both sides (Type = Encoded = S["Encoded"]). Produced by {@link toEncoded}.
+ *
  * @since 4.0.0
  */
 export interface toEncoded<S extends Top> extends Bottom<S["Encoded"], S["Encoded"], never, never, AST.AST, toEncoded<S>, S["Encoded"], S["Encoded"], ReadonlyArray<Top>, S["Encoded"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -739,11 +1298,17 @@ interface toEncodedLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? toEncoded<this["~lambda.in"]> : never;
 }
 /**
+ * Extracts the encoded-side schema: sets `Type` to equal the `Encoded`,
+ * discarding the decoding transformation path.
+ *
  * @since 4.0.0
  */
 export declare const toEncoded: toEncodedLambda;
 declare const FlipTypeId = "~effect/Schema/flip";
 /**
+ * Schema type representing a flipped schema where `Type` and `Encoded` are
+ * swapped. Produced by {@link flip}.
+ *
  * @since 4.0.0
  */
 export interface flip<S extends Top> extends Bottom<S["Encoded"], S["Type"], S["EncodingServices"], S["DecodingServices"], AST.AST, flip<S>, S["Encoded"], S["Encoded"], ReadonlyArray<Top>, S["Encoded"], S["~encoded.mutability"], S["~encoded.optionality"], ConstructorDefault, S["~type.mutability"], S["~type.optionality"]> {
@@ -752,10 +1317,26 @@ export interface flip<S extends Top> extends Bottom<S["Encoded"], S["Type"], S["
     readonly schema: S;
 }
 /**
+ * Swaps the `Type` and `Encoded` of a schema, inverting the transformation
+ * direction. Calling `flip` twice returns the original schema.
+ *
+ * **Example** (Flip a number-from-string schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // NumberFromString: decodes string → number
+ * const flipped = Schema.flip(Schema.NumberFromString)
+ * // flipped: decodes number → string
+ * ```
+ *
  * @since 4.0.0
  */
 export declare function flip<S extends Top>(schema: S): S extends flip<infer F> ? F["~rebuild.out"] : flip<S>;
 /**
+ * Represents a schema for a single literal value.
+ *
+ * @see {@link Literal} for the constructor function.
  * @since 4.0.0
  */
 export interface Literal<L extends AST.LiteralValue> extends Bottom<L, L, never, never, AST.Literal, Literal<L>> {
@@ -764,6 +1345,16 @@ export interface Literal<L extends AST.LiteralValue> extends Bottom<L, L, never,
     transform<L2 extends AST.LiteralValue>(to: L2): decodeTo<Literal<L2>, Literal<L>>;
 }
 /**
+ * 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.
@@ -771,6 +1362,8 @@ export interface Literal<L extends AST.LiteralValue> extends Bottom<L, L, never,
  */
 export declare function Literal<L extends AST.LiteralValue>(literal: L): Literal<L>;
 /**
+ * Namespace for {@link TemplateLiteral} helper types.
+ *
  * @since 4.0.0
  */
 export declare namespace TemplateLiteral {
@@ -799,6 +1392,10 @@ export declare namespace TemplateLiteral {
     type Encoded<Parts> = Parts extends readonly [...infer Init, infer Last] ? AppendType<Encoded<Init>, Last> : ``;
 }
 /**
+ * Represents a schema that validates strings matching a template literal pattern.
+ * The encoded type is a string formed by concatenating the parts.
+ *
+ * @see {@link TemplateLiteral} for the constructor function.
  * @since 4.0.0
  */
 export interface TemplateLiteral<Parts extends TemplateLiteral.Parts> extends Bottom<TemplateLiteral.Encoded<Parts>, TemplateLiteral.Encoded<Parts>, never, never, AST.TemplateLiteral, TemplateLiteral<Parts>> {
@@ -806,10 +1403,24 @@ export interface TemplateLiteral<Parts extends TemplateLiteral.Parts> extends Bo
     readonly parts: Parts;
 }
 /**
+ * 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 declare function TemplateLiteral<const Parts extends TemplateLiteral.Parts>(parts: Parts): TemplateLiteral<Parts>;
 /**
+ * Namespace for {@link TemplateLiteralParser} helper types.
+ *
  * @since 4.0.0
  */
 export declare namespace TemplateLiteralParser {
@@ -822,6 +1433,10 @@ export declare namespace TemplateLiteralParser {
     ] : [];
 }
 /**
+ * Represents a schema that validates strings matching a template literal pattern and decodes
+ * them into a tuple of typed values, one per schema part.
+ *
+ * @see {@link TemplateLiteralParser} for the constructor function.
  * @since 4.0.0
  */
 export interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> extends Bottom<TemplateLiteralParser.Type<Parts>, TemplateLiteral.Encoded<Parts>, never, never, AST.Arrays, TemplateLiteralParser<Parts>> {
@@ -829,10 +1444,26 @@ export interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> exte
     readonly parts: Parts;
 }
 /**
- * @since 4.0.0
- */
-export declare function TemplateLiteralParser<const Parts extends TemplateLiteral.Parts>(parts: Parts): TemplateLiteralParser<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 declare function TemplateLiteralParser<const Parts extends TemplateLiteral.Parts>(parts: Parts): TemplateLiteralParser<Parts>;
 /**
+ * Represents a schema derived from a TypeScript `const enum` or a plain enum object,
+ * accepting any of its values.
+ *
+ * @see {@link Enum} for the constructor function.
  * @since 4.0.0
  */
 export interface Enum<A extends {
@@ -842,176 +1473,262 @@ export interface Enum<A extends {
     readonly enums: A;
 }
 /**
+ * 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 declare function Enum<A extends {
     [x: string]: string | number;
 }>(enums: A): Enum<A>;
 /**
+ * Schema for the `never` type. Always fails validation.
+ *
+ * @see {@link Never} for the schema value.
  * @since 4.0.0
  */
 export interface Never extends Bottom<never, never, never, never, AST.Never, Never> {
     readonly "~rebuild.out": this;
 }
 /**
+ * Schema for the `never` type. Always fails validation — no value satisfies it.
+ *
  * @since 4.0.0
  */
 export declare const Never: Never;
 /**
+ * Schema for the `any` type. Accepts any value without validation.
+ *
+ * @see {@link Any} for the schema value.
  * @since 4.0.0
  */
 export interface Any extends Bottom<any, any, never, never, AST.Any, Any> {
     readonly "~rebuild.out": this;
 }
 /**
+ * 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 declare const Any: Any;
 /**
+ * Schema for the `unknown` type. Accepts any value without validation.
+ *
+ * @see {@link Unknown} for the schema value.
  * @since 4.0.0
  */
 export interface Unknown extends Bottom<unknown, unknown, never, never, AST.Unknown, Unknown> {
     readonly "~rebuild.out": this;
 }
 /**
+ * Schema for the `unknown` type. Accepts any value without validation.
+ *
+ * @see {@link Any} for the `any` variant.
  * @since 4.0.0
  */
 export declare const Unknown: Unknown;
 /**
+ * Schema for the `null` literal. Validates that the input is strictly `null`.
+ *
+ * @see {@link Null} for the schema value.
  * @since 4.0.0
  */
 export interface Null extends Bottom<null, null, never, never, AST.Null, Null> {
     readonly "~rebuild.out": this;
 }
 /**
+ * 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 declare const Null: Null;
 /**
+ * Schema for the `undefined` literal. Validates that the input is strictly `undefined`.
+ *
+ * @see {@link Undefined} for the schema value.
  * @since 4.0.0
  */
 export interface Undefined extends Bottom<undefined, undefined, never, never, AST.Undefined, Undefined> {
     readonly "~rebuild.out": this;
 }
 /**
+ * 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 declare const Undefined: Undefined;
 /**
+ * Schema for `string` values.
+ *
+ * @see {@link String} for the schema value.
  * @since 4.0.0
  */
 export interface String extends Bottom<string, string, never, never, AST.String, String> {
     readonly "~rebuild.out": this;
 }
 /**
- * A schema for all strings.
+ * Schema for `string` values. Validates that the input is `typeof` `"string"`.
  *
  * @since 4.0.0
  */
 export declare const String: String;
 /**
+ * Schema for `number` values, including `NaN`, `Infinity`, and `-Infinity`.
+ *
+ * @see {@link Number} for the schema value.
  * @since 4.0.0
  */
 export interface Number extends Bottom<number, number, never, never, AST.Number, Number> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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 declare const Number: Number;
 /**
+ * Schema for `boolean` values.
+ *
+ * @see {@link Boolean} for the schema value.
  * @since 4.0.0
  */
 export interface Boolean extends Bottom<boolean, boolean, never, never, AST.Boolean, Boolean> {
     readonly "~rebuild.out": this;
 }
 /**
- * A schema for all booleans.
+ * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
  * @category Boolean
  * @since 4.0.0
  */
 export declare const Boolean: Boolean;
 /**
+ * Schema for `symbol` values.
+ *
+ * @see {@link Symbol} for the schema value.
  * @since 4.0.0
  */
 export interface Symbol extends Bottom<symbol, symbol, never, never, AST.Symbol, Symbol> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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 declare const Symbol: Symbol;
 /**
+ * Schema for `bigint` values.
+ *
+ * @see {@link BigInt} for the schema value.
  * @since 4.0.0
  */
 export interface BigInt extends Bottom<bigint, bigint, never, never, AST.BigInt, BigInt> {
     readonly "~rebuild.out": this;
 }
 /**
- * A schema for all bigints.
+ * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
  * @since 4.0.0
  */
 export declare const BigInt: BigInt;
 /**
+ * Schema for the `void` type.
+ *
+ * @see {@link Void} for the schema value.
  * @since 4.0.0
  */
 export interface Void extends Bottom<void, void, never, never, AST.Void, Void> {
     readonly "~rebuild.out": this;
 }
 /**
- * A schema for the `void` type.
+ * Schema for the `void` type. Accepts `undefined` as the encoded value.
  *
  * @since 4.0.0
  */
 export declare const Void: Void;
 /**
+ * Schema for the `object` type keyword.
+ *
+ * @see {@link ObjectKeyword} for the schema value.
  * @since 4.0.0
  */
 export interface ObjectKeyword extends Bottom<object, object, never, never, AST.ObjectKeyword, ObjectKeyword> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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 declare const ObjectKeyword: ObjectKeyword;
 /**
+ * Represents a schema for a specific unique symbol.
+ *
+ * @see {@link UniqueSymbol} for the constructor function.
  * @since 4.0.0
  */
 export interface UniqueSymbol<sym extends symbol> extends Bottom<sym, sym, never, never, AST.UniqueSymbol, UniqueSymbol<sym>> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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 declare function UniqueSymbol<const sym extends symbol>(symbol: sym): UniqueSymbol<sym>;
 /**
+ * Namespace for struct field type utilities.
+ *
+ * These types compute the decoded `Type`, encoded `Encoded`, and constructor
+ * input `MakeIn` of a {@link Struct} from its field map, handling optional,
+ * mutable, and other field modifiers automatically.
+ *
+ * - `Struct.Fields` — constraint for the field map object
+ * - `Struct.Type<F>` — decoded type of the struct
+ * - `Struct.Encoded<F>` — encoded type of the struct
+ * - `Struct.MakeIn<F>` — constructor input (optional/defaulted fields may be omitted)
+ * - `Struct.DecodingServices<F>` / `Struct.EncodingServices<F>` — required services
+ *
  * @since 4.0.0
  */
 export declare namespace Struct {
     /**
+     * Constraint for a struct field map: an object whose values are schemas.
+     *
      * @since 4.0.0
      */
     type Fields = {
@@ -1108,6 +1825,27 @@ export declare namespace Struct {
  */
 export interface Struct<Fields extends Struct.Fields> extends Bottom<Simplify<Struct.Type<Fields>>, Simplify<Struct.Encoded<Fields>>, Struct.DecodingServices<Fields>, Struct.EncodingServices<Fields>, AST.Objects, Struct<Fields>, Simplify<Struct.MakeIn<Fields>>, Simplify<Struct.Iso<Fields>>> {
     readonly "~rebuild.out": this;
+    /**
+     * The field definitions of this struct. Spread them into a new struct to
+     * reuse fields across schemas.
+     *
+     * **Example** (Reusing fields across structs)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const Timestamped = Schema.Struct({
+     *   createdAt: Schema.Date,
+     *   updatedAt: Schema.Date
+     * })
+     *
+     * const User = Schema.Struct({
+     *   ...Timestamped.fields,
+     *   name: Schema.String,
+     *   email: Schema.String
+     * })
+     * ```
+     */
     readonly fields: Fields;
     /**
      * Returns a new struct with the fields modified by the provided function.
@@ -1128,6 +1866,34 @@ export interface Struct<Fields extends Struct.Fields> extends Bottom<Simplify<St
     } | undefined): Struct<Simplify<Readonly<To>>>;
 }
 /**
+ * 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 declare function Struct<const Fields extends Struct.Fields>(fields: Fields): Struct<Fields>;
@@ -1155,13 +1921,60 @@ interface fieldsAssign<NewFields extends Struct.Fields> extends Lambda {
  */
 export declare function fieldsAssign<const NewFields extends Struct.Fields>(fields: NewFields): fieldsAssign<NewFields>;
 /**
+ * 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
  */
-export declare function encodeKeys<S extends Struct<Struct.Fields>, const M extends {
+export declare function encodeKeys<S extends Top & {
+    readonly fields: Struct.Fields;
+}, const M extends {
     readonly [K in keyof S["fields"]]?: PropertyKey;
 }>(mapping: M): (self: S) => decodeTo<S, Struct<{ [K in keyof S["fields"] as K extends keyof M ? M[K] extends PropertyKey ? M[K] : K : K]: toEncoded<S["fields"][K]>; }>>;
 /**
+ * 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
  */
@@ -1173,6 +1986,12 @@ derive: {
     readonly [K in keyof Fields]: (s: S["Type"]) => Option_.Option<Fields[K]["Type"]>;
 }): (self: S) => decodeTo<Struct<Simplify<{ [K in keyof S["fields"]]: toType<S["fields"][K]>; } & Fields>>, S>;
 /**
+ * Namespace for `Record` type utilities.
+ *
+ * - `Record.Key` — constraint for the key schema (must encode to `PropertyKey`)
+ * - `Record.Type<K, V>` — decoded type of the record
+ * - `Record.Encoded<K, V>` — encoded type of the record
+ *
  * @since 4.0.0
  */
 export declare namespace Record {
@@ -1183,10 +2002,6 @@ export declare namespace Record {
         readonly "~type.make": PropertyKey;
         readonly "Iso": PropertyKey;
     }
-    /**
-     * @since 4.0.0
-     */
-    type Record = Record$<Record.Key, Top>;
     /**
      * @since 4.0.0
      */
@@ -1269,14 +2084,35 @@ export declare namespace Record {
     };
 }
 /**
+ * Schema type for a key-value record (map) with a typed key and value schema.
+ * Produced by {@link Record}.
+ *
  * @since 4.0.0
  */
-export interface Record$<Key extends Record.Key, Value extends Top> extends Bottom<Record.Type<Key, Value>, Record.Encoded<Key, Value>, Record.DecodingServices<Key, Value>, Record.EncodingServices<Key, Value>, AST.Objects, Record$<Key, Value>, Simplify<Record.MakeIn<Key, Value>>, Record.Iso<Key, Value>> {
+export interface $Record<Key extends Record.Key, Value extends Top> extends Bottom<Record.Type<Key, Value>, Record.Encoded<Key, Value>, Record.DecodingServices<Key, Value>, Record.EncodingServices<Key, Value>, AST.Objects, $Record<Key, Value>, Simplify<Record.MakeIn<Key, Value>>, Record.Iso<Key, Value>> {
     readonly "~rebuild.out": this;
     readonly key: Key;
     readonly value: Value;
 }
 /**
+ * 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 declare function Record<Key extends Record.Key, Value extends Top>(key: Key, value: Value, options?: {
@@ -1284,8 +2120,13 @@ export declare function Record<Key extends Record.Key, Value extends Top>(key: K
         readonly decode?: Combiner.Combiner<readonly [Key["Type"], Value["Type"]]> | undefined;
         readonly encode?: Combiner.Combiner<readonly [Key["Encoded"], Value["Encoded"]]> | undefined;
     };
-}): Record$<Key, Value>;
+}): $Record<Key, Value>;
 /**
+ * Namespace for `StructWithRest` type utilities.
+ *
+ * - `StructWithRest.Type<S, R>` — decoded type (struct type intersected with record types)
+ * - `StructWithRest.Encoded<S, R>` — encoded type
+ *
  * @since 4.0.0
  */
 export declare namespace StructWithRest {
@@ -1298,7 +2139,7 @@ export declare namespace StructWithRest {
     /**
      * @since 4.0.0
      */
-    type Records = ReadonlyArray<Record.Record>;
+    type Records = ReadonlyArray<$Record<Record.Key, Top>>;
     type MergeTuple<T extends ReadonlyArray<unknown>> = T extends readonly [infer Head, ...infer Tail] ? Head & MergeTuple<Tail> : {};
     /**
      * @since 4.0.0
@@ -1338,6 +2179,9 @@ export declare namespace StructWithRest {
     }>;
 }
 /**
+ * Schema type for a struct combined with one or more record schemas. Produced
+ * by {@link StructWithRest}.
+ *
  * @since 4.0.0
  */
 export interface StructWithRest<S extends StructWithRest.Objects, Records extends StructWithRest.Records> extends Bottom<Simplify<StructWithRest.Type<S, Records>>, Simplify<StructWithRest.Encoded<S, Records>>, StructWithRest.DecodingServices<S, Records>, StructWithRest.EncodingServices<S, Records>, AST.Objects, StructWithRest<S, Records>, Simplify<StructWithRest.MakeIn<S, Records>>, Simplify<StructWithRest.Iso<S, Records>>> {
@@ -1346,10 +2190,35 @@ export interface StructWithRest<S extends StructWithRest.Objects, Records extend
     readonly records: Records;
 }
 /**
+ * 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 declare function StructWithRest<const S extends StructWithRest.Objects, const Records extends StructWithRest.Records>(schema: S, records: Records): StructWithRest<S, Records>;
 /**
+ * Namespace for `Tuple` type utilities.
+ *
+ * - `Tuple.Elements` — constraint for the element schema array
+ * - `Tuple.Type<E>` — decoded tuple type
+ * - `Tuple.Encoded<E>` — encoded tuple type
+ * - `Tuple.MakeIn<E>` — constructor input tuple
+ *
  * @since 4.0.0
  */
 export declare namespace Tuple {
@@ -1405,6 +2274,8 @@ export declare namespace Tuple {
     type MakeIn<E extends Elements> = MakeIn_<E>;
 }
 /**
+ * Schema type for a fixed-length tuple. Produced by {@link Tuple}.
+ *
  * @since 4.0.0
  */
 export interface Tuple<Elements extends Tuple.Elements> extends Bottom<Tuple.Type<Elements>, Tuple.Encoded<Elements>, Tuple.DecodingServices<Elements>, Tuple.EncodingServices<Elements>, AST.Arrays, Tuple<Elements>, Tuple.MakeIn<Elements>, Tuple.Iso<Elements>> {
@@ -1429,11 +2300,32 @@ export interface Tuple<Elements extends Tuple.Elements> extends Bottom<Tuple.Typ
     } | undefined): Tuple<Simplify<Readonly<To>>>;
 }
 /**
+ * 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
  */
 export declare function Tuple<const Elements extends ReadonlyArray<Top>>(elements: Elements): Tuple<Elements>;
 /**
+ * Namespace for `TupleWithRest` type utilities.
+ *
+ * - `TupleWithRest.TupleType` — constraint for the leading tuple schema
+ * - `TupleWithRest.Rest` — the rest element schema(s)
+ * - `TupleWithRest.Type<T, R>` — decoded type (fixed elements + rest)
+ * - `TupleWithRest.Encoded<T, R>` — encoded type
+ *
  * @since 4.0.0
  */
 export declare namespace TupleWithRest {
@@ -1493,6 +2385,9 @@ export declare namespace TupleWithRest {
     ] : M;
 }
 /**
+ * Schema type for a tuple with additional rest elements. Produced by
+ * {@link TupleWithRest}.
+ *
  * @since 4.0.0
  */
 export interface TupleWithRest<S extends TupleWithRest.TupleType, Rest extends TupleWithRest.Rest> extends Bottom<TupleWithRest.Type<S["Type"], Rest>, TupleWithRest.Encoded<S["Encoded"], Rest>, S["DecodingServices"] | Rest[number]["DecodingServices"], S["EncodingServices"] | Rest[number]["EncodingServices"], AST.Arrays, TupleWithRest<S, Rest>, TupleWithRest.MakeIn<S["~type.make"], Rest>, TupleWithRest.Iso<S["Iso"], Rest>> {
@@ -1501,27 +2396,65 @@ export interface TupleWithRest<S extends TupleWithRest.TupleType, Rest extends T
     readonly rest: Rest;
 }
 /**
+ * Extends a fixed-length tuple schema with rest elements, creating a variadic
+ * tuple that starts with the fixed elements and ends with zero or more rest
+ * elements.
+ *
+ * **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
  */
 export declare function TupleWithRest<S extends Tuple<Tuple.Elements>, const Rest extends TupleWithRest.Rest>(schema: S, rest: Rest): TupleWithRest<S, Rest>;
 /**
+ * Schema type for a `ReadonlyArray`. Produced by {@link Array}.
+ *
  * @since 4.0.0
  */
-export interface Array$<S extends Top> extends Bottom<ReadonlyArray<S["Type"]>, ReadonlyArray<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"], AST.Arrays, Array$<S>, ReadonlyArray<S["~type.make"]>, ReadonlyArray<S["Iso"]>> {
+export interface $Array<S extends Top> extends Bottom<ReadonlyArray<S["Type"]>, ReadonlyArray<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"], AST.Arrays, $Array<S>, ReadonlyArray<S["~type.make"]>, ReadonlyArray<S["Iso"]>> {
     readonly "~rebuild.out": this;
     readonly schema: S;
 }
 interface ArrayLambda extends Lambda {
-    <S extends Top>(self: S): Array$<S>;
-    readonly "~lambda.out": this["~lambda.in"] extends Top ? Array$<this["~lambda.in"]> : never;
+    <S extends Top>(self: S): $Array<S>;
+    readonly "~lambda.out": this["~lambda.in"] extends Top ? $Array<this["~lambda.in"]> : never;
 }
 /**
+ * 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
  */
 export declare const Array: ArrayLambda;
 /**
+ * Schema type for a non-empty `ReadonlyArray`. Produced by {@link NonEmptyArray}.
+ *
  * @since 4.0.0
  */
 export interface NonEmptyArray<S extends Top> extends Bottom<readonly [S["Type"], ...Array<S["Type"]>], readonly [S["Encoded"], ...Array<S["Encoded"]>], S["DecodingServices"], S["EncodingServices"], AST.Arrays, NonEmptyArray<S>, readonly [S["~type.make"], ...Array<S["~type.make"]>], readonly [S["Iso"], ...Array<S["Iso"]>]> {
@@ -1533,14 +2466,30 @@ interface NonEmptyArrayLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? NonEmptyArray<this["~lambda.in"]> : never;
 }
 /**
+ * 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
  */
 export declare const NonEmptyArray: NonEmptyArrayLambda;
 /**
+ * Schema type for an array with unique elements. Produced by {@link UniqueArray}.
+ *
  * @since 4.0.0
  */
-export interface UniqueArray<S extends Top> extends Array$<S> {
+export interface UniqueArray<S extends Top> extends $Array<S> {
 }
 /**
  * Returns a new array schema that ensures all elements are unique.
@@ -1553,6 +2502,9 @@ export interface UniqueArray<S extends Top> extends Array$<S> {
  */
 export declare function UniqueArray<S extends Top>(item: S): UniqueArray<S>;
 /**
+ * Schema type that makes array or tuple elements mutable (removes `readonly`).
+ * Produced by {@link mutable}.
+ *
  * @since 4.0.0
  */
 export interface mutable<S extends Top & {
@@ -1570,12 +2522,25 @@ interface mutableLambda extends Lambda {
     } ? mutable<this["~lambda.in"]> : "Error: schema not eligible for mutable";
 }
 /**
- * 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
  */
 export declare const mutable: mutableLambda;
 /**
+ * Schema type for a union of multiple schemas. Produced by {@link Union}.
+ *
  * @since 4.0.0
  */
 export interface Union<Members extends ReadonlyArray<Top>> extends Bottom<{
@@ -1614,12 +2579,23 @@ export interface Union<Members extends ReadonlyArray<Top>> extends Bottom<{
     } | undefined): Union<Simplify<Readonly<To>>>;
 }
 /**
- * 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)
  *
- * Optionally, you can specify the `mode` to be `"anyOf"` or `"oneOf"`.
+ * ```ts
+ * import { Schema } from "effect"
  *
- * - `"anyOf"` - The union matches if any member matches.
- * - `"oneOf"` - The union matches if exactly one member matches.
+ * const schema = Schema.Union([Schema.String, Schema.Number])
+ *
+ * Schema.decodeUnknownSync(schema)("hello") // "hello"
+ * Schema.decodeUnknownSync(schema)(42)       // 42
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -1628,6 +2604,9 @@ export declare function Union<const Members extends ReadonlyArray<Top>>(members:
     mode?: "anyOf" | "oneOf";
 }): Union<Members>;
 /**
+ * Represents a union schema of multiple literal values.
+ *
+ * @see {@link Literals} for the constructor function.
  * @since 4.0.0
  */
 export interface Literals<L extends ReadonlyArray<AST.LiteralValue>> extends Bottom<L[number], L[number], never, never, AST.Union<AST.Literal>, Literals<L>> {
@@ -1648,12 +2627,24 @@ export interface Literals<L extends ReadonlyArray<AST.LiteralValue>> extends Bot
     }>;
 }
 /**
+ * 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
  */
 export declare function Literals<const L extends ReadonlyArray<AST.LiteralValue>>(literals: L): Literals<L>;
 /**
+ * Schema type for `S | null`. Produced by {@link NullOr}.
+ *
  * @since 4.0.0
  */
 export interface NullOr<S extends Top> extends Union<readonly [S, Null]> {
@@ -1663,11 +2654,15 @@ interface NullOrLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? NullOr<this["~lambda.in"]> : never;
 }
 /**
+ * Creates a union schema of `S | null`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export declare const NullOr: NullOrLambda;
 /**
+ * Schema type for `S | undefined`. Produced by {@link UndefinedOr}.
+ *
  * @since 4.0.0
  */
 export interface UndefinedOr<S extends Top> extends Union<readonly [S, Undefined]> {
@@ -1677,11 +2672,14 @@ interface UndefinedOrLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? UndefinedOr<this["~lambda.in"]> : never;
 }
 /**
+ * Creates a union schema of `S | undefined`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export declare const UndefinedOr: UndefinedOrLambda;
 /**
+ * Schema type for `S | null | undefined`. Produced by {@link NullishOr}.
  * @since 4.0.0
  */
 export interface NullishOr<S extends Top> extends Union<readonly [S, Null, Undefined]> {
@@ -1691,11 +2689,13 @@ interface NullishOrLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Top ? NullishOr<this["~lambda.in"]> : never;
 }
 /**
+ * Creates a union schema of `S | null | undefined`.
  * @category Constructors
  * @since 4.0.0
  */
 export declare const NullishOr: NullishOrLambda;
 /**
+ * Schema type wrapping a lazily-evaluated schema. Produced by {@link suspend}.
  * @since 4.0.0
  */
 export interface suspend<S extends Top> extends Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], AST.Suspend, suspend<S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1706,16 +2706,46 @@ export interface suspend<S extends Top> extends Bottom<S["Type"], S["Encoded"],
  * 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
  */
 export declare function suspend<S extends Top>(f: () => S): suspend<S>;
 /**
+ * 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
  */
 export declare function check<S extends Top>(...checks: readonly [AST.Check<S["Type"]>, ...Array<AST.Check<S["Type"]>>]): (self: S) => S["~rebuild.out"];
 /**
+ * The output type of {@link refine}, narrowing the schema's `Type` to `T` via a
+ * type guard.
+ *
  * @since 4.0.0
  */
 export interface refine<T extends S["Type"], S extends Top> extends Bottom<T, S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], refine<T, S>, S["~type.make.in"], T, S["~type.parameters"], T, S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1723,12 +2753,18 @@ export interface refine<T extends S["Type"], S extends Top> extends Bottom<T, S[
     readonly schema: S;
 }
 /**
+ * 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
  */
 export declare function refine<S extends Top, T extends S["Type"]>(refinement: (value: S["Type"]) => value is T, annotations?: Annotations.Filter): (schema: S) => refine<T, S>;
 type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string ? Brand.Brand<U> : never>;
 /**
+ * The output type of {@link brand}, intersecting the schema's `Type` with one or
+ * more {@link Brand.Brand} tags.
+ *
  * @since 4.0.0
  */
 export interface brand<S extends Top, B> extends Bottom<S["Type"] & DistributeBrands<B>, S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], brand<S, B>, S["~type.make.in"], S["Type"] & DistributeBrands<B>, S["~type.parameters"], S["Type"] & DistributeBrands<B>, S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1737,20 +2773,30 @@ export interface brand<S extends Top, B> extends Bottom<S["Type"] & DistributeBr
     readonly identifier: string;
 }
 /**
- * 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
  */
 export declare function brand<B extends string>(identifier: B): <S extends Top>(schema: S) => brand<S["~rebuild.out"], B>;
 /**
- * @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 declare function fromBrand<A extends Brand.Brand<any>>(identifier: string, ctor: Brand.Constructor<A>): <S extends Top & {
     readonly "Type": Brand.Brand.Unbranded<A>;
 }>(self: S) => brand<S["~rebuild.out"], Brand.Brand.Keys<A>>;
 /**
+ * A schema that wraps another schema and intercepts its decoding pipeline.
+ *
+ * The interceptor receives the full decoding `Effect` and may replace, modify,
+ * or augment it — including adding service requirements via `RD`.
+ *
+ * @see {@link middlewareDecoding} for the constructor
  * @since 4.0.0
  */
 export interface middlewareDecoding<S extends Top, RD> extends Bottom<S["Type"], S["Encoded"], RD, S["EncodingServices"], S["ast"], middlewareDecoding<S, RD>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1758,10 +2804,35 @@ export interface middlewareDecoding<S extends Top, RD> extends Bottom<S["Type"],
     readonly schema: S;
 }
 /**
+ * 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 declare function middlewareDecoding<S extends Top, RD>(decode: (effect: Effect.Effect<Option_.Option<S["Type"]>, Issue.Issue, S["DecodingServices"]>, options: AST.ParseOptions) => Effect.Effect<Option_.Option<S["Type"]>, Issue.Issue, RD>): (schema: S) => middlewareDecoding<S, RD>;
 /**
+ * A schema that wraps another schema and intercepts its encoding pipeline.
+ *
+ * The interceptor receives the full encoding `Effect` and may replace, modify,
+ * or augment it — including adding service requirements via `RE`.
+ *
+ * @see {@link middlewareEncoding} for the constructor
  * @since 4.0.0
  */
 export interface middlewareEncoding<S extends Top, RE> extends Bottom<S["Type"], S["Encoded"], S["DecodingServices"], RE, S["ast"], middlewareEncoding<S, RE>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1769,26 +2840,77 @@ export interface middlewareEncoding<S extends Top, RE> extends Bottom<S["Type"],
     readonly schema: S;
 }
 /**
+ * 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 declare function middlewareEncoding<S extends Top, RE>(encode: (effect: Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue, S["EncodingServices"]>, options: AST.ParseOptions) => Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue, RE>): (schema: S) => middlewareEncoding<S, RE>;
 /**
+ * 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 declare function catchDecoding<S extends Top>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Type"]>, Issue.Issue>): (self: S) => S["~rebuild.out"];
 /**
+ * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export declare function catchDecodingWithContext<S extends Top, R = never>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Type"]>, Issue.Issue, R>): (self: S) => middlewareDecoding<S, S["DecodingServices"] | R>;
 /**
+ * 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 declare function catchEncoding<S extends Top>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue>): (self: S) => S["~rebuild.out"];
 /**
+ * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export declare function catchEncodingWithContext<S extends Top, R = never>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue, R>): (self: S) => middlewareEncoding<S, S["EncodingServices"] | R>;
 /**
+ * The type produced by {@link decodeTo} when a custom transformation is provided.
+ *
+ * - `Type` is `To["Type"]`, `Encoded` is `From["Encoded"]`
+ * - Decoding services from both `from` and `to` are combined
+ *
+ * @see {@link compose} for the passthrough (no transformation) variant
  * @since 4.0.0
  */
 export interface decodeTo<To extends Top, From extends Top, RD = never, RE = never> extends Bottom<To["Type"], From["Encoded"], To["DecodingServices"] | From["DecodingServices"] | RD, To["EncodingServices"] | From["EncodingServices"] | RE, To["ast"], decodeTo<To, From, RD, RE>, To["~type.make.in"], To["Iso"], To["~type.parameters"], To["~type.make"], To["~type.mutability"], To["~type.optionality"], To["~type.constructor.default"], From["~encoded.mutability"], From["~encoded.optionality"]> {
@@ -1797,6 +2919,12 @@ export interface decodeTo<To extends Top, From extends Top, RD = never, RE = nev
     readonly to: To;
 }
 /**
+ * The type produced by {@link decodeTo} when called without a custom transformation (passthrough composition).
+ *
+ * Equivalent to {@link decodeTo} with `RD = never` and `RE = never`, meaning the schemas
+ * are composed using their natural encoding/decoding chain.
+ *
+ * @see {@link decodeTo} for the transformation variant
  * @since 4.0.0
  */
 export interface compose<To extends Top, From extends Top> extends decodeTo<To, From> {
@@ -1890,6 +3018,25 @@ export declare function decode<S extends Top, RD = never, RE = never>(transforma
     readonly encode: Getter.Getter<S["Type"], S["Type"], RE>;
 }): (self: S) => decodeTo<toType<S>, S, RD, RE>;
 /**
+ * Like {@link decodeTo} but reverses the direction: the `from` schema acts as the target (decoded type)
+ * and `to` acts as the encoded source.
+ *
+ * `encodeTo(to)(from)` is equivalent to `to.pipe(decodeTo(from))` — useful when it reads more
+ * naturally to specify the encoded schema first.
+ *
+ * **Example** (Encode a number back to string)
+ *
+ * ```ts
+ * import { Schema, SchemaGetter } from "effect"
+ *
+ * const NumberFromString = Schema.Number.pipe(
+ *   Schema.encodeTo(Schema.String, {
+ *     decode: SchemaGetter.transform((s: string) => Number(s)),
+ *     encode: SchemaGetter.transform((n: number) => String(n))
+ *   })
+ * )
+ * ```
+ *
  * @since 4.0.0
  */
 export declare function encodeTo<To extends Top>(to: To): <From extends Top>(from: From) => decodeTo<From, To>;
@@ -1898,19 +3045,45 @@ export declare function encodeTo<To extends Top, From extends Top, RD = never, R
     readonly encode: Getter.Getter<NoInfer<To["Type"]>, NoInfer<From["Encoded"]>, RE>;
 }): (from: From) => decodeTo<From, To, RD, RE>;
 /**
- * @since 4.0.0
- */
-export declare function encode<S extends Top, RD = never, RE = never>(transformation: {
-    readonly decode: Getter.Getter<S["Encoded"], S["Encoded"], RD>;
+ * 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 declare function encode<S extends Top, RD = never, RE = never>(transformation: {
+    readonly decode: Getter.Getter<S["Encoded"], S["Encoded"], RD>;
     readonly encode: Getter.Getter<S["Encoded"], S["Encoded"], RE>;
 }): (self: S) => decodeTo<S, toEncoded<S>, RD, RE>;
 /**
+ * Constraint used to ensure a schema field does not already have a constructor default.
+ *
+ * Only schemas that satisfy this constraint can be passed to {@link withConstructorDefault}.
+ *
  * @since 4.0.0
  */
 export interface WithoutConstructorDefault {
     readonly "~type.constructor.default": "no-default";
 }
 /**
+ * The type produced by {@link withConstructorDefault} — a schema with `"~type.constructor.default": "with-default"`.
+ *
+ * @see {@link withConstructorDefault} for the constructor
  * @since 4.0.0
  */
 export interface withConstructorDefault<S extends Top & WithoutConstructorDefault> extends Bottom<S["Type"], S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], withConstructorDefault<S>, S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], "with-default", S["~encoded.mutability"], S["~encoded.optionality"]> {
@@ -1918,15 +3091,50 @@ export interface withConstructorDefault<S extends Top & WithoutConstructorDefaul
     readonly schema: S;
 }
 /**
+ * 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 declare function withConstructorDefault<S extends Top & WithoutConstructorDefault>(defaultValue: (input: Option_.Option<undefined>) => Option_.Option<S["~type.make.in"]> | Effect.Effect<Option_.Option<S["~type.make.in"]>>): (schema: S) => withConstructorDefault<S>;
 /**
+ * The type produced by {@link withDecodingDefaultKey} — a schema that decodes from an `optionalKey` encoded source.
+ *
+ * @see {@link withDecodingDefaultKey} for the constructor
  * @since 4.0.0
  */
 export interface withDecodingDefaultKey<S extends Top> extends decodeTo<S, optionalKey<toEncoded<S>>> {
 }
 /**
+ * Options for {@link withDecodingDefaultKey} and {@link withDecodingDefault}.
+ *
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): pass the value through during encoding
+ *   - `"omit"`: omit the key from the encoded output
+ *
  * @since 4.0.0
  */
 export type DecodingDefaultOptions = {
@@ -1939,10 +3147,34 @@ export type DecodingDefaultOptions = {
  *   - `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 declare function withDecodingDefaultKey<S extends Top>(defaultValue: () => S["Encoded"], options?: DecodingDefaultOptions): (self: S) => withDecodingDefaultKey<S>;
 /**
+ * The type produced by {@link withDecodingDefault} — a schema that decodes from an `optional` encoded source.
+ *
+ * @see {@link withDecodingDefault} for the constructor
  * @since 4.0.0
  */
 export interface withDecodingDefault<S extends Top> extends decodeTo<S, optional<toEncoded<S>>> {
@@ -1954,34 +3186,93 @@ export interface withDecodingDefault<S extends Top> extends decodeTo<S, optional
  *   - `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 declare function withDecodingDefault<S extends Top>(defaultValue: () => S["Encoded"], options?: DecodingDefaultOptions): (self: S) => withDecodingDefault<S>;
 /**
+ * The type produced by {@link tag} — a literal schema with a constructor default.
+ *
+ * Used as the type of the `_tag` field in {@link TaggedStruct} and related helpers.
+ *
+ * @see {@link tag} for the constructor
  * @since 4.0.0
  */
 export interface tag<Tag extends AST.LiteralValue> extends withConstructorDefault<Literal<Tag>> {
 }
 /**
- * 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.
+ *
+ * **Example** (Discriminated union tag)
  *
- * 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.
+ * ```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 declare function tag<Tag extends AST.LiteralValue>(literal: Tag): tag<Tag>;
 /**
- * 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 declare function tagDefaultOmit<Tag extends AST.LiteralValue>(literal: Tag): withDecodingDefaultKey<tag<Tag>>;
 /**
+ * The type produced by {@link TaggedStruct} — a {@link Struct} with an extra `_tag` field of type {@link tag}.
+ *
+ * @see {@link TaggedStruct} for the constructor
  * @since 4.0.0
  */
 export type TaggedStruct<Tag extends AST.LiteralValue, Fields extends Struct.Fields> = Struct<Simplify<{
@@ -2053,15 +3344,18 @@ type TaggedUnionUtils<Tag extends PropertyKey, Members extends ReadonlyArray<Top
         [M in Flattened[number] as M["Type"][Tag]]: (u: unknown) => u is M["Type"];
     };
     readonly match: {
-        <Output>(value: Members[number]["Type"], cases: {
-            [M in Flattened[number] as M["Type"][Tag]]: (value: M["Type"]) => Output;
-        }): Output;
-        <Output>(cases: {
-            [M in Flattened[number] as M["Type"][Tag]]: (value: M["Type"]) => Output;
-        }): (value: Members[number]["Type"]) => Output;
+        <Cases extends {
+            [M in Flattened[number] as M["Type"][Tag]]: (value: M["Type"]) => any;
+        }>(value: Members[number]["Type"], cases: Cases): Cases[keyof Cases] extends (value: any) => infer R ? Unify<R> : never;
+        <Cases extends {
+            [M in Flattened[number] as M["Type"][Tag]]: (value: M["Type"]) => any;
+        }>(cases: Cases): (value: Members[number]["Type"]) => Cases[keyof Cases] extends (value: any) => infer R ? Unify<R> : never;
     };
 };
 /**
+ * The type produced by {@link toTaggedUnion} — a {@link Union} augmented with `cases`, `guards`, `isAnyOf`, and `match` utilities.
+ *
+ * @see {@link toTaggedUnion} for the constructor
  * @since 4.0.0
  * @experimental
  */
@@ -2071,6 +3365,26 @@ export type toTaggedUnion<Tag extends PropertyKey, Members extends ReadonlyArray
     };
 }>> = Union<Members> & TaggedUnionUtils<Tag, Members>;
 /**
+ * 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
  */
@@ -2078,6 +3392,10 @@ export declare function toTaggedUnion<const Tag extends PropertyKey>(tag: Tag):
     readonly Type: { readonly [K in Tag]: PropertyKey; };
 }>>(self: Union<Members>) => toTaggedUnion<Tag, Members>;
 /**
+ * A union schema that exposes `cases`, `guards`, `isAnyOf`, and `match` utilities keyed by the `_tag` discriminant.
+ * Produced by {@link TaggedUnion}.
+ *
+ * @see {@link TaggedUnion} for the constructor
  * @since 4.0.0
  * @experimental
  */
@@ -2101,15 +3419,37 @@ export interface TaggedUnion<Cases extends Record<string, Top>> extends Bottom<{
         [K in keyof Cases]: (u: unknown) => u is Cases[K]["Type"];
     };
     readonly match: {
-        <Output>(value: Cases[keyof Cases]["Type"], cases: {
-            [K in keyof Cases]: (value: Cases[K]["Type"]) => Output;
-        }): Output;
         <Output>(cases: {
             [K in keyof Cases]: (value: Cases[K]["Type"]) => Output;
         }): (value: Cases[keyof Cases]["Type"]) => Output;
+        <Output>(value: Cases[keyof Cases]["Type"], cases: {
+            [K in keyof Cases]: (value: Cases[K]["Type"]) => Output;
+        }): Output;
     };
 }
 /**
+ * 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
  */
@@ -2117,29 +3457,69 @@ export declare function TaggedUnion<const CasesByTag extends Record<string, Stru
     readonly [K in keyof CasesByTag & string]: TaggedStruct<K, CasesByTag[K]>;
 }>;
 /**
+ * The interface type for schemas created by {@link Opaque}.
+ * Carries the same encoded/decoded shape as `S` but replaces `Type` with `Self & Brand`,
+ * making the decoded value nominally distinct.
+ *
+ * @see {@link Opaque} for the constructor
  * @since 4.0.0
  */
 export interface Opaque<Self, S extends Top, Brand> extends Bottom<Self, S["Encoded"], S["DecodingServices"], S["EncodingServices"], S["ast"], S["~rebuild.out"], S["~type.make.in"], S["Iso"], S["~type.parameters"], S["~type.make"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
     new (_: never): S["Type"] & Brand;
 }
 /**
+ * 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 declare function Opaque<Self, Brand = {}>(): <S extends Top>(schema: S) => Opaque<Self, S, Brand> & Omit<S, "Type">;
 /**
+ * The type produced by {@link instanceOf} — a declaration schema that validates class instances.
+ *
+ * @see {@link instanceOf} for the constructor
  * @since 4.0.0
  */
 export interface instanceOf<T, Iso = T> extends declare<T, Iso> {
     readonly "~rebuild.out": this;
 }
 /**
- * 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
  */
 export declare function instanceOf<C extends abstract new (...args: any) => any, Iso = InstanceType<C>>(constructor: C, annotations?: Annotations.Declaration<InstanceType<C>> | undefined): instanceOf<InstanceType<C>, Iso>;
 /**
+ * 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
  */
@@ -2148,6 +3528,22 @@ export declare function link<T>(): <To extends Top>(encodeTo: To, transformation
     readonly encode: Getter.Getter<NoInfer<To["Type"]>, T>;
 }) => AST.Link;
 /**
+ * Creates a custom filter check from a predicate function. The predicate
+ * receives the input value, the schema's AST, and parse options, and returns
+ * `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
  */
@@ -2156,6 +3552,9 @@ export declare const makeFilter: <T>(filter: (input: T, ast: AST.AST, options: A
     readonly message: string;
 }, annotations?: Annotations.Filter | undefined, abort?: boolean) => AST.Filter<T>;
 /**
+ * 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
  */
@@ -2262,7 +3661,7 @@ export declare const isStringSymbol: (annotations?: Annotations.Filter) => AST.F
  * @category String checks
  * @since 4.0.0
  */
-export declare function isUUID(version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | undefined, annotations?: Annotations.Filter): AST.Filter<string>;
+export declare function isUUID(version?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, annotations?: Annotations.Filter): AST.Filter<string>;
 /**
  * Validates that a string is a valid ULID (Universally Unique Lexicographically
  * Sortable Identifier).
@@ -2453,6 +3852,9 @@ export declare function isUncapitalized(annotations?: Annotations.Filter): AST.F
  */
 export declare function isFinite(annotations?: Annotations.Filter): AST.Filter<number>;
 /**
+ * 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
  */
@@ -2462,6 +3864,9 @@ export declare function makeIsGreaterThan<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (exclusiveMinimum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
+ * Generic factory for creating a ">=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -2471,6 +3876,9 @@ export declare function makeIsGreaterThanOrEqualTo<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (minimum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
+ * Generic factory for creating a "<" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -2480,6 +3888,9 @@ export declare function makeIsLessThan<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (exclusiveMaximum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
+ * Generic factory for creating a "<=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -2489,6 +3900,9 @@ export declare function makeIsLessThanOrEqualTo<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (maximum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
+ * 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
  */
@@ -2508,6 +3922,9 @@ export declare function makeIsBetween<T>(deriveOptions: {
     readonly exclusiveMaximum?: boolean | undefined;
 }, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
+ * 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
  */
@@ -2856,6 +4273,48 @@ export declare const isBetweenBigInt: (options: {
     readonly exclusiveMinimum?: boolean | undefined;
     readonly exclusiveMaximum?: boolean | undefined;
 }, annotations?: Annotations.Filter) => AST.Filter<bigint>;
+/**
+ * Validates that a BigDecimal is greater than the specified value (exclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export declare const isGreaterThanBigDecimal: (exclusiveMinimum: BigDecimal_.BigDecimal, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
+/**
+ * Validates that a BigDecimal is greater than or equal to the specified value
+ * (inclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export declare const isGreaterThanOrEqualToBigDecimal: (minimum: BigDecimal_.BigDecimal, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
+/**
+ * Validates that a BigDecimal is less than the specified value (exclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export declare const isLessThanBigDecimal: (exclusiveMaximum: BigDecimal_.BigDecimal, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
+/**
+ * Validates that a BigDecimal is less than or equal to the specified value
+ * (inclusive).
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export declare const isLessThanOrEqualToBigDecimal: (maximum: BigDecimal_.BigDecimal, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
+/**
+ * Validates that a BigDecimal is within a specified range.
+ *
+ * @category BigDecimal checks
+ * @since 4.0.0
+ */
+export declare const isBetweenBigDecimal: (options: {
+    readonly minimum: BigDecimal_.BigDecimal;
+    readonly maximum: BigDecimal_.BigDecimal;
+    readonly exclusiveMinimum?: boolean | undefined;
+    readonly exclusiveMaximum?: boolean | undefined;
+}, annotations?: Annotations.Filter) => AST.Filter<BigDecimal_.BigDecimal>;
 /**
  * Validates that a value has at least the specified length. Works with strings
  * and arrays.
@@ -2871,6 +4330,14 @@ export declare const isBetweenBigInt: (options: {
  * 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
  */
@@ -3086,6 +4553,7 @@ export declare function isPropertyNames(keySchema: Top, annotations?: Annotation
  * constraint using the provided equivalence function to ensure generated arrays
  * contain only unique items.
  *
+ * @category Array checks
  * @since 4.0.0
  */
 export declare function isUnique<T>(annotations?: Annotations.Filter): AST.Filter<readonly T[]>;
@@ -3103,6 +4571,23 @@ export declare const NonEmptyString: String;
  */
 export declare const Char: String;
 /**
+ * Schema for the `Option<A>` type, representing an optional value that is
+ * either `None` or `Some<A>`.
+ *
+ * **Example** (Option schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Option } from "effect"
+ *
+ * const schema = Schema.Option(Schema.Number)
+ *
+ * Schema.decodeUnknownSync(schema)(Option.some(1))
+ * // => Some(1)
+ * Schema.decodeUnknownSync(schema)(Option.none())
+ * // => None
+ * ```
+ *
  * @category Option
  * @since 4.0.0
  */
@@ -3120,11 +4605,16 @@ export type OptionIso<A extends Top> = {
     readonly value: A["Iso"];
 };
 /**
+ * Creates a schema for `Option<A>`. See {@link Option} for details.
+ *
  * @category Option
  * @since 4.0.0
  */
 export declare function Option<A extends Top>(value: A): Option<A>;
 /**
+ * Schema type for {@link OptionFromNullOr}.
+ *
+ * @category Option
  * @since 4.0.0
  */
 export interface OptionFromNullOr<S extends Top> extends decodeTo<Option<toType<S>>, NullOr<S>> {
@@ -3145,6 +4635,57 @@ export interface OptionFromNullOr<S extends Top> extends decodeTo<Option<toType<
  */
 export declare function OptionFromNullOr<S extends Top>(schema: S): OptionFromNullOr<S>;
 /**
+ * Schema type for {@link OptionFromUndefinedOr}.
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export interface OptionFromUndefinedOr<S extends Top> extends decodeTo<Option<toType<S>>, UndefinedOr<S>> {
+}
+/**
+ * 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 declare function OptionFromUndefinedOr<S extends Top>(schema: S): OptionFromUndefinedOr<S>;
+/**
+ * Schema type for {@link OptionFromNullishOr}.
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export interface OptionFromNullishOr<S extends Top> extends decodeTo<Option<toType<S>>, NullishOr<S>> {
+}
+/**
+ * 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 declare function OptionFromNullishOr<S extends Top>(schema: S, options?: {
+    onNoneEncoding: null | undefined;
+}): OptionFromNullishOr<S>;
+/**
+ * Schema type for {@link OptionFromOptionalKey}.
+ *
+ * @category Option
  * @since 4.0.0
  */
 export interface OptionFromOptionalKey<S extends Top> extends decodeTo<Option<toType<S>>, optionalKey<S>> {
@@ -3165,6 +4706,9 @@ export interface OptionFromOptionalKey<S extends Top> extends decodeTo<Option<to
  */
 export declare function OptionFromOptionalKey<S extends Top>(schema: S): OptionFromOptionalKey<S>;
 /**
+ * Schema type for {@link OptionFromOptional}.
+ *
+ * @category Option
  * @since 4.0.0
  */
 export interface OptionFromOptional<S extends Top> extends decodeTo<Option<toType<S>>, optional<S>> {
@@ -3187,6 +4731,9 @@ export interface OptionFromOptional<S extends Top> extends decodeTo<Option<toTyp
  */
 export declare function OptionFromOptional<S extends Top>(schema: S): OptionFromOptional<S>;
 /**
+ * Schema for the `Result<A, E>` type, representing a computation that either
+ * succeeds with `A` or fails with `E`.
+ *
  * @category Result
  * @since 4.0.0
  */
@@ -3206,11 +4753,16 @@ export type ResultIso<A extends Top, E extends Top> = {
     readonly failure: E["Iso"];
 };
 /**
+ * Creates a schema for `Result<A, E>`. See {@link Result} for details.
+ *
  * @category Result
  * @since 4.0.0
  */
 export declare function Result<A extends Top, E extends Top>(success: A, failure: E): Result<A, E>;
 /**
+ * Schema for the `Redacted<A>` type, providing secure handling of sensitive
+ * values. The inner value is hidden from error messages.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3244,17 +4796,26 @@ export declare function Redacted<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
 }): Redacted<S>;
 /**
+ * Schema type for {@link RedactedFromValue}.
+ *
  * @category Redacted
  * @since 4.0.0
  */
 export interface RedactedFromValue<S extends Top> extends decodeTo<Redacted<toType<S>>, middlewareDecoding<S, S["DecodingServices"]>> {
 }
 /**
+ * Middleware that wraps decoded errors in `Redacted`, preventing sensitive
+ * schema details from leaking in error messages.
+ *
  * @category Redacted
  * @since 4.0.0
  */
 export declare function redact<S extends Top>(schema: S): middlewareDecoding<S, S["DecodingServices"]>;
 /**
+ * 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
  */
@@ -3262,18 +4823,22 @@ export declare function RedactedFromValue<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
 }): RedactedFromValue<S>;
 /**
- * @category CauseFailure
+ * Schema for a single `Cause.Reason<E>`, representing one reason a fiber may
+ * fail: a typed error (`Fail`), an unexpected defect (`Die`), or an interrupt
+ * (`Interrupt`).
+ *
+ * @category CauseReason
  * @since 4.0.0
  */
-export interface CauseFailure<E extends Top, D extends Top> extends declareConstructor<Cause_.Reason<E["Type"]>, Cause_.Reason<E["Encoded"]>, readonly [E, D], CauseFailureIso<E, D>> {
+export interface CauseReason<E extends Top, D extends Top> extends declareConstructor<Cause_.Reason<E["Type"]>, Cause_.Reason<E["Encoded"]>, readonly [E, D], CauseReasonIso<E, D>> {
     readonly error: E;
     readonly defect: D;
 }
 /**
- * @category CauseFailure
+ * @category CauseReason
  * @since 4.0.0
  */
-export type CauseFailureIso<E extends Top, D extends Top> = {
+export type CauseReasonIso<E extends Top, D extends Top> = {
     readonly _tag: "Fail";
     readonly error: E["Iso"];
 } | {
@@ -3284,11 +4849,16 @@ export type CauseFailureIso<E extends Top, D extends Top> = {
     readonly fiberId: number | undefined;
 };
 /**
- * @category CauseFailure
+ * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ *
+ * @category CauseReason
  * @since 4.0.0
  */
-export declare function CauseFailure<E extends Top, D extends Top>(error: E, defect: D): CauseFailure<E, D>;
+export declare function CauseReason<E extends Top, D extends Top>(error: E, defect: D): CauseReason<E, D>;
 /**
+ * Schema for `Cause<E>`, an ordered collection of reasons a fiber failed,
+ * combining typed errors, defects, and interrupts.
+ *
  * @category Cause
  * @since 4.0.0
  */
@@ -3300,13 +4870,18 @@ export interface Cause<E extends Top, D extends Top> extends declareConstructor<
  * @category Cause
  * @since 4.0.0
  */
-export type CauseIso<E extends Top, D extends Top> = ReadonlyArray<CauseFailureIso<E, D>>;
+export type CauseIso<E extends Top, D extends Top> = ReadonlyArray<CauseReasonIso<E, D>>;
 /**
+ * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ *
  * @category Cause
  * @since 4.0.0
  */
 export declare function Cause<E extends Top, D extends Top>(error: E, defect: D): Cause<E, D>;
 /**
+ * Schema type for {@link Error}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Error extends instanceOf<globalThis.Error> {
@@ -3332,6 +4907,9 @@ export declare const Error: Error;
  */
 export declare const ErrorWithStack: Error;
 /**
+ * Schema type for {@link Defect}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Defect extends Union<readonly [
@@ -3359,6 +4937,9 @@ export declare const Defect: Defect;
  */
 export declare const DefectWithStack: Defect;
 /**
+ * Schema for `Exit<A, E>`, representing the result of a fiber execution —
+ * either a success with value `A` or a failure with `Cause<E>`.
+ *
  * @category Exit
  * @since 4.0.0
  */
@@ -3379,15 +4960,19 @@ export type ExitIso<A extends Top, E extends Top, D extends Top> = {
     readonly cause: CauseIso<E, D>;
 };
 /**
+ * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ *
  * @category Exit
  * @since 4.0.0
  */
 export declare function Exit<A extends Top, E extends Top, D extends Top>(value: A, error: E, defect: D): Exit<A, E, D>;
 /**
+ * Schema type for {@link ReadonlyMap}.
+ *
  * @category ReadonlyMap
  * @since 4.0.0
  */
-export interface ReadonlyMap$<Key extends Top, Value extends Top> extends declareConstructor<globalThis.ReadonlyMap<Key["Type"], Value["Type"]>, globalThis.ReadonlyMap<Key["Encoded"], Value["Encoded"]>, readonly [Key, Value], ReadonlyMapIso<Key, Value>> {
+export interface $ReadonlyMap<Key extends Top, Value extends Top> extends declareConstructor<globalThis.ReadonlyMap<Key["Type"], Value["Type"]>, globalThis.ReadonlyMap<Key["Encoded"], Value["Encoded"]>, readonly [Key, Value], ReadonlyMapIso<Key, Value>> {
     readonly key: Key;
     readonly value: Value;
 }
@@ -3403,50 +4988,136 @@ export type ReadonlyMapIso<Key extends Top, Value extends Top> = ReadonlyArray<r
  * @category ReadonlyMap
  * @since 4.0.0
  */
-export declare function ReadonlyMap<Key extends Top, Value extends Top>(key: Key, value: Value): ReadonlyMap$<Key, Value>;
+export declare function ReadonlyMap<Key extends Top, Value extends Top>(key: Key, value: Value): $ReadonlyMap<Key, Value>;
 /**
- * @category ReadonlySet
+ * Schema for an Effect `HashMap` where keys and values must conform to the
+ * provided schemas.
+ *
+ * @category HashMap
  * @since 4.0.0
  */
-export interface ReadonlySet$<Value extends Top> extends declareConstructor<globalThis.ReadonlySet<Value["Type"]>, globalThis.ReadonlySet<Value["Encoded"]>, readonly [Value], ReadonlySetIso<Value>> {
+export interface HashMap<Key extends Top, Value extends Top> extends declareConstructor<HashMap_.HashMap<Key["Type"], Value["Type"]>, HashMap_.HashMap<Key["Encoded"], Value["Encoded"]>, readonly [Key, Value], HashMapIso<Key, Value>> {
+    readonly key: Key;
     readonly value: Value;
 }
 /**
- * @category ReadonlySet
+ * @category HashMap
  * @since 4.0.0
  */
-export type ReadonlySetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
+export type HashMapIso<Key extends Top, Value extends Top> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>;
 /**
- * @category ReadonlySet
+ * Creates a schema that validates a `HashMap` where keys and values must
+ * conform to the provided schemas.
+ *
+ * @category HashMap
  * @since 4.0.0
  */
-export declare function ReadonlySet<Value extends Top>(value: Value): ReadonlySet$<Value>;
+export declare function HashMap<Key extends Top, Value extends Top>(key: Key, value: Value): HashMap<Key, Value>;
 /**
+ * Schema type for {@link ReadonlySet}.
+ *
+ * @category ReadonlySet
  * @since 4.0.0
  */
-export interface RegExp extends instanceOf<globalThis.RegExp> {
+export interface $ReadonlySet<Value extends Top> extends declareConstructor<globalThis.ReadonlySet<Value["Type"]>, globalThis.ReadonlySet<Value["Encoded"]>, readonly [Value], ReadonlySetIso<Value>> {
+    readonly value: Value;
 }
 /**
+ * @category ReadonlySet
  * @since 4.0.0
  */
-export declare const RegExp: RegExp;
+export type ReadonlySetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
 /**
+ * @category ReadonlySet
  * @since 4.0.0
  */
-export interface URL extends instanceOf<globalThis.URL> {
-}
+export declare function ReadonlySet<Value extends Top>(value: Value): $ReadonlySet<Value>;
 /**
- * A schema for JavaScript `URL` objects.
- *
- * **Default JSON serializer**
- *
- * - encodes `URL` as a `string`
+ * Schema for an Effect `HashSet` where values must conform to the provided
+ * schema.
  *
+ * @category HashSet
  * @since 4.0.0
- * @category URL
  */
-export declare const URL: URL;
+export interface HashSet<Value extends Top> extends declareConstructor<HashSet_.HashSet<Value["Type"]>, HashSet_.HashSet<Value["Encoded"]>, readonly [Value], HashSetIso<Value>> {
+    readonly value: Value;
+}
 /**
+ * @category HashSet
+ * @since 4.0.0
+ */
+export type HashSetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
+/**
+ * Creates a schema that validates a `HashSet` where values must conform to the
+ * provided schema.
+ *
+ * @category HashSet
+ * @since 4.0.0
+ */
+export declare function HashSet<Value extends Top>(value: Value): HashSet<Value>;
+/**
+ * Schema for an Effect `Chunk` (immutable array-like collection) where values
+ * must conform to the provided schema.
+ *
+ * @category Chunk
+ * @since 4.0.0
+ */
+export interface Chunk<Value extends Top> extends declareConstructor<Chunk_.Chunk<Value["Type"]>, Chunk_.Chunk<Value["Encoded"]>, readonly [Value], ChunkIso<Value>> {
+    readonly value: Value;
+}
+/**
+ * @category Chunk
+ * @since 4.0.0
+ */
+export type ChunkIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
+/**
+ * Creates a schema that validates a `Chunk` where values must conform to the
+ * provided schema.
+ *
+ * @category Chunk
+ * @since 4.0.0
+ */
+export declare function Chunk<Value extends Top>(value: Value): Chunk<Value>;
+/**
+ * Schema type for {@link RegExp}.
+ *
+ * @category Schemas
+ * @since 4.0.0
+ */
+export interface RegExp extends instanceOf<globalThis.RegExp> {
+}
+/**
+ * Schema for JavaScript `RegExp` objects.
+ *
+ * The default JSON serializer encodes a `RegExp` as `{ source, flags }`.
+ *
+ * @category Schemas
+ * @since 4.0.0
+ */
+export declare const RegExp: RegExp;
+/**
+ * Schema type for {@link URL}.
+ *
+ * @category URL
+ * @since 4.0.0
+ */
+export interface URL extends instanceOf<globalThis.URL> {
+}
+/**
+ * A schema for JavaScript `URL` objects.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `URL` as a `string`
+ *
+ * @since 4.0.0
+ * @category URL
+ */
+export declare const URL: URL;
+/**
+ * Schema type for {@link URLFromString}.
+ *
+ * @category URL
  * @since 4.0.0
  */
 export interface URLFromString extends decodeTo<URL, String> {
@@ -3465,6 +5136,9 @@ export interface URLFromString extends decodeTo<URL, String> {
  */
 export declare const URLFromString: URLFromString;
 /**
+ * Schema type for {@link Date}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Date extends instanceOf<globalThis.Date> {
@@ -3473,12 +5147,26 @@ export interface Date extends instanceOf<globalThis.Date> {
  * A schema for JavaScript `Date` objects.
  *
  * This schema accepts any `Date` instance, including invalid dates (e.g., `new
- * Date("invalid")`). For validating only valid dates, use `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 declare const Date: Date;
 /**
+ * Schema type for {@link DateValid}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface DateValid extends Date {
@@ -3493,6 +5181,9 @@ export interface DateValid extends Date {
  */
 export declare const DateValid: Date;
 /**
+ * Schema type for {@link Duration}.
+ *
+ * @category Duration
  * @since 4.0.0
  */
 export interface Duration extends declare<Duration_.Duration> {
@@ -3500,14 +5191,28 @@ export interface Duration extends declare<Duration_.Duration> {
 /**
  * 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
  */
 export declare const Duration: Duration;
 /**
+ * Schema type for {@link DurationFromNanos}.
+ *
+ * @category Duration
  * @since 4.0.0
  */
 export interface DurationFromNanos extends decodeTo<Duration, BigInt> {
@@ -3527,6 +5232,9 @@ export interface DurationFromNanos extends decodeTo<Duration, BigInt> {
  */
 export declare const DurationFromNanos: DurationFromNanos;
 /**
+ * Schema type for {@link DurationFromMillis}.
+ *
+ * @category Duration
  * @since 4.0.0
  */
 export interface DurationFromMillis extends decodeTo<Duration, Number> {
@@ -3549,6 +5257,27 @@ export interface DurationFromMillis extends decodeTo<Duration, Number> {
  */
 export declare const DurationFromMillis: DurationFromMillis;
 /**
+ * Schema type for {@link BigDecimal}.
+ *
+ * @category Schemas
+ * @since 4.0.0
+ */
+export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
+}
+/**
+ * A schema for `BigDecimal` values.
+ *
+ * **Default JSON serializer**
+ *
+ * - encodes `BigDecimal` as a `string`
+ *
+ * @since 4.0.0
+ */
+export declare const BigDecimal: BigDecimal;
+/**
+ * Schema type for {@link UnknownFromJsonString}.
+ *
+ * @category JSON
  * @since 4.0.0
  */
 export interface UnknownFromJsonString extends fromJsonString<Unknown> {
@@ -3577,6 +5306,9 @@ export interface UnknownFromJsonString extends fromJsonString<Unknown> {
  */
 export declare const UnknownFromJsonString: fromJsonString<Unknown>;
 /**
+ * Schema type for {@link fromJsonString}.
+ *
+ * @category JSON
  * @since 4.0.0
  */
 export interface fromJsonString<S extends Top> extends decodeTo<S, String> {
@@ -3646,24 +5378,45 @@ export interface fromJsonString<S extends Top> extends decodeTo<S, String> {
  */
 export declare function fromJsonString<S extends Top>(schema: S): fromJsonString<S>;
 /**
+ * Schema type for {@link File}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface File extends instanceOf<globalThis.File> {
 }
 /**
+ * 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 declare const File: File;
 /**
+ * Schema type for {@link FormData}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface FormData extends instanceOf<globalThis.FormData> {
 }
 /**
+ * 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 declare const FormData: FormData;
 /**
+ * Schema type for {@link fromFormData}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface fromFormData<S extends Top> extends decodeTo<S, FormData> {
@@ -3753,15 +5506,26 @@ export interface fromFormData<S extends Top> extends decodeTo<S, FormData> {
  */
 export declare function fromFormData<S extends Top>(schema: S): fromFormData<S>;
 /**
+ * Schema type for {@link URLSearchParams}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface URLSearchParams extends instanceOf<globalThis.URLSearchParams> {
 }
 /**
+ * Schema for JavaScript `URLSearchParams` objects.
+ *
+ * The default JSON serializer encodes a `URLSearchParams` as a query string.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export declare const URLSearchParams: URLSearchParams;
 /**
+ * Schema type for {@link fromURLSearchParams}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface fromURLSearchParams<S extends Top> extends decodeTo<S, URLSearchParams> {
@@ -3842,6 +5606,9 @@ export interface fromURLSearchParams<S extends Top> extends decodeTo<S, URLSearc
  */
 export declare function fromURLSearchParams<S extends Top>(schema: S): fromURLSearchParams<S>;
 /**
+ * Schema type for {@link Finite}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Finite extends Number {
@@ -3853,6 +5620,9 @@ export interface Finite extends Number {
  */
 export declare const Finite: Finite;
 /**
+ * Schema type for {@link Int}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Int extends Number {
@@ -3864,6 +5634,9 @@ export interface Int extends Number {
  */
 export declare const Int: Int;
 /**
+ * Schema type for {@link NumberFromString}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface NumberFromString extends decodeTo<Finite, String> {
@@ -3881,6 +5654,9 @@ export interface NumberFromString extends decodeTo<Finite, String> {
  */
 export declare const NumberFromString: NumberFromString;
 /**
+ * Schema type for {@link FiniteFromString}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface FiniteFromString extends decodeTo<Finite, String> {
@@ -3899,6 +5675,9 @@ export interface FiniteFromString extends decodeTo<Finite, String> {
  */
 export declare const FiniteFromString: FiniteFromString;
 /**
+ * Schema type for {@link Trimmed}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Trimmed extends String {
@@ -3910,6 +5689,9 @@ export interface Trimmed extends String {
  */
 export declare const Trimmed: Trimmed;
 /**
+ * Schema type for {@link Trim}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Trim extends decodeTo<Trimmed, String> {
@@ -3927,6 +5709,9 @@ export interface Trim extends decodeTo<Trimmed, String> {
  */
 export declare const Trim: Trim;
 /**
+ * A union schema for JavaScript property keys: `number | symbol | string`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export declare const PropertyKey: Union<readonly [Finite, Symbol, String]>;
@@ -3934,14 +5719,17 @@ export declare const PropertyKey: Union<readonly [Finite, Symbol, String]>;
  * @since 4.0.0
  */
 export declare const StandardSchemaV1FailureResult: Struct<{
-    readonly issues: Array$<Struct<{
+    readonly issues: $Array<Struct<{
         readonly message: String;
-        readonly path: optional<Array$<Union<readonly [Union<readonly [Finite, Symbol, String]>, Struct<{
+        readonly path: optional<$Array<Union<readonly [Union<readonly [Finite, Symbol, String]>, Struct<{
             readonly key: Union<readonly [Finite, Symbol, String]>;
         }>]>>>;
     }>>;
 }>;
 /**
+ * Schema type for {@link BooleanFromBit}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0, 1]>> {
@@ -3954,6 +5742,9 @@ export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0,
  */
 export declare const BooleanFromBit: BooleanFromBit;
 /**
+ * Schema type for {@link Uint8Array}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBufferLike>> {
@@ -3970,6 +5761,9 @@ export interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBuffer
  */
 export declare const Uint8Array: Uint8Array;
 /**
+ * Schema type for {@link Uint8ArrayFromBase64}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
@@ -3989,6 +5783,9 @@ export interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromBase64: Uint8ArrayFromBase64;
 /**
+ * Schema type for {@link Uint8ArrayFromBase64Url}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
@@ -4008,6 +5805,9 @@ export interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromBase64Url: Uint8ArrayFromBase64Url;
 /**
+ * Schema type for {@link Uint8ArrayFromHex}.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
@@ -4027,6 +5827,9 @@ export interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
  */
 export declare const Uint8ArrayFromHex: Uint8ArrayFromHex;
 /**
+ * Schema type for {@link DateTimeUtc}.
+ *
+ * @category DateTime
  * @since 4.0.0
  */
 export interface DateTimeUtc extends declare<DateTime.Utc> {
@@ -4043,6 +5846,9 @@ export interface DateTimeUtc extends declare<DateTime.Utc> {
  */
 export declare const DateTimeUtc: DateTimeUtc;
 /**
+ * Schema type for {@link DateTimeUtcFromDate}.
+ *
+ * @category DateTime
  * @since 4.0.0
  */
 export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
@@ -4061,6 +5867,9 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
  */
 export declare const DateTimeUtcFromDate: DateTimeUtcFromDate;
 /**
+ * Schema type for {@link DateTimeUtcFromString}.
+ *
+ * @category DateTime
  * @since 4.0.0
  */
 export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
@@ -4081,6 +5890,9 @@ export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
  */
 export declare const DateTimeUtcFromString: DateTimeUtcFromString;
 /**
+ * Schema type for {@link DateTimeUtcFromMillis}.
+ *
+ * @category DateTime
  * @since 4.0.0
  */
 export interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>, Number> {
@@ -4099,12 +5911,98 @@ export interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>
  */
 export declare const DateTimeUtcFromMillis: DateTimeUtcFromMillis;
 /**
+ * Schema type for {@link TimeZoneOffset}.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export interface TimeZoneOffset extends declare<DateTime.TimeZone.Offset> {
+}
+/**
+ * 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 declare const TimeZoneOffset: TimeZoneOffset;
+/**
+ * Schema type for {@link TimeZoneNamed}.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export interface TimeZoneNamed extends declare<DateTime.TimeZone.Named> {
+}
+/**
+ * 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 declare const TimeZoneNamed: TimeZoneNamed;
+/**
+ * Schema type for {@link TimeZone}.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export interface TimeZone extends declare<DateTime.TimeZone> {
+}
+/**
+ * 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 declare const TimeZone: TimeZone;
+/**
+ * Schema type for {@link DateTimeZoned}.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export interface DateTimeZoned extends declare<DateTime.Zoned> {
+}
+/**
+ * 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 declare const DateTimeZoned: DateTimeZoned;
+/**
+ * Interface for schema-backed classes created with {@link Class}.
+ *
+ * A `Class` is a TypeScript class whose constructor validates its input
+ * against a {@link Struct} schema. Instances are always structurally valid.
+ *
+ * The interface exposes the schema's `fields`, an `identifier` string, and
+ * helpers such as `mapFields`, `annotate`, `check`, and `extend`.
+ *
  * @since 4.0.0
  */
 export interface Class<Self, S extends Top & {
     readonly fields: Struct.Fields;
 }, Inherited> extends Bottom<Self, S["Encoded"], S["DecodingServices"], S["EncodingServices"], AST.Declaration, decodeTo<declareConstructor<Self, S["Encoded"], readonly [S], S["Iso"]>, S>, S["~type.make.in"], S["Iso"], readonly [S], Self, S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
-    new (props: S["~type.make.in"], options?: MakeOptions): S["Type"] & Inherited;
+    new (...args: {} extends S["~type.make.in"] ? [props?: S["~type.make.in"], options?: MakeOptions] : [props: S["~type.make.in"], options?: MakeOptions]): S["Type"] & Inherited;
     readonly identifier: string;
     readonly fields: S["fields"];
     /**
@@ -4127,6 +6025,10 @@ export interface Class<Self, S extends Top & {
 }
 type AddStaticMembers<C, Static> = C & Pick<Static, Exclude<keyof Static, keyof C>>;
 /**
+ * A {@link Class} that additionally exposes an `extend` method, allowing
+ * subclasses to be derived with extra fields while inheriting all parent
+ * fields and validation.
+ *
  * @since 4.0.0
  */
 export interface ExtendableClass<Self, S extends Top & {
@@ -4135,21 +6037,181 @@ export interface ExtendableClass<Self, S extends Top & {
     extend<Extended, Static = {}, Brand = {}>(identifier: string): <NewFields extends Struct.Fields>(fields: NewFields, annotations?: Annotations.Declaration<Extended, readonly [Struct<Simplify<Assign<S["fields"], NewFields>>>]>) => AddStaticMembers<ExtendableClass<Extended, Struct<Simplify<Assign<S["fields"], NewFields>>>, Self & Brand>, Static>;
 }
 /**
+ * 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
  */
 export declare const Class: {
     /**
+     * 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
      */
     <Self, Brand = {}>(identifier: string): {
         /**
+         * 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
          */
         <const Fields extends Struct.Fields>(fields: Fields, annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>): ExtendableClass<Self, Struct<Fields>, Brand>;
         /**
+         * 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
          */
@@ -4157,21 +6219,105 @@ export declare const Class: {
     };
 };
 /**
+ * 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
  */
 export declare const TaggedClass: {
     /**
+     * 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
      */
     <Self, Brand = {}>(identifier?: string): {
         /**
+         * 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
          */
         <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): ExtendableClass<Self, TaggedStruct<Tag, Fields>, Brand>;
         /**
+         * 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
          */
@@ -4183,6 +6329,10 @@ export declare const TaggedClass: {
     };
 };
 /**
+ * Interface for schema-backed error classes created with {@link ErrorClass}.
+ * Extends {@link ExtendableClass} and is also a `YieldableError`, so instances
+ * can be yielded inside `Effect.gen` as failures.
+ *
  * @since 4.0.0
  */
 export interface ErrorClass<Self, S extends Top & {
@@ -4190,21 +6340,97 @@ export interface ErrorClass<Self, S extends Top & {
 }, Inherited> extends ExtendableClass<Self, S, Inherited> {
 }
 /**
+ * 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 declare const ErrorClass: {
     /**
+     * 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
      */
     <Self, Brand = {}>(identifier: string): {
         /**
+         * 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
          */
         <const Fields extends Struct.Fields>(fields: Fields, annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>): ErrorClass<Self, Struct<Fields>, Cause_.YieldableError & Brand>;
         /**
+         * 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
          */
@@ -4212,21 +6438,93 @@ export declare const ErrorClass: {
     };
 };
 /**
+ * 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
  */
 export declare const TaggedErrorClass: {
     /**
+     * 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
      */
     <Self, Brand = {}>(identifier?: string): {
         /**
+         * 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
          */
         <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): ErrorClass<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
         /**
+         * 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
          */
@@ -4238,16 +6536,43 @@ export declare const TaggedErrorClass: {
     };
 };
 /**
+ * A thunk that, given the `fast-check` module, returns an `Arbitrary<T>`.
+ * Use this type when you need to defer instantiation of the arbitrary, for
+ * example to support recursive schemas.
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
 export type LazyArbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>;
 /**
+ * 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
  */
 export declare function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary<S["Type"]>;
 /**
+ * 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
  */
@@ -4263,6 +6588,13 @@ export declare function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitra
  */
 export declare function overrideToFormatter<S extends Top>(toFormatter: () => Formatter<S["Type"]>): (self: S) => S["~rebuild.out"];
 /**
+ * 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
  */
@@ -4270,26 +6602,46 @@ export declare function toFormatter<T>(schema: Schema<T>, options?: {
     readonly onBefore?: ((ast: AST.AST, recur: (ast: AST.AST) => Formatter<any>) => Formatter<any> | undefined) | undefined;
 }): Formatter<T>;
 /**
- * **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
  */
 export declare function overrideToEquivalence<S extends Top>(toEquivalence: () => Equivalence.Equivalence<S["Type"]>): (self: S) => S["~rebuild.out"];
 /**
+ * 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
  */
 export declare function toEquivalence<T>(schema: Schema<T>): Equivalence.Equivalence<T>;
 /**
+ * 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
  */
 export declare function toRepresentation(schema: Top): SchemaRepresentation.Document;
 /**
+ * Options for {@link toJsonSchemaDocument}.
+ *
  * @since 4.0.0
  */
 export interface ToJsonSchemaOptions {
@@ -4319,22 +6671,31 @@ export interface ToJsonSchemaOptions {
  */
 export declare function toJsonSchemaDocument(schema: Top, options?: ToJsonSchemaOptions): JsonSchema.Document<"draft-2020-12">;
 /**
- * @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 declare function toCodecJson<T, E, RD, RE>(schema: Codec<T, E, RD, RE>): Codec<T, unknown, RD, RE>;
+export declare function toCodecJson<T, E, RD, RE>(schema: Codec<T, E, RD, RE>): Codec<T, Json, RD, RE>;
 /**
- * @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 declare function toCodecIso<S extends Top>(schema: S): Codec<S["Type"], S["Iso"]>;
 /**
- * @category Serializer
+ * A {@link Tree} of `string | undefined` nodes. Leaf values are either a
+ * string representation or `undefined` for opaque/declaration types.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export type StringTree = Tree<string | undefined>;
 /**
- * The StringTree serializer converts **every leaf value to a string**, while
+ * The StringTree canonical codec converts **every leaf value to a string**, while
  * preserving the original structure.
  *
  * Declarations are converted to `undefined` (unless they have a
@@ -4348,7 +6709,7 @@ export type StringTree = Tree<string | undefined>;
  *
  *    Defaults to `false`.
  *
- * @category Serializer
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export declare function toCodecStringTree<T, E, RD, RE>(schema: Codec<T, E, RD, RE>): Codec<T, StringTree, RD, RE>;
@@ -4368,26 +6729,40 @@ type XmlEncoderOptions = {
     readonly sortKeys?: boolean | undefined;
 };
 /**
- * @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 declare function toEncoderXml<T, E, RD, RE>(codec: Codec<T, E, RD, RE>, options?: XmlEncoderOptions): (t: T) => Effect.Effect<string, SchemaError, RE>;
 /**
+ * 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
  */
 export declare function toIso<S extends Top>(schema: S): Optic_.Iso<S["Type"], S["Iso"]>;
 /**
+ * Returns an identity `Iso` over the schema's source (`Type`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
 export declare function toIsoSource<S extends Top>(_: S): Optic_.Iso<S["Type"], S["Type"]>;
 /**
+ * Returns an identity `Iso` over the schema's focus (`Iso`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
 export declare function toIsoFocus<S extends Top>(_: S): Optic_.Iso<S["Iso"], S["Iso"]>;
 /**
+ * The schema type returned by {@link overrideToCodecIso}. Carries a custom
+ * `Iso` type parameter and exposes the original `schema`.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -4396,10 +6771,11 @@ export interface overrideToCodecIso<S extends Top, Iso> extends Bottom<S["Type"]
     readonly schema: S;
 }
 /**
- * **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
@@ -4409,6 +6785,10 @@ export declare function overrideToCodecIso<S extends Top, Iso>(to: Codec<Iso>, t
     readonly encode: Getter.Getter<Iso, S["Type"]>;
 }): (schema: S) => overrideToCodecIso<S, Iso>;
 /**
+ * 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
  */
@@ -4417,53 +6797,47 @@ export declare function toDifferJsonPatch<T, E>(schema: Codec<T, E>): Differ<T,
  * @category Tree
  * @since 4.0.0
  */
-export type Tree<Node> = Node | TreeObject<Node> | ReadonlyArray<Tree<Node>>;
+export type Tree<Node> = Node | TreeRecord<Node> | ReadonlyArray<Tree<Node>>;
 /**
+ * A record node in a {@link Tree}: an object mapping string keys to child
+ * `Tree` nodes.
+ *
  * @category Tree
  * @since 4.0.0
  */
-export interface TreeObject<A> {
+export interface TreeRecord<A> {
     readonly [x: string]: Tree<A>;
 }
 /**
+ * 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
  */
-export declare function Tree<S extends Top>(node: S): Union<readonly [S, Array$<suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>, Record$<String, suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>]>;
-/**
- * @category Tree
- * @since 4.0.0
- */
-export type MutableTree<A> = A | MutableTreeRecord<A> | Array<MutableTree<A>>;
-/**
- * @category Tree
- * @since 4.0.0
- */
-export interface MutableTreeRecord<A> {
-    [x: string]: MutableTree<A>;
-}
-/**
- * @category Tree
- * @since 4.0.0
- */
-export declare function MutableTree<S extends Top>(node: S): Union<readonly [S, mutable<Array$<suspend<Codec<MutableTree<S["Type"]>, MutableTree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>>, Record$<String, mutableKey<suspend<Codec<MutableTree<S["Type"]>, MutableTree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>>]>;
+export declare function Tree<S extends Top>(node: S): Union<readonly [S, $Array<suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>, $Record<String, suspend<Codec<Tree<S["Type"]>, Tree<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"]>>>]>;
 /**
+ * Recursive TypeScript type for any valid immutable JSON value: `null`,
+ * `number`, `boolean`, `string`, a readonly array of `Json` values, or a
+ * readonly record of `string → Json`. For the corresponding schema, see the
+ * {@link Json} const.
+ *
  * @category JSON
  * @since 4.0.0
  */
 export type Json = null | number | boolean | string | JsonArray | JsonObject;
 /**
- * @category JSON
- * @since 4.0.0
- */
-export declare const Json: Codec<Json>;
-/**
+ * A readonly array of {@link Json} values.
+ *
  * @category JSON
  * @since 4.0.0
  */
 export interface JsonArray extends ReadonlyArray<Json> {
 }
 /**
+ * A readonly record whose values are {@link Json} values.
+ *
  * @category JSON
  * @since 4.0.0
  */
@@ -4471,28 +6845,51 @@ export interface JsonObject {
     readonly [x: string]: Json;
 }
 /**
+ * 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 type MutableJson = null | number | boolean | string | MutableJsonArray | MutableJsonObject;
+export declare const Json: Codec<Json>;
 /**
  * @category JSON
  * @since 4.0.0
  */
-export declare const MutableJson: Codec<MutableJson>;
+export type MutableJson = null | number | boolean | string | MutableJsonArray | MutableJsonObject;
 /**
+ * A mutable array of {@link MutableJson} values.
+ *
  * @category JSON
  * @since 4.0.0
  */
 export interface MutableJsonArray extends Array<MutableJson> {
 }
 /**
+ * A mutable record whose values are {@link MutableJson} values.
+ *
  * @category JSON
  * @since 4.0.0
  */
 export interface MutableJsonObject {
     [x: string]: MutableJson;
 }
+/**
+ * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
+ * the immutable variant.
+ *
+ * @category JSON
+ * @since 4.0.0
+ */
+export declare const MutableJson: Codec<MutableJson>;
 /**
  * Return all the typed annotations from the schema.
  *
@@ -4501,6 +6898,13 @@ export interface MutableJsonObject {
  */
 export declare function resolveInto<S extends Top>(schema: S): S["~annotate.in"] | undefined;
 /**
+ * The `Annotations` namespace groups all annotation interfaces used to attach
+ * metadata to schemas. Annotations control documentation, validation messages,
+ * JSON Schema generation, equivalence, arbitrary generation, and more.
+ *
+ * Use {@link resolveInto} to read the annotations attached to a schema at
+ * runtime.
+ *
  * @since 4.0.0
  */
 export declare namespace Annotations {
@@ -4549,6 +6953,9 @@ export declare namespace Annotations {
         readonly [x: string]: unknown;
     }
     /**
+     * Annotations shared by all schema nodes. These map to common JSON Schema /
+     * OpenAPI fields: `title`, `description`, `format`, etc.
+     *
      * @since 4.0.0
      */
     interface Augment extends Annotations {
@@ -4563,6 +6970,8 @@ export declare namespace Annotations {
         readonly contentMediaType?: string | undefined;
     }
     /**
+     * Extends {@link Augment} with type-parametric `default` and `examples` fields.
+     *
      * @since 4.0.0
      */
     interface Documentation<T> extends Augment {
@@ -4570,6 +6979,10 @@ export declare namespace Annotations {
         readonly examples?: ReadonlyArray<T> | undefined;
     }
     /**
+     * Annotations for struct property schemas. Extends {@link Documentation}
+     * with an optional `messageMissingKey` to override the error message when
+     * the property key is absent during decoding.
+     *
      * @category Model
      * @since 4.0.0
      */
@@ -4580,6 +6993,11 @@ export declare namespace Annotations {
         readonly messageMissingKey?: string | undefined;
     }
     /**
+     * Base annotations shared by all composite schema nodes. Extends
+     * {@link Documentation} with error messages, branding, parse options, and
+     * arbitrary generation hooks. {@link Declaration} and other annotation
+     * interfaces build on top of this.
+     *
      * @category Model
      * @since 4.0.0
      */
@@ -4622,6 +7040,12 @@ export declare namespace Annotations {
         };
     }
     /**
+     * Full annotation set for `Declaration` schema nodes — used when defining
+     * custom, opaque schema types via `Schema.declare`. Extends {@link Bottom}
+     * with optional codec, arbitrary, equivalence, and formatter hooks so that
+     * derived capabilities (JSON encoding, property testing, etc.) can be
+     * provided for the custom type.
+     *
      * @category Model
      * @since 4.0.0
      */
@@ -4643,10 +7067,9 @@ export declare namespace Annotations {
         } | undefined;
     }
     /**
-     * **Technical Note**
-     *
-     * This annotation group is not parametric since it would make the filters
-     * invariant
+     * Annotations for filter schema nodes (created via `Schema.filter`). Extends
+     * {@link Augment} with an optional error message, identifier, and metadata.
+     * Filters are intentionally non-parametric to keep them covariant.
      *
      * @category Model
      * @since 4.0.0