effect 4.0.0-beta.6 → 4.0.0-beta.62

package/dist/Schema.js

@@ -1,9 +1,92 @@
 /**
+ * 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 ArraySchema}, {@link NonEmptyArray}
+ * - Define a record: {@link Record}
+ * - Define a tuple: {@link Tuple}, {@link TupleWithRest}
+ * - Validate unknown data synchronously: {@link decodeUnknownSync}
+ * - Validate unknown data (Effect): {@link decodeUnknownEffect}
+ * - Encode a value: {@link encodeUnknownSync}, {@link encodeUnknownEffect}
+ * - Type guard: {@link is}
+ * - Assertion: {@link asserts}
+ * - Add constraints: `.check(...)` with filters like {@link isMinLength},
+ *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}
+ * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
+ * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
+ * - Create branded types: {@link brand}
+ * - Define classes with validation: {@link Class}, {@link TaggedClass}
+ * - Define error classes: {@link ErrorClass}, {@link TaggedErrorClass}
+ * - Generate JSON Schema: {@link toJsonSchemaDocument}
+ * - Generate test data: {@link toArbitrary}
+ * - Derive equivalence: {@link toEquivalence}
+ *
+ * ## Gotchas
+ *
+ * - `Schema.optional` creates `T | undefined` (key can be missing *or*
+ *   `undefined`). Use `Schema.optionalKey` for exact optional properties.
+ * - `decodeTo` is curried: use `from.pipe(Schema.decodeTo(to, ...))`.
+ * - `decodeUnknownSync` throws on failure. Use `decodeUnknownExit` or
+ *   `decodeUnknownOption` for non-throwing alternatives.
+ * - Filters do not change the TypeScript type. Use {@link refine} or
+ *   {@link brand} to narrow the type.
+ * - Recursive schemas require {@link suspend} to avoid infinite loops.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Validate a user object)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const User = Schema.Struct({
+ *   name: Schema.String.check(Schema.isMinLength(1)),
+ *   age: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // Decode unknown input — throws on failure
+ * const user = Schema.decodeUnknownSync(User)({
+ *   name: "Alice",
+ *   age: 30
+ * })
+ *
+ * console.log(user)
+ * // { name: "Alice", age: 30 }
+ * ```
+ *
+ * @see {@link Schema} — type-level view tracking only the decoded Type
+ * @see {@link Codec} — type-level view tracking both Type and Encoded
+ * @see {@link Struct} — define object shapes
+ * @see {@link decodeUnknownSync} — synchronous validation
+ * @see {@link decodeTo} — schema transformations
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.js";
 import * as BigDecimal_ from "./BigDecimal.js";
 import * as Cause_ from "./Cause.js";
+import * as Chunk_ from "./Chunk.js";
 import * as Data from "./Data.js";
 import * as DateTime from "./DateTime.js";
 import * as Duration_ from "./Duration.js";
@@ -12,8 +95,8 @@ import * as Encoding from "./Encoding.js";
 import * as Equal from "./Equal.js";
 import * as Equivalence from "./Equivalence.js";
 import * as Exit_ from "./Exit.js";
-import { format, formatDate, formatPropertyKey } from "./Formatter.js";
-import { identity } from "./Function.js";
+import { format, formatPropertyKey } from "./Formatter.js";
+import { identity, memoize } from "./Function.js";
 import * as HashMap_ from "./HashMap.js";
 import * as HashSet_ from "./HashSet.js";
 import * as core from "./internal/core.js";
@@ -22,7 +105,7 @@ import * as InternalArbitrary from "./internal/schema/arbitrary.js";
 import * as InternalEquivalence from "./internal/schema/equivalence.js";
 import * as InternalStandard from "./internal/schema/representation.js";
 import * as InternalSchema from "./internal/schema/schema.js";
-import * as InternalToCodec from "./internal/schema/to-codec.js";
+import { SchemaError } from "./internal/schema/schema.js";
 import * as JsonPatch from "./JsonPatch.js";
 import * as JsonSchema from "./JsonSchema.js";
 import { remainder } from "./Number.js";
@@ -44,9 +127,51 @@ import * as Struct_ from "./Struct.js";
 import * as FastCheck from "./testing/FastCheck.js";
 const TypeId = InternalSchema.TypeId;
 /**
- * An API for creating schemas for parametric types.
+ * Creates a schema for a **parametric** type (a generic container such as
+ * `Array<A>`, `Option<A>`, etc.) by accepting a list of type-parameter schemas
+ * and a decoder factory.
+ *
+ * The outer call `declareConstructor<T, E, Iso>()` fixes the decoded type `T`,
+ * the encoded type `E`, and the optional iso type. The inner call receives:
+ * - `typeParameters` — the concrete schemas for each type variable
+ * - `run` — a factory that, given resolved codecs for each type parameter,
+ *   returns a parsing function `(u, ast, options) => Effect<T, Issue>`
+ * - `annotations` — optional metadata
  *
- * @see {@link declare} for creating schemas for non parametric types.
+ * @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 })
+ *         )
+ *       }
+ *   )
+ *
+ * const schema = Box(Schema.Number)
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -57,18 +182,60 @@ export function declareConstructor() {
   };
 }
 /**
- * An API for creating schemas for non parametric types.
+ * Creates a schema for a **non-parametric** opaque type using a type-guard
+ * function. The schema accepts any unknown value and succeeds when `is` returns
+ * `true`, failing with an `InvalidType` issue otherwise.
+ *
+ * Use this when the type has no type parameters. For parametric types such as
+ * `Option<A>` or `Array<A>`, use {@link declareConstructor} instead.
+ *
+ * **Example** (Schema for a custom `UserId` branded type)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * type UserId = string & { readonly _tag: "UserId" }
+ *
+ * const isUserId = (u: unknown): u is UserId =>
+ *   typeof u === "string" && u.startsWith("user_")
+ *
+ * const UserId = Schema.declare<UserId>(isUserId, {
+ *   title: "UserId",
+ *   description: "A user identifier starting with 'user_'"
+ * })
+ * ```
  *
  * @see {@link declareConstructor} for creating schemas for parametric types.
  *
+ * @category Constructors
  * @since 4.0.0
  */
 export function declare(is, annotations) {
   return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new Issue.InvalidType(ast, Option_.some(input))), annotations);
 }
 /**
- * Reveals the complete Bottom interface type of a schema, exposing all 14 type
- * parameters.
+ * Widens a schema's type to the fully-parameterized {@link Bottom} interface,
+ * making all 14 type parameters visible to TypeScript.
+ *
+ * Normally, concrete schema interfaces (e.g. `Schema<string>`) hide most type
+ * parameters. `revealBottom` is useful when writing generic utilities that need
+ * to inspect or propagate the complete set of type parameters.
+ *
+ * **Example** (Inspecting all type parameters of a schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.String
+ *
+ * // Widen to Bottom to access all 14 type parameters
+ * const bottom = Schema.revealBottom(schema)
+ *
+ * // `bottom` now exposes Type, Encoded, DecodingServices, EncodingServices,
+ * // ast, Rebuild, ~type.make.in, Iso, ~type.parameters, etc.
+ * type T = typeof bottom["Type"]     // string
+ * type E = typeof bottom["Encoded"]  // string
+ * ```
  *
  * @since 4.0.0
  */
@@ -77,21 +244,88 @@ export function revealBottom(bottom) {
 }
 /**
  * Adds metadata annotations to a schema without changing its runtime behavior.
- * Annotations are used to provide additional context for documentation,
- * JSON schema generation, error formatting, and other tooling.
+ * This is the pipeable (curried) counterpart of the `.annotate` method.
+ *
+ * Annotations provide extra context used by documentation generators, JSON
+ * Schema converters, error formatters, and other tooling. Common keys include
+ * `title`, `description`, `examples`, `message`, and `identifier`.
+ *
+ * **Example** (Adding a title and description)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Age = Schema.Number.pipe(
+ *   Schema.annotate({
+ *     title: "Age",
+ *     description: "A non-negative integer representing age in years"
+ *   })
+ * )
+ * ```
+ *
+ * @see {@link annotateEncoded} to annotate the encoded side instead.
  *
  * @category Annotations
  * @since 4.0.0
  */
 export function annotate(annotations) {
-  return self => {
-    return self.annotate(annotations);
-  };
+  return self => self.annotate(annotations);
+}
+/**
+ * Adds metadata annotations to the **encoded** side of a schema without
+ * changing its runtime behavior. This is the encoded-side counterpart of
+ * `annotate`, which targets the decoded (Type) side.
+ *
+ * Internally the schema is flipped so that `Encoded` becomes `Type`,
+ * annotated, and then flipped back.
+ *
+ * **Example** (Adding a title to the encoded representation)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.NumberFromString.pipe(
+ *   Schema.annotateEncoded({
+ *     title: "my title"
+ *   })
+ * )
+ *
+ * console.log(Schema.toEncoded(schema).ast.annotations?.title)
+ * // "my title"
+ * ```
+ *
+ * @see {@link annotate} to annotate the type side instead.
+ *
+ * @category Annotations
+ * @since 4.0.0
+ */
+export function annotateEncoded(annotations) {
+  return self => flip(flip(self).annotate(annotations));
 }
 /**
- * Adds key-specific annotations to a schema field. This is useful for providing
- * custom error messages and documentation for individual fields within
- * structures.
+ * Adds key-level annotations to a schema field. This is the pipeable
+ * (curried) counterpart of the `.annotateKey` method.
+ *
+ * Key annotations apply to a field's position inside a `Struct` or `Tuple`
+ * rather than to the field's value type. They can carry a
+ * `messageMissingKey` to customise the error shown when the field is absent,
+ * as well as standard documentation fields such as `title`, `description`,
+ * and `examples`.
+ *
+ * **Example** (Custom missing-key message for a required field)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Struct({
+ *   username: Schema.String.pipe(
+ *     Schema.annotateKey({
+ *       description: "The username used to log in",
+ *       messageMissingKey: "Username is required"
+ *     })
+ *   )
+ * })
+ * ```
  *
  * @category Annotations
  * @since 4.0.0
@@ -102,42 +336,81 @@ export function annotateKey(annotations) {
   };
 }
 /**
+ * Identity function that widens a value to the full {@link Codec} interface,
+ * prompting TypeScript to infer all four type parameters (`T`, `E`, `RD`, `RE`).
+ *
+ * When a schema is stored in a variable typed as `Schema<T>` or `Top`, the
+ * encoded type and service requirements are erased. Passing the value through
+ * `revealCodec` recovers those parameters without any runtime cost.
+ *
+ * **Example** (Recovering encoded type from a schema variable)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema: Schema.Schema<number> = Schema.NumberFromString
+ *
+ * // Without revealCodec, Encoded is unknown
+ * const codec = Schema.revealCodec(schema)
+ * type Enc = typeof codec["Encoded"] // string
+ * ```
+ *
  * @since 4.0.0
  */
 export function revealCodec(codec) {
   return codec;
 }
-const SchemaErrorTypeId = "~effect/Schema/SchemaError";
+export {
 /**
- * A `SchemaError` is returned when schema decoding or encoding fails.
+ * Error thrown (or returned as the error channel value) when schema decoding
+ * or encoding fails.
  *
- * This error extends `Data.TaggedError` and contains detailed information about
- * what went wrong during schema processing. The error includes an `issue` field
- * that provides comprehensive details about the validation failure, including
- * the path to the problematic data, expected types, and actual values.
+ * The `issue` field contains a structured {@link Issue.Issue} tree describing
+ * every validation failure, including the path to the problematic value,
+ * expected types, and actual values received. `message` renders the issue tree
+ * as a human-readable string.
+ *
+ * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
+ *
+ * **Example** (Catching a SchemaError)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("not a number")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err.message)
+ *     // Expected number, actual "not a number"
+ *   }
+ * }
+ * ```
  *
  * @since 4.0.0
  */
-export class SchemaError {
-  [SchemaErrorTypeId] = SchemaErrorTypeId;
-  _tag = "SchemaError";
-  name = "SchemaError";
-  issue;
-  constructor(issue) {
-    this.issue = issue;
-  }
-  get message() {
-    return this.issue.toString();
-  }
-  toString() {
-    return `SchemaError(${this.message})`;
-  }
-}
+SchemaError };
 /**
+ * Returns `true` if `u` is a {@link SchemaError}.
+ *
+ * **Example** (Type guard in a catch block)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("oops")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err._tag) // "SchemaError"
+ *   }
+ * }
+ * ```
+ *
  * @since 4.0.0
  */
 export function isSchemaError(u) {
-  return Predicate.hasProperty(u, SchemaErrorTypeId);
+  return Predicate.hasProperty(u, InternalSchema.SchemaErrorTypeId);
 }
 function makeStandardResult(exit) {
   return Exit_.isSuccess(exit) ? exit.value : {
@@ -224,7 +497,7 @@ export function toStandardSchemaV1(self, options) {
     }), {
       scheduler
     });
-    scheduler.flush();
+    fiber.currentDispatcher?.flush();
     const exit = fiber.pollUnsafe();
     if (exit) {
       return makeStandardResult(exit);
@@ -373,6 +646,11 @@ export const is = Parser.is;
  */
 export const asserts = Parser.asserts;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Effect` that
+ * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
+ * when the input type is not statically known. Prefer {@link decodeEffect} when
+ * the input is already typed as the schema's `Encoded` type.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -383,11 +661,22 @@ export function decodeUnknownEffect(schema) {
   };
 }
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Effect` that succeeds with the decoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link decodeUnknownEffect}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeEffect = decodeUnknownEffect;
 /**
+ * Decodes an `unknown` input against a schema synchronously, returning an
+ * `Exit` that is either a `Success` with the decoded value or a `Failure` with
+ * a {@link SchemaError}. Only usable with schemas that have no
+ * `DecodingServices` requirement. Prefer {@link decodeExit} when the input is
+ * already typed as the schema's `Encoded` type.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -398,41 +687,120 @@ export function decodeUnknownExit(schema) {
   };
 }
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, returning an `Exit` that is either a `Success` with the
+ * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
+ * schemas that have no `DecodingServices` requirement. For `unknown` input use
+ * {@link decodeUnknownExit}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeExit = decodeUnknownExit;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the decoded value on success or `None` on failure. Prefer this
+ * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
+ * need to know whether decoding succeeded and don't need error details. For
+ * typed input use {@link decodeOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownOption = Parser.decodeUnknownOption;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Option` that is `Some` with the decoded value on success or
+ * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeOption = Parser.decodeOption;
+/**
+ * Decodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link decodePromise}.
+ *
+ * @category Decoding
+ * @since 4.0.0
+ */
+export const decodeUnknownResult = Parser.decodeUnknownResult;
+/**
+ * @category Decoding
+ * @since 4.0.0
+ */
+export const decodeResult = Parser.decodeResult;
 /**
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownPromise = Parser.decodeUnknownPromise;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Promise` that resolves with the decoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodePromise = Parser.decodePromise;
 /**
+ * Decodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to validate data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link decodeUnknownOption},
+ * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
+ * use {@link decodeSync}.
+ *
+ * **Example** (Decoding with a transformation schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * console.log(Schema.decodeUnknownSync(NumberFromString)("42"))
+ * // Output: 42
+ *
+ * Schema.decodeUnknownSync(NumberFromString)("not a number")
+ * // throws SchemaError: NumberFromString
+ * //   └─ Encoded side transformation failure
+ * //      └─ NumberFromString
+ * //         └─ Expected a numeric string, actual "not a number"
+ * ```
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownSync = Parser.decodeUnknownSync;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
+ * use {@link decodeUnknownSync}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeSync = Parser.decodeSync;
 /**
+ * Encodes an `unknown` input against a schema, returning an `Effect` that
+ * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
+ * when the input type is not statically known. Prefer {@link encodeEffect} when
+ * the input is already typed as the schema's `Type`.
+ *
+ * **Example** (Encoding a value to a string)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * Effect.runPromise(Schema.encodeUnknownEffect(NumberFromString)(42)).then(console.log)
+ * // Output: "42"
+ * ```
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -443,11 +811,22 @@ export function encodeUnknownEffect(schema) {
   };
 }
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Effect` that succeeds with the encoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link encodeUnknownEffect}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeEffect = encodeUnknownEffect;
 /**
+ * Encodes an `unknown` input against a schema synchronously, returning an
+ * `Exit` that is either a `Success` with the encoded value or a `Failure` with
+ * a {@link SchemaError}. Only usable with schemas that have no
+ * `EncodingServices` requirement. Prefer {@link encodeExit} when the input is
+ * already typed as the schema's `Type`.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -458,36 +837,82 @@ export function encodeUnknownExit(schema) {
   };
 }
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * returning an `Exit` that is either a `Success` with the encoded value or a
+ * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
+ * `EncodingServices` requirement. For `unknown` input use
+ * {@link encodeUnknownExit}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeExit = encodeUnknownExit;
 /**
+ * Encodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the encoded value on success or `None` on failure. Prefer this
+ * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
+ * need to know whether encoding succeeded and don't need error details. For
+ * typed input use {@link encodeOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownOption = Parser.encodeUnknownOption;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Option` that is `Some` with the encoded value on success or `None` on
+ * failure. For `unknown` input use {@link encodeUnknownOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeOption = Parser.encodeOption;
+/**
+ * Encodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link encodePromise}.
+ *
+ * @category Encoding
+ * @since 4.0.0
+ */
+export const encodeUnknownResult = Parser.encodeUnknownResult;
+/**
+ * @category Encoding
+ * @since 4.0.0
+ */
+export const encodeResult = Parser.encodeResult;
 /**
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownPromise = Parser.encodeUnknownPromise;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Promise` that resolves with the encoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodePromise = Parser.encodePromise;
 /**
+ * Encodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to serialize data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link encodeUnknownOption},
+ * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
+ * use {@link encodeSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownSync = Parser.encodeUnknownSync;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * throwing a {@link SchemaError} on failure. For `unknown` input use
+ * {@link encodeUnknownSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -508,6 +933,31 @@ export const encodeSync = Parser.encodeSync;
  * @since 4.0.0
  */
 export const make = InternalSchema.make;
+/**
+ * Transforms a schema into a class that can be extended with `extends`. The
+ * resulting class inherits the full schema API (e.g. `annotate`) and can define
+ * static methods that reference `this`.
+ *
+ * **Example** (Wrapping a primitive schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class MyString extends Schema.asClass(Schema.String) {
+ *   static readonly decodeUnknownSync = Schema.decodeUnknownSync(this)
+ * }
+ *
+ * console.log(MyString.decodeUnknownSync("a"))
+ * // "a"
+ * ```
+ *
+ * @since 4.0.0
+ */
+export function asClass(schema) {
+  // oxlint-disable-next-line @typescript-eslint/no-extraneous-class
+  class Class {}
+  return Object.setPrototypeOf(Class, schema);
+}
 /**
  * Tests if a value is a `Schema`.
  *
@@ -542,57 +992,74 @@ export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.option
   schema
 }));
 /**
+ * Reverses {@link optionalKey}, returning the inner required schema. Only
+ * applicable to schemas already wrapped with `optionalKey`.
+ *
  * @since 4.0.0
  */
 export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
 /**
- * Creates an optional schema field that allows both the specified type and
+ * Marks a struct field as optional, allowing the key to be absent or
  * `undefined`.
  *
- * This is equivalent to `optionalKey(UndefinedOr(schema))`, creating a field
- * that:
- * - Can be omitted from the object entirely
- * - Can be explicitly set to `undefined`
- * - Can contain the specified schema type
+ * explicitly set to `undefined`. Equivalent to `optionalKey(UndefinedOr(S))`.
  *
- * **Example** (Creating a struct with optional)
+ * Use {@link optionalKey} instead if you want exact optional semantics (absent
+ * only, not `undefined`).
+ *
+ * **Example** (Optional field accepting undefined)
  *
  * ```ts
  * import { Schema } from "effect"
  *
  * const schema = Schema.Struct({
  *   name: Schema.String,
- *   age: Schema.optionalKey(Schema.Number)
+ *   age: Schema.optional(Schema.Number)
  * })
  *
- * // Type: { readonly name: string; readonly age?: number | undefined }
- * type Person = typeof schema["Type"]
+ * // { readonly name: string; readonly age?: number | undefined }
+ * type Person = typeof schema.Type
  * ```
  *
  * @since 4.0.0
  */
 export const optional = /*#__PURE__*/Struct_.lambda(self => optionalKey(UndefinedOr(self)));
 /**
+ * Reverses {@link optional}, returning the inner schema (unwrapping `UndefinedOr`).
+ * Only applicable to schemas already wrapped with `optional`.
+ *
  * @since 4.0.0
  */
 export const required = /*#__PURE__*/Struct_.lambda(self => self.schema.members[0]);
 /**
+ * Makes a struct field mutable (removes the `readonly` modifier on the property).
+ * Use {@link readonlyKey} to reverse.
+ *
  * @since 4.0.0
  */
 export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutableKey(schema.ast), {
   schema
 }));
 /**
+ * Reverses {@link mutableKey}, returning the inner schema as readonly again.
+ * Only applicable to schemas already wrapped with `mutableKey`.
+ *
  * @since 4.0.0
  */
 export const readonlyKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
 /**
+ * Extracts the type-side schema: sets `Encoded` to equal the decoded `Type`,
+ * discarding the encoding transformation path.
+ *
  * @since 4.0.0
  */
 export const toType = /*#__PURE__*/Struct_.lambda(schema => make(AST.toType(schema.ast), {
   schema
 }));
 /**
+ * Extracts the encoded-side schema: sets `Type` to equal the `Encoded`,
+ * discarding the decoding transformation path.
+ *
  * @since 4.0.0
  */
 export const toEncoded = /*#__PURE__*/Struct_.lambda(schema => make(AST.toEncoded(schema.ast), {
@@ -612,6 +1079,16 @@ export function flip(schema) {
   });
 }
 /**
+ * Creates a schema for a single literal value (string, number, bigint, boolean, or null).
+ *
+ * **Example** (String literal)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Literal("hello")
+ * // Type: Schema.Literal<"hello">
+ * ```
+ *
  * @see {@link Literals} for a schema that represents a union of literals.
  * @see {@link tag} for a schema that represents a literal value that can be
  * used as a discriminator field in tagged unions and has a constructor default.
@@ -633,6 +1110,18 @@ function templateLiteralFromParts(parts) {
   return new AST.TemplateLiteral(parts.map(part => isSchema(part) ? part.ast : new AST.Literal(part)));
 }
 /**
+ * Creates a schema that validates strings matching a template literal pattern. Each part can be
+ * a literal string/number/bigint or a schema whose encoded type is a string, number, or bigint.
+ *
+ * **Example** (URL path pattern)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.TemplateLiteral(["/user/", Schema.Number])
+ * // matches strings like "/user/123", "/user/42", etc.
+ * ```
+ *
+ * @see {@link TemplateLiteralParser} for a schema that also parses matched parts into a tuple.
  * @since 4.0.0
  */
 export function TemplateLiteral(parts) {
@@ -641,14 +1130,41 @@ export function TemplateLiteral(parts) {
   });
 }
 /**
+ * Like {@link TemplateLiteral} but decodes the matched string into a readonly tuple of typed values,
+ * one element per schema part.
+ *
+ * **Example** (Parse path parameters)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.TemplateLiteralParser(["/user/", Schema.NumberFromString])
+ * // decodes "/user/42" => readonly ["/user/", 42]
+ * ```
+ *
+ * @see {@link TemplateLiteral} for a validation-only version that keeps the string encoded.
  * @since 4.0.0
  */
 export function TemplateLiteralParser(parts) {
   return make(templateLiteralFromParts(parts).asTemplateLiteralParser(), {
-    parts: [...parts]
+    parts
   });
 }
 /**
+ * Creates a schema from a TypeScript enum object. Validates that the input is one of the enum's values.
+ *
+ * **Example** (Direction enum)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * enum Direction {
+ *   Up = "Up",
+ *   Down = "Down"
+ * }
+ *
+ * const schema = Schema.Enum(Direction)
+ * // accepts "Up" or "Down"
+ * ```
+ *
  * @since 4.0.0
  */
 export function Enum(enums) {
@@ -657,84 +1173,102 @@ export function Enum(enums) {
   });
 }
 /**
+ * Schema for the `never` type. Always fails validation — no value satisfies it.
+ *
  * @since 4.0.0
  */
 export const Never = /*#__PURE__*/make(AST.never);
 /**
+ * Schema for the `any` type. Accepts any value without validation.
+ *
+ * @see {@link Unknown} for a safer alternative that uses `unknown`.
  * @since 4.0.0
  */
 export const Any = /*#__PURE__*/make(AST.any);
 /**
+ * Schema for the `unknown` type. Accepts any value without validation.
+ *
+ * @see {@link Any} for the `any` variant.
  * @since 4.0.0
  */
 export const Unknown = /*#__PURE__*/make(AST.unknown);
 /**
+ * Schema for the `null` literal. Validates that the input is strictly `null`.
+ *
+ * @see {@link NullOr} for a union with another schema.
  * @since 4.0.0
  */
 export const Null = /*#__PURE__*/make(AST.null);
 /**
+ * Schema for the `undefined` literal. Validates that the input is strictly `undefined`.
+ *
+ * @see {@link UndefinedOr} for a union with another schema.
  * @since 4.0.0
  */
 export const Undefined = /*#__PURE__*/make(AST.undefined);
 /**
- * A schema for all strings.
+ * Schema for `string` values. Validates that the input is `typeof` `"string"`.
  *
  * @since 4.0.0
  */
 export const String = /*#__PURE__*/make(AST.string);
 /**
- * A schema for all numbers, including `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for `number` values, including `NaN`, `Infinity`, and `-Infinity`.
  *
  * **Default Json Serializer**
  *
- * - If the number is finite, it is serialized as a number.
- * - Otherwise, it is serialized as a string ("NaN", "Infinity", or "-Infinity").
+ * - Finite numbers are serialized as numbers.
+ * - Non-finite values are serialized as strings (`"NaN"`, `"Infinity"`, `"-Infinity"`).
  *
+ * @see {@link Finite} for a schema that excludes non-finite values.
  * @since 4.0.0
  */
 export const Number = /*#__PURE__*/make(AST.number);
 /**
- * A schema for all booleans.
+ * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
  * @category Boolean
  * @since 4.0.0
  */
 export const Boolean = /*#__PURE__*/make(AST.boolean);
 /**
- * A schema for all symbols.
+ * Schema for `symbol` values. Validates that the input is `typeof` `"symbol"`.
  *
+ * @see {@link UniqueSymbol} for a schema that matches a specific symbol.
  * @since 4.0.0
  */
 export const Symbol = /*#__PURE__*/make(AST.symbol);
 /**
- * A schema for all bigints.
+ * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
  * @since 4.0.0
  */
 export const BigInt = /*#__PURE__*/make(AST.bigInt);
 /**
- * A schema for the `void` type.
+ * Schema for the `void` type. Accepts `undefined` as the encoded value.
  *
  * @since 4.0.0
  */
 export const Void = /*#__PURE__*/make(AST.void);
 /**
- * A schema for the `object` type.
+ * Schema for the `object` type. Validates that the input is a non-null object or function
+ * (i.e. `typeof value === "object" && value !== null || typeof value === "function"`).
  *
  * @since 4.0.0
  */
 export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
 /**
- * A schema for unique symbols.
- *
- * **Example**
+ * Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.
  *
+ * **Example** (Specific symbol)
  * ```ts
  * import { Schema } from "effect"
  *
- * const a = Symbol.for("a")
- * const schema = Schema.UniqueSymbol(a)
+ * const mySymbol = Symbol.for("mySymbol")
+ * const schema = Schema.UniqueSymbol(mySymbol)
  * ```
+ *
+ * @see {@link Symbol} for a schema that accepts any symbol.
  * @since 4.0.0
  */
 export function UniqueSymbol(symbol) {
@@ -750,6 +1284,34 @@ function makeStruct(ast, fields) {
   });
 }
 /**
+ * Defines a struct schema from a map of field schemas.
+ *
+ * Each field value is a schema. Use {@link optionalKey} or {@link optional} to
+ * mark fields as optional, and {@link mutableKey} to mark them as mutable.
+ *
+ * The resulting schema's `Type` is a readonly object type with the fields'
+ * decoded types. The `Encoded` form mirrors the field schemas' encoded types.
+ *
+ * **Example** (Basic struct)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   age: Schema.Number,
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // { readonly name: string; readonly age: number; readonly email?: string }
+ * type Person = typeof Person.Type
+ *
+ * const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Struct(fields) {
@@ -777,6 +1339,26 @@ export function fieldsAssign(fields) {
   return Struct_.lambda(struct => struct.mapFields(Struct_.assign(fields)));
 }
 /**
+ * Renames struct keys in the encoded form without changing the decoded type.
+ *
+ * Takes a partial mapping `{ decodedKey: encodedKey }` and produces a
+ * transformation schema that decodes from the renamed keys and encodes back to
+ * the renamed keys. Keys not present in the mapping are left unchanged.
+ *
+ * **Example** (Rename `name` to `full_name` in the encoded form)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * const Encoded = Person.pipe(Schema.encodeKeys({ name: "full_name" }))
+ *
+ * // Decodes { full_name: "Alice", age: 30 } → { name: "Alice", age: 30 }
+ * const alice = Schema.decodeUnknownSync(Encoded)({ full_name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
  * @category Struct transformations
  * @since 4.0.0
  */
@@ -785,11 +1367,12 @@ export function encodeKeys(mapping) {
     const fields = {};
     const reverseMapping = {};
     for (const k in self.fields) {
+      const encoded = toEncoded(self.fields[k]);
       if (Object.hasOwn(mapping, k)) {
-        fields[mapping[k]] = toEncoded(self.fields[k]);
+        fields[mapping[k]] = encoded;
         reverseMapping[mapping[k]] = k;
       } else {
-        fields[k] = self.fields[k];
+        fields[k] = encoded;
       }
     }
     return Struct(fields).pipe(decodeTo(self, Transformation.transform({
@@ -799,6 +1382,31 @@ export function encodeKeys(mapping) {
   };
 }
 /**
+ * Adds derived fields to a struct schema during decoding.
+ *
+ * Each new field is derived from the decoded struct value via a function that
+ * returns `Option`. On encoding the derived fields are stripped. This allows
+ * computed or enriched fields to live in the decoded type without appearing in
+ * the encoded form.
+ *
+ * **Example** (Add a computed `fullName` field)
+ *
+ * ```ts
+ * import { Option, Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ first: Schema.String, last: Schema.String })
+ * const Extended = Person.pipe(
+ *   Schema.extendTo(
+ *     { fullName: Schema.String },
+ *     { fullName: (p) => Option.some(`${p.first} ${p.last}`) }
+ *   )
+ * )
+ *
+ * const alice = Schema.decodeUnknownSync(Extended)({ first: "Alice", last: "Smith" })
+ * console.log(alice.fullName)
+ * // Alice Smith
+ * ```
+ *
  * @since 4.0.0
  * @experimental
  */
@@ -838,6 +1446,24 @@ derive) {
   };
 }
 /**
+ * Defines a record (dictionary) schema with typed keys and values.
+ *
+ * **Example** (String-keyed record of numbers)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Record(Schema.String, Schema.Number)
+ *
+ * // { readonly [x: string]: number }
+ * type R = typeof schema.Type
+ *
+ * const result = Schema.decodeUnknownSync(schema)({ a: 1, b: 2 })
+ * console.log(result)
+ * // { a: 1, b: 2 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Record(key, value, options) {
@@ -848,6 +1474,24 @@ export function Record(key, value, options) {
   });
 }
 /**
+ * Extends a struct schema with one or more record (index-signature) schemas,
+ * producing a schema whose decoded type intersects the struct and all records.
+ *
+ * **Example** (Struct with string-indexed extra keys)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.StructWithRest(
+ *   Schema.Struct({ id: Schema.Number }),
+ *   [Schema.Record(Schema.String, Schema.String)]
+ * )
+ *
+ * // { readonly id: number } & { readonly [x: string]: string }
+ * type T = typeof schema.Type
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function StructWithRest(schema, records) {
@@ -866,6 +1510,20 @@ function makeTuple(ast, elements) {
   });
 }
 /**
+ * Defines a fixed-length tuple schema from an array of element schemas.
+ *
+ * **Example** (Pair of string and number)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Tuple([Schema.String, Schema.Number])
+ *
+ * const pair = Schema.decodeUnknownSync(schema)(["hello", 42])
+ * console.log(pair)
+ * // [ 'hello', 42 ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -873,6 +1531,26 @@ export function Tuple(elements) {
   return makeTuple(AST.tuple(elements), elements);
 }
 /**
+ * Extends a fixed-length tuple schema with rest elements, creating a variadic
+ * tuple that starts with the fixed elements and ends with zero or more rest
+ * elements.
+ *
+ * **Example** (Tuple with rest)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // [string, number, ...boolean[]]
+ * const schema = Schema.TupleWithRest(
+ *   Schema.Tuple([Schema.String, Schema.Number]),
+ *   [Schema.Boolean]
+ * )
+ *
+ * const result = Schema.decodeUnknownSync(schema)(["hello", 1, true, false])
+ * console.log(result)
+ * // [ 'hello', 1, true, false ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -886,16 +1564,70 @@ export function TupleWithRest(schema, rest) {
  * @category Constructors
  * @since 4.0.0
  */
-export const Array = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [], [schema.ast]), {
+const ArraySchema = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [], [schema.ast]), {
   schema
 }));
+export {
+/**
+ * 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
+ */
+ArraySchema as Array };
 /**
+ * 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 const NonEmptyArray = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [schema.ast], [schema.ast]), {
   schema
 }));
+/**
+ * Decodes a single value or an array of values into an array.
+ *
+ * Decoding:
+ * - a single value is decoded as a one-element array
+ * - an array is decoded as-is
+ *
+ * Encoding:
+ * - a one-element array is encoded as a single value
+ * - arrays with more than one element are encoded as arrays
+ *
+ * @category Arrays
+ * @since 4.0.0
+ */
+export function ArrayEnsure(schema) {
+  return Union([schema, ArraySchema(schema)]).pipe(decodeTo(ArraySchema(toType(schema)), Transformation.transform({
+    decode: Arr.ensure,
+    encode: array => array.length === 1 ? array[0] : array
+  })));
+}
 /**
  * Returns a new array schema that ensures all elements are unique.
  *
@@ -906,10 +1638,21 @@ export const NonEmptyArray = /*#__PURE__*/Struct_.lambda(schema => make(new AST.
  * @since 4.0.0
  */
 export function UniqueArray(item) {
-  return Array(item).check(isUnique());
+  return ArraySchema(item).check(isUnique());
 }
 /**
- * Makes arrays or tuples mutable.
+ * Makes an array or tuple schema mutable, removing the `readonly` modifier.
+ *
+ * **Example** (Mutable array)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.mutable(Schema.Array(Schema.Number))
+ *
+ * // number[]   (mutable)
+ * type T = typeof schema.Type
+ * ```
  *
  * @since 4.0.0
  */
@@ -928,12 +1671,23 @@ function makeUnion(ast, members) {
   });
 }
 /**
- * Creates a schema that represents a union of multiple schemas. Members are checked in order, and the first match is returned.
+ * Creates a union schema from an array of member schemas. Members are tested in
+ * order; the first match is returned.
+ *
+ * Optionally, specify `mode`:
+ * - `"anyOf"` (default) — matches if any member matches.
+ * - `"oneOf"` — matches if exactly one member matches.
  *
- * Optionally, you can specify the `mode` to be `"anyOf"` or `"oneOf"`.
+ * **Example** (String or number union)
  *
- * - `"anyOf"` - The union matches if any member matches.
- * - `"oneOf"` - The union matches if exactly one member matches.
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Union([Schema.String, Schema.Number])
+ *
+ * Schema.decodeUnknownSync(schema)("hello") // "hello"
+ * Schema.decodeUnknownSync(schema)(42)       // 42
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -942,6 +1696,16 @@ export function Union(members, options) {
   return makeUnion(AST.union(members, options?.mode ?? "anyOf", undefined), members);
 }
 /**
+ * Creates a union schema from an array of literal values.
+ *
+ * **Example** (Status codes)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Literals(["active", "inactive", "pending"])
+ * // accepts "active", "inactive", or "pending"
+ * ```
+ *
  * @see {@link Literal} for a schema that represents a single literal.
  * @category Constructors
  * @since 4.0.0
@@ -963,16 +1727,21 @@ export function Literals(literals) {
   });
 }
 /**
+ * Creates a union schema of `S | null`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const NullOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null]));
 /**
+ * Creates a union schema of `S | undefined`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const UndefinedOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Undefined]));
 /**
+ * Creates a union schema of `S | null | undefined`.
  * @category Constructors
  * @since 4.0.0
  */
@@ -982,6 +1751,21 @@ export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null,
  * essential for creating recursive schemas where a schema references itself,
  * preventing infinite recursion during schema definition.
  *
+ * **Example** (Recursive tree schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * interface Tree {
+ *   readonly value: number
+ *   readonly children: ReadonlyArray<Tree>
+ * }
+ *
+ * const Tree = Schema.Struct({
+ *   value: Schema.Number,
+ *   children: Schema.Array(Schema.suspend((): Schema.Codec<Tree> => Tree))
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -989,6 +1773,18 @@ export function suspend(f) {
   return make(new AST.Suspend(() => f().ast));
 }
 /**
+ * Pipeable function that attaches one or more filter checks to a schema without
+ * changing the TypeScript type.
+ *
+ * **Example** (Adding checks to a schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const AgeSchema = Schema.Number.pipe(
+ *   Schema.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(120))
+ * )
+ * ```
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -996,6 +1792,9 @@ export function check(...checks) {
   return self => self.check(...checks);
 }
 /**
+ * Narrows the TypeScript type of a schema's output via a type guard predicate,
+ * attaching the guard as a runtime filter check.
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -1005,7 +1804,8 @@ export function refine(refinement, annotations) {
   });
 }
 /**
- * Adds a brand to a schema.
+ * Adds a nominal brand to a schema, intersecting the output type with
+ * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
  * @category Branding
  * @since 4.0.0
@@ -1017,7 +1817,10 @@ export function brand(identifier) {
   });
 }
 /**
- * @category Constructors
+ * Creates a branded schema from a {@link Brand.Constructor}, applying the
+ * constructor's checks and brand tag to the underlying schema.
+ *
+ * @category Branding
  * @since 4.0.0
  */
 export function fromBrand(identifier, ctor) {
@@ -1026,6 +1829,25 @@ export function fromBrand(identifier, ctor) {
   };
 }
 /**
+ * Intercepts the decoding pipeline of a schema.
+ *
+ * The provided function receives the current decoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RD`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging decode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareDecoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("decode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchDecoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareDecoding(decode) {
@@ -1034,6 +1856,25 @@ export function middlewareDecoding(decode) {
   });
 }
 /**
+ * Intercepts the encoding pipeline of a schema.
+ *
+ * The provided function receives the current encoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RE`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging encode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareEncoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("encode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchEncoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareEncoding(encode) {
@@ -1042,24 +1883,50 @@ export function middlewareEncoding(encode) {
   });
 }
 /**
+ * Recovers from a decoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * **Example** (Returning a default on decode failure)
+ *
+ * ```ts
+ * import { Effect, Option, Schema } from "effect"
+ *
+ * const schema = Schema.Number.pipe(
+ *   Schema.catchDecoding((_issue) => Effect.succeed(Option.some(0)))
+ * )
+ * ```
+ *
+ * @see {@link catchDecodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchDecoding(f) {
   return catchDecodingWithContext(f);
 }
 /**
+ * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchDecodingWithContext(f) {
   return self => self.pipe(middlewareDecoding(Effect.catchEager(f)));
 }
 /**
+ * Recovers from an encoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * @see {@link catchEncodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchEncoding(f) {
   return catchEncodingWithContext(f);
 }
 /**
+ * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchEncodingWithContext(f) {
@@ -1121,6 +1988,25 @@ export function encodeTo(to, transformation) {
   };
 }
 /**
+ * Applies a transformation to a schema's encoded type, creating a new schema where encoding/decoding
+ * operate on `S["Encoded"]` rather than `S["Type"]`.
+ *
+ * The `decode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during decoding),
+ * and the `encode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during encoding).
+ *
+ * **Example** (Upper-casing encoded strings)
+ *
+ * ```ts
+ * import { Schema, SchemaGetter } from "effect"
+ *
+ * const UpperFromLower = Schema.String.pipe(
+ *   Schema.encode({
+ *     decode: SchemaGetter.transform((s: string) => s.toLowerCase()),
+ *     encode: SchemaGetter.transform((s: string) => s.toUpperCase())
+ *   })
+ * )
+ * ```
+ *
  * @since 4.0.0
  */
 export function encode(transformation) {
@@ -1129,22 +2015,66 @@ export function encode(transformation) {
   };
 }
 /**
+ * Attaches a constructor default value to a schema field.
+ *
+ * Constructor defaults are applied only during `make*`, not during decoding or
+ * encoding.
+ *
+ * **Example** (Optional field with a static default)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(
+ *     Schema.optionalKey,
+ *     Schema.withConstructorDefault(Effect.succeed("anonymous"))
+ *   )
+ * })
+ *
+ * const value = MySchema.make({})
+ * // value: { name: "anonymous" }
+ * ```
+ *
  * @since 4.0.0
  */
-export function withConstructorDefault(defaultValue) {
-  return schema => {
-    return make(AST.withConstructorDefault(schema.ast, defaultValue), {
-      schema
-    });
-  };
+export function withConstructorDefault(
+// `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
+// it makes easier to define the default value if there are nested defaults
+defaultValue) {
+  return schema => make(AST.withConstructorDefault(schema.ast, defaultValue), {
+    schema
+  });
 }
 /**
+ * Makes a struct key optional on the `Encoded` side and provides a default
+ * `Encoded` value when the key is missing during decoding.
+ *
+ * The key uses `optionalKey` on the encoded side, so it may be absent from the
+ * input object but **not** `undefined`. The default value is specified in terms
+ * of the `Encoded` type (before any decoding transformations).
+ *
  * **Options**
  *
- * - `encodingStrategy`: The strategy to use when encoding.
- *   - `passthrough`: (default) Pass the default value through to the output.
- *   - `omit`: Omit the value from the output.
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
+ *
+ * **Example** (Default for a missing struct key)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
  *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("anonymous")))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({})
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefault} for the value-level variant (key absent **or** `undefined`)
+ * @see {@link withDecodingDefaultTypeKey} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
 export function withDecodingDefaultKey(defaultValue, options) {
@@ -1157,12 +2087,58 @@ export function withDecodingDefaultKey(defaultValue, options) {
   };
 }
 /**
+ * Makes a struct key optional on the `Encoded` side (`optionalKey`, so the
+ * key may be absent but **not** `undefined`) and provides a default `Type`
+ * value when the key is missing during decoding.
+ *
+ * Unlike {@link withDecodingDefaultKey}, the default value is specified in
+ * terms of the `Type` (decoded) representation, so it does not need to go
+ * through the decoding transformation.
+ *
  * **Options**
  *
- * - `encodingStrategy`: The strategy to use when encoding.
- *   - `passthrough`: (default) Pass the default value through to the output.
- *   - `omit`: Omit the value from the output.
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
+ *
+ * @see {@link withDecodingDefaultKey} for the variant where the default is an `Encoded` value
+ * @see {@link withDecodingDefaultType} for the value-level variant
+ * @since 4.0.0
+ */
+export function withDecodingDefaultTypeKey(defaultValue, options) {
+  return self => {
+    return toType(self).pipe(withDecodingDefaultKey(defaultValue, options), encodeTo(optionalKey(self)));
+  };
+}
+/**
+ * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
+ * and provides a default `Encoded` value when the field is missing or
+ * `undefined` during decoding.
+ *
+ * The default value is specified in terms of the `Encoded` type (before any
+ * decoding transformations).
+ *
+ * **Options**
+ *
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
+ *
+ * **Example** (Default for an optional field value)
  *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.optional, Schema.withDecodingDefault(Effect.succeed("anonymous")))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({ name: undefined })
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefaultKey} for the key-level variant (key absent only, not `undefined`)
+ * @see {@link withDecodingDefaultType} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
 export function withDecodingDefault(defaultValue, options) {
@@ -1175,27 +2151,78 @@ export function withDecodingDefault(defaultValue, options) {
   };
 }
 /**
- * Creates a schema for a literal value and automatically provides itself as a
- * default.
+ * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
+ * and provides a default `Type` value when the field is missing or
+ * `undefined` during decoding.
+ *
+ * Unlike {@link withDecodingDefault}, the default value is specified in terms
+ * of the `Type` (decoded) representation, so it does not need to go through
+ * the decoding transformation.
+ *
+ * **Options**
+ *
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
+ *
+ * @see {@link withDecodingDefault} for the variant where the default is an `Encoded` value
+ * @see {@link withDecodingDefaultTypeKey} for the key-level variant
+ * @since 4.0.0
+ */
+export function withDecodingDefaultType(defaultValue, options) {
+  return self => {
+    return toType(self).pipe(withDecodingDefault(defaultValue, options), encodeTo(optional(self)));
+  };
+}
+/**
+ * Combines a {@link Literal} schema with {@link withConstructorDefault}, making it ideal
+ * for discriminator fields in tagged unions. When constructing via `make`, the
+ * `_tag` field can be omitted and will be filled automatically.
+ *
+ * **Example** (Discriminated union tag)
+ *
+ * ```ts
+ * import { Schema } from "effect"
  *
- * 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.
+ * const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
+ *
+ * // _tag is optional in make, auto-filled to "A"
+ * const a = A.make({ value: 42 })
+ * // a: { _tag: "A", value: 42 }
+ * ```
  *
+ * @see {@link tagDefaultOmit} to also omit the tag during encoding
+ * @see {@link TaggedStruct} for a shorthand that adds `_tag` automatically
  * @since 4.0.0
  */
 export function tag(literal) {
-  return Literal(literal).pipe(withConstructorDefault(() => Option_.some(literal)));
+  return Literal(literal).pipe(withConstructorDefault(Effect.succeed(literal)));
 }
 /**
- * Similar to `tag`, but provides itself as a default when decoding and omits
- * the value from the output when encoding.
+ * Like {@link tag}, but additionally omits the tag field from the encoded output.
+ * Useful when the encoded form (e.g. JSON) does not include the discriminator key,
+ * but the decoded type and constructor still need it.
+ *
+ * **Example** (Tag omitted during encoding)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.Struct({
+ *   _tag: Schema.tagDefaultOmit("A"),
+ *   value: Schema.Number
+ * })
+ *
+ * // Encode strips the _tag field
+ * const encoded = Schema.encodeUnknownSync(A)({ _tag: "A", value: 1 })
+ * // encoded: { value: 1 }
+ * ```
  *
+ * @see {@link tag} for the variant that keeps the tag during encoding
  * @since 4.0.0
  */
 export function tagDefaultOmit(literal) {
-  return tag(literal).pipe(withDecodingDefaultKey(() => literal, {
+  return tag(literal).pipe(withDecodingDefaultKey(Effect.succeed(literal), {
     encodingStrategy: "omit"
   }));
 }
@@ -1204,7 +2231,7 @@ export function tagDefaultOmit(literal) {
  * to identify the specific variant of the object, which is especially useful
  * when working with union types.
  *
- * When using the `makeUnsafe` method, the `_tag` field is optional and will be
+ * When using the `make` method, the `_tag` field is optional and will be
  * added automatically. However, when decoding or encoding, the `_tag` field
  * must be present in the input.
  *
@@ -1247,18 +2274,27 @@ export function TaggedStruct(value, fields) {
     ...fields
   });
 }
-/** @internal */
-export function _getTagValueIfPropertyKey(tag, ast) {
-  const ps = ast.propertySignatures.find(p => p.name === tag);
-  if (ps) {
-    if (AST.isLiteral(ps.type) && Predicate.isPropertyKey(ps.type.literal)) {
-      return ps.type.literal;
-    } else if (AST.isUniqueSymbol(ps.type)) {
-      return ps.type.symbol;
-    }
-  }
-}
 /**
+ * Augments an existing {@link Union} of tagged structs with utility methods keyed by the discriminant field.
+ *
+ * **Example** (Adding tagged-union utilities to an existing union)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.TaggedStruct("A", { value: Schema.Number })
+ * const B = Schema.TaggedStruct("B", { name: Schema.String })
+ *
+ * const MyUnion = Schema.Union([A, B]).pipe(Schema.toTaggedUnion("_tag"))
+ *
+ * // Pattern-match on the union
+ * const result = MyUnion.match({ _tag: "A", value: 1 }, {
+ *   A: (a) => `number: ${a.value}`,
+ *   B: (b) => `name: ${b.name}`
+ * })
+ * ```
+ *
+ * @see {@link TaggedUnion} for a shorthand that builds the union from scratch
  * @since 4.0.0
  * @experimental
  */
@@ -1279,15 +2315,16 @@ export function toTaggedUnion(tag) {
       if (AST.isUnion(ast) && "members" in schema && globalThis.Array.isArray(schema.members) && schema.members.every(isSchema)) {
         return schema.members.forEach(walk);
       }
-      if (AST.isObjects(ast)) {
-        const key = _getTagValueIfPropertyKey(tag, ast);
-        if (key !== undefined) {
-          cases[key] = schema;
-          guards[key] = is(toType(schema));
+      const sentinels = AST.collectSentinels(ast);
+      if (sentinels.length > 0) {
+        const literal = sentinels.find(s => s.key === tag)?.literal;
+        if (Predicate.isPropertyKey(literal)) {
+          cases[literal] = schema;
+          guards[literal] = is(toType(schema));
           return;
         }
       }
-      throw new globalThis.Error("No literal found");
+      throw new globalThis.Error("No literal or unique symbol found");
     }
     function match() {
       if (arguments.length === 1) {
@@ -1303,6 +2340,28 @@ export function toTaggedUnion(tag) {
   };
 }
 /**
+ * Builds a discriminated union from a record of field sets, one per variant.
+ * Each key becomes the `_tag` literal and the value is passed to {@link TaggedStruct}.
+ * The result includes `cases`, `guards`, `isAnyOf`, and `match` utilities.
+ *
+ * **Example** (Discriminated union with pattern matching)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Shape = Schema.TaggedUnion({
+ *   Circle: { radius: Schema.Number },
+ *   Rectangle: { width: Schema.Number, height: Schema.Number }
+ * })
+ *
+ * // Pattern-match on a decoded value
+ * const area = Shape.match({ _tag: "Circle", radius: 5 }, {
+ *   Circle: (c) => Math.PI * c.radius ** 2,
+ *   Rectangle: (r) => r.width * r.height
+ * })
+ * ```
+ *
+ * @see {@link toTaggedUnion} to augment an existing union instead
  * @category Constructors
  * @since 4.0.0
  */
@@ -1326,18 +2385,49 @@ export function TaggedUnion(casesByTag) {
   });
 }
 /**
+ * Wraps a struct schema so that its decoded `Type` becomes a nominally distinct type `Self`.
+ * Useful for creating opaque types that are structurally identical to a base struct
+ * but type-incompatible with it.
+ *
+ * **Example** (Opaque struct)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Person extends Schema.Opaque<Person>()(
+ *   Schema.Struct({
+ *     name: Schema.String
+ *   })
+ * ) {}
+ *
+ * // Decoded value is Person, not { name: string }
+ * const person = Schema.decodeUnknownSync(Person)({ name: "Alice" })
+ * // person: Person
+ * ```
+ *
  * @since 4.0.0
  */
 export function Opaque() {
   return schema => {
     // oxlint-disable-next-line @typescript-eslint/no-extraneous-class
     class Opaque {}
-    Object.setPrototypeOf(Opaque, schema);
-    return Opaque;
+    return Object.setPrototypeOf(Opaque, schema);
   };
 }
 /**
- * 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
@@ -1346,8 +2436,10 @@ export function instanceOf(constructor, annotations) {
   return declare(u => u instanceof constructor, annotations);
 }
 /**
+ * Constructs an `AST.Link` that describes how a value of type `T` encodes to and decodes from a `To` schema.
+ * Used when building low-level AST transformations that bridge two schema types.
+ *
  * @since 4.0.0
- * @experimental
  */
 export function link() {
   return (encodeTo, transformation) => {
@@ -1358,11 +2450,59 @@ export function link() {
 // Checks
 // -----------------------------------------------------------------------------
 /**
+ * Creates a custom filter check from a predicate function. The predicate
+ * receives the input value, the schema's AST, and parse options, and returns
+ * a value of type {@link FilterOutput}.
+ *
+ * **Example** (Failure at a nested path)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Struct({ password: Schema.String, confirmPassword: Schema.String }).check(
+ *   Schema.makeFilter((o) =>
+ *     o.password === o.confirmPassword
+ *       ? undefined
+ *       : { path: ["password"], issue: "password and confirmPassword must match" }
+ *   )
+ * )
+ *
+ * console.log(String(Schema.decodeUnknownExit(schema)({ password: "123456", confirmPassword: "1234567" })))
+ * // Failure(Cause([Fail(SchemaError: password and confirmPassword must match
+ * //   at ["password"])]))
+ * ```
+ *
+ * **Example** (Reporting multiple failures at once)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Struct({ a: Schema.Finite, b: Schema.Finite, c: Schema.Finite }).check(
+ *   Schema.makeFilter((o) => {
+ *     const issues: Array<Schema.FilterIssue> = []
+ *     if (o.a > 0) {
+ *       if (o.b <= 0) issues.push({ path: ["b"], issue: "b must be greater than 0" })
+ *       if (o.c <= 0) issues.push({ path: ["c"], issue: "c must be greater than 0" })
+ *     }
+ *     return issues
+ *   })
+ * )
+ *
+ * console.log(String(Schema.decodeUnknownExit(schema)({ a: 1, b: 0, c: 0 })))
+ * // Failure(Cause([Fail(SchemaError: b must be greater than 0
+ * //   at ["b"]
+ * // c must be greater than 0
+ * //   at ["c"])]))
+ * ```
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
 export const makeFilter = AST.makeFilter;
 /**
+ * Groups multiple checks into a single {@link AST.FilterGroup}, applying
+ * optional shared annotations to the group as a whole.
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
@@ -1850,6 +2990,9 @@ export function isFinite(annotations) {
   });
 }
 /**
+ * Generic factory for creating a "greater than" (`>`) check for any ordered
+ * type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1865,6 +3008,9 @@ export function makeIsGreaterThan(options) {
   };
 }
 /**
+ * Generic factory for creating a ">=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1880,6 +3026,9 @@ export function makeIsGreaterThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating a "<" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1895,6 +3044,9 @@ export function makeIsLessThan(options) {
   };
 }
 /**
+ * Generic factory for creating a "<=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1910,6 +3062,9 @@ export function makeIsLessThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating an inclusive/exclusive range check for any
+ * ordered type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1930,6 +3085,9 @@ export function makeIsBetween(deriveOptions) {
   };
 }
 /**
+ * Generic factory for creating a divisibility check for any numeric type by
+ * supplying a remainder function and a zero value.
+ *
  * @category Numeric checks
  * @since 4.0.0
  */
@@ -2598,6 +3756,14 @@ export const isBetweenBigDecimal = /*#__PURE__*/makeIsBetween({
  * constraint to ensure generated strings or arrays have at least the required
  * length.
  *
+ * **Example** (Minimum length check)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NonEmptyStringSchema = Schema.String.check(Schema.isMinLength(1))
+ * const NonEmptyArraySchema = Schema.Array(Schema.Number).check(Schema.isMinLength(1))
+ * ```
+ *
  * @category Length checks
  * @since 4.0.0
  */
@@ -2990,6 +4156,7 @@ export function isPropertyNames(keySchema, annotations) {
  * constraint using the provided equivalence function to ensure generated arrays
  * contain only unique items.
  *
+ * @category Array checks
  * @since 4.0.0
  */
 export function isUnique(annotations) {
@@ -3007,23 +4174,24 @@ export function isUnique(annotations) {
     ...annotations
   });
 }
-// -----------------------------------------------------------------------------
-// Built-in Schemas
-// -----------------------------------------------------------------------------
 /**
  * A schema for non-empty strings. Validates that a string has at least one
  * character.
  *
+ * @category String
  * @since 4.0.0
  */
 export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty());
 /**
  * A schema representing a single character.
  *
+ * @category String
  * @since 4.0.0
  */
 export const Char = /*#__PURE__*/String.check(/*#__PURE__*/isLengthBetween(1, 1));
 /**
+ * Creates a schema for `Option<A>`. See {@link Option} for details.
+ *
  * @category Option
  * @since 4.0.0
  */
@@ -3096,6 +4264,40 @@ export function Option(value) {
 export function OptionFromNullOr(schema) {
   return NullOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullOr()));
 }
+/**
+ * Decodes an undefined-or value `T` to a required `Option<T>` value.
+ *
+ * Decoding:
+ * - `undefined` is decoded as `None`
+ * - other values are decoded as `Some`
+ *
+ * Encoding:
+ * - `None` is encoded as `undefined`
+ * - `Some` is encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromUndefinedOr(schema) {
+  return UndefinedOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromUndefinedOr()));
+}
+/**
+ * Decodes a nullish value `T` to a required `Option<T>` value.
+ *
+ * Decoding:
+ * - `null` and `undefined` are decoded as `None`
+ * - other values are decoded as `Some`
+ *
+ * Encoding:
+ * - `None` is encoded as `null` or `undefined` depending on the provided `options.onNoneEncoding` (defaults to `undefined`)
+ * - `Some` is encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromNullishOr(schema, options) {
+  return NullishOr(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromNullishOr(options)));
+}
 /**
  * Decodes an optional value `A` to a required `Option<A>` value.
  *
@@ -3133,6 +4335,35 @@ export function OptionFromOptional(schema) {
   return optional(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromOptional()));
 }
 /**
+ * Decodes an optional or `null` or `undefined` value `A` to a required `Option<A>`
+ * value.
+ *
+ * Decoding:
+ * - a missing key is decoded as `None`
+ * - a present key with an `undefined` value is decoded as `None`
+ * - a present key with a `null` value is decoded as `None`
+ * - all other values are decoded as `Some`
+ *
+ * Encoding (controlled by `options.onNoneEncoding`):
+ * - `"omit"` (default): `None` is encoded as a missing key
+ * - `null`: `None` is encoded as `null`
+ * - `undefined`: `None` is encoded as `undefined`
+ * - `Some` is always encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromOptionalNullOr(schema, options) {
+  const onNoneEncoding = options === undefined ? "omit" : options.onNoneEncoding;
+  const noneValue = onNoneEncoding === null ? null : undefined;
+  return optional(NullOr(schema)).pipe(decodeTo(Option(toType(schema)), Transformation.transformOptional({
+    decode: oe => oe.pipe(Option_.filter(Predicate.isNotNullish), Option_.some),
+    encode: onNoneEncoding === "omit" ? Option_.flatten : ot => Option_.some(Option_.getOrElse(Option_.flatten(ot), () => noneValue))
+  })));
+}
+/**
+ * Creates a schema for `Result<A, E>`. See {@link Result} for details.
+ *
  * @category Result
  * @since 4.0.0
  */
@@ -3261,6 +4492,9 @@ export function Redacted(value, options) {
   });
 }
 /**
+ * Middleware that wraps decoded errors in `Redacted`, preventing sensitive
+ * schema details from leaking in error messages.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3268,6 +4502,10 @@ export function redact(schema) {
   return schema.pipe(middlewareDecoding(Effect.mapErrorEager(Issue.redact)));
 }
 /**
+ * Decodes a value and wraps it in `Redacted<A>`. Unlike {@link Redacted} which
+ * expects the input to already be a `Redacted` instance, this schema decodes
+ * the raw value and wraps it.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3280,6 +4518,8 @@ export function RedactedFromValue(value, options) {
   }));
 }
 /**
+ * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -3379,12 +4619,14 @@ function causeReasonToFormatter(error, defect) {
   };
 }
 /**
+ * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ *
  * @category Cause
  * @since 4.0.0
  */
 export function Cause(error, defect) {
   const schema = declareConstructor()([error, defect], ([error, defect]) => {
-    const failures = Array(CauseReason(error, defect));
+    const failures = ArraySchema(CauseReason(error, defect));
     return (input, ast, options) => {
       if (!Cause_.isCause(input)) {
         return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
@@ -3404,7 +4646,7 @@ export function Cause(error, defect) {
       importDeclaration: `import * as Cause from "effect/Cause"`
     },
     expected: "Cause",
-    toCodec: ([error, defect]) => link()(Array(CauseReason(error, defect)), Transformation.transform({
+    toCodec: ([error, defect]) => link()(ArraySchema(CauseReason(error, defect)), Transformation.transform({
       decode: Cause_.fromReasons,
       encode: ({
         reasons: failures
@@ -3502,7 +4744,7 @@ export const Defect = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#
  * A schema that represents defects, that also includes stack traces in the
  * encoded form.
  *
- * @category Constructors
+ * @category Defect
  * @since 4.0.0
  */
 export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#__PURE__*/decodeTo(ErrorWithStack, /*#__PURE__*/Transformation.errorFromErrorJsonEncoded({
@@ -3512,6 +4754,8 @@ export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
+ * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ *
  * @category Exit
  * @since 4.0.0
  */
@@ -3604,7 +4848,7 @@ export function Exit(value, error, defect) {
  */
 export function ReadonlyMap(key, value) {
   const schema = declareConstructor()([key, value], ([key, value]) => {
-    const array = Array(Tuple([key, value]));
+    const array = ArraySchema(Tuple([key, value]));
     return (input, ast, options) => {
       if (input instanceof globalThis.Map) {
         return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
@@ -3623,7 +4867,7 @@ export function ReadonlyMap(key, value) {
       Type: `globalThis.ReadonlyMap<?, ?>`
     },
     expected: "ReadonlyMap",
-    toCodec: ([key, value]) => link()(Array(Tuple([key, value])), Transformation.transform({
+    toCodec: ([key, value]) => link()(ArraySchema(Tuple([key, value])), Transformation.transform({
       decode: e => new globalThis.Map(e),
       encode: map => [...map.entries()]
     })),
@@ -3657,7 +4901,7 @@ export function ReadonlyMap(key, value) {
  */
 export function HashMap(key, value) {
   const schema = declareConstructor()([key, value], ([key, value]) => {
-    const entries = Array(Tuple([key, value]));
+    const entries = ArraySchema(Tuple([key, value]));
     return (input, ast, options) => {
       if (HashMap_.isHashMap(input)) {
         return Effect.mapBothEager(Parser.decodeUnknownEffect(entries)(HashMap_.toEntries(input), options), {
@@ -3677,7 +4921,7 @@ export function HashMap(key, value) {
       importDeclaration: `import * as HashMap from "effect/HashMap"`
     },
     expected: "HashMap",
-    toCodec: ([key, value]) => link()(Array(Tuple([key, value])), Transformation.transform({
+    toCodec: ([key, value]) => link()(ArraySchema(Tuple([key, value])), Transformation.transform({
       decode: HashMap_.fromIterable,
       encode: HashMap_.toEntries
     })),
@@ -3708,7 +4952,7 @@ export function HashMap(key, value) {
  */
 export function ReadonlySet(value) {
   const schema = declareConstructor()([value], ([value]) => {
-    const array = Array(value);
+    const array = ArraySchema(value);
     return (input, ast, options) => {
       if (input instanceof globalThis.Set) {
         return Effect.mapBothEager(Parser.decodeUnknownEffect(array)([...input], options), {
@@ -3727,7 +4971,7 @@ export function ReadonlySet(value) {
       Type: `globalThis.ReadonlySet<?>`
     },
     expected: "ReadonlySet",
-    toCodec: ([value]) => link()(Array(value), Transformation.transform({
+    toCodec: ([value]) => link()(ArraySchema(value), Transformation.transform({
       decode: e => new globalThis.Set(e),
       encode: set => [...set.values()]
     })),
@@ -3760,7 +5004,7 @@ export function ReadonlySet(value) {
  */
 export function HashSet(value) {
   const schema = declareConstructor()([value], ([value]) => {
-    const values = Array(value);
+    const values = ArraySchema(value);
     return (input, ast, options) => {
       if (HashSet_.isHashSet(input)) {
         return Effect.mapBothEager(Parser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
@@ -3772,14 +5016,14 @@ export function HashSet(value) {
     };
   }, {
     typeConstructor: {
-      _tag: "HashSet"
+      _tag: "effect/HashSet"
     },
     generation: {
       runtime: `Schema.HashSet(?)`,
       Type: `HashSet.HashSet<?>`
     },
     expected: "HashSet",
-    toCodec: ([value]) => link()(Array(value), Transformation.transform({
+    toCodec: ([value]) => link()(ArraySchema(value), Transformation.transform({
       decode: HashSet_.fromIterable,
       encode: Arr.fromIterable
     })),
@@ -3804,6 +5048,63 @@ export function HashSet(value) {
   });
 }
 /**
+ * Creates a schema that validates a `Chunk` where values must conform to the
+ * provided schema.
+ *
+ * @category Chunk
+ * @since 4.0.0
+ */
+export function Chunk(value) {
+  const schema = declareConstructor()([value], ([value]) => {
+    const values = ArraySchema(value);
+    return (input, ast, options) => {
+      if (Chunk_.isChunk(input)) {
+        return Effect.mapBothEager(Parser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
+          onSuccess: Chunk_.fromIterable,
+          onFailure: issue => new Issue.Composite(ast, Option_.some(input), [new Issue.Pointer(["values"], issue)])
+        });
+      }
+      return Effect.fail(new Issue.InvalidType(ast, Option_.some(input)));
+    };
+  }, {
+    typeConstructor: {
+      _tag: "effect/Chunk"
+    },
+    generation: {
+      runtime: `Schema.Chunk(?)`,
+      Type: `Chunk.Chunk<?>`
+    },
+    expected: "Chunk",
+    toCodec: ([value]) => link()(ArraySchema(value), Transformation.transform({
+      decode: Chunk_.fromIterable,
+      encode: Arr.fromIterable
+    })),
+    toArbitrary: ([value]) => (fc, ctx) => {
+      return fc.oneof(ctx?.isSuspend ? {
+        maxDepth: 2,
+        depthIdentifier: "Chunk"
+      } : {}, fc.constant([]), fc.array(value, ctx?.constraints?.array)).map(Chunk_.fromIterable);
+    },
+    toEquivalence: ([value]) => Chunk_.makeEquivalence(value),
+    toFormatter: ([value]) => t => {
+      const size = Chunk_.size(t);
+      if (size === 0) {
+        return "Chunk(0) {}";
+      }
+      const values = globalThis.Array.from(t).sort().map(v => `${value(v)}`);
+      return `Chunk(${size}) { ${values.join(", ")} }`;
+    }
+  });
+  return make(schema.ast, {
+    value
+  });
+}
+/**
+ * Schema for JavaScript `RegExp` objects.
+ *
+ * The default JSON serializer encodes a `RegExp` as `{ source, flags }`.
+ *
+ * @category RegExp
  * @since 4.0.0
  */
 export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
@@ -3837,6 +5138,9 @@ export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
   }).map(flags => flags.join(""))).map(([source, flags]) => new globalThis.RegExp(source, flags)),
   toEquivalence: () => (a, b) => a.source === b.source && a.flags === b.flags
 });
+const URLString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a URL"
+});
 /**
  * A schema for JavaScript `URL` objects.
  *
@@ -3856,9 +5160,7 @@ export const URL = /*#__PURE__*/instanceOf(globalThis.URL, {
     Type: `globalThis.URL`
   },
   expected: "URL",
-  toCodecJson: () => link()(String.annotate({
-    expected: "a string that will be decoded as a URL"
-  }), Transformation.urlFromString),
+  toCodecJson: () => link()(URLString, Transformation.urlFromString),
   toArbitrary: () => fc => fc.webUrl().map(s => new globalThis.URL(s)),
   toEquivalence: () => (a, b) => a.toString() === b.toString()
 });
@@ -3874,15 +5176,27 @@ export const URL = /*#__PURE__*/instanceOf(globalThis.URL, {
  * @category URL
  * @since 4.0.0
  */
-export const URLFromString = /*#__PURE__*/String.annotate({
-  expected: "a string that will be decoded as a URL"
-}).pipe(/*#__PURE__*/decodeTo(URL, Transformation.urlFromString)); // TODO: remove duplication with URL schema
+export const URLFromString = /*#__PURE__*/URLString.pipe(/*#__PURE__*/decodeTo(URL, Transformation.urlFromString));
+const DateString = /*#__PURE__*/String.annotate({
+  expected: "a string in ISO 8601 format that will be decoded as a 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 Date
  * @since 4.0.0
  */
 export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
@@ -3894,29 +5208,49 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
     Type: `globalThis.Date`
   },
   expected: "Date",
-  toCodecJson: () => link()(String.annotate({
-    expected: "a string in ISO 8601 format that will be decoded as a Date"
-  }), Transformation.transform({
-    decode: s => new globalThis.Date(s),
-    encode: formatDate
-  })),
+  toCodecJson: () => link()(DateString, Transformation.dateFromString),
   toArbitrary: () => (fc, ctx) => fc.date(ctx?.constraints?.date)
 });
+/**
+ * A transformation schema that parses an ISO 8601 string into a `Date`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `Date`.
+ *
+ * Encoding:
+ * - A `Date` is encoded as a `string`.
+ *
+ * @category Date
+ * @since 4.0.0
+ */
+export const DateFromString = /*#__PURE__*/DateString.pipe(/*#__PURE__*/decodeTo(Date, Transformation.dateFromString));
 /**
  * A schema for **valid** JavaScript `Date` objects.
  *
  * This schema accepts `Date` instances but rejects invalid dates (such as `new
  * Date("invalid")`).
  *
+ * @category Date
  * @since 4.0.0
  */
 export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
 /**
  * A schema for `Duration` values.
  *
- * **Default JSON serializer**
+ * The default JSON serializer encodes `Duration` as a tagged object with the
+ * duration type and value.
+ *
+ * **Example** (Duration schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Duration } from "effect"
+ *
+ * Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(5))
+ * // => Duration(5s)
+ * ```
  *
- * - encodes `Duration` as a `string`
+ * @category Duration
  *
  * @since 4.0.0
  */
@@ -3980,6 +5314,24 @@ export const Duration = /*#__PURE__*/declare(Duration_.isDuration, {
   toFormatter: () => globalThis.String,
   toEquivalence: () => Duration_.Equivalence
 });
+const DurationString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a Duration"
+});
+/**
+ * A transformation schema that parses a string into a `Duration`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `Duration`, accepting any format that
+ *   `Duration.fromInput` can parse.
+ *
+ * Encoding:
+ * - A `Duration` is encoded as a parseable `string`.
+ *
+ * @category Duration
+ * @since 4.0.0
+ */
+export const DurationFromString = /*#__PURE__*/DurationString.pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromString));
+const bigint0 = /*#__PURE__*/globalThis.BigInt(0);
 /**
  * A transformation schema that decodes a non-negative `bigint` into a
  * `Duration`, treating the `bigint` value as the duration in nanoseconds.
@@ -3993,7 +5345,7 @@ export const Duration = /*#__PURE__*/declare(Duration_.isDuration, {
  * @category Duration
  * @since 4.0.0
  */
-export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualToBigInt(0n)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromNanos));
+export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualToBigInt(bigint0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromNanos));
 /**
  * A transformation schema that decodes a non-negative (possibly infinite)
  * integer into a `Duration`, treating the integer value as the duration in
@@ -4011,6 +5363,9 @@ export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualT
  * @since 4.0.0
  */
 export const DurationFromMillis = /*#__PURE__*/Number.check(isGreaterThanOrEqualTo(0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromMillis));
+const BigDecimalString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a BigDecimal"
+});
 /**
  * A schema for `BigDecimal` values.
  *
@@ -4018,6 +5373,7 @@ export const DurationFromMillis = /*#__PURE__*/Number.check(isGreaterThanOrEqual
  *
  * - encodes `BigDecimal` as a `string`
  *
+ * @category BigDecimal
  * @since 4.0.0
  */
 export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
@@ -4030,9 +5386,7 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
     importDeclaration: `import * as BigDecimal from "effect/BigDecimal"`
   },
   expected: "BigDecimal",
-  toCodecJson: () => link()(String.annotate({
-    expected: "a string that will be decoded as a BigDecimal"
-  }), Transformation.bigDecimalFromString),
+  toCodecJson: () => link()(BigDecimalString, Transformation.bigDecimalFromString),
   toArbitrary: () => fc => fc.tuple(fc.bigInt(), fc.integer({
     min: 0,
     max: 20
@@ -4040,6 +5394,19 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
   toFormatter: () => bd => BigDecimal_.format(bd),
   toEquivalence: () => BigDecimal_.Equivalence
 });
+/**
+ * A transformation schema that parses a string into a `BigDecimal`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `BigDecimal`.
+ *
+ * Encoding:
+ * - A `BigDecimal` is encoded as a `string`.
+ *
+ * @category BigDecimal
+ * @since 4.0.0
+ */
+export const BigDecimalFromString = /*#__PURE__*/BigDecimalString.pipe(/*#__PURE__*/decodeTo(BigDecimal, Transformation.bigDecimalFromString));
 /**
  * A transformation schema that decodes a JSON-encoded string into an `unknown` value.
  *
@@ -4060,6 +5427,7 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
  * // => { a: 1, b: 2 }
  * ```
  *
+ * @category JSON
  * @since 4.0.0
  */
 export const UnknownFromJsonString = /*#__PURE__*/fromJsonString(Unknown);
@@ -4124,6 +5492,7 @@ export const UnknownFromJsonString = /*#__PURE__*/fromJsonString(Unknown);
  * // }
  * ```
  *
+ * @category JSON
  * @since 4.0.0
  */
 export function fromJsonString(schema) {
@@ -4134,6 +5503,12 @@ export function fromJsonString(schema) {
   }).pipe(decodeTo(schema, Transformation.fromJsonString));
 }
 /**
+ * Schema for JavaScript `File` objects.
+ *
+ * The default JSON serializer encodes a `File` as `{ data, type, name, lastModified }`
+ * where `data` is base64-encoded.
+ *
+ * @category File
  * @since 4.0.0
  */
 export const File = /*#__PURE__*/instanceOf(globalThis.File, {
@@ -4180,6 +5555,12 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
   }))
 });
 /**
+ * Schema for JavaScript `FormData` objects.
+ *
+ * The default JSON serializer encodes a `FormData` as an array of `[key, entry]`
+ * pairs where each entry is tagged as `"String"` or `"File"`.
+ *
+ * @category FormData
  * @since 4.0.0
  */
 export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
@@ -4191,7 +5572,7 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
     Type: `globalThis.FormData`
   },
   expected: "FormData",
-  toCodecJson: () => link()(Array(Tuple([String, Union([Struct({
+  toCodecJson: () => link()(ArraySchema(Tuple([String, Union([Struct({
     _tag: tag("String"),
     value: String
   }), Struct({
@@ -4309,6 +5690,11 @@ export function fromFormData(schema) {
   return FormData.pipe(decodeTo(schema, Transformation.fromFormData));
 }
 /**
+ * Schema for JavaScript `URLSearchParams` objects.
+ *
+ * The default JSON serializer encodes a `URLSearchParams` as a query string.
+ *
+ * @category URLSearchParams
  * @since 4.0.0
  */
 export const URLSearchParams = /*#__PURE__*/instanceOf(globalThis.URLSearchParams, {
@@ -4407,75 +5793,177 @@ export function fromURLSearchParams(schema) {
 /**
  * A schema for finite numbers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
+ * @category Number
  * @since 4.0.0
  */
 export const Finite = /*#__PURE__*/Number.check(/*#__PURE__*/isFinite());
 /**
  * A schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
+ * @category Number
  * @since 4.0.0
  */
 export const Int = /*#__PURE__*/Number.check(/*#__PURE__*/isInt());
 /**
- * A transformation schema that parses a string into a number.
+ * A transformation schema that parses a string into a number.
+ *
+ * Decoding:
+ * - A `string` is decoded as a finite number.
+ *
+ * Encoding:
+ * - A number is encoded as a `string`.
+ *
+ * @category Number
+ * @since 4.0.0
+ */
+export const NumberFromString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a number"
+}).pipe(/*#__PURE__*/decodeTo(Number, Transformation.numberFromString));
+/**
+ * A transformation schema that parses a string into a finite number.
+ *
+ * Decoding:
+ * - A `string` is decoded as a finite number, rejecting `NaN`, `Infinity`, and
+ *   `-Infinity` values.
+ *
+ * Encoding:
+ * - A finite number is encoded as a `string`.
+ *
+ * @category Number
+ * @since 4.0.0
+ */
+export const FiniteFromString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a finite number"
+}).pipe(/*#__PURE__*/decodeTo(Finite, Transformation.numberFromString));
+/**
+ * A transformation schema that parses a string into a `bigint`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `bigint`.
+ *
+ * Encoding:
+ * - A `bigint` is encoded as a `string`.
+ *
+ * @category BigInt
+ * @since 4.0.0
+ */
+export const BigIntFromString = /*#__PURE__*/make(AST.bigIntString).pipe(/*#__PURE__*/decodeTo(BigInt, Transformation.bigintFromString));
+/**
+ * A schema for strings that contains no leading or trailing whitespaces.
+ *
+ * @category String
+ * @since 4.0.0
+ */
+export const Trimmed = /*#__PURE__*/String.check(/*#__PURE__*/isTrimmed());
+/**
+ * A transformation schema that trims whitespace from a string.
+ *
+ * Decoding:
+ * - A `string` is decoded as a string with no leading or trailing whitespaces.
+ *
+ * Encoding:
+ * - The trimmed string is encoded as is.
+ *
+ * @category String
+ * @since 4.0.0
+ */
+export const Trim = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a trimmed string"
+}).pipe(/*#__PURE__*/decodeTo(Trimmed, /*#__PURE__*/Transformation.trim()));
+/**
+ * Decodes a base64 (RFC4648) encoded string into a UTF-8 string.
  *
  * Decoding:
- * - A `string` is decoded as a finite number.
+ * - A **valid** base64 encoded string is decoded as a UTF-8 `string`.
  *
  * Encoding:
- * - A number is encoded as a `string`.
+ * - A `string` is encoded as a base64-encoded string.
  *
+ * @category String
  * @since 4.0.0
  */
-export const NumberFromString = /*#__PURE__*/String.annotate({
-  expected: "a string that will be decoded as a number"
-}).pipe(/*#__PURE__*/decodeTo(Number, Transformation.numberFromString));
+export const StringFromBase64 = /*#__PURE__*/String.annotate({
+  expected: "a base64 encoded string that will be decoded as a UTF-8 string"
+}).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromBase64String));
 /**
- * A transformation schema that parses a string into a finite number.
+ * Decodes a base64 (URL) encoded string into a UTF-8 string.
  *
  * Decoding:
- * - A `string` is decoded as a finite number, rejecting `NaN`, `Infinity`, and
- *   `-Infinity` values.
+ * - A **valid** base64 (URL) encoded string is decoded as a UTF-8 `string`.
  *
  * Encoding:
- * - A finite number is encoded as a `string`.
+ * - A `string` is encoded as a base64 (URL) encoded string.
  *
+ * @category String
  * @since 4.0.0
  */
-export const FiniteFromString = /*#__PURE__*/String.annotate({
-  expected: "a string that will be decoded as a finite number"
-}).pipe(/*#__PURE__*/decodeTo(Finite, Transformation.numberFromString));
+export const StringFromBase64Url = /*#__PURE__*/String.annotate({
+  expected: "a base64 (URL) encoded string that will be decoded as a UTF-8 string"
+}).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromBase64UrlString));
 /**
- * A schema for strings that contains no leading or trailing whitespaces.
+ * Decodes a hex encoded string into a UTF-8 string.
  *
+ * Decoding:
+ * - A **valid** hex encoded string is decoded as a UTF-8 `string`.
+ *
+ * Encoding:
+ * - A `string` is encoded as a hex string.
+ *
+ * @category String
  * @since 4.0.0
  */
-export const Trimmed = /*#__PURE__*/String.check(/*#__PURE__*/isTrimmed());
+export const StringFromHex = /*#__PURE__*/String.annotate({
+  expected: "a hex encoded string that will be decoded as a UTF-8 string"
+}).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromHexString));
 /**
- * A transformation schema that trims whitespace from a string.
+ * Decodes a URI component encoded string into a UTF-8 string.
+ * Can be used to store data in a URL.
  *
  * Decoding:
- * - A `string` is decoded as a string with no leading or trailing whitespaces.
+ * - A **valid** URI component encoded string is decoded as a UTF-8 `string`.
  *
  * Encoding:
- * - The trimmed string is encoded as is.
+ * - A `string` is encoded as a URI component encoded string.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const PaginationSchema = Schema.Struct({
+ *   maxItemPerPage: Schema.Number,
+ *   page: Schema.Number
+ * })
+ *
+ * const UrlSchema = Schema.StringFromUriComponent.pipe(
+ *   Schema.decodeTo(Schema.fromJsonString(PaginationSchema))
+ * )
+ *
+ * console.log(Schema.encodeSync(UrlSchema)({ maxItemPerPage: 10, page: 1 }))
+ * // %7B%22maxItemPerPage%22%3A10%2C%22page%22%3A1%7D
+ * ```
  *
+ * @category String
  * @since 4.0.0
  */
-export const Trim = /*#__PURE__*/String.annotate({
-  expected: "a string that will be decoded as a trimmed string"
-}).pipe(/*#__PURE__*/decodeTo(Trimmed, /*#__PURE__*/Transformation.trim()));
+export const StringFromUriComponent = /*#__PURE__*/String.annotate({
+  expected: "a URI component encoded string that will be decoded as a UTF-8 string"
+}).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromUriComponent));
 /**
+ * A union schema for JavaScript property keys: `number | symbol | string`.
+ *
+ * @category PropertyKey
  * @since 4.0.0
  */
 export const PropertyKey = /*#__PURE__*/Union([Finite, Symbol, String]);
 /**
+ * @category StandardSchema
  * @since 4.0.0
  */
 export const StandardSchemaV1FailureResult = /*#__PURE__*/Struct({
-  issues: /*#__PURE__*/Array(/*#__PURE__*/Struct({
+  issues: /*#__PURE__*/ArraySchema(/*#__PURE__*/Struct({
     message: String,
-    path: /*#__PURE__*/optional(/*#__PURE__*/Array(/*#__PURE__*/Union([PropertyKey, /*#__PURE__*/Struct({
+    path: /*#__PURE__*/optional(/*#__PURE__*/ArraySchema(/*#__PURE__*/Union([PropertyKey, /*#__PURE__*/Struct({
       key: PropertyKey
     })])))
   }))
@@ -4581,7 +6069,7 @@ export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
  */
 export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isUtc(u), {
   typeConstructor: {
-    _tag: "DateTime.Utc"
+    _tag: "effect/DateTime.Utc"
   },
   generation: {
     runtime: `Schema.DateTimeUtc`,
@@ -4658,7 +6146,7 @@ export const DateTimeUtcFromMillis = /*#__PURE__*/Number.pipe(/*#__PURE__*/decod
  */
 export const TimeZoneOffset = /*#__PURE__*/declare(DateTime.isTimeZoneOffset, {
   typeConstructor: {
-    _tag: "DateTime.TimeZone.Offset"
+    _tag: "effect/DateTime.TimeZone.Offset"
   },
   generation: {
     runtime: `Schema.TimeZoneOffset`,
@@ -4674,6 +6162,9 @@ export const TimeZoneOffset = /*#__PURE__*/declare(DateTime.isTimeZoneOffset, {
   toFormatter: () => tz => DateTime.zoneToString(tz),
   toEquivalence: () => (a, b) => a.offset === b.offset
 });
+const TimeZoneNamedString = /*#__PURE__*/String.annotate({
+  expected: "an IANA time zone identifier"
+});
 /**
  * A schema for `DateTime.TimeZone.Named` values.
  *
@@ -4686,7 +6177,7 @@ export const TimeZoneOffset = /*#__PURE__*/declare(DateTime.isTimeZoneOffset, {
  */
 export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
   typeConstructor: {
-    _tag: "DateTime.TimeZone.Named"
+    _tag: "effect/DateTime.TimeZone.Named"
   },
   generation: {
     runtime: `Schema.TimeZoneNamed`,
@@ -4694,13 +6185,27 @@ export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
     importDeclaration: `import * as DateTime from "effect/DateTime"`
   },
   expected: "DateTime.TimeZone.Named",
-  toCodecJson: () => link()(String.annotate({
-    expected: "an IANA time zone identifier"
-  }), Transformation.timeZoneNamedFromString),
+  toCodecJson: () => link()(TimeZoneNamedString, Transformation.timeZoneNamedFromString),
   toArbitrary: () => fc => fc.constantFrom(...["UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney"].map(DateTime.zoneMakeNamedUnsafe)),
   toFormatter: () => tz => DateTime.zoneToString(tz),
   toEquivalence: () => (a, b) => a.id === b.id
 });
+/**
+ * A transformation schema that parses an IANA time zone identifier string into a `DateTime.TimeZone.Named`.
+ *
+ * Decoding:
+ * - A `string` is decoded as a `DateTime.TimeZone.Named`.
+ *
+ * Encoding:
+ * - A `DateTime.TimeZone.Named` is encoded as a `string`.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const TimeZoneNamedFromString = /*#__PURE__*/TimeZoneNamedString.pipe(/*#__PURE__*/decodeTo(TimeZoneNamed, Transformation.timeZoneNamedFromString));
+const TimeZoneString = /*#__PURE__*/String.annotate({
+  expected: "a time zone string (IANA identifier or offset like +03:00)"
+});
 /**
  * A schema for `DateTime.TimeZone` values.
  *
@@ -4714,7 +6219,7 @@ export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
  */
 export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
   typeConstructor: {
-    _tag: "DateTime.TimeZone"
+    _tag: "effect/DateTime.TimeZone"
   },
   generation: {
     runtime: `Schema.TimeZone`,
@@ -4722,9 +6227,7 @@ export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
     importDeclaration: `import * as DateTime from "effect/DateTime"`
   },
   expected: "DateTime.TimeZone",
-  toCodecJson: () => link()(String.annotate({
-    expected: "a time zone string (IANA identifier or offset like +03:00)"
-  }), Transformation.timeZoneFromString),
+  toCodecJson: () => link()(TimeZoneString, Transformation.timeZoneFromString),
   toArbitrary: () => fc => fc.oneof(fc.integer({
     min: -12 * 60 * 60 * 1000,
     max: 14 * 60 * 60 * 1000
@@ -4732,6 +6235,22 @@ export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
   toFormatter: () => tz => DateTime.zoneToString(tz),
   toEquivalence: () => (a, b) => DateTime.zoneToString(a) === DateTime.zoneToString(b)
 });
+/**
+ * A transformation schema that parses a time zone string into a `DateTime.TimeZone`.
+ *
+ * Decoding:
+ * - A `string` (IANA identifier or offset like `+03:00`) is decoded as a `DateTime.TimeZone`.
+ *
+ * Encoding:
+ * - A `DateTime.TimeZone` is encoded as a `string`.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const TimeZoneFromString = /*#__PURE__*/TimeZoneString.pipe(/*#__PURE__*/decodeTo(TimeZone, Transformation.timeZoneFromString));
+const DateTimeZonedString = /*#__PURE__*/String.annotate({
+  expected: "a zoned DateTime string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London])"
+});
 /**
  * A schema for `DateTime.Zoned` values.
  *
@@ -4745,7 +6264,7 @@ export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
  */
 export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && DateTime.isZoned(u), {
   typeConstructor: {
-    _tag: "DateTime.Zoned"
+    _tag: "effect/DateTime.Zoned"
   },
   generation: {
     runtime: `Schema.DateTimeZoned`,
@@ -4753,9 +6272,7 @@ export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) &&
     importDeclaration: `import * as DateTime from "effect/DateTime"`
   },
   expected: "DateTime.Zoned",
-  toCodecJson: () => link()(String.annotate({
-    expected: "a zoned DateTime string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London])"
-  }), Transformation.dateTimeZonedFromString),
+  toCodecJson: () => link()(DateTimeZonedString, Transformation.dateTimeZonedFromString),
   toArbitrary: () => (fc, ctx) => fc.tuple(fc.date({
     noInvalidDate: true,
     min: new globalThis.Date(-8640000000000000 + 14 * 60 * 60 * 1000),
@@ -4767,30 +6284,34 @@ export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) &&
   toFormatter: () => zoned => DateTime.formatIsoZoned(zoned),
   toEquivalence: () => DateTime.Equivalence
 });
+/**
+ * A transformation schema that parses a zoned DateTime string into a `DateTime.Zoned`.
+ *
+ * Decoding:
+ * - A `string` (e.g. `2024-01-01T00:00:00.000+00:00[Europe/London]`) is decoded as a `DateTime.Zoned`.
+ *
+ * Encoding:
+ * - A `DateTime.Zoned` is encoded as a `string`.
+ *
+ * @category DateTime
+ * @since 4.0.0
+ */
+export const DateTimeZonedFromString = /*#__PURE__*/DateTimeZonedString.pipe(/*#__PURE__*/decodeTo(DateTimeZoned, Transformation.dateTimeZonedFromString));
 const immerable = /*#__PURE__*/globalThis.Symbol.for("immer-draftable");
-function makeClass(Inherited, identifier, struct, annotations) {
+function makeClass(Inherited, identifier, struct, annotations, proto) {
   const getClassSchema = getClassSchemaFactory(struct, identifier, annotations);
   const ClassTypeId = getClassTypeId(identifier); // HMR support
-  return class extends Inherited {
+  const out = class extends Inherited {
     constructor(...[input, options]) {
-      const props = input ?? {};
-      if (options?.disableValidation) {
-        super(props, options);
-      } else {
-        const validated = struct.makeUnsafe(props, options);
-        super({
-          ...props,
-          ...validated
-        }, {
-          ...options,
-          disableValidation: true
-        });
-      }
-    }
-    toString() {
-      return `${identifier}(${format({
-        ...this
-      })})`;
+      input = input ?? {};
+      const validated = struct.make(input, options);
+      super({
+        ...input,
+        ...validated
+      }, {
+        ...options,
+        disableChecks: true
+      });
     }
     static [TypeId] = TypeId;
     get [ClassTypeId]() {
@@ -4808,9 +6329,15 @@ function makeClass(Inherited, identifier, struct, annotations) {
     static rebuild(ast) {
       return getClassSchema(this).rebuild(ast);
     }
-    static makeUnsafe(input, options) {
+    static make(input, options) {
       return new this(input, options);
     }
+    static makeOption(input, options) {
+      return Parser.makeOption(getClassSchema(this))(input ?? {}, options);
+    }
+    static makeEffect(input, options) {
+      return Effect.mapErrorEager(Parser.makeEffect(getClassSchema(this))(input ?? {}, options), issue => new SchemaError(issue));
+    }
     static annotate(annotations) {
       return this.rebuild(AST.annotate(this.ast, annotations));
     }
@@ -4828,13 +6355,17 @@ function makeClass(Inherited, identifier, struct, annotations) {
         };
         return makeClass(this, identifier, makeStruct(AST.struct(fields, struct.ast.checks, {
           identifier
-        }), fields), annotations);
+        }), fields), annotations, proto);
       };
     }
     static mapFields(f, options) {
       return struct.mapFields(f, options);
     }
   };
+  if (proto !== undefined) {
+    Object.assign(out.prototype, proto(identifier));
+  }
+  return out;
 }
 function getClassTransformation(self) {
   return new Transformation.Transformation(Getter.transform(input => new self(input)), Getter.passthrough());
@@ -4855,6 +6386,7 @@ function getClassSchemaFactory(from, identifier, annotations) {
         toCodec: ([from]) => new AST.Link(from.ast, transformation),
         toArbitrary: ([from]) => () => from.map(args => new self(args)),
         toFormatter: ([from]) => t => `${self.identifier}(${from(t)})`,
+        "~sentinels": AST.collectSentinels(from.ast),
         ...annotations
       }));
       memo = from.pipe(decodeTo(to, transformation));
@@ -4866,14 +6398,81 @@ function isStruct(schema) {
   return isSchema(schema);
 }
 /**
+ * Creates a schema-backed class whose constructor validates input against a
+ * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
+ * input (unless `disableChecks` 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 const Class = identifier => (schema, annotations) => {
   const struct = isStruct(schema) ? schema : Struct(schema);
-  return makeClass(Data.Class, identifier, struct, annotations);
+  return makeClass(Data.Class, identifier, struct, annotations, identifier => ({
+    toString() {
+      return `${identifier}(${format({
+        ...this
+      })})`;
+    }
+  }));
 };
 /**
+ * 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
  */
@@ -4888,14 +6487,54 @@ export const TaggedClass = identifier => {
   };
 };
 /**
+ * Creates a schema-backed error class that can be used as a typed,
+ * yieldable error in Effect programs. Combines {@link Class} validation with
+ * the `YieldableError` interface so instances can be yielded directly inside
+ * `Effect.gen`.
+ *
+ * **Example** (Schema-backed error)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 1 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const ErrorClass = identifier => (schema, annotations) => {
   const struct = isStruct(schema) ? schema : Struct(schema);
-  return makeClass(core.Error, identifier, struct, annotations);
+  const self = makeClass(core.Error, identifier, struct, annotations, identifier => ({
+    name: identifier
+  }));
+  return self;
 };
 /**
+ * Like {@link ErrorClass} but automatically adds a `_tag` literal field. The
+ * resulting class is both a schema-validated, yieldable error and a tagged
+ * union member.
+ *
+ * **Example** (Tagged error class)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 42 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4910,6 +6549,11 @@ export const TaggedErrorClass = identifier => {
   };
 };
 /**
+ * Derives a {@link LazyArbitrary} from a schema. The result is memoized so
+ * repeated calls with the same schema are cheap.
+ *
+ * Prefer {@link toArbitrary} when you just need the arbitrary directly.
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -4918,6 +6562,24 @@ export function toArbitraryLazy(schema) {
   return fc => lawc(fc, {});
 }
 /**
+ * Derives a `fast-check` `Arbitrary` from a schema for property-based
+ * testing. The derived arbitrary generates values that satisfy the schema.
+ *
+ * **Example** (Generating arbitrary values)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import * as FastCheck from "fast-check"
+ *
+ * const PersonArb = Schema.toArbitrary(
+ *   Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * )
+ *
+ * // Sample a random value
+ * const sample = FastCheck.sample(PersonArb, 1)[0]
+ * console.log(typeof sample.name) // "string"
+ * ```
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -4944,6 +6606,13 @@ export function overrideToFormatter(toFormatter) {
   };
 }
 /**
+ * Derives a string formatter function from a schema. The formatter converts
+ * a value to its human-readable string representation, recursing into structs,
+ * arrays, and unions.
+ *
+ * The optional `onBefore` hook lets you intercept specific AST nodes before
+ * the default formatting logic runs.
+ *
  * @category Formatter
  * @since 4.0.0
  */
@@ -5082,10 +6751,9 @@ export function toFormatter(schema, options) {
 // Equivalence
 // -----------------------------------------------------------------------------
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it would make
- * the schema invariant.
+ * Overrides the equivalence derivation for a schema by supplying a custom
+ * `Equivalence`. Use this when the default structural equivalence derived by
+ * {@link toEquivalence} is not appropriate for a type.
  *
  * @category Equivalence
  * @since 4.0.0
@@ -5096,6 +6764,21 @@ export function overrideToEquivalence(toEquivalence) {
   });
 }
 /**
+ * Derives an `Equivalence` from a schema. Two values are considered equal when
+ * every field (and nested field) compares equal according to the schema
+ * structure.
+ *
+ * **Example** (Struct equivalence)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const eq = Schema.toEquivalence(Schema.Struct({ id: Schema.Number, name: Schema.String }))
+ *
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 1, name: "Alice" })) // true
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 2, name: "Alice" })) // false
+ * ```
+ *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -5106,6 +6789,10 @@ export function toEquivalence(schema) {
 // Representation
 // -----------------------------------------------------------------------------
 /**
+ * Derives an intermediate `SchemaRepresentation.Document` from a schema. This
+ * document is used internally by {@link toJsonSchemaDocument} and related
+ * functions to produce JSON Schema output.
+ *
  * @category Representation
  * @since 4.0.0
  */
@@ -5130,31 +6817,114 @@ export function toJsonSchemaDocument(schema, options) {
   };
 }
 // -----------------------------------------------------------------------------
-// Serializer
+// Canonical Codecs
 // -----------------------------------------------------------------------------
 /**
- * @category Serializer
+ * Derives a canonical JSON codec from a schema. The encoded form is `unknown`
+ * (any JSON-compatible value), decoded to the schema's `Type`.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toCodecJson(schema) {
-  return make(InternalToCodec.toCodecJson(schema.ast));
+  return make(toCodecJsonTop(schema.ast));
+}
+const toCodecJsonTop = /*#__PURE__*/AST.toCodec(ast => {
+  const out = toCodecJsonBase(ast, toCodecJsonTop);
+  return out !== ast && AST.isOptional(ast) ? AST.optionalKeyLastLink(out) : out;
+});
+function toCodecJsonBase(ast, recur) {
+  switch (ast._tag) {
+    case "Declaration":
+      {
+        const getLink = ast.annotations?.toCodecJson ?? ast.annotations?.toCodec;
+        if (Predicate.isFunction(getLink)) {
+          const tps = AST.isDeclaration(ast) ? ast.typeParameters.map(tp => InternalSchema.make(AST.toEncoded(tp))) : [];
+          const link = getLink(tps);
+          const to = recur(link.to);
+          return AST.replaceEncoding(ast, to === link.to ? [link] : [new AST.Link(to, link.transformation)]);
+        }
+        return AST.replaceEncoding(ast, [AST.unknownToNull]);
+      }
+    case "Unknown":
+    case "ObjectKeyword":
+      return AST.replaceEncoding(ast, [AST.unknownToJson]);
+    case "Undefined":
+    case "Void":
+    case "Literal":
+    case "Number":
+      return ast.toCodecJson();
+    case "UniqueSymbol":
+    case "Symbol":
+    case "BigInt":
+      return ast.toCodecStringTree();
+    case "Objects":
+      {
+        if (ast.propertySignatures.some(ps => typeof ps.name !== "string")) {
+          throw new globalThis.Error("Objects property names must be strings", {
+            cause: ast
+          });
+        }
+        return ast.recur(recur);
+      }
+    case "Union":
+      {
+        const sortedTypes = InternalSchema.jsonReorder(ast.types);
+        if (sortedTypes !== ast.types) {
+          return new AST.Union(sortedTypes, ast.mode, ast.annotations, ast.checks, ast.encoding, ast.context).recur(recur);
+        }
+        return ast.recur(recur);
+      }
+    case "Arrays":
+    case "Suspend":
+      return ast.recur(recur);
+  }
+  // `Schema.Any` is used as an escape hatch
+  return ast;
 }
 /**
- * @category Serializer
+ * Derives an isomorphism codec from a schema. The encoded form is the
+ * schema's `Iso` type — the intermediate representation used for round-tripping.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toCodecIso(schema) {
-  return make(InternalToCodec.toCodecIso(AST.toType(schema.ast)));
+  return make(toCodecIsoTop(AST.toType(schema.ast)));
 }
-export function toCodecStringTree(schema, options) {
-  if (options?.keepDeclarations === true) {
-    return make(toCodecEnsureArray(serializerStringTreeKeepDeclarations(schema.ast)));
-  } else {
-    return make(toCodecEnsureArray(serializerStringTree(schema.ast)));
+const toCodecIsoTop = /*#__PURE__*/memoize(ast => {
+  const out = toCodecIsoBase(ast, toCodecIsoTop);
+  return out !== ast && AST.isOptional(ast) ? AST.optionalKeyLastLink(out) : out;
+});
+function toCodecIsoBase(ast, recur) {
+  switch (ast._tag) {
+    case "Declaration":
+      {
+        const getLink = ast.annotations?.toCodecIso ?? ast.annotations?.toCodec;
+        if (Predicate.isFunction(getLink)) {
+          const link = getLink(ast.typeParameters.map(tp => InternalSchema.make(tp)));
+          const to = recur(link.to);
+          return AST.replaceEncoding(ast, to === link.to ? [link] : [new AST.Link(to, link.transformation)]);
+        }
+        return ast;
+      }
+    case "Arrays":
+    case "Objects":
+    case "Union":
+    case "Suspend":
+      return ast.recur(recur);
   }
+  return ast;
+}
+export function toCodecStringTree(schema, options) {
+  return make(toCodecEnsureArray(options?.keepDeclarations === true ? serializerStringTreeKeepDeclarations(schema.ast) : serializerStringTree(schema.ast)));
 }
 /**
- * @category Serializer
+ * Derives an XML encoder from a codec. Encodes a value to an XML string by
+ * first converting it through {@link toCodecStringTree}, then serializing the
+ * resulting tree to XML.
+ *
+ * @category Canonical Codecs
  * @since 4.0.0
  */
 export function toEncoderXml(codec, options) {
@@ -5267,11 +7037,9 @@ function getStringTreePriority(ast) {
       return 1;
   }
 }
-const treeReorder = /*#__PURE__*/InternalToCodec.makeReorder(getStringTreePriority);
+const treeReorder = /*#__PURE__*/InternalSchema.makeReorder(getStringTreePriority);
 function serializerTree(ast, recur, onMissingAnnotation) {
   switch (ast._tag) {
-    case "Unknown":
-    case "ObjectKeyword":
     case "Declaration":
       {
         const getLink = ast.annotations?.toCodecJson ?? ast.annotations?.toCodec;
@@ -5287,6 +7055,9 @@ function serializerTree(ast, recur, onMissingAnnotation) {
       return AST.replaceEncoding(ast, [nullToString]);
     case "Boolean":
       return AST.replaceEncoding(ast, [booleanToString]);
+    case "Unknown":
+    case "ObjectKeyword":
+      return AST.replaceEncoding(ast, [AST.unknownToStringTree]);
     case "Enum":
     case "Number":
     case "Literal":
@@ -5365,6 +7136,9 @@ function onSerializerEnsureArray(ast) {
 // Optic APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives an `Iso` optic from a schema that isomorphically converts between
+ * the schema's `Type` and its `Iso` (intermediate / serialized form).
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5373,6 +7147,8 @@ export function toIso(schema) {
   return Optic_.makeIso(Parser.encodeSync(serializer), Parser.decodeSync(serializer));
 }
 /**
+ * Returns an identity `Iso` over the schema's source (`Type`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5380,6 +7156,8 @@ export function toIsoSource(_) {
   return Optic_.id();
 }
 /**
+ * Returns an identity `Iso` over the schema's focus (`Iso`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5387,10 +7165,11 @@ export function toIsoFocus(_) {
   return Optic_.id();
 }
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it changes
- * the schema type.
+ * Overrides the ISO codec derivation for a schema by providing a target codec
+ * and explicit `decode`/`encode` getters. The resulting schema carries a
+ * custom `Iso` type, which changes the schema's type parameter — use
+ * {@link overrideToCodecIso} when the default ISO transformation is not
+ * appropriate.
  *
  * @category Optic
  * @since 4.0.0
@@ -5408,11 +7187,15 @@ export function overrideToCodecIso(to, transformation) {
 // Differ APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives a JSON Patch differ from a codec. Serializes values to JSON (via
+ * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
+ * and new values, and can apply patches back to the typed value.
+ *
  * @category JsonPatch
  * @since 4.0.0
  */
 export function toDifferJsonPatch(schema) {
-  const serializer = toCodecJson(schema); // TODO: remove this cast
+  const serializer = toCodecJson(schema);
   const get = Parser.encodeSync(serializer);
   const set = Parser.decodeSync(serializer);
   return {
@@ -5427,43 +7210,66 @@ export function toDifferJsonPatch(schema) {
   };
 }
 /**
+ * Creates a recursive schema for a {@link Tree} of values described by `node`.
+ * The resulting schema accepts a single node value, an array of trees, or an
+ * object whose values are trees.
+ *
  * @category Tree
  * @since 4.0.0
  */
 export function Tree(node) {
   const Tree$ref = suspend(() => Tree);
-  const Tree = Union([node, Array(Tree$ref), Record(String, Tree$ref)]);
+  const Tree = Union([node, ArraySchema(Tree$ref), Record(String, Tree$ref)]);
   return Tree;
 }
 /**
- * @category Tree
- * @since 4.0.0
- */
-export function MutableTree(node) {
-  const MutableTree$ref = suspend(() => MutableTree);
-  const MutableTree = Union([node, mutable(Array(MutableTree$ref)), Record(String, mutableKey(MutableTree$ref))]);
-  return MutableTree;
-}
-/**
+ * Schema that accepts and validates any immutable JSON-compatible value.
+ *
+ * **Example** (Validating a JSON value)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const result = Schema.decodeUnknownOption(Schema.Json)({ key: [1, true, null] })
+ * console.log(result._tag) // "Some"
+ * ```
+ *
  * @category JSON
  * @since 4.0.0
  */
-export const Json = /*#__PURE__*/Tree(/*#__PURE__*/Union([Null, Number, Boolean, String]));
+export const Json = /*#__PURE__*/make(AST.Json);
 /**
+ * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
+ * the immutable variant.
+ *
  * @category JSON
  * @since 4.0.0
  */
-export const MutableJson = /*#__PURE__*/MutableTree(/*#__PURE__*/Union([Null, Number, Boolean, String]));
+export const MutableJson = /*#__PURE__*/make(AST.MutableJson);
 // -----------------------------------------------------------------------------
 // Annotations
 // -----------------------------------------------------------------------------
 /**
- * Return all the typed annotations from the schema.
+ * Resolves the typed annotations from a schema. The term "resolve" (rather
+ * than "get") reflects the lookup strategy: if the schema has checks, the
+ * annotations are taken from the last check; otherwise they are taken from
+ * the base schema instance.
  *
  * @category Schema Resolvers
  * @since 4.0.0
  */
-export function resolveInto(schema) {
+export function resolveAnnotations(schema) {
   return InternalAnnotations.resolve(schema.ast);
 }
+/**
+ * Resolves the context (key-level) annotations from a schema. Context
+ * annotations are those attached via `annotateKey` and live on the AST's
+ * `context` rather than on the schema node itself.
+ *
+ * @category Schema Resolvers
+ * @since 4.0.0
+ */
+export function resolveAnnotationsKey(schema) {
+  return schema.ast.context?.annotations;
+}
 //# sourceMappingURL=Schema.js.map