effect 4.0.0-rc.111 → 4.0.0-rc.113

package/dist/SchemaAST.d.ts

@@ -15,6 +15,7 @@ import * as Pipeable from "./Pipeable.ts";
 import type * as Schema from "./Schema.ts";
 import * as SchemaIssue from "./SchemaIssue.ts";
 import * as SchemaTransformation from "./SchemaTransformation.ts";
+import type * as Types from "./Types.ts";
 /**
  * Discriminated union of all AST node types.
  *
@@ -24,14 +25,13 @@ import * as SchemaTransformation from "./SchemaTransformation.ts";
  * ({@link isString}, {@link isObjects}, etc.) to narrow to a specific variant,
  * then access variant-specific fields.
  *
- * - All variants share the {@link Base} fields: `annotations`, `checks`,
- *   `encoding`, `context`.
+ * - All variants share the `annotations`, `checks`, `encoding`, and `context`
+ *   fields.
  * - Discriminate on the `_tag` field (e.g. `"String"`, `"Objects"`, `"Union"`).
  *
- * @see {@link Base}
  * @see {@link isAST}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
 export type AST = Declaration | Null | Undefined | Void | Never | Unknown | Any | String | Number | Boolean | BigInt | Symbol | Literal | UniqueSymbol | ObjectKeyword | Enum | TemplateLiteral | Arrays | Objects | Union | Suspend;
 /**
@@ -331,18 +331,24 @@ export declare const isSuspend: (ast: AST) => ast is Suspend;
  * @category models
  * @since 4.0.0
  */
-export declare class Link {
+export interface Link {
     readonly to: AST;
     readonly transformation: SchemaTransformation.Transformation<any, any, any, any> | SchemaTransformation.Middleware<any, any, any, any, any, any>;
-    constructor(to: AST, transformation: SchemaTransformation.Transformation<any, any, any, any> | SchemaTransformation.Middleware<any, any, any, any, any, any>);
 }
+/**
+ * Constructs a {@link Link}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Link: new (to: AST, transformation: SchemaTransformation.Transformation<any, any, any, any> | SchemaTransformation.Middleware<any, any, any, any, any, any>) => Link;
 /**
  * A non-empty chain of {@link Link} values representing the transformation
  * steps between a schema's decoded (type) form and its encoded (wire) form.
  *
  * **Details**
  *
- * Stored on {@link Base.encoding}. When `undefined`, the node has no
+ * Stored on an AST node's `encoding` field. When `undefined`, the node has no
  * encoding transformation (type and encoded forms are identical).
  *
  * @see {@link Link}
@@ -357,22 +363,25 @@ export type Encoding = readonly [Link, ...Array<Link>];
  * **Details**
  *
  * Pass to `Schema.decodeUnknown`, `Schema.encode`, and related APIs to customize
- * error reporting, excess property handling, output key ordering, check
- * execution, and asynchronous parser concurrency.
+ * error reporting, excess property handling, check execution, and product
+ * concurrency. Options apply throughout the parse; schema annotations do not
+ * override them.
  *
  * - `errors` — `"first"` (default) stops at the first error; `"all"` collects
  *   every error.
  * - `onExcessProperty` — `"ignore"` (default) strips unknown object keys;
- *   `"error"` fails; `"preserve"` keeps them.
- * - `propertyOrder` — `"none"` (default) lets the system choose key order;
- *   `"original"` preserves input key order.
+ *   `"error"` fails.
  * - `disableChecks` — skips validation checks while still applying defaults and
  *   transformations.
- * - `concurrency` — maximum number of async parse effects to run concurrently;
- *   defaults to `1`, or use `"unbounded"`.
+ * - `concurrency` — controls concurrent parsing of tuple elements, array
+ *   elements, struct fields, and record entries using the same semantics as
+ *   `Effect.forEach`; the default is sequential.
  * - `reportInput` — includes rejected input values in value-bearing schema
  *   issues.
  *
+ * Object property order is unspecified, including in values passed to checks.
+ * Decoding and encoding do not guarantee preservation of input key order.
+ *
  * @category options
  * @since 3.10.0
  */
@@ -395,45 +404,43 @@ export interface ParseOptions {
      * **Details**
      *
      * The default, `"ignore"`, strips unspecified properties from the output. Use
-     * `"error"` to fail when an excess property is present, or `"preserve"` to
-     * keep excess properties in the output.
+     * `"error"` to fail when an excess property is present. A key is covered by a
+     * declared property or any index signature selecting that key. This applies
+     * to structs, records, and structs with rest. Values must satisfy every
+     * applicable index signature. Empty structs keep their non-nullish behavior.
      *
      * @default "ignore"
      */
-    readonly onExcessProperty?: "ignore" | "error" | "preserve" | undefined;
+    readonly onExcessProperty?: "ignore" | "error" | undefined;
+    /**
+     * Whether to disable checks while still applying defaults and
+     * transformations.
+     */
+    readonly disableChecks?: boolean | undefined;
     /**
-     * The `propertyOrder` option provides control over the order of object fields
-     * in the output. This feature is useful when the sequence of keys is
-     * important for the consuming processes or when maintaining the input order
-     * enhances readability and usability.
+     * Controls how many children of a product schema may parse concurrently.
      *
      * **Details**
      *
-     * By default, the `propertyOrder` option is set to `"none"`. This means that
-     * the internal system decides the order of keys to optimize parsing speed.
+     * This option has the same concurrency semantics as {@link Effect.forEach}.
+     * It applies to tuples, arrays, structs, records, and structs with rest. Each
+     * nested product applies the limit independently. Union members remain
+     * sequential, though products inside the current union member still receive
+     * the option.
      *
-     * Setting `propertyOrder` to `"original"` ensures that the keys are ordered
-     * as they appear in the input during the decoding/encoding process.
+     * Array and tuple outputs retain their element order. Other observable work,
+     * including issue accumulation and colliding transformed record keys, follows
+     * effect completion order when concurrency is greater than `1`.
      *
      * **Gotchas**
      *
-     * The key order for `"none"` should not be considered stable and may change
-     * in future updates without notice.
+     * With `errors: "first"`, the first observed child failure interrupts the
+     * remaining children and may not belong to the earliest product position.
+     * Concurrent children may perform effects before another child fails.
      *
-     * @default "none"
+     * @default undefined
      */
-    readonly propertyOrder?: "none" | "original" | undefined;
-    /**
-     * Whether to disable checks while still applying defaults and
-     * transformations.
-     */
-    readonly disableChecks?: boolean | undefined;
-    /**
-     * The maximum number of async effects to run concurrently.
-     *
-     * @default 1
-     */
-    readonly concurrency?: number | "unbounded" | undefined;
+    readonly concurrency?: Types.Concurrency | undefined;
     /**
      * Whether schema issues should retain and report rejected input values.
      *
@@ -448,13 +455,12 @@ export interface ParseOptions {
      * Enabling this option can retain or disclose secrets, personally
      * identifiable information, and large object graphs. The `input` field is
      * enumerable and may be included by object enumeration, spread, or
-     * serialization. Disabling it on a nested schema does not redact that value
-     * from an ancestor issue whose input reporting remains enabled. Issues
-     * returned directly by user-defined declarations, checks, transformations,
-     * and middleware are not modified; their authors decide whether to retain an
-     * input. To respect this option, pass the callback's input and parse options
-     * directly to a value-bearing issue constructor. Custom messages and
-     * annotations remain the caller's responsibility regardless of this option.
+     * serialization. Issues returned directly by user-defined declarations,
+     * checks, transformations, and middleware are not modified; their authors
+     * decide whether to retain an input. To respect this option, pass the
+     * callback's input and parse options directly to a value-bearing issue
+     * constructor. Custom messages and annotations remain the caller's
+     * responsibility regardless of this option.
      * Formatting an issue with `SchemaIssue.makeFormatterDefault()`, reading
      * `SchemaError.message`, or formatting a Standard Schema failure can disclose
      * retained input.
@@ -464,7 +470,7 @@ export interface ParseOptions {
     readonly reportInput?: boolean | undefined;
 }
 /**
- * Represents per-property metadata attached to AST nodes via {@link Base.context}.
+ * Represents per-property metadata attached to an AST node's `context` field.
  *
  * **Details**
  *
@@ -479,24 +485,28 @@ export interface ParseOptions {
  * - `annotations` — key-level annotations (e.g. description of the key
  *   itself).
  *
- * @see {@link optionalKey}
+ * @see `Schema.optionalKey`
  * @see {@link isOptional}
  * @category models
  * @since 4.0.0
  */
-export declare class Context {
+export interface Context {
     readonly isOptional: boolean;
     readonly isMutable: boolean;
     /** Used for constructor default values (e.g. `withConstructorDefault` API) */
     readonly constructorDefault: Link | undefined;
     readonly annotations: Schema.Annotations.Key<unknown> | undefined;
-    constructor(isOptional: boolean, isMutable: boolean, 
-    /** Used for constructor default values (e.g. `withConstructorDefault` API) */
-    constructorDefault?: Link | undefined, annotations?: Schema.Annotations.Key<unknown> | undefined);
 }
 /**
- * Non-empty array of validation {@link Check} values attached to an AST node
- * via {@link Base.checks}.
+ * Constructs a {@link Context}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Context: new (isOptional: boolean, isMutable: boolean, /** Used for constructor default values (e.g. `withConstructorDefault` API) */ constructorDefault?: Link | undefined, annotations?: Schema.Annotations.Key<unknown> | undefined) => Context;
+/**
+ * Non-empty array of validation {@link Check} values attached to an AST node's
+ * `checks` field.
  *
  * **Details**
  *
@@ -511,36 +521,16 @@ export declare class Context {
  */
 export type Checks = readonly [Check<any>, ...Array<Check<any>>];
 declare const TypeId = "~effect/Schema";
-/**
- * Represents the abstract base class for all {@link AST} node variants.
- *
- * **Details**
- *
- * Every AST node extends `Base` and inherits these fields:
- *
- * - `annotations` — user-supplied metadata (identifier, title, description,
- *   arbitrary keys).
- * - `checks` — optional {@link Checks} for post-type-match validation.
- * - `encoding` — optional {@link Encoding} chain for type ↔ wire
- *   transformations.
- * - `context` — optional {@link Context} for per-property metadata.
- *
- * Subclasses add a `_tag` discriminant and variant-specific data.
- *
- * @see {@link AST}
- * @category models
- * @since 4.0.0
- */
-export declare abstract class Base {
-    readonly [TypeId] = "~effect/Schema";
-    abstract readonly _tag: string;
+interface ASTNode {
+    readonly [TypeId]: typeof TypeId;
+    readonly _tag: string;
     readonly annotations: Schema.Annotations.Annotations | undefined;
     readonly checks: Checks | undefined;
     readonly encoding: Encoding | undefined;
     readonly context: Context | undefined;
-    constructor(annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined);
     toString(): string;
 }
+type DeclarationRun = (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue>;
 /**
  * AST node for user-defined opaque types with custom parsing logic.
  *
@@ -554,20 +544,31 @@ export declare abstract class Base {
  * - `typeParameters` — inner schemas this declaration is parameterized over
  *   (e.g. the element type for a custom collection).
  * - `run` — factory that receives `typeParameters` and returns a parser that
- *   validates or transforms raw input.
+ *   validates or transforms raw input. The `Effect` returned by the parser must
+ *   complete synchronously.
  *
  * @see {@link isDeclaration}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class Declaration extends Base {
-    readonly _tag = "Declaration";
+export interface Declaration extends ASTNode {
+    readonly _tag: "Declaration";
     readonly typeParameters: ReadonlyArray<AST>;
-    readonly run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>;
+    readonly run: DeclarationRun;
     readonly encodingChecks: Checks | undefined;
-    constructor(typeParameters: ReadonlyArray<AST>, run: (typeParameters: ReadonlyArray<AST>) => (input: unknown, self: Declaration, options: ParseOptions) => Effect.Effect<any, SchemaIssue.Issue, any>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks);
-    private _rebuild;
+    /**
+     * Parser factory {@link flip} swaps in, so a declaration can behave
+     * differently when encoding. `undefined` reuses `run`.
+     */
+    readonly encodingRun: DeclarationRun | undefined;
 }
+/**
+ * Constructs a {@link Declaration}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Declaration: new (typeParameters: ReadonlyArray<AST>, run: DeclarationRun, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks, encodingRun?: DeclarationRun) => Declaration;
 /**
  * AST node matching the `null` literal value.
  *
@@ -580,9 +581,16 @@ export declare class Declaration extends Base {
  * @category models
  * @since 4.0.0
  */
-export declare class Null extends Base {
-    readonly _tag = "Null";
+export interface Null extends ASTNode {
+    readonly _tag: "Null";
 }
+/**
+ * Constructs a {@link Null}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Null: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Null;
 declare const null_: Null;
 export { 
 /**
@@ -609,9 +617,16 @@ null_ as null };
  * @category models
  * @since 4.0.0
  */
-export declare class Undefined extends Base {
-    readonly _tag = "Undefined";
+export interface Undefined extends ASTNode {
+    readonly _tag: "Undefined";
 }
+/**
+ * Constructs a {@link Undefined}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Undefined: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Undefined;
 declare const undefined_: Undefined;
 export { 
 /**
@@ -646,9 +661,16 @@ undefined_ as undefined };
  * @category models
  * @since 4.0.0
  */
-export declare class Void extends Base {
-    readonly _tag = "Void";
+export interface Void extends ASTNode {
+    readonly _tag: "Void";
 }
+/**
+ * Constructs a {@link Void}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Void: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Void;
 declare const void_: Void;
 export { 
 /**
@@ -685,9 +707,16 @@ void_ as void };
  * @category models
  * @since 4.0.0
  */
-export declare class Never extends Base {
-    readonly _tag = "Never";
+export interface Never extends ASTNode {
+    readonly _tag: "Never";
 }
+/**
+ * Constructs a {@link Never}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Never: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Never;
 /**
  * Provides the singleton {@link Never} AST instance.
  *
@@ -712,9 +741,16 @@ export declare const never: Never;
  * @category models
  * @since 4.0.0
  */
-export declare class Any extends Base {
-    readonly _tag = "Any";
+export interface Any extends ASTNode {
+    readonly _tag: "Any";
 }
+/**
+ * Constructs a {@link Any}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Any: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Any;
 /**
  * Provides the singleton {@link Any} AST instance.
  *
@@ -742,9 +778,16 @@ export declare const any: Any;
  * @category models
  * @since 4.0.0
  */
-export declare class Unknown extends Base {
-    readonly _tag = "Unknown";
+export interface Unknown extends ASTNode {
+    readonly _tag: "Unknown";
 }
+/**
+ * Constructs a {@link Unknown}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Unknown: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Unknown;
 /**
  * Provides the singleton {@link Unknown} AST instance.
  *
@@ -767,11 +810,18 @@ export declare const unknown: Unknown;
  * @see {@link isObjectKeyword}
  *
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class ObjectKeyword extends Base {
-    readonly _tag = "ObjectKeyword";
+export interface ObjectKeyword extends ASTNode {
+    readonly _tag: "ObjectKeyword";
 }
+/**
+ * Constructs a {@link ObjectKeyword}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const ObjectKeyword: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => ObjectKeyword;
 /**
  * Provides the singleton {@link ObjectKeyword} AST instance.
  *
@@ -799,11 +849,23 @@ export declare const objectKeyword: ObjectKeyword;
  * @category models
  * @since 4.0.0
  */
-export declare class Enum extends Base {
-    readonly _tag = "Enum";
-    readonly enums: ReadonlyArray<readonly [string, string | number]>;
-    constructor(enums: ReadonlyArray<readonly [string, string | number]>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context);
+export interface Enum extends ASTNode {
+    readonly _tag: "Enum";
+    readonly enums: ReadonlyArray<readonly [
+        string,
+        string | number
+    ]>;
 }
+/**
+ * Constructs a {@link Enum}. Numeric values must be finite.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Enum: new (enums: ReadonlyArray<readonly [
+    string,
+    string | number
+]>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context) => Enum;
 /**
  * AST node representing a TypeScript template literal type
  * (e.g. `` `user_${string}` ``).
@@ -815,13 +877,24 @@ export declare class Enum extends Base {
  *
  * @see {@link isTemplateLiteral}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class TemplateLiteral extends Base {
-    readonly _tag = "TemplateLiteral";
+export interface TemplateLiteral extends ASTNode {
+    readonly _tag: "TemplateLiteral";
     readonly parts: ReadonlyArray<AST>;
-    constructor(parts: ReadonlyArray<AST>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context);
 }
+/**
+ * Constructs a {@link TemplateLiteral}.
+ *
+ * **Gotchas**
+ *
+ * Throws if a part contains an encoding, including inside unions or nested
+ * template literals. Parts must describe their values without transformations.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const TemplateLiteral: new (parts: ReadonlyArray<AST>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context) => TemplateLiteral;
 /**
  * AST node matching a specific `unique symbol` value.
  *
@@ -832,13 +905,19 @@ export declare class TemplateLiteral extends Base {
  *
  * @see {@link isUniqueSymbol}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class UniqueSymbol extends Base {
-    readonly _tag = "UniqueSymbol";
+export interface UniqueSymbol extends ASTNode {
+    readonly _tag: "UniqueSymbol";
     readonly symbol: symbol;
-    constructor(symbol: symbol, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context);
 }
+/**
+ * Constructs a {@link UniqueSymbol}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const UniqueSymbol: new (symbol: symbol, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context) => UniqueSymbol;
 /**
  * The set of primitive types that can appear as a {@link Literal} value.
  *
@@ -855,8 +934,10 @@ export type LiteralValue = string | number | boolean | bigint;
  * **Details**
  *
  * Parsing succeeds only when the input is strictly equal (`===`) to the
- * stored `literal`. Numeric literals must be finite — `Infinity`, `-Infinity`,
- * and `NaN` are rejected at construction time.
+ * stored `literal`, preserving the input value. Both `0` and `-0` are accepted
+ * by either zero literal, and parsing preserves the input's sign. Numeric
+ * literals must be finite. `Infinity`, `-Infinity`, and `NaN` are rejected at
+ * construction time.
  *
  * **Example** (Creating a literal AST)
  *
@@ -870,13 +951,19 @@ export type LiteralValue = string | number | boolean | bigint;
  * @see {@link LiteralValue}
  * @see {@link isLiteral}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class Literal extends Base {
-    readonly _tag = "Literal";
+export interface Literal extends ASTNode {
+    readonly _tag: "Literal";
     readonly literal: LiteralValue;
-    constructor(literal: LiteralValue, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context);
 }
+/**
+ * Constructs a {@link Literal}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Literal: new (literal: LiteralValue, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context) => Literal;
 /**
  * AST node matching any `string` value.
  *
@@ -886,9 +973,16 @@ export declare class Literal extends Base {
  * @category models
  * @since 4.0.0
  */
-export declare class String extends Base {
-    readonly _tag = "String";
+export interface String extends ASTNode {
+    readonly _tag: "String";
 }
+/**
+ * Constructs a {@link String}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const String: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => String;
 /**
  * Provides the singleton {@link String} AST instance.
  *
@@ -922,10 +1016,16 @@ export declare const string: String;
  * @category models
  * @since 4.0.0
  */
-export declare class Number extends Base {
-    readonly _tag = "Number";
-    private _match;
+export interface Number extends ASTNode {
+    readonly _tag: "Number";
 }
+/**
+ * Constructs a {@link Number}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Number: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Number;
 /**
  * Provides the singleton {@link Number} AST instance.
  *
@@ -950,9 +1050,16 @@ export declare const number: Number;
  * @category models
  * @since 4.0.0
  */
-export declare class Boolean extends Base {
-    readonly _tag = "Boolean";
+export interface Boolean extends ASTNode {
+    readonly _tag: "Boolean";
 }
+/**
+ * Constructs a {@link Boolean}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Boolean: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Boolean;
 /**
  * Provides the singleton {@link Boolean} AST instance.
  *
@@ -986,9 +1093,16 @@ export declare const boolean: Boolean;
  * @category models
  * @since 4.0.0
  */
-export declare class Symbol extends Base {
-    readonly _tag = "Symbol";
+export interface Symbol extends ASTNode {
+    readonly _tag: "Symbol";
 }
+/**
+ * Constructs a {@link Symbol}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Symbol: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => Symbol;
 /**
  * Provides the singleton {@link Symbol} AST instance.
  *
@@ -1021,9 +1135,16 @@ export declare const symbol: Symbol;
  * @category models
  * @since 4.0.0
  */
-export declare class BigInt extends Base {
-    readonly _tag = "BigInt";
+export interface BigInt extends ASTNode {
+    readonly _tag: "BigInt";
 }
+/**
+ * Constructs a {@link BigInt}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const BigInt: new (annotations?: Schema.Annotations.Annotations | undefined, checks?: Checks | undefined, encoding?: Encoding | undefined, context?: Context | undefined) => BigInt;
 /**
  * Provides the singleton {@link BigInt} AST instance.
  *
@@ -1050,7 +1171,7 @@ export declare const bigInt: BigInt;
  * **Details**
  *
  * - `elements` — positional element types (tuple elements). An element is
- *   optional if its {@link Context.isOptional} is `true`.
+ *   optional if its context's `isOptional` field is `true`.
  * - `rest` — the rest/variadic element types. When non-empty, the first
  *   entry is the "spread" type (e.g. `...Array<string>`), and subsequent
  *   entries are trailing positional elements after the spread.
@@ -1081,15 +1202,20 @@ export declare const bigInt: BigInt;
  * @category models
  * @since 4.0.0
  */
-export declare class Arrays extends Base {
-    readonly _tag = "Arrays";
+export interface Arrays extends ASTNode {
+    readonly _tag: "Arrays";
     readonly isMutable: boolean;
     readonly elements: ReadonlyArray<AST>;
     readonly rest: ReadonlyArray<AST>;
     readonly encodingChecks: Checks | undefined;
-    constructor(isMutable: boolean, elements: ReadonlyArray<AST>, rest: ReadonlyArray<AST>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks);
-    private _rebuild;
 }
+/**
+ * Constructs a {@link Arrays}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Arrays: new (isMutable: boolean, elements: ReadonlyArray<AST>, rest: ReadonlyArray<AST>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks) => Arrays;
 /**
  * Represents a named property within an {@link Objects} node.
  *
@@ -1101,13 +1227,19 @@ export declare class Arrays extends Base {
  *
  * @see {@link Objects}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class PropertySignature {
+export interface PropertySignature {
     readonly name: PropertyKey;
     readonly type: AST;
-    constructor(name: PropertyKey, type: AST);
 }
+/**
+ * Constructs a {@link PropertySignature}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const PropertySignature: new (name: PropertyKey, type: AST) => PropertySignature;
 type IndexSignatureParameter = String | Number | Symbol | TemplateLiteral | Union<IndexSignatureParameter>;
 /**
  * Represents an index signature entry within an {@link Objects} node.
@@ -1131,13 +1263,19 @@ type IndexSignatureParameter = String | Number | Symbol | TemplateLiteral | Unio
  * @see {@link Objects}
  * @see {@link PropertySignature}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class IndexSignature {
+export interface IndexSignature {
     readonly parameter: IndexSignatureParameter;
     readonly type: AST;
-    constructor(parameter: AST, type: AST);
 }
+/**
+ * Constructs a {@link IndexSignature}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const IndexSignature: new (parameter: AST, type: AST) => IndexSignature;
 /**
  * AST node for object-like schemas, including structs and records.
  *
@@ -1180,21 +1318,26 @@ export declare class IndexSignature {
  * @category models
  * @since 4.0.0
  */
-export declare class Objects extends Base {
-    readonly _tag = "Objects";
+export interface Objects extends ASTNode {
+    readonly _tag: "Objects";
     readonly propertySignatures: ReadonlyArray<PropertySignature>;
     readonly indexSignatures: ReadonlyArray<IndexSignature>;
     readonly encodingChecks: Checks | undefined;
-    constructor(propertySignatures: ReadonlyArray<PropertySignature>, indexSignatures: ReadonlyArray<IndexSignature>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks);
-    private _rebuild;
 }
+/**
+ * Constructs a {@link Objects}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Objects: new (propertySignatures: ReadonlyArray<PropertySignature>, indexSignatures: ReadonlyArray<IndexSignature>, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks) => Objects;
 /**
  * AST node representing a union of schemas.
  *
  * **Details**
  *
  * - `types` — the member AST nodes.
- * - `mode` — `"anyOf"` succeeds on the first match (like TypeScript unions);
+ * - `options.mode` selects matching behavior. `"anyOf"` succeeds on the first match;
  *   `"oneOf"` requires exactly one member to match (fails if multiple do).
  *
  * During parsing, members are tried in order. An internal candidate index
@@ -1210,22 +1353,37 @@ export declare class Objects extends Base {
  * const ast = schema.ast
  *
  * if (SchemaAST.isUnion(ast)) {
- *   [ast.types.length, ast.mode] // => [2, "anyOf"]
+ *   [ast.types.length, ast.options?.mode ?? "anyOf"] // => [2, "anyOf"]
  * }
  * ```
  *
  * @see {@link isUnion}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class Union<A extends AST = AST> extends Base {
-    readonly _tag = "Union";
+export interface Union<A extends AST = AST> extends ASTNode {
+    readonly _tag: "Union";
     readonly types: ReadonlyArray<A>;
-    readonly mode: "anyOf" | "oneOf";
+    readonly options: UnionOptions | undefined;
     readonly encodingChecks: Checks | undefined;
-    constructor(types: ReadonlyArray<A>, mode: "anyOf" | "oneOf", annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks);
-    private _rebuild;
 }
+/**
+ * Local matching options stored on {@link Union} nodes.
+ *
+ * @category options
+ * @since 4.0.0
+ */
+export interface UnionOptions {
+    /** Defaults to `"anyOf"`; `"oneOf"` requires exactly one matching member. */
+    readonly mode?: "anyOf" | "oneOf" | undefined;
+}
+/**
+ * Constructs a {@link Union}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Union: new <A extends AST = AST>(types: ReadonlyArray<A>, options?: UnionOptions, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context, encodingChecks?: Checks) => Union<A>;
 /**
  * AST node for lazy/recursive schemas.
  *
@@ -1255,13 +1413,19 @@ export declare class Union<A extends AST = AST> extends Base {
  *
  * @see {@link isSuspend}
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export declare class Suspend extends Base {
-    readonly _tag = "Suspend";
+export interface Suspend extends ASTNode {
+    readonly _tag: "Suspend";
     readonly thunk: () => AST;
-    constructor(thunk: () => AST, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context);
 }
+/**
+ * Constructs a {@link Suspend}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Suspend: new (thunk: () => AST, annotations?: Schema.Annotations.Annotations, checks?: Checks, encoding?: Encoding, context?: Context) => Suspend;
 /**
  * Represents a single validation check attached to an AST node.
  *
@@ -1283,23 +1447,27 @@ export declare class Suspend extends Base {
  * @category models
  * @since 4.0.0
  */
-export declare class Filter<in E> extends Pipeable.Class {
-    readonly _tag = "Filter";
+export interface Filter<in E> extends Pipeable.Pipeable {
+    readonly _tag: "Filter";
     readonly run: (input: E, self: AST, options: ParseOptions) => SchemaIssue.Issue | undefined;
     readonly annotations: Schema.Annotations.Filter | undefined;
     /**
      * Whether the parsing process should be aborted after this check has failed.
      */
     readonly aborted: boolean;
-    constructor(run: (input: E, self: AST, options: ParseOptions) => SchemaIssue.Issue | undefined, annotations?: Schema.Annotations.Filter | undefined, 
-    /**
-     * Whether the parsing process should be aborted after this check has failed.
-     */
-    aborted?: boolean);
     annotate(annotations: Schema.Annotations.Filter): Filter<E>;
     abort(): Filter<E>;
     and(other: Check<E>, annotations?: Schema.Annotations.Filter): FilterGroup<E>;
 }
+/**
+ * Constructs a {@link Filter}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const Filter: new <E>(run: (input: E, self: AST, options: ParseOptions) => SchemaIssue.Issue | undefined, annotations?: Schema.Annotations.Filter | undefined, /**
+ * Whether the parsing process should be aborted after this check has failed.
+ */ aborted?: boolean) => Filter<E>;
 /**
  * Represents a composite validation check grouping multiple {@link Check} values.
  *
@@ -1314,21 +1482,33 @@ export declare class Filter<in E> extends Pipeable.Class {
  * @category models
  * @since 4.0.0
  */
-export declare class FilterGroup<in E> extends Pipeable.Class {
-    readonly _tag = "FilterGroup";
-    readonly checks: readonly [Check<E>, ...Array<Check<E>>];
+export interface FilterGroup<in E> extends Pipeable.Pipeable {
+    readonly _tag: "FilterGroup";
+    readonly checks: readonly [
+        Check<E>,
+        ...Array<Check<E>>
+    ];
     readonly annotations: Schema.Annotations.Filter | undefined;
-    constructor(checks: readonly [Check<E>, ...Array<Check<E>>], annotations?: Schema.Annotations.Filter | undefined);
     annotate(annotations: Schema.Annotations.Filter): FilterGroup<E>;
     and(other: Check<E>, annotations?: Schema.Annotations.Filter): FilterGroup<E>;
 }
+/**
+ * Constructs a {@link FilterGroup}.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const FilterGroup: new <E>(checks: readonly [
+    Check<E>,
+    ...Array<Check<E>>
+], annotations?: Schema.Annotations.Filter | undefined) => FilterGroup<E>;
 /**
  * A validation check — either a single {@link Filter} or a composite
  * {@link FilterGroup}.
  *
  * **Details**
  *
- * Stored in the {@link Checks} array on {@link Base.checks}.
+ * Stored in an AST node's {@link Checks} array.
  *
  * @see {@link Filter}
  * @see {@link FilterGroup}
@@ -1355,8 +1535,12 @@ export type Check<T> = Filter<T> | FilterGroup<T>;
  *
  * **Gotchas**
  *
- * When deriving an arbitrary, only `regExp.source` is used. Regular expression
- * flags are ignored because fast-check does not support them.
+ * Arbitrary metadata preserves both `regExp.source` and `regExp.flags`.
+ * Implementations that cannot consume all flags may still use the source as a
+ * generation hint because the Schema filter validates every generated value.
+ * JSON Schema has no way to carry JavaScript regular-expression flags. The
+ * generated `pattern` contains the source only, so validation can differ when
+ * the RegExp uses flags or relies on JavaScript's non-Unicode behavior.
  *
  * **Example** (Validating an email pattern)
  *
@@ -1380,9 +1564,8 @@ export declare function mapOrSame<A>(as: ReadonlyArray<A>, f: (a: A) => A): Read
  *
  * **Details**
  *
- * This is the low-level primitive behind `Schema.transform` and
- * `Schema.transformOrFail`. It appends a {@link Link} to the `to` node's
- * encoding chain.
+ * This is the low-level primitive behind `Schema.decodeTo`. It appends a
+ * {@link Link} to the `to` node's encoding chain.
  *
  * - Returns a new AST with the same type as `to`.
  *
@@ -1401,7 +1584,7 @@ export declare function decodeTo<A extends AST>(from: AST, to: A, transformation
  * Checks `ast.context?.isOptional`. Defaults to `false` when no
  * {@link Context} is set.
  *
- * @see {@link optionalKey}
+ * @see `Schema.optionalKey`
  * @see {@link Context}
  * @category predicates
  * @since 4.0.0
@@ -1485,7 +1668,7 @@ export declare const flip: (ast: AST) => AST;
  *
  * If the node has {@link Checks}, returns annotations from the last check
  * (which is where user-supplied annotations end up after `.pipe(Schema.annotations(...))`).
- * Otherwise returns `Base.annotations` directly.
+ * Otherwise returns the node's `annotations` directly.
  *
  * **Example** (Reading annotations)
  *