effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/SchemaAST.ts

@@ -1,74 +1,12 @@
 /**
- * Abstract Syntax Tree (AST) representation for Effect schemas.
- *
- * This module defines the runtime data structures that represent schemas.
- * Most users work with the `Schema` module directly; use `SchemaAST` when you
- * need to inspect, traverse, or programmatically transform schema definitions.
- *
- * ## Mental model
- *
- * - **{@link AST}** — discriminated union (`_tag`) of all schema node types
- *   (e.g. `String`, `Objects`, `Union`, `Suspend`)
- * - **{@link Base}** — abstract base class shared by every node; carries
- *   annotations, checks, encoding chain, and context
- * - **{@link Encoding}** — a non-empty chain of {@link Link} values describing
- *   how to transform between the decoded (type) and encoded (wire) form
- * - **{@link Check}** — a validation filter ({@link Filter} or
- *   {@link FilterGroup}) attached to an AST node
- * - **{@link Context}** — per-property metadata: optionality, mutability,
- *   default values, key annotations
- * - **Guards** — type-narrowing predicates for each AST variant (e.g.
- *   {@link isString}, {@link isObjects})
- *
- * ## Common tasks
- *
- * - Inspect what kind of schema you have → guard functions ({@link isString},
- *   {@link isObjects}, {@link isUnion}, etc.)
- * - Get the decoded (type-level) AST → {@link toType}
- * - Get the encoded (wire-format) AST → {@link toEncoded}
- * - Swap decode/encode directions → {@link flip}
- * - Read annotations → {@link resolve}, {@link resolveAt},
- *   {@link resolveIdentifier}
- * - Build a transformation between schemas → {@link decodeTo}
- * - Add regex validation → {@link isPattern}
- *
- * ## Gotchas
- *
- * - AST nodes are structurally immutable; modification helpers return new
- *   objects via `Object.create`.
- * - {@link Arrays} represents both tuples and arrays; {@link Objects}
- *   represents both structs and records.
- * - {@link toType} and {@link toEncoded} are memoized — same input yields
- *   same output reference.
- * - {@link Suspend} lazily resolves its inner AST via a thunk; the thunk is
- *   memoized on first call.
- *
- * ## Quickstart
- *
- * **Example** (Inspecting a schema's AST)
+ * Represents Effect schemas as runtime trees.
  *
- * ```ts
- * import { Schema, SchemaAST } from "effect"
- *
- * const schema = Schema.Struct({ name: Schema.String, age: Schema.Number })
- * const ast = schema.ast
- *
- * if (SchemaAST.isObjects(ast)) {
- *   console.log(ast.propertySignatures.map(ps => ps.name))
- *   // ["name", "age"]
- * }
- *
- * const encoded = SchemaAST.toEncoded(ast)
- * console.log(SchemaAST.isObjects(encoded)) // true
- * ```
- *
- * ## See also
- *
- * - {@link AST}
- * - {@link toType}
- * - {@link toEncoded}
- * - {@link flip}
- * - {@link resolve}
+ * Every `Schema` has an AST made from nodes for declarations, primitives,
+ * literals, arrays, objects, unions, suspended schemas, checks, annotations,
+ * encoding links, and parsing context. Most users work with the higher-level
+ * `Schema` module. Use `SchemaAST` when you need to inspect schema nodes, build
+ * ASTs programmatically, change encoded or decoded views, collect issues, or
+ * run low-level schema checks.
  *
  * @since 4.0.0
  */
@@ -714,6 +652,7 @@ export class Declaration extends Base {
   readonly run: (
     typeParameters: ReadonlyArray<AST>
   ) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>
+  readonly encodingChecks: Checks | undefined
 
   constructor(
     typeParameters: ReadonlyArray<AST>,
@@ -723,11 +662,13 @@ export class Declaration extends Base {
     annotations?: Schema.Annotations.Annotations,
     checks?: Checks,
     encoding?: Encoding,
-    context?: Context
+    context?: Context,
+    encodingChecks?: Checks
   ) {
     super(annotations, checks, encoding, context)
     this.typeParameters = typeParameters
     this.run = run
+    this.encodingChecks = encodingChecks
   }
   /** @internal */
   getParser(): SchemaParser.Parser {
@@ -737,12 +678,19 @@ export class Declaration extends Base {
       return Effect.mapEager(run(oinput.value, this, options), Option.some)
     }
   }
-  /** @internal */
-  recur(recur: (ast: AST) => AST) {
+  private rebuild(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) {
     const tps = mapOrSame(this.typeParameters, recur)
     return tps === this.typeParameters ?
       this :
-      new Declaration(tps, this.run, this.annotations, this.checks, undefined, this.context)
+      new Declaration(tps, this.run, this.annotations, checks, undefined, this.context, encodingChecks)
+  }
+  /** @internal */
+  recur(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.checks, this.encodingChecks)
+  }
+  /** @internal */
+  flip(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.encodingChecks, this.checks)
   }
   /** @internal */
   getExpected(): string {
@@ -1618,6 +1566,7 @@ export class Arrays extends Base {
   readonly isMutable: boolean
   readonly elements: ReadonlyArray<AST>
   readonly rest: ReadonlyArray<AST>
+  readonly encodingChecks: Checks | undefined
 
   constructor(
     isMutable: boolean,
@@ -1626,12 +1575,14 @@ export class Arrays extends Base {
     annotations?: Schema.Annotations.Annotations,
     checks?: Checks,
     encoding?: Encoding,
-    context?: Context
+    context?: Context,
+    encodingChecks?: Checks
   ) {
     super(annotations, checks, encoding, context)
     this.isMutable = isMutable
     this.elements = elements
     this.rest = rest
+    this.encodingChecks = encodingChecks
 
     // A required element cannot follow an optional element. ts(1257)
     const i = elements.findIndex(isOptional)
@@ -1716,13 +1667,29 @@ export class Arrays extends Base {
       return Option.some(state.output)
     })
   }
-  /** @internal */
-  recur(recur: (ast: AST) => AST) {
+  private rebuild(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) {
     const elements = mapOrSame(this.elements, recur)
     const rest = mapOrSame(this.rest, recur)
     return elements === this.elements && rest === this.rest ?
       this :
-      new Arrays(this.isMutable, elements, rest, this.annotations, this.checks, undefined, this.context)
+      new Arrays(
+        this.isMutable,
+        elements,
+        rest,
+        this.annotations,
+        checks,
+        undefined,
+        this.context,
+        encodingChecks
+      )
+  }
+  /** @internal */
+  recur(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.checks, this.encodingChecks)
+  }
+  /** @internal */
+  flip(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.encodingChecks, this.checks)
   }
   /** @internal */
   getExpected(): string {
@@ -1986,6 +1953,7 @@ export class Objects extends Base {
   readonly _tag = "Objects"
   readonly propertySignatures: ReadonlyArray<PropertySignature>
   readonly indexSignatures: ReadonlyArray<IndexSignature>
+  readonly encodingChecks: Checks | undefined
 
   constructor(
     propertySignatures: ReadonlyArray<PropertySignature>,
@@ -1993,11 +1961,13 @@ export class Objects extends Base {
     annotations?: Schema.Annotations.Annotations,
     checks?: Checks,
     encoding?: Encoding,
-    context?: Context
+    context?: Context,
+    encodingChecks?: Checks
   ) {
     super(annotations, checks, encoding, context)
     this.propertySignatures = propertySignatures
     this.indexSignatures = indexSignatures
+    this.encodingChecks = encodingChecks
 
     // Duplicate property signatures
     const duplicates = propertySignatures.map((ps) => ps.name).filter((name, i, arr) => arr.indexOf(name) !== i)
@@ -2069,6 +2039,9 @@ export class Objects extends Base {
             return
           } else if (exitKey.value._tag === "Some" && exitValue.value._tag === "Some") {
             const k2 = exitKey.value.value
+            if (expectedKeysSet.has(key) || expectedKeysSet.has(k2)) {
+              return
+            }
             const v2 = exitValue.value.value
             if (is.merge && is.merge.decode && Object.hasOwn(s.out, k2)) {
               const [k, v] = is.merge.decode.combine([k2, s.out[k2]], [k2, v2])
@@ -2180,7 +2153,9 @@ export class Objects extends Base {
   }
   private rebuild(
     recur: (ast: AST) => AST,
-    flipMerge: boolean
+    flipMerge: boolean,
+    checks: Checks | undefined,
+    encodingChecks: Checks | undefined
   ): Objects {
     const props = mapOrSame(this.propertySignatures, (ps) => {
       const t = recur(ps.type)
@@ -2198,15 +2173,23 @@ export class Objects extends Base {
 
     return props === this.propertySignatures && indexes === this.indexSignatures
       ? this
-      : new Objects(props, indexes, this.annotations, this.checks, undefined, this.context)
+      : new Objects(
+        props,
+        indexes,
+        this.annotations,
+        checks,
+        undefined,
+        this.context,
+        encodingChecks
+      )
   }
   /** @internal */
   flip(recur: (ast: AST) => AST): AST {
-    return this.rebuild(recur, true)
+    return this.rebuild(recur, true, this.encodingChecks, this.checks)
   }
   /** @internal */
   recur(recur: (ast: AST) => AST): AST {
-    return this.rebuild(recur, false)
+    return this.rebuild(recur, false, this.checks, this.encodingChecks)
   }
   /** @internal */
   getExpected(): string {
@@ -2554,6 +2537,7 @@ export class Union<A extends AST = AST> extends Base {
   readonly _tag = "Union"
   readonly types: ReadonlyArray<A>
   readonly mode: "anyOf" | "oneOf"
+  readonly encodingChecks: Checks | undefined
 
   constructor(
     types: ReadonlyArray<A>,
@@ -2561,11 +2545,13 @@ export class Union<A extends AST = AST> extends Base {
     annotations?: Schema.Annotations.Annotations,
     checks?: Checks,
     encoding?: Encoding,
-    context?: Context
+    context?: Context,
+    encodingChecks?: Checks
   ) {
     super(annotations, checks, encoding, context)
     this.types = types
     this.mode = mode
+    this.encodingChecks = encodingChecks
   }
   /** @internal */
   getParser(recur: (ast: AST) => SchemaParser.Parser): SchemaParser.Parser {
@@ -2603,12 +2589,19 @@ export class Union<A extends AST = AST> extends Base {
       })
     }
   }
-  /** @internal */
-  recur(recur: (ast: AST) => AST) {
+  private rebuild(recur: (ast: AST) => AST, checks: Checks | undefined, encodingChecks: Checks | undefined) {
     const types = mapOrSame(this.types, recur)
     return types === this.types ?
       this :
-      new Union(types, this.mode, this.annotations, this.checks, undefined, this.context)
+      new Union(types, this.mode, this.annotations, checks, undefined, this.context, encodingChecks)
+  }
+  /** @internal */
+  recur(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.checks, this.encodingChecks)
+  }
+  /** @internal */
+  flip(recur: (ast: AST) => AST) {
+    return this.rebuild(recur, this.encodingChecks, this.checks)
   }
   /** @internal */
   getExpected(getExpected: (ast: AST) => string): string {
@@ -2763,7 +2756,10 @@ export class Suspend extends Base {
     encoding?: Encoding,
     context?: Context
   ) {
-    super(annotations, checks, encoding, context)
+    if (checks !== undefined) {
+      throw new Error("Cannot add checks to Suspend")
+    }
+    super(annotations, undefined, encoding, context)
     this.thunk = memoizeThunk(thunk)
   }
   /** @internal */
@@ -2772,7 +2768,13 @@ export class Suspend extends Base {
   }
   /** @internal */
   recur(recur: (ast: AST) => AST) {
-    return new Suspend(() => recur(this.thunk()), this.annotations, this.checks, undefined, this.context)
+    return new Suspend(
+      () => recur(this.thunk()),
+      this.annotations,
+      undefined,
+      undefined,
+      this.context
+    )
   }
   /** @internal */
   getExpected(getExpected: (ast: AST) => string): string {
@@ -2780,6 +2782,19 @@ export class Suspend extends Base {
   }
 }
 
+/** @internal */
+export function getEncodingChecks(ast: AST): Checks | undefined {
+  switch (ast._tag) {
+    case "Declaration":
+    case "Arrays":
+    case "Objects":
+    case "Union":
+      return ast.encodingChecks
+    default:
+      return undefined
+  }
+}
+
 // -----------------------------------------------------------------------------
 // Checks
 // -----------------------------------------------------------------------------
@@ -2957,8 +2972,8 @@ export function isPattern(regExp: globalThis.RegExp, annotations?: Schema.Annota
         _tag: "isPattern",
         regExp
       },
-      toArbitraryConstraint: {
-        string: {
+      arbitrary: {
+        constraint: {
           patterns: [regExp.source]
         }
       },
@@ -3016,6 +3031,9 @@ export function annotate<A extends AST>(ast: A, annotations: Schema.Annotations.
 
 /** @internal */
 export function replaceChecks<A extends AST>(ast: A, checks: Checks | undefined): A {
+  if (ast._tag === "Suspend" && checks !== undefined) {
+    throw new Error("Cannot add checks to Suspend")
+  }
   if (ast.checks === checks) {
     return ast
   }
@@ -3295,7 +3313,13 @@ export const toType = memoize(<A extends AST>(ast: A): A => {
     return toType(replaceEncoding(ast, undefined))
   }
   const out: any = ast
-  return out.recur?.(toType) ?? out
+  const type = out.recur?.(toType) ?? out
+  if (getEncodingChecks(type)) {
+    return modifyOwnPropertyDescriptors(type, (d) => {
+      d.encodingChecks.value = undefined
+    })
+  }
+  return type
 })
 
 /**

package/src/SchemaGetter.ts

@@ -1,87 +1,13 @@
 /**
- * Composable transformation primitives for the Effect Schema system.
- *
- * A `Getter<T, E, R>` represents a single-direction transformation from an
- * encoded type `E` to a decoded type `T`. Getters are the building blocks
- * that `Schema.decodeTo` and `Schema.decode` use to define how values are
- * transformed during encoding and decoding. They handle optionality
- * (`Option<E>` in, `Option<T>` out), can fail with `Issue`, and can require
- * Effect services via `R`.
- *
- * ## Mental model
- *
- * - **Getter**: A function `Option<E> -> Effect<Option<T>, Issue, R>`. It
- *   transforms an optional encoded value into an optional decoded value,
- *   possibly failing or requiring services.
- * - **Passthrough**: The identity getter — returns the input unchanged. Used
- *   when no transformation is needed. Optimized away during composition.
- * - **Option-awareness**: Getters receive and return `Option` to handle
- *   missing keys in structs. `Option.None` means the key is absent.
- * - **Composition**: Getters compose left-to-right via `.compose()`. A
- *   passthrough on either side is a no-op (identity optimization).
- * - **Issue**: The error type for all getter failures (see `SchemaIssue`).
- *
- * ## Common tasks
- *
- * - Pass a value through unchanged → {@link passthrough}
- * - Transform a value purely → {@link transform}
- * - Transform a value with possible failure → {@link transformOrFail}
- * - Transform with full Option control → {@link transformOptional}
- * - Handle missing keys → {@link onNone}, {@link required}, {@link withDefault}
- * - Handle present values → {@link onSome}
- * - Validate a value with an effectful check → {@link checkEffect}
- * - Produce a constant value → {@link succeed}
- * - Always fail → {@link fail}, {@link forbidden}
- * - Omit a value from output → {@link omit}
- * - Coerce to a primitive type → {@link String}, {@link Number}, {@link Boolean}, {@link BigInt}, {@link Date}
- * - Transform strings → {@link trim}, {@link capitalize}, {@link toLowerCase}, {@link toUpperCase}, {@link split}, {@link splitKeyValue}, {@link joinKeyValue}
- * - Parse/stringify JSON → {@link parseJson}, {@link stringifyJson}
- * - Encode/decode Base64 → {@link encodeBase64}, {@link decodeBase64}, {@link decodeBase64String}
- * - Encode/decode Hex → {@link encodeHex}, {@link decodeHex}, {@link decodeHexString}
- * - Encode/decode URI components → {@link encodeUriComponent}, {@link decodeUriComponent}
- * - Parse DateTime → {@link dateTimeUtcFromInput}
- * - Decode/encode FormData → {@link decodeFormData}, {@link encodeFormData}
- * - Decode/encode URLSearchParams → {@link decodeURLSearchParams}, {@link encodeURLSearchParams}
- * - Build nested tree from bracket paths → {@link makeTreeRecord}
- * - Flatten nested tree to bracket paths → {@link collectBracketPathEntries}
- *
- * ## Gotchas
- *
- * - Getters are not bidirectional. To define a full encode/decode pair, supply
- *   both a `decode` and an `encode` getter to `Schema.decodeTo`.
- * - `passthrough` requires `T === E` by default. Use `{ strict: false }` to
- *   bypass the type constraint, or use {@link passthroughSupertype} / {@link passthroughSubtype}.
- * - `transform` skips `None` inputs (missing keys) — the function is only
- *   called when a value is present. Use `transformOptional` if you need to
- *   handle missing values.
- * - `parseJson` without a `reviver` returns `Schema.MutableJson`. With a
- *   reviver, the return type widens to `unknown`.
- * - `split` treats an empty string as an empty array, not `[""]`.
- *
- * ## Quickstart
- *
- * **Example** (Using SchemaGetter with Schema.decodeTo)
- *
- * ```ts
- * import { Schema, SchemaGetter } from "effect"
- *
- * const NumberFromString = Schema.String.pipe(
- *   Schema.decodeTo(Schema.Number, {
- *     decode: SchemaGetter.transform((s) => Number(s)),
- *     encode: SchemaGetter.transform((n) => String(n))
- *   })
- * )
- *
- * const result = Schema.decodeUnknownSync(NumberFromString)("42")
- * // result: 42
- * ```
- *
- * ## See also
- *
- * - {@link Getter} — the core class
- * - {@link transform} — most common constructor
- * - {@link passthrough} — identity getter
- * - {@link transformOrFail} — fallible transformation
+ * Builds one-way conversions used by schemas.
+ *
+ * A `Getter<T, E, R>` receives an optional encoded value and returns an
+ * optional decoded value. It can also report a schema issue or require Effect
+ * services. Schema transformations use getters to describe one direction of a
+ * conversion, for example decoding a field from input data. This module
+ * includes basic getters, validation helpers, pure and effectful conversions,
+ * and ready-made conversions for common string, number, binary, date, form, and
+ * URL-related values.
  *
  * @since 4.0.0
  */

package/src/SchemaIssue.ts

@@ -1,80 +1,12 @@
 /**
- * Structured validation errors produced by the Effect Schema system.
- *
- * When `Schema.decode`, `Schema.encode`, or a filter rejects a value, the
- * result is an {@link Issue} — a recursive tree that describes *what* went
- * wrong and *where*. This module defines every node type in that tree and
- * provides formatters that turn an `Issue` into a human-readable string or a
- * Standard Schema V1 failure result.
- *
- * ## Mental model
- *
- * - **Issue**: A discriminated union (`_tag`) of all possible validation error
- *   nodes. It is recursive — composite nodes wrap inner `Issue` children.
- * - **Leaf**: A terminal issue with no inner children ({@link InvalidType},
- *   {@link InvalidValue}, {@link MissingKey}, {@link UnexpectedKey},
- *   {@link Forbidden}, {@link OneOf}).
- * - **Composite nodes**: Wrap one or more inner issues to add context —
- *   {@link Filter}, {@link Encoding}, {@link Pointer}, {@link Composite},
- *   {@link AnyOf}.
- * - **Pointer**: Adds a property-key path to an inner issue, indicating
- *   *where* in the input the error occurred.
- * - **Formatter**: A function `Issue → Format` that serialises the error tree.
- *   Two built-in factories are provided: {@link makeFormatterDefault} (plain
- *   string) and {@link makeFormatterStandardSchemaV1} (Standard Schema V1).
- *
- * ## Common tasks
- *
- * - Check if a value is an Issue → {@link isIssue}
- * - Extract the actual input from any issue → {@link getActual}
- * - Format an issue as a string → {@link makeFormatterDefault}
- * - Format an issue for Standard Schema V1 → {@link makeFormatterStandardSchemaV1}
- * - Customise leaf formatting → {@link defaultLeafHook}
- * - Customise filter formatting → {@link defaultCheckHook}
- *
- * ## Gotchas
- *
- * - `Pointer` and `MissingKey` carry no actual value — {@link getActual}
- *   returns `Option.none()` for them.
- * - `AnyOf`, `UnexpectedKey`, `OneOf`, and `Filter` store `actual` as a plain
- *   `unknown` (not `Option`), so {@link getActual} wraps them with
- *   `Option.some`.
- * - Calling `toString()` on any `Issue` uses the default formatter. To
- *   customise output, create your own formatter with
- *   {@link makeFormatterDefault} or {@link makeFormatterStandardSchemaV1}.
- * - The `Issue` tree can be deeply nested for complex schemas. Formatters
- *   flatten composite nodes for display.
- *
- * ## Quickstart
- *
- * **Example** (Inspecting a validation error)
- *
- * ```ts
- * import { Schema, SchemaIssue } from "effect"
- *
- * const Person = Schema.Struct({
- *   name: Schema.String,
- *   age: Schema.Number
- * })
- *
- * try {
- *   Schema.decodeUnknownSync(Person)({ name: 42 })
- * } catch (e) {
- *   if (Schema.isSchemaError(e)) {
- *     console.log(SchemaIssue.isIssue(e.issue))
- *     // true
- *     console.log(String(e.issue))
- *     // formatted error message
- *   }
- * }
- * ```
- *
- * ## See also
- *
- * - {@link Issue} — the root union type
- * - {@link Leaf} — terminal issue types
- * - {@link Formatter} — the formatter interface
- * - {@link makeFormatterDefault} — default string formatter
+ * Describes problems found while decoding, encoding, or checking data with
+ * schemas.
+ *
+ * An `Issue` records what failed and, for nested data, where the failure
+ * happened. The Schema system uses these values for missing keys, unexpected
+ * keys, invalid types, invalid values, failed filters, failed transformations,
+ * and alternatives that did not match. This module also formats issues and
+ * supports redaction for sensitive values.
  *
  * @since 4.0.0
  */

package/src/SchemaParser.ts

@@ -1,45 +1,12 @@
 /**
- * Build reusable runtime parsers from Effect schemas.
- *
- * `SchemaParser` is the execution layer behind schema ASTs. It walks schema
- * structure, applies transformations, merges parse options, runs checks, and
- * reports failures as `SchemaIssue.Issue` values while exposing adapters for
- * the result shape a boundary needs.
- *
- * **Mental model**
- *
- * - A schema has a decoded `Type` side and an `Encoded` side.
- * - Decoders read `Encoded` or `unknown` input and produce `Type`.
- * - Encoders read `Type` or `unknown` input and produce `Encoded`.
- * - Maker helpers construct decoded `Type` values and apply constructor
- *   defaults before validation.
- * - The same underlying parser can be adapted to `Effect`, `Promise`, `Exit`,
- *   `Result`, `Option`, a throwing synchronous function, or a type guard.
- *
- * **Common tasks**
- *
- * - Construct decoded values: {@link make}, {@link makeEffect},
- *   {@link makeOption}
- * - Decode untrusted boundary input: {@link decodeUnknownEffect},
- *   {@link decodeUnknownSync}, {@link decodeUnknownResult}
- * - Decode already typed encoded input: {@link decodeEffect},
- *   {@link decodeSync}
- * - Encode values back to their encoded representation:
- *   {@link encodeEffect}, {@link encodeSync}, {@link encodeUnknownEffect}
- * - Check values without collecting issue details: {@link is}, {@link asserts}
- * - Build directly from an AST: {@link run}
+ * Runs schemas against real values.
  *
- * **Gotchas**
- *
- * - `decodeUnknown*` accepts untyped input; `decode*` variants expect the
- *   schema's `Encoded` type.
- * - `encodeUnknown*` accepts untyped input; `encode*` variants expect the
- *   schema's decoded `Type`.
- * - Synchronous adapters cannot run asynchronous parsing work. Use `Effect`
- *   adapters when transformations require services or asynchronous effects.
- * - Parse options supplied when a parser is created are merged with options
- *   supplied at call time, and schema-level parse annotations can further
- *   refine behavior.
+ * Schema parsers construct values from schema input, check whether a value
+ * matches a schema, decode encoded input, and encode decoded values back to
+ * their external form. This module exposes those operations through several
+ * result styles, including `Effect`, `Promise`, `Exit`, `Option`, `Result`, and
+ * synchronous functions that throw. It also contains the lower-level runner that
+ * walks a schema AST and reports schema failures as `SchemaIssue.Issue` values.
  *
  * @since 4.0.0
  */
@@ -48,7 +15,6 @@ import * as Cause from "./Cause.ts"
 import * as Effect from "./Effect.ts"
 import * as Exit from "./Exit.ts"
 import { identity, memoize } from "./Function.ts"
-import * as InternalAnnotations from "./internal/schema/annotations.ts"
 import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.ts"
 import * as Result from "./Result.ts"
@@ -902,8 +868,11 @@ export interface Parser {
 const recur = memoize(
   (ast: SchemaAST.AST): Parser => {
     let parser: Parser
-    const astOptions = InternalAnnotations.resolve(ast)?.["parseOptions"]
-    if (!ast.context && !ast.encoding && !ast.checks) {
+    const encodingChecks = SchemaAST.getEncodingChecks(ast)
+    const resolvedChecks = ast.checks ?? encodingChecks
+    const astOptions = (resolvedChecks ? resolvedChecks[resolvedChecks.length - 1].annotations : ast.annotations)
+      ?.["parseOptions"]
+    if (!ast.context && !ast.encoding && !ast.checks && !encodingChecks) {
       return (ou, options) => {
         parser ??= ast.getParser(recur)
         if (astOptions) {
@@ -941,6 +910,21 @@ const recur = memoize(
       parser ??= ast.getParser(recur)
       let sroa = srou ? Effect.flatMapEager(srou, (ou) => parser(ou, options)) : parser(ou, options)
 
+      if (encodingChecks && !options?.disableChecks) {
+        sroa = Effect.flatMapEager(sroa, (oa) => {
+          if (Option.isSome(ou) && Option.isSome(oa)) {
+            const issues: Array<SchemaIssue.Issue> = []
+
+            SchemaAST.collectIssues(encodingChecks, ou.value, issues, ast, options)
+
+            if (Arr.isArrayNonEmpty(issues)) {
+              return Effect.fail(new SchemaIssue.Composite(ast, ou, issues))
+            }
+          }
+          return Effect.succeed(oa)
+        })
+      }
+
       if (ast.checks && !options?.disableChecks) {
         const checks = ast.checks
         if (options?.errors === "all" && isStructural && Option.isSome(ou)) {