effect 4.0.0-beta.100 → 4.0.0-beta.102

package/src/SchemaRepresentation.ts

@@ -1,72 +1,150 @@
 /**
- * Plain data structures for describing schemas in a serializable form. A
- * `Representation` is not the original `Schema` object; it is a JSON-friendly
- * description of the schema's types, fields, unions, checks, annotations, and
- * references.
- *
- * This module defines the representation node types, document types, and
- * codecs used to validate those documents. It can build representation
- * documents from schema ASTs, turn representation documents back into schemas,
- * convert them to and from JSON Schema documents, and generate TypeScript code
- * artifacts for schema definitions.
+ * Open, compiler-extensible representation of Effect schemas.
  *
  * @since 4.0.0
  */
-import * as Arr from "./Array.ts"
-import { format, formatPropertyKey } from "./Formatter.ts"
-import { collectBrands } from "./internal/schema/annotations.ts"
-import * as InternalRepresentation from "./internal/schema/representation.ts"
-import { unescapeToken } from "./JsonPointer.ts"
+import * as InternalRecord from "./internal/record.ts"
+import * as InternalFromJsonSchemaDocument from "./internal/schema/fromJsonSchemaDocument.ts"
+import * as InternalFromRepresentation from "./internal/schema/fromRepresentation.ts"
+import * as InternalSchema from "./internal/schema/schema.ts"
+import * as InternalToCodeDocument from "./internal/schema/toCodeDocument.ts"
+import * as InternalToJsonSchemaDocument from "./internal/schema/toJsonSchemaDocument.ts"
+import * as InternalToRepresentation from "./internal/schema/toRepresentation.ts"
 import type * as JsonSchema from "./JsonSchema.ts"
-import { remainder } from "./Number.ts"
 import * as Option from "./Option.ts"
-import * as Predicate from "./Predicate.ts"
-import * as Rec from "./Record.ts"
 import * as Schema from "./Schema.ts"
 import * as SchemaAST from "./SchemaAST.ts"
 import * as SchemaGetter from "./SchemaGetter.ts"
 
-// -----------------------------------------------------------------------------
-// specification
-// -----------------------------------------------------------------------------
-
 /**
- * A custom type declaration, such as `Date`, `Option`, or `ReadonlySet`.
- *
- * **When to use**
+ * Open persistence identity carried by declarations and opaque checks.
  *
- * Use when inspecting or transforming non-primitive schema types.
+ * @category annotations
+ * @since 4.0.0
+ */
+export interface RepresentationAnnotation {
+  readonly id: string
+  readonly payload: Schema.Json
+}
+
+/**
+ * Open persistence identity and schema dependencies carried by opaque checks.
  *
- * **Details**
+ * @category annotations
+ * @since 4.0.0
+ */
+export interface CheckRepresentationAnnotation<S> extends RepresentationAnnotation {
+  readonly schemas?: ReadonlyArray<S> | undefined
+}
+
+/**
+ * Input passed to JSON Schema compiler annotations.
  *
- * `typeParameters` holds the inner type arguments, such as the `A` in
- * `Option<A>`. `encodedSchema` is the fallback representation when no
- * {@link Reviver} recognizes this declaration. `annotations.typeConstructor`
- * identifies the declaration kind, such as `{ _tag: "effect/Option" }`.
+ * @since 4.0.0
+ */
+export declare namespace ToJsonSchema {
+  /**
+   * Input for a check compiler.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface CheckInput {
+    readonly type: JsonSchema.Type | undefined
+    readonly schemas: ReadonlyArray<JsonSchema.JsonSchema>
+  }
+
+  /**
+   * JSON Schema compiler for a check.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export type Check = (input: CheckInput) => JsonSchema.JsonSchema
+}
+
+/**
+ * Input and output contracts for code generation annotations.
  *
- * @see {@link Reviver}
- * @see {@link toSchemaDefaultReviver}
+ * @since 4.0.0
+ */
+export declare namespace Generation {
+  /**
+   * Input for declaration code generation.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface DeclarationInput {
+    readonly typeParameters: ReadonlyArray<Code>
+  }
+
+  /**
+   * Output of declaration code generation.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface DeclarationOutput {
+    readonly runtime: string
+    readonly Type: string
+    readonly importDeclarations?: ReadonlyArray<string> | undefined
+  }
+
+  /**
+   * Declaration code generator.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export type Declaration = (input: DeclarationInput) => DeclarationOutput
+
+  /**
+   * Input for check code generation.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface CheckInput {
+    readonly schemas: ReadonlyArray<Code>
+  }
+
+  /**
+   * Output of check code generation.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface CheckOutput {
+    readonly runtime: string
+    readonly importDeclarations?: ReadonlyArray<string> | undefined
+  }
+
+  /**
+   * Check code generator.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export type Check = (input: CheckInput) => CheckOutput
+}
+
+/**
+ * A custom opaque declaration.
  *
  * @category models
  * @since 4.0.0
  */
 export interface Declaration {
   readonly _tag: "Declaration"
+  readonly representation?: RepresentationAnnotation | undefined
   readonly annotations?: Schema.Annotations.Annotations | undefined
   readonly typeParameters: ReadonlyArray<Representation>
-  readonly checks: ReadonlyArray<Check<DeclarationMeta>>
-  readonly encodedSchema: Representation
+  readonly checks: ReadonlyArray<Check>
 }
 
 /**
- * A lazily resolved representation used for recursive schemas.
- *
- * **Details**
- *
- * `thunk` points to the actual representation, possibly via a
- * {@link Reference}. `checks` is always empty on `Suspend` nodes.
- *
- * @see {@link Reference}
+ * A lazily resolved representation.
  *
  * @category models
  * @since 4.0.0
@@ -79,25 +157,7 @@ export interface Suspend {
 }
 
 /**
- * A named reference to a definition in the {@link References} map.
- *
- * **When to use**
- *
- * Use when a representation should point to a named definition instead of
- * embedding the definition inline.
- *
- * **Details**
- *
- * `$ref` is the key into `Document.references` or `MultiDocument.references`.
- * References are resolved lazily by {@link toSchema} and
- * {@link toCodeDocument}.
- *
- * **Gotchas**
- *
- * Resolution throws at runtime if the key is not found in the references map.
- *
- * @see {@link References}
- * @see {@link Document}
+ * A named reference.
  *
  * @category models
  * @since 4.0.0
@@ -107,244 +167,152 @@ export interface Reference {
   readonly $ref: string
 }
 
-/**
- * The `null` type.
- *
- * @category models
- * @since 4.0.0
- */
-export interface Null {
-  readonly _tag: "Null"
+interface Keyword<Tag extends string> {
+  readonly _tag: Tag
   readonly annotations?: Schema.Annotations.Annotations | undefined
+  readonly checks: ReadonlyArray<Check>
 }
 
 /**
- * The `undefined` type.
+ * The null keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Undefined {
-  readonly _tag: "Undefined"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Null extends Keyword<"Null"> {}
 /**
- * The `void` type.
+ * The undefined keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Void {
-  readonly _tag: "Void"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Undefined extends Keyword<"Undefined"> {}
 /**
- * The `never` type (no valid values).
+ * The void keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Never {
-  readonly _tag: "Never"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Void extends Keyword<"Void"> {}
 /**
- * The `unknown` type (any value accepted).
+ * The never keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Unknown {
-  readonly _tag: "Unknown"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Never extends Keyword<"Never"> {}
 /**
- * The `any` type.
+ * The unknown keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Any {
-  readonly _tag: "Any"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Unknown extends Keyword<"Unknown"> {}
 /**
- * The `string` type with optional validation checks.
- *
- * **Details**
- *
- * `checks` holds string-specific constraints, such as min/max length, pattern,
- * and UUID checks. `contentMediaType` and `contentSchema` indicate that the
- * string contains encoded data, such as `"application/json"` with a nested
- * schema.
- *
- * @see {@link StringMeta}
- * @see {@link Check}
+ * The any keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface String {
-  readonly _tag: "String"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly checks: ReadonlyArray<Check<StringMeta>>
-  readonly contentMediaType?: string | undefined
-  readonly contentSchema?: Representation | undefined
-}
+export interface Any extends Keyword<"Any"> {}
 
 /**
- * The `number` type with optional validation checks.
- *
- * **Details**
- *
- * `checks` holds number-specific constraints, such as int, finite, min, max,
- * multipleOf, and between checks.
- *
- * @see {@link NumberMeta}
+ * A string representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Number {
-  readonly _tag: "Number"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly checks: ReadonlyArray<Check<NumberMeta>>
-}
+export interface String extends Keyword<"String"> {}
 
 /**
- * The `boolean` type.
+ * A number representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Boolean {
-  readonly _tag: "Boolean"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface Number extends Keyword<"Number"> {}
 /**
- * The `bigint` type with optional validation checks.
- *
- * @see {@link BigIntMeta}
+ * A boolean representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface BigInt {
-  readonly _tag: "BigInt"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly checks: ReadonlyArray<Check<BigIntMeta>>
-}
-
+export interface Boolean extends Keyword<"Boolean"> {}
 /**
- * The `symbol` type.
+ * A bigint representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Symbol {
-  readonly _tag: "Symbol"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-}
-
+export interface BigInt extends Keyword<"BigInt"> {}
 /**
- * A specific literal value (`string`, `number`, `boolean`, or `bigint`).
+ * A symbol representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Literal {
-  readonly _tag: "Literal"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly literal: string | number | boolean | bigint
-}
+export interface Symbol extends Keyword<"Symbol"> {}
 
 /**
- * A specific unique `symbol` value.
+ * A literal representation.
+ *
+ * **Details**
+ *
+ * The live representation stores the native literal value. Persistent codecs
+ * add an explicit type discriminator when encoding it.
  *
  * @category models
  * @since 4.0.0
  */
-export interface UniqueSymbol {
-  readonly _tag: "UniqueSymbol"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly symbol: symbol
+export interface Literal extends Keyword<"Literal"> {
+  readonly literal: SchemaAST.LiteralValue
 }
 
 /**
- * The `object` keyword type (matches any non-primitive).
+ * A unique global symbol representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface ObjectKeyword {
-  readonly _tag: "ObjectKeyword"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
+export interface UniqueSymbol extends Keyword<"UniqueSymbol"> {
+  readonly symbol: symbol
 }
 
 /**
- * A TypeScript-style enum. Each entry is a `[name, value]` pair.
+ * The object keyword representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Enum {
-  readonly _tag: "Enum"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly enums: ReadonlyArray<readonly [string, string | number]>
-}
+export interface ObjectKeyword extends Keyword<"ObjectKeyword"> {}
 
 /**
- * A template literal type composed of a sequence of parts (literals, strings,
- * numbers, etc.).
+ * An enum representation.
+ *
+ * **Details**
+ *
+ * Enum members are stored as native string or number values. Persistent
+ * codecs add an explicit type discriminator when encoding them.
  *
  * @category models
  * @since 4.0.0
  */
-export interface TemplateLiteral {
-  readonly _tag: "TemplateLiteral"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly parts: ReadonlyArray<Representation>
+export interface Enum extends Keyword<"Enum"> {
+  readonly enums: ReadonlyArray<readonly [string, string | number]>
 }
 
 /**
- * An array or tuple type.
- *
- * **Details**
- *
- * `elements` are the fixed positional elements, or tuple prefix, and each may
- * be optional. `rest` contains the variadic tail types; a single-element
- * `rest` with no `elements` produces a plain `Array<T>`. `checks` holds
- * array-specific constraints, such as minLength, maxLength, and unique checks.
- *
- * @see {@link Element}
- * @see {@link ArraysMeta}
+ * A template literal representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Arrays {
-  readonly _tag: "Arrays"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly elements: ReadonlyArray<Element>
-  readonly rest: ReadonlyArray<Representation>
-  readonly checks: ReadonlyArray<Check<ArraysMeta>>
+export interface TemplateLiteral extends Keyword<"TemplateLiteral"> {
+  readonly parts: ReadonlyArray<Representation>
 }
 
 /**
- * A positional element within an {@link Arrays} tuple.
- *
- * **Details**
- *
- * `isOptional` indicates whether this element can be absent. `type` is the
- * schema representation for this element's value.
- *
- * @see {@link Arrays}
+ * A tuple element.
  *
  * @category models
  * @since 4.0.0
@@ -356,39 +324,28 @@ export interface Element {
 }
 
 /**
- * An object/struct type with named properties and optional index signatures.
- *
- * **Details**
- *
- * `propertySignatures` are the explicitly named fields. `indexSignatures`
- * define catch-all key/value types, such as `Record<string, T>`. `checks`
- * holds object-specific constraints, such as minProperties and maxProperties.
- *
- * @see {@link PropertySignature}
- * @see {@link IndexSignature}
- * @see {@link ObjectsMeta}
+ * An array or tuple representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Objects {
-  readonly _tag: "Objects"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
-  readonly propertySignatures: ReadonlyArray<PropertySignature>
-  readonly indexSignatures: ReadonlyArray<IndexSignature>
-  readonly checks: ReadonlyArray<Check<ObjectsMeta>>
+export interface Arrays extends Keyword<"Arrays"> {
+  readonly elements: ReadonlyArray<Element>
+  readonly rest: ReadonlyArray<Representation>
 }
 
 /**
- * A named property within an {@link Objects} representation.
+ * A property signature.
  *
  * **Details**
  *
- * `name` is the property key, which can be a string, number, or symbol.
- * `isOptional` indicates whether the key can be absent. `isMutable` indicates
- * whether the property is mutable rather than readonly.
+ * The live representation stores the native property key. Persistent codecs
+ * add an explicit type discriminator when encoding it.
+ *
+ * **Gotchas**
  *
- * @see {@link Objects}
+ * Local symbols can be represented while the schema is live, but persistent
+ * codecs reject them because they cannot be reconstructed by identity.
  *
  * @category models
  * @since 4.0.0
@@ -402,15 +359,7 @@ export interface PropertySignature {
 }
 
 /**
- * An index signature, such as `[key: string]: number`, within an
- * {@link Objects}.
- *
- * **Details**
- *
- * `parameter` is the key type representation. `type` is the value type
- * representation.
- *
- * @see {@link Objects}
+ * An index signature.
  *
  * @category models
  * @since 4.0.0
@@ -421,34 +370,29 @@ export interface IndexSignature {
 }
 
 /**
- * A union of multiple representations.
- *
- * **Details**
+ * An object representation.
  *
- * `types` are the union members. `mode` controls JSON Schema output as either
- * `"anyOf"` (the default) or mutually exclusive `"oneOf"`.
+ * @category models
+ * @since 4.0.0
+ */
+export interface Objects extends Keyword<"Objects"> {
+  readonly propertySignatures: ReadonlyArray<PropertySignature>
+  readonly indexSignatures: ReadonlyArray<IndexSignature>
+}
+
+/**
+ * A union representation.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Union {
-  readonly _tag: "Union"
-  readonly annotations?: Schema.Annotations.Annotations | undefined
+export interface Union extends Keyword<"Union"> {
   readonly types: ReadonlyArray<Representation>
   readonly mode: "anyOf" | "oneOf"
 }
 
 /**
- * The core tagged union of all supported schema shapes.
- *
- * **Details**
- *
- * Each variant has a `_tag` discriminator. Switch on `_tag` to handle each
- * shape. Most variants carry optional `annotations` and some carry `checks`
- * for validation constraints.
- *
- * @see {@link Document}
- * @see {@link fromAST}
+ * The structural schema representation.
  *
  * @category models
  * @since 4.0.0
@@ -478,3430 +422,785 @@ export type Representation =
   | Union
 
 /**
- * A validation constraint attached to a type. Either a single {@link Filter}
- * or a {@link FilterGroup} combining multiple checks.
- *
- * @see {@link Filter}
- * @see {@link FilterGroup}
+ * A structural check.
  *
  * @category models
  * @since 4.0.0
  */
-export type Check<M> = Filter<M> | FilterGroup<M>
+export type Check = Filter | FilterGroup
 
 /**
- * A single validation constraint with typed metadata describing the check
- * (e.g. `{ _tag: "isMinLength", minLength: 3 }`).
- *
- * @see {@link Check}
+ * An opaque leaf check.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Filter<M> {
+export interface Filter {
   readonly _tag: "Filter"
-  readonly annotations?: Schema.Annotations.Filter | undefined
-  readonly meta: M
+  readonly representation?: CheckRepresentationAnnotation<Representation> | undefined
+  readonly annotations?: Schema.Annotations.Annotations | undefined
+  readonly aborted: boolean
 }
 
 /**
- * A group of validation constraints that are logically combined. Contains
- * at least one {@link Check}.
- *
- * @see {@link Check}
+ * A non-empty group of checks.
  *
  * @category models
  * @since 4.0.0
  */
-export interface FilterGroup<M> {
+export interface FilterGroup {
   readonly _tag: "FilterGroup"
-  readonly annotations?: Schema.Annotations.Filter | undefined
-  readonly checks: readonly [Check<M>, ...Array<Check<M>>]
+  readonly representation?: CheckRepresentationAnnotation<Representation> | undefined
+  readonly annotations?: Schema.Annotations.Annotations | undefined
+  readonly checks: readonly [Check, ...Array<Check>]
 }
 
 /**
- * Metadata union for string-specific validation checks (minLength, maxLength,
- * pattern, UUID, trimmed, etc.).
- *
- * @see {@link String}
- * @see {@link Check}
+ * Named representation definitions.
  *
  * @category models
  * @since 4.0.0
  */
-export type StringMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isStringFinite"
-  | "isStringBigInt"
-  | "isStringSymbol"
-  | "isMinLength"
-  | "isMaxLength"
-  | "isPattern"
-  | "isLengthBetween"
-  | "isTrimmed"
-  | "isUUID"
-  | "isGUID"
-  | "isULID"
-  | "isBase64"
-  | "isBase64Url"
-  | "isStartsWith"
-  | "isEndsWith"
-  | "isIncludes"
-  | "isUppercased"
-  | "isLowercased"
-  | "isCapitalized"
-  | "isUncapitalized"
-]
-
-/**
- * Metadata union for number-specific validation checks (int, finite,
- * min, max, multipleOf, between).
- *
- * @see {@link Number}
- * @see {@link Check}
+export interface References {
+  readonly [$ref: string]: Representation
+}
+
+/**
+ * A single representation and its definitions.
  *
  * @category models
  * @since 4.0.0
  */
-export type NumberMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isInt"
-  | "isFinite"
-  | "isMultipleOf"
-  | "isGreaterThanOrEqualTo"
-  | "isLessThanOrEqualTo"
-  | "isGreaterThan"
-  | "isLessThan"
-  | "isBetween"
-]
+export interface Document {
+  readonly representation: Representation
+  readonly references: References
+}
 
 /**
- * Metadata union for bigint-specific validation checks (min, max, between).
- *
- * @see {@link BigInt}
- * @see {@link Check}
+ * Multiple representations sharing definitions.
  *
  * @category models
  * @since 4.0.0
  */
-export type BigIntMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isGreaterThanOrEqualToBigInt"
-  | "isLessThanOrEqualToBigInt"
-  | "isGreaterThanBigInt"
-  | "isLessThanBigInt"
-  | "isBetweenBigInt"
-]
+export interface MultiDocument {
+  readonly representations: readonly [Representation, ...Array<Representation>]
+  readonly references: References
+}
 
 /**
- * Metadata union for array-specific validation checks (minLength, maxLength,
- * length, unique).
- *
- * @see {@link Arrays}
- * @see {@link Check}
+ * Live schemas reconstructed from a multi-document.
  *
  * @category models
  * @since 4.0.0
  */
-export type ArraysMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isMinLength"
-  | "isMaxLength"
-  | "isLengthBetween"
-  | "isUnique"
-]
+export interface SchemaMultiDocument {
+  readonly schemas: readonly [Schema.Top, ...Array<Schema.Top>]
+  readonly definitions: Readonly<Record<string, Schema.Top>>
+}
 
 /**
- * Metadata union for object-specific validation checks (minProperties,
- * maxProperties, propertiesLength, propertyNames).
- *
- * @see {@link Objects}
- * @see {@link Check}
+ * Reviver for a declaration.
  *
  * @category models
  * @since 4.0.0
  */
-export type ObjectsMeta =
-  | Schema.Annotations.BuiltInMetaDefinitions[
-    | "isMinProperties"
-    | "isMaxProperties"
-    | "isPropertiesLengthBetween"
-  ]
-  | { readonly _tag: "isPropertyNames"; readonly propertyNames: Representation }
+export interface DeclarationReviver<P> {
+  readonly id: string
+  readonly payloadSchema: Schema.Decoder<P>
+  readonly revive: (input: {
+    readonly payload: P
+    readonly typeParameters: ReadonlyArray<Schema.Top>
+    readonly annotations: Schema.Annotations.Annotations | undefined
+  }) => Schema.Top
+}
 
 /**
- * Metadata union for Date-specific validation checks (valid, min, max, between).
- *
- * @see {@link Declaration}
- * @see {@link DeclarationMeta}
+ * Reviver for a leaf check.
  *
  * @category models
  * @since 4.0.0
  */
-export type DateMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isDateValid"
-  | "isGreaterThanDate"
-  | "isGreaterThanOrEqualToDate"
-  | "isLessThanDate"
-  | "isLessThanOrEqualToDate"
-  | "isBetweenDate"
-]
+export interface FilterReviver<P> {
+  readonly id: string
+  readonly payloadSchema: Schema.Decoder<P>
+  readonly revive: (input: {
+    readonly payload: P
+    readonly schemas: ReadonlyArray<Schema.Top>
+    readonly annotations: Schema.Annotations.Filter | undefined
+  }) => SchemaAST.Filter<any>
+}
 
 /**
- * Metadata union for size-based validation checks (minSize, maxSize, size).
- * Used for collection types like `Set`, `Map`.
- *
- * @see {@link Declaration}
- * @see {@link DeclarationMeta}
+ * Reviver for a check group.
  *
  * @category models
  * @since 4.0.0
  */
-export type SizeMeta = Schema.Annotations.BuiltInMetaDefinitions[
-  | "isMinSize"
-  | "isMaxSize"
-  | "isSizeBetween"
-]
+export interface FilterGroupReviver<P> {
+  readonly id: string
+  readonly payloadSchema: Schema.Decoder<P>
+  readonly revive: (input: {
+    readonly payload: P
+    readonly schemas: ReadonlyArray<Schema.Top>
+    readonly annotations: Schema.Annotations.Filter | undefined
+  }) => SchemaAST.FilterGroup<any>
+}
 
 /**
- * Metadata union for {@link Declaration} checks — either {@link DateMeta}
- * or {@link SizeMeta}.
+ * A check reviver.
  *
  * @category models
  * @since 4.0.0
  */
-export type DeclarationMeta = DateMeta | SizeMeta
-
-/** @internal */
-export type Meta = StringMeta | NumberMeta | BigIntMeta | ArraysMeta | ObjectsMeta | DeclarationMeta
+export type CheckReviver<P> = FilterReviver<P> | FilterGroupReviver<P>
 
 /**
- * A string-keyed map of named {@link Representation} definitions. Used by
- * {@link Document} and {@link MultiDocument} for `$ref` resolution (analogous
- * to JSON Schema `$defs`).
- *
- * @see {@link Reference}
- * @see {@link Document}
+ * A typed reviver.
  *
  * @category models
  * @since 4.0.0
  */
-export interface References {
-  readonly [$ref: string]: Representation
-}
+export type Reviver<P> = DeclarationReviver<P> | CheckReviver<P>
 
 /**
- * A single {@link Representation} together with its named {@link References}.
- *
- * **When to use**
- *
- * Use when representing a single Schema AST together with its named references
- * before reconstructing a runtime Schema, converting to JSON Schema, or
- * wrapping it as a {@link MultiDocument}.
- *
- * @see {@link MultiDocument}
- * @see {@link fromAST}
+ * A reviver erased only at collection boundaries.
  *
  * @category models
  * @since 4.0.0
  */
-export type Document = {
-  readonly representation: Representation
-  readonly references: References
-}
+export type AnyReviver = Reviver<any>
 
 /**
- * One or more {@link Representation}s sharing a common {@link References} map.
- *
- * **When to use**
+ * Creates a declaration reviver while inferring its payload type from `payloadSchema`.
  *
- * Use when you use {@link fromASTs} to create this from multiple Schema ASTs,
- * {@link toCodeDocument} to generate TypeScript code, and
- * {@link toJsonSchemaMultiDocument} to convert to JSON Schema.
- *
- * @see {@link Document}
- * @see {@link fromASTs}
- *
- * @category models
+ * @category constructors
  * @since 4.0.0
  */
-export type MultiDocument = {
-  readonly representations: readonly [Representation, ...Array<Representation>]
-  readonly references: References
-}
-
-// -----------------------------------------------------------------------------
-// schemas
-// -----------------------------------------------------------------------------
-
-const Representation$ref = Schema.suspend(() => $Representation)
-
-const toJsonAnnotationsBlacklist: Set<string> = new Set([
-  ...InternalRepresentation.fromASTBlacklist,
-  "expected",
-  "contentMediaType",
-  "contentSchema"
-])
+export const makeDeclarationReviver: <P>(
+  id: string,
+  payloadSchema: Schema.Decoder<P>,
+  revive: DeclarationReviver<P>["revive"]
+) => DeclarationReviver<P> = InternalSchema.makeDeclarationReviver
 
 /**
- * A tree of primitive values used to serialize annotations to JSON.
+ * Creates a filter reviver while inferring its payload type from `payloadSchema`.
  *
- * @category Tree
+ * @category constructors
  * @since 4.0.0
  */
-export type PrimitiveTree = Schema.Tree<null | number | boolean | bigint | symbol | string>
+export const makeFilterReviver: <P>(
+  id: string,
+  payloadSchema: Schema.Decoder<P>,
+  revive: FilterReviver<P>["revive"]
+) => FilterReviver<P> = InternalSchema.makeFilterReviver
 
 /**
- * Schema for {@link PrimitiveTree}.
- *
- * **When to use**
- *
- * Use to validate recursive annotation metadata trees whose leaves are `null`,
- * `number`, `boolean`, `bigint`, `symbol`, or `string`.
- *
- * @see {@link PrimitiveTree} for the recursive tree type accepted by this codec
- * @see {@link $Annotations} for the annotation codec that filters values through this codec
+ * Creates a filter group reviver while inferring its payload type from `payloadSchema`.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
-export const $PrimitiveTree: Schema.Codec<PrimitiveTree> = Schema.Tree(
-  Schema.Union([
-    Schema.Null,
-    Schema.Number, // allows NaN, Infinity, -Infinity
-    Schema.Boolean,
-    Schema.BigInt,
-    Schema.Symbol,
-    Schema.String
-  ])
-)
-
-const isPrimitiveTree = Schema.is($PrimitiveTree)
+export const makeFilterGroupReviver: <P>(
+  id: string,
+  payloadSchema: Schema.Decoder<P>,
+  revive: FilterGroupReviver<P>["revive"]
+) => FilterGroupReviver<P> = InternalSchema.makeFilterGroupReviver
 
 /**
- * Schema for serializing public `Schema.Annotations.Annotations` values. It
- * filters out internal annotation keys and non-primitive values during
- * encoding.
+ * Options for importing JSON Schema Draft 2020-12 documents.
  *
  * **When to use**
  *
- * Use to serialize schema annotations in representation schemas while retaining
- * only primitive-tree metadata.
+ * Use when each JSON Schema node must be transformed before it is translated.
  *
- * **Details**
- *
- * Decoding is passthrough. Encoding removes internal annotation keys and values
- * that are not accepted by `$PrimitiveTree`.
+ * **Gotchas**
  *
- * @see {@link $PrimitiveTree} for the codec used to filter annotation values
+ * `onEnter` must return a JSON Schema object. Its result is used directly, and exceptions raised by the callback pass through unchanged.
  *
- * @category schemas
+ * @category models
  * @since 4.0.0
  */
-export const $Annotations = Schema.Record(Schema.String, Schema.Unknown).pipe(
-  Schema.encodeTo(Schema.Record(Schema.String, $PrimitiveTree), {
-    decode: SchemaGetter.passthrough(),
-    encode: SchemaGetter.transformOptional(Option.flatMap((r) => {
-      const out: Record<string, typeof $PrimitiveTree["Type"]> = {}
-      for (const [k, v] of Object.entries(r)) {
-        if (!toJsonAnnotationsBlacklist.has(k) && isPrimitiveTree(v)) {
-          out[k] = v
-        }
-      }
-      return Rec.isEmptyRecord(out) ? Option.none() : Option.some(out)
-    }))
-  })
-).annotate({ identifier: "Annotations" })
+export interface FromJsonSchemaOptions {
+  readonly onEnter?: ((schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
+}
 
 /**
- * Schema for the {@link Null} representation node.
+ * Runtime and TypeScript source generated for one schema.
  *
- * @category schemas
+ * @category models
  * @since 4.0.0
  */
-export const $Null = Schema.Struct({
-  _tag: Schema.tag("Null"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Null" })
+export interface Code {
+  readonly runtime: string
+  readonly Type: string
+}
 
 /**
- * Schema for the {@link Undefined} representation node.
+ * Creates generated runtime and TypeScript source strings for a schema.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
-export const $Undefined = Schema.Struct({
-  _tag: Schema.tag("Undefined"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Undefined" })
+export const makeCode: (runtime: string, Type: string) => Code = InternalToCodeDocument.makeCode
 
 /**
- * Schema for the {@link Void} representation node.
+ * Auxiliary source artifact emitted while generating schema code.
  *
- * @category schemas
+ * @category models
  * @since 4.0.0
  */
-export const $Void = Schema.Struct({
-  _tag: Schema.tag("Void"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Void" })
+export type Artifact =
+  | {
+    readonly _tag: "Symbol"
+    readonly identifier: string
+    readonly code: Code
+  }
+  | {
+    readonly _tag: "Enum"
+    readonly identifier: string
+    readonly code: Code
+  }
+  | {
+    readonly _tag: "Import"
+    readonly importDeclaration: string
+  }
 
 /**
- * Schema for the {@link Never} representation node.
+ * Generated schema code together with named references and auxiliary artifacts.
  *
- * @category schemas
+ * @category models
  * @since 4.0.0
  */
-export const $Never = Schema.Struct({
-  _tag: Schema.tag("Never"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Never" })
-
-/**
- * Schema for the {@link Unknown} representation node.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $Unknown = Schema.Struct({
-  _tag: Schema.tag("Unknown"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Unknown" })
+export interface CodeDocument {
+  readonly codes: ReadonlyArray<Code>
+  readonly references: {
+    readonly nonRecursives: ReadonlyArray<{
+      readonly $ref: string
+      readonly code: Code
+    }>
+    readonly recursives: Readonly<Record<string, Code>>
+  }
+  readonly artifacts: ReadonlyArray<Artifact>
+}
 
 /**
- * Schema for the {@link Any} representation node.
+ * Lowers the encoded side of an AST to a live representation document.
  *
- * @category schemas
+ * **Details**
+ *
+ * Apply `SchemaAST.toType` to the AST first to lower its type side instead.
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export const $Any = Schema.Struct({
-  _tag: Schema.tag("Any"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Any" })
-
-const $IsStringFinite = Schema.Struct({
-  _tag: Schema.tag("isStringFinite"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsStringFinite" })
-
-const $IsStringBigInt = Schema.Struct({
-  _tag: Schema.tag("isStringBigInt"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsStringBigInt" })
-
-const $IsStringSymbol = Schema.Struct({
-  _tag: Schema.tag("isStringSymbol"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsStringSymbol" })
-
-const $IsTrimmed = Schema.Struct({
-  _tag: Schema.tag("isTrimmed"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsTrimmed" })
-
-const $IsUUID = Schema.Struct({
-  _tag: Schema.tag("isUUID"),
-  regExp: Schema.RegExp,
-  version: Schema.UndefinedOr(Schema.Literals([1, 2, 3, 4, 5, 6, 7, 8]))
-}).annotate({ identifier: "IsUUID" })
-
-const $IsGUID = Schema.Struct({
-  _tag: Schema.tag("isGUID"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsGUID" })
-
-const $IsULID = Schema.Struct({
-  _tag: Schema.tag("isULID"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsULID" })
-
-const $IsBase64 = Schema.Struct({
-  _tag: Schema.tag("isBase64"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsBase64" })
-
-const $IsBase64Url = Schema.Struct({
-  _tag: Schema.tag("isBase64Url"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsBase64Url" })
-
-const $IsStartsWith = Schema.Struct({
-  _tag: Schema.tag("isStartsWith"),
-  startsWith: Schema.String,
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsStartsWith" })
-
-const $IsEndsWith = Schema.Struct({
-  _tag: Schema.tag("isEndsWith"),
-  endsWith: Schema.String,
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsEndsWith" })
-
-const $IsIncludes = Schema.Struct({
-  _tag: Schema.tag("isIncludes"),
-  includes: Schema.String,
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsIncludes" })
-
-const $IsUppercased = Schema.Struct({
-  _tag: Schema.tag("isUppercased"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsUppercased" })
-
-const $IsLowercased = Schema.Struct({
-  _tag: Schema.tag("isLowercased"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsLowercased" })
-
-const $IsCapitalized = Schema.Struct({
-  _tag: Schema.tag("isCapitalized"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsCapitalized" })
-
-const $IsUncapitalized = Schema.Struct({
-  _tag: Schema.tag("isUncapitalized"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsUncapitalized" })
-
-const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
-
-const $IsMinLength = Schema.Struct({
-  _tag: Schema.tag("isMinLength"),
-  minLength: NonNegativeInt
-}).annotate({ identifier: "IsMinLength" })
-
-const $IsMaxLength = Schema.Struct({
-  _tag: Schema.tag("isMaxLength"),
-  maxLength: NonNegativeInt
-}).annotate({ identifier: "IsMaxLength" })
-
-const $IsLengthBetween = Schema.Struct({
-  _tag: Schema.tag("isLengthBetween"),
-  minimum: NonNegativeInt,
-  maximum: NonNegativeInt
-}).annotate({ identifier: "IsLengthBetween" })
-
-const $IsPattern = Schema.Struct({
-  _tag: Schema.tag("isPattern"),
-  regExp: Schema.RegExp
-}).annotate({ identifier: "IsPattern" })
-
-/**
- * Schema for {@link StringMeta}.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $StringMeta = Schema.Union([
-  $IsStringFinite,
-  $IsStringBigInt,
-  $IsStringSymbol,
-  $IsTrimmed,
-  $IsUUID,
-  $IsGUID,
-  $IsULID,
-  $IsBase64,
-  $IsBase64Url,
-  $IsStartsWith,
-  $IsEndsWith,
-  $IsIncludes,
-  $IsUppercased,
-  $IsLowercased,
-  $IsCapitalized,
-  $IsUncapitalized,
-  $IsMinLength,
-  $IsMaxLength,
-  $IsPattern,
-  $IsLengthBetween
-]).annotate({ identifier: "StringMeta" })
-
-function makeCheck<T>(meta: Schema.Codec<T>, identifier: string) {
-  const Check$ref = Schema.suspend(() => Check)
-  const Check: Schema.Codec<Check<T>> = Schema.Union([
-    Schema.Struct({
-      _tag: Schema.tag("Filter"),
-      annotations: Schema.optional($Annotations),
-      meta
-    }).annotate({ identifier: `${identifier}Filter` }),
-    Schema.Struct({
-      _tag: Schema.tag("FilterGroup"),
-      annotations: Schema.optional($Annotations),
-      checks: Schema.NonEmptyArray(Check$ref)
-    }).annotate({ identifier: `${identifier}FilterGroup` })
-  ]).annotate({ identifier: `${identifier}Check` })
-  return Check
+export function toRepresentation(ast: SchemaAST.AST): Document {
+  return InternalToRepresentation.toRepresentation(ast)
 }
 
 /**
- * Schema for the {@link String} representation node.
+ * Lowers one or more AST encoded sides in a shared reference environment.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $String = Schema.Struct({
-  _tag: Schema.tag("String"),
-  annotations: Schema.optional($Annotations),
-  checks: Schema.Array(makeCheck($StringMeta, "String")),
-  contentMediaType: Schema.optional(Schema.String),
-  contentSchema: Schema.optional(Representation$ref)
-}).annotate({ identifier: "String" })
-
-const $IsInt = Schema.Struct({
-  _tag: Schema.tag("isInt")
-}).annotate({ identifier: "IsInt" })
-
-const $IsMultipleOf = Schema.Struct({
-  _tag: Schema.tag("isMultipleOf"),
-  divisor: Schema.Finite
-}).annotate({ identifier: "IsMultipleOf" })
-
-const $IsFinite = Schema.Struct({
-  _tag: Schema.tag("isFinite")
-}).annotate({ identifier: "IsFinite" })
-
-const $IsGreaterThan = Schema.Struct({
-  _tag: Schema.tag("isGreaterThan"),
-  exclusiveMinimum: Schema.Finite
-}).annotate({ identifier: "IsGreaterThan" })
-
-const $IsGreaterThanOrEqualTo = Schema.Struct({
-  _tag: Schema.tag("isGreaterThanOrEqualTo"),
-  minimum: Schema.Finite
-}).annotate({ identifier: "IsGreaterThanOrEqualTo" })
-
-const $IsLessThan = Schema.Struct({
-  _tag: Schema.tag("isLessThan"),
-  exclusiveMaximum: Schema.Finite
-}).annotate({ identifier: "IsLessThan" })
-
-const $IsLessThanOrEqualTo = Schema.Struct({
-  _tag: Schema.tag("isLessThanOrEqualTo"),
-  maximum: Schema.Finite
-}).annotate({ identifier: "IsLessThanOrEqualTo" })
-
-const $IsBetween = Schema.Struct({
-  _tag: Schema.tag("isBetween"),
-  minimum: Schema.Finite,
-  maximum: Schema.Finite,
-  exclusiveMinimum: Schema.optional(Schema.Boolean),
-  exclusiveMaximum: Schema.optional(Schema.Boolean)
-}).annotate({ identifier: "IsBetween" })
-
-/**
- * Schema for {@link NumberMeta}.
+ * **Details**
+ *
+ * Apply `SchemaAST.toType` to an AST first to lower its type side instead.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
-export const $NumberMeta = Schema.Union([
-  $IsInt,
-  $IsMultipleOf,
-  $IsFinite,
-  $IsGreaterThan,
-  $IsGreaterThanOrEqualTo,
-  $IsLessThan,
-  $IsLessThanOrEqualTo,
-  $IsBetween
-]).annotate({ identifier: "NumberMeta" })
+export function toRepresentations(
+  asts: readonly [SchemaAST.AST, ...Array<SchemaAST.AST>]
+): MultiDocument {
+  return InternalToRepresentation.toRepresentations(asts)
+}
 
 /**
- * Schema for the {@link Number} representation node.
+ * Converts live schemas and their named definitions to a shared representation document.
+ *
+ * **When to use**
+ *
+ * Use when schemas with shared or unreachable definitions must be passed to representation compilers such as `toCodeDocument`.
+ *
+ * **Gotchas**
+ *
+ * Every schema is projected to its encoded side. Definitions are preserved even when no root reaches them.
  *
- * @category schemas
+ * @see {@link toRepresentations} for converting AST roots without an explicit definition map
+ * @see {@link toCodeDocument} for generating code from the result
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export const $Number = Schema.Struct({
-  _tag: Schema.tag("Number"),
-  annotations: Schema.optional($Annotations),
-  checks: Schema.Array(makeCheck($NumberMeta, "Number"))
-}).annotate({ identifier: "Number" })
+export function fromSchemaMultiDocument(document: SchemaMultiDocument): MultiDocument {
+  return InternalToRepresentation.fromSchemaMultiDocument(document)
+}
 
 /**
- * Schema for the {@link Boolean} representation node.
+ * Wraps a single representation document as a multi-document with one root.
+ *
+ * **When to use**
+ *
+ * Use when an API such as `toCodeDocument` requires a `MultiDocument`.
  *
- * @category schemas
+ * @category transforming
  * @since 4.0.0
  */
-export const $Boolean = Schema.Struct({
-  _tag: Schema.tag("Boolean"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Boolean" })
-
-const $IsGreaterThanBigInt = Schema.Struct({
-  _tag: Schema.tag("isGreaterThanBigInt"),
-  exclusiveMinimum: Schema.BigInt
-}).annotate({ identifier: "IsGreaterThanBigInt" })
-
-const $IsGreaterThanOrEqualToBigInt = Schema.Struct({
-  _tag: Schema.tag("isGreaterThanOrEqualToBigInt"),
-  minimum: Schema.BigInt
-}).annotate({ identifier: "IsGreaterThanOrEqualToBigInt" })
-
-const $IsLessThanBigInt = Schema.Struct({
-  _tag: Schema.tag("isLessThanBigInt"),
-  exclusiveMaximum: Schema.BigInt
-}).annotate({ identifier: "IsLessThanBigInt" })
-
-const $IsLessThanOrEqualToBigInt = Schema.Struct({
-  _tag: Schema.tag("isLessThanOrEqualToBigInt"),
-  maximum: Schema.BigInt
-}).annotate({ identifier: "IsLessThanOrEqualToBigInt" })
-
-const $IsBetweenBigInt = Schema.Struct({
-  _tag: Schema.tag("isBetweenBigInt"),
-  minimum: Schema.BigInt,
-  maximum: Schema.BigInt,
-  exclusiveMinimum: Schema.optional(Schema.Boolean),
-  exclusiveMaximum: Schema.optional(Schema.Boolean)
-}).annotate({ identifier: "IsBetweenBigInt" })
-
-const $BigIntMeta = Schema.Union([
-  $IsGreaterThanBigInt,
-  $IsGreaterThanOrEqualToBigInt,
-  $IsLessThanBigInt,
-  $IsLessThanOrEqualToBigInt,
-  $IsBetweenBigInt
-]).annotate({ identifier: "BigIntMeta" })
+export function toMultiDocument(document: Document): MultiDocument {
+  return {
+    representations: [document.representation],
+    references: document.references
+  }
+}
 
 /**
- * Schema for the {@link BigInt} representation node.
+ * Compiles a live representation document to JSON Schema Draft 2020-12.
  *
  * **When to use**
  *
- * Use to encode, decode, or validate serialized `BigInt` representation nodes,
- * not application `bigint` values.
+ * Use when you need JSON Schema output from a representation whose checks carry compiler annotations.
  *
- * **Details**
+ * **Gotchas**
  *
- * Accepts representation nodes with `_tag: "BigInt"`, optional annotations,
- * and bigint-specific validation metadata in `checks`.
+ * Opaque declarations are represented by an unconstrained JSON Schema. Check callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
- * @see {@link BigIntMeta} for the metadata accepted by the `checks` array
+ * @see {@link toJsonSchemaMultiDocument} for multiple roots sharing definitions
  *
- * @category schemas
+ * @category transforming
  * @since 4.0.0
  */
-export const $BigInt = Schema.Struct({
-  _tag: Schema.tag("BigInt"),
-  annotations: Schema.optional($Annotations),
-  checks: Schema.Array(makeCheck($BigIntMeta, "BigInt"))
-}).annotate({ identifier: "BigInt" })
+export function toJsonSchemaDocument(
+  document: Document,
+  options?: Schema.ToJsonSchemaOptions
+): JsonSchema.Document<"draft-2020-12"> {
+  return InternalToJsonSchemaDocument.toJsonSchemaDocument(document, options)
+}
 
 /**
- * Schema for the {@link Symbol} representation node.
+ * Compiles multiple live representations to a shared JSON Schema Draft 2020-12 document.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Symbol = Schema.Struct({
-  _tag: Schema.tag("Symbol"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Symbol" })
-
-/**
- * Schema for the literal value types allowed in a {@link Literal} node
- * (string, finite number, boolean, or bigint).
+ * **When to use**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $LiteralValue = Schema.Union([
-  Schema.String,
-  Schema.Finite,
-  Schema.Boolean,
-  Schema.BigInt
-]).annotate({ identifier: "LiteralValue" })
-
-/**
- * Schema for the {@link Literal} representation node.
+ * Use when several representation roots must share the same JSON Schema definitions.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Literal = Schema.Struct({
-  _tag: Schema.tag("Literal"),
-  annotations: Schema.optional($Annotations),
-  literal: $LiteralValue
-}).annotate({ identifier: "Literal" })
-
-/**
- * Schema for the {@link UniqueSymbol} representation node.
+ * **Gotchas**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $UniqueSymbol = Schema.Struct({
-  _tag: Schema.tag("UniqueSymbol"),
-  annotations: Schema.optional($Annotations),
-  symbol: Schema.Symbol
-}).annotate({ identifier: "UniqueSymbol" })
-
-/**
- * Schema for the {@link ObjectKeyword} representation node.
+ * Every definition is compiled, including definitions that are not reachable from a root.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $ObjectKeyword = Schema.Struct({
-  _tag: Schema.tag("ObjectKeyword"),
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "ObjectKeyword" })
-
-/**
- * Schema for the {@link Enum} representation node.
+ * @see {@link toJsonSchemaDocument} for a single root
  *
- * @category schemas
+ * @category transforming
  * @since 4.0.0
  */
-export const $Enum = Schema.Struct({
-  _tag: Schema.tag("Enum"),
-  annotations: Schema.optional($Annotations),
-  enums: Schema.Array(
-    Schema.Tuple([
-      Schema.String,
-      Schema.Union([
-        Schema.String,
-        Schema.Number // NaN, Infinity, -Infinity are allowed enum values
-      ])
-    ])
-  )
-}).annotate({ identifier: "Enum" })
+export function toJsonSchemaMultiDocument(
+  document: MultiDocument,
+  options?: Schema.ToJsonSchemaOptions
+): JsonSchema.MultiDocument<"draft-2020-12"> {
+  return InternalToJsonSchemaDocument.toJsonSchemaMultiDocument(document, options)
+}
 
 /**
- * Schema for the {@link TemplateLiteral} representation node.
+ * Generates TypeScript source for live schema representations and their definitions.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $TemplateLiteral = Schema.Struct({
-  _tag: Schema.tag("TemplateLiteral"),
-  annotations: Schema.optional($Annotations),
-  parts: Schema.Array(Representation$ref)
-}).annotate({ identifier: "TemplateLiteral" })
-
-/**
- * Schema for the {@link Element} type (positional tuple element).
+ * **When to use**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Element = Schema.Struct({
-  isOptional: Schema.Boolean,
-  type: Representation$ref,
-  annotations: Schema.optional($Annotations)
-}).annotate({ identifier: "Element" })
-
-const $IsUnique = Schema.Struct({
-  _tag: Schema.tag("isUnique")
-}).annotate({ identifier: "IsUnique" })
-
-const $ArraysMeta = Schema.Union([
-  $IsMinLength,
-  $IsMaxLength,
-  $IsLengthBetween,
-  $IsUnique
-]).annotate({ identifier: "ArraysMeta" })
-
-/**
- * Schema for the {@link Arrays} representation node.
+ * Use when custom declarations and checks provide `toCode` callbacks and must be emitted without a central handler registry.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Arrays = Schema.Struct({
-  _tag: Schema.tag("Arrays"),
-  annotations: Schema.optional($Annotations),
-  elements: Schema.Array($Element),
-  rest: Schema.Array(Representation$ref),
-  checks: Schema.Array(makeCheck($ArraysMeta, "Arrays"))
-}).annotate({ identifier: "Arrays" })
-
-/**
- * Schema for the {@link PropertySignature} type.
+ * **Gotchas**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $PropertySignature = Schema.Struct({
-  annotations: Schema.optional($Annotations),
-  name: Schema.PropertyKey,
-  type: Representation$ref,
-  isOptional: Schema.Boolean,
-  isMutable: Schema.Boolean
-}).annotate({ identifier: "PropertySignature" })
-
-/**
- * Schema for the {@link IndexSignature} type.
+ * Opaque declarations and leaf checks require `toCode` callbacks. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
- * @category schemas
+ * @category transforming
  * @since 4.0.0
  */
-export const $IndexSignature = Schema.Struct({
-  parameter: Representation$ref,
-  type: Representation$ref
-}).annotate({ identifier: "IndexSignature" })
+export function toCodeDocument(document: MultiDocument): CodeDocument {
+  return InternalToCodeDocument.toCodeDocument(document)
+}
 
-const $IsMinProperties = Schema.Struct({
-  _tag: Schema.tag("isMinProperties"),
-  minProperties: NonNegativeInt
-}).annotate({ identifier: "IsMinProperties" })
+const RepresentationSchema = Schema.suspend(
+  (): Schema.Codec<Representation, unknown> => RepresentationUnion
+)
+const RepresentationsSchema = Schema.Array(RepresentationSchema)
 
-const $IsMaxProperties = Schema.Struct({
-  _tag: Schema.tag("isMaxProperties"),
-  maxProperties: NonNegativeInt
-}).annotate({ identifier: "IsMaxProperties" })
+const RepresentationAnnotationSchema = Schema.Struct({
+  id: Schema.NonEmptyString,
+  payload: Schema.Json
+})
 
-const $IsPropertiesLengthBetween = Schema.Struct({
-  _tag: Schema.tag("isPropertiesLengthBetween"),
-  minimum: NonNegativeInt,
-  maximum: NonNegativeInt
-}).annotate({ identifier: "IsPropertiesLengthBetween" })
+const CheckRepresentationAnnotationSchema = Schema.Struct({
+  ...RepresentationAnnotationSchema.fields,
+  schemas: Schema.optional(RepresentationsSchema)
+})
 
-const $IsPropertyNames = Schema.Struct({
-  _tag: Schema.tag("isPropertyNames"),
-  propertyNames: Representation$ref
-}).annotate({ identifier: "IsPropertyNames" })
+const LiveAnnotationsSchema = Schema.Record(Schema.String, Schema.Unknown)
+const JsonAnnotationsSchema = Schema.Record(Schema.String, Schema.Json)
 
-/**
- * Schema for {@link ObjectsMeta}.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $ObjectsMeta = Schema.Union([
-  $IsMinProperties,
-  $IsMaxProperties,
-  $IsPropertiesLengthBetween,
-  $IsPropertyNames
-]).annotate({ identifier: "ObjectsMeta" })
+function pruneAnnotations(
+  annotations: Readonly<Record<string, unknown>>
+): Option.Option<Readonly<Record<string, Schema.Json>>> {
+  const out: Record<string, Schema.Json> = {}
+  for (const [key, value] of Object.entries(annotations)) {
+    if (SchemaAST.isJson(value)) {
+      InternalRecord.assignProperty(out, key, value)
+    }
+  }
+  return Object.keys(out).length === 0 ? Option.none() : Option.some(out)
+}
 
-/**
- * Schema for the {@link Objects} representation node.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $Objects = Schema.Struct({
-  _tag: Schema.tag("Objects"),
-  annotations: Schema.optional($Annotations),
-  propertySignatures: Schema.Array($PropertySignature),
-  indexSignatures: Schema.Array($IndexSignature),
-  checks: Schema.Array(makeCheck($ObjectsMeta, "Objects"))
-}).annotate({ identifier: "Objects" })
+const AnnotationsSchema = Schema.optional(LiveAnnotationsSchema).pipe(
+  Schema.encodeTo(Schema.optionalKey(JsonAnnotationsSchema), {
+    decode: SchemaGetter.passthroughSubtype(),
+    encode: SchemaGetter.transformOptional((annotations) =>
+      Option.isNone(annotations) || annotations.value === undefined
+        ? Option.none()
+        : pruneAnnotations(annotations.value)
+    )
+  })
+)
 
-/**
- * Schema for the {@link Union} representation node.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $Union = Schema.Struct({
+const CheckSchema = Schema.suspend((): Schema.Codec<Check, unknown> => CheckUnion)
+const ChecksSchema = Schema.Array(CheckSchema)
+const KeywordFields = {
+  annotations: AnnotationsSchema,
+  checks: ChecksSchema
+}
+const FilterSchema = Schema.Struct({
+  _tag: Schema.tag("Filter"),
+  representation: CheckRepresentationAnnotationSchema,
+  annotations: AnnotationsSchema,
+  aborted: Schema.Boolean
+})
+const FilterGroupSchema = Schema.Struct({
+  _tag: Schema.tag("FilterGroup"),
+  representation: Schema.optional(CheckRepresentationAnnotationSchema),
+  annotations: AnnotationsSchema,
+  checks: Schema.NonEmptyArray(CheckSchema)
+})
+const CheckUnion = Schema.Union([FilterSchema, FilterGroupSchema])
+
+function makeKeywordSchema<Tag extends Exclude<Representation["_tag"], "Reference">>(tag: Tag) {
+  return Schema.Struct({
+    _tag: Schema.tag(tag),
+    ...KeywordFields
+  })
+}
+
+const DeclarationSchema = Schema.Struct({
+  _tag: Schema.tag("Declaration"),
+  representation: RepresentationAnnotationSchema,
+  annotations: AnnotationsSchema,
+  typeParameters: RepresentationsSchema,
+  checks: ChecksSchema
+})
+const SuspendSchema = Schema.Struct({
+  _tag: Schema.tag("Suspend"),
+  annotations: AnnotationsSchema,
+  checks: Schema.Tuple([]),
+  thunk: RepresentationSchema
+})
+function makeValueSchema<Type extends string, Value>(type: Type, value: Schema.Codec<Value>) {
+  return value.pipe(
+    Schema.encodeTo(Schema.Struct({ type: Schema.tag(type), value }), {
+      decode: SchemaGetter.transform((encoded: { readonly type: Type; readonly value: Value }) => encoded.value),
+      encode: SchemaGetter.transform((value: Value) => ({ type, value }))
+    })
+  )
+}
+const StringValueCodec = makeValueSchema("string", Schema.String)
+const NumberValueCodec = makeValueSchema("number", Schema.Number)
+const LiteralSchema = Schema.Struct({
+  _tag: Schema.tag("Literal"),
+  ...KeywordFields,
+  literal: Schema.Union([
+    StringValueCodec,
+    makeValueSchema("number", Schema.Finite),
+    makeValueSchema("bigint", Schema.BigInt),
+    makeValueSchema("boolean", Schema.Boolean)
+  ])
+})
+const UniqueSymbolSchema = Schema.Struct({
+  _tag: Schema.tag("UniqueSymbol"),
+  ...KeywordFields,
+  symbol: Schema.Symbol
+})
+const EnumSchema = Schema.Struct({
+  _tag: Schema.tag("Enum"),
+  ...KeywordFields,
+  enums: Schema.Array(Schema.Tuple([
+    Schema.String,
+    Schema.Union([StringValueCodec, NumberValueCodec])
+  ]))
+})
+const TemplateLiteralSchema = Schema.Struct({
+  _tag: Schema.tag("TemplateLiteral"),
+  ...KeywordFields,
+  parts: RepresentationsSchema
+})
+const ElementSchema = Schema.Struct({
+  isOptional: Schema.Boolean,
+  type: RepresentationSchema,
+  annotations: AnnotationsSchema
+})
+const ArraysSchema = Schema.Struct({
+  _tag: Schema.tag("Arrays"),
+  ...KeywordFields,
+  elements: Schema.Array(ElementSchema),
+  rest: RepresentationsSchema
+})
+const PropertySignatureSchema = Schema.Struct({
+  name: Schema.Union([
+    StringValueCodec,
+    NumberValueCodec,
+    makeValueSchema("symbol", Schema.Symbol)
+  ]),
+  type: RepresentationSchema,
+  isOptional: Schema.Boolean,
+  isMutable: Schema.Boolean,
+  annotations: AnnotationsSchema
+})
+const IndexSignatureSchema = Schema.Struct({
+  parameter: RepresentationSchema,
+  type: RepresentationSchema
+})
+const ObjectsSchema = Schema.Struct({
+  _tag: Schema.tag("Objects"),
+  ...KeywordFields,
+  propertySignatures: Schema.Array(PropertySignatureSchema),
+  indexSignatures: Schema.Array(IndexSignatureSchema)
+})
+const UnionSchema = Schema.Struct({
   _tag: Schema.tag("Union"),
-  annotations: Schema.optional($Annotations),
-  types: Schema.Array(Representation$ref),
+  ...KeywordFields,
+  types: RepresentationsSchema,
   mode: Schema.Literals(["anyOf", "oneOf"])
-}).annotate({ identifier: "Union" })
-
-/**
- * Schema for the {@link Reference} representation node.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $Reference = Schema.Struct({
+})
+const ReferenceSchema = Schema.Struct({
   _tag: Schema.tag("Reference"),
-  $ref: Schema.String
-}).annotate({ identifier: "Reference" })
-
-const $IsDateValid = Schema.Struct({
-  _tag: Schema.tag("isDateValid")
-}).annotate({ identifier: "IsDateValid" })
-
-const $IsGreaterThanDate = Schema.Struct({
-  _tag: Schema.tag("isGreaterThanDate"),
-  exclusiveMinimum: Schema.Date
-}).annotate({ identifier: "IsGreaterThanDate" })
-
-const $IsGreaterThanOrEqualToDate = Schema.Struct({
-  _tag: Schema.tag("isGreaterThanOrEqualToDate"),
-  minimum: Schema.Date
-}).annotate({ identifier: "IsGreaterThanOrEqualToDate" })
-
-const $IsLessThanDate = Schema.Struct({
-  _tag: Schema.tag("isLessThanDate"),
-  exclusiveMaximum: Schema.Date
-}).annotate({ identifier: "IsLessThanDate" })
-
-const $IsLessThanOrEqualToDate = Schema.Struct({
-  _tag: Schema.tag("isLessThanOrEqualToDate"),
-  maximum: Schema.Date
-}).annotate({ identifier: "IsLessThanOrEqualToDate" })
-
-const $IsBetweenDate = Schema.Struct({
-  _tag: Schema.tag("isBetweenDate"),
-  minimum: Schema.Date,
-  maximum: Schema.Date,
-  exclusiveMinimum: Schema.optional(Schema.Boolean),
-  exclusiveMaximum: Schema.optional(Schema.Boolean)
-}).annotate({ identifier: "IsBetweenDate" })
+  $ref: Schema.NonEmptyString
+})
+
+const RepresentationUnion = Schema.Union([
+  DeclarationSchema,
+  ReferenceSchema,
+  SuspendSchema,
+  makeKeywordSchema("Null"),
+  makeKeywordSchema("Undefined"),
+  makeKeywordSchema("Void"),
+  makeKeywordSchema("Never"),
+  makeKeywordSchema("Unknown"),
+  makeKeywordSchema("Any"),
+  makeKeywordSchema("String"),
+  makeKeywordSchema("Number"),
+  makeKeywordSchema("Boolean"),
+  makeKeywordSchema("BigInt"),
+  makeKeywordSchema("Symbol"),
+  makeKeywordSchema("ObjectKeyword"),
+  LiteralSchema,
+  UniqueSymbolSchema,
+  EnumSchema,
+  TemplateLiteralSchema,
+  ArraysSchema,
+  ObjectsSchema,
+  UnionSchema
+])
 
-/**
- * Schema for {@link DateMeta}.
- *
- * @category schemas
- * @since 4.0.0
- */
-export const $DateMeta = Schema.Union([
-  $IsDateValid,
-  $IsGreaterThanDate,
-  $IsGreaterThanOrEqualToDate,
-  $IsLessThanDate,
-  $IsLessThanOrEqualToDate,
-  $IsBetweenDate
-]).annotate({ identifier: "DateMeta" })
+const ReferencesSchema = Schema.Record(Schema.String, RepresentationSchema)
 
-const $IsMinSize = Schema.Struct({
-  _tag: Schema.tag("isMinSize"),
-  minSize: NonNegativeInt
-}).annotate({ identifier: "IsMinSize" })
+const DocumentFromJson: Schema.Codec<Document, Schema.Json> = Schema.toCodecJson(
+  Schema.Struct({
+    representation: RepresentationSchema,
+    references: ReferencesSchema
+  })
+)
 
-const $IsMaxSize = Schema.Struct({
-  _tag: Schema.tag("isMaxSize"),
-  maxSize: NonNegativeInt
-}).annotate({ identifier: "IsMaxSize" })
+const MultiDocumentFromJson: Schema.Codec<MultiDocument, Schema.Json> = Schema.toCodecJson(
+  Schema.Struct({
+    representations: Schema.NonEmptyArray(RepresentationSchema),
+    references: ReferencesSchema
+  })
+)
 
-const $IsSizeBetween = Schema.Struct({
-  _tag: Schema.tag("isSizeBetween"),
-  minimum: NonNegativeInt,
-  maximum: NonNegativeInt
-}).annotate({ identifier: "IsSizeBetween" })
+const encodeDocument = Schema.encodeSync(DocumentFromJson)
+const encodeMultiDocument = Schema.encodeSync(MultiDocumentFromJson)
+const decodeDocument = Schema.decodeSync(DocumentFromJson)
+const decodeMultiDocument = Schema.decodeSync(MultiDocumentFromJson)
 
 /**
- * Schema for {@link SizeMeta}.
+ * Projects a live single-root representation document and encodes it as JSON.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $SizeMeta = Schema.Union([
-  $IsMinSize,
-  $IsMaxSize,
-  $IsSizeBetween
-]).annotate({ identifier: "SizeMeta" })
-
-/**
- * Schema for {@link DeclarationMeta}.
+ * **When to use**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $DeclarationMeta = Schema.Union([
-  $DateMeta,
-  $SizeMeta
-]).annotate({ identifier: "DeclarationMeta" })
-
-/**
- * Schema for the {@link Declaration} representation node.
+ * Use when you need a stable JSON value for storage or transport after calling `toRepresentation`.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Declaration = Schema.Struct({
-  _tag: Schema.tag("Declaration"),
-  annotations: Schema.optional($Annotations),
-  typeParameters: Schema.Array(Representation$ref),
-  checks: Schema.Array(makeCheck($DeclarationMeta, "Declaration")),
-  encodedSchema: Representation$ref
-}).annotate({ identifier: "Declaration" })
-
-/**
- * Schema for the {@link Suspend} representation node.
+ * **Gotchas**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Suspend = Schema.Struct({
-  _tag: Schema.tag("Suspend"),
-  annotations: Schema.optional($Annotations),
-  checks: Schema.Tuple([]),
-  thunk: Representation$ref
-}).annotate({ identifier: "Suspend" })
-
-/**
- * Type-level helper for the recursive {@link $Representation} codec.
+ * Generic annotations that are not JSON are omitted. Invalid persistence identities and unsupported structural values throw an `Error` containing their representation path.
  *
- * @category schemas
- * @since 4.0.0
- */
-export interface $Representation extends Schema.Codec<Representation> {}
-
-/**
- * Schema for the full {@link Representation} union. It recursively validates
- * and encodes any representation node.
+ * @see {@link toRepresentation} for constructing the live document
+ * @see {@link toJsonMultiDocument} for documents with multiple roots
  *
- * @category schemas
+ * @category encoding
  * @since 4.0.0
  */
-export const $Representation: $Representation = Schema.Union([
-  $Null,
-  $Undefined,
-  $Void,
-  $Never,
-  $Unknown,
-  $Any,
-  $String,
-  $Number,
-  $Boolean,
-  $BigInt,
-  $Symbol,
-  $Literal,
-  $UniqueSymbol,
-  $ObjectKeyword,
-  $Enum,
-  $TemplateLiteral,
-  $Arrays,
-  $Objects,
-  $Union,
-  $Reference,
-  $Declaration,
-  $Suspend
-]).annotate({ identifier: "Schema" })
+export function toJson(document: Document): Schema.Json {
+  return encodeDocument(document)
+}
 
 /**
- * Schema for {@link Document}.
+ * Projects a live multi-root representation document and encodes it as JSON.
  *
  * **When to use**
  *
- * Use to validate or serialize a single schema representation document with
- * `Schema.decodeUnknownSync` or `Schema.encodeSync`.
+ * Use when you need one JSON value for multiple live roots that share a reference environment.
  *
  * **Gotchas**
  *
- * This codec validates document structure but does not resolve `$ref` keys
- * against `references`.
- *
- * @see {@link DocumentFromJson} for the JSON-string codec wrapper
- * @see {@link $MultiDocument} for validating documents with multiple root representations
+ * The root order and shared reference keys are preserved, while non-JSON generic annotations are omitted.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const $Document = Schema.Struct({
-  representation: $Representation,
-  references: Schema.Record(Schema.String, $Representation)
-}).annotate({ identifier: "Document" })
-
-/**
- * Schema for {@link MultiDocument}.
+ * @see {@link toRepresentations} for constructing the live multi-document
+ * @see {@link toJson} for a single-root document
  *
- * @category schemas
+ * @category encoding
  * @since 4.0.0
  */
-export const $MultiDocument = Schema.Struct({
-  representations: Schema.NonEmptyArray($Representation),
-  references: Schema.Record(Schema.String, $Representation)
-}).annotate({ identifier: "MultiDocument" })
-
-// -----------------------------------------------------------------------------
-// APIs
-// -----------------------------------------------------------------------------
+export function toJsonMultiDocument(document: MultiDocument): Schema.Json {
+  return encodeMultiDocument(document)
+}
 
 /**
- * Converts a Schema AST into a {@link Document}.
+ * Decodes a persisted single-root representation document from JSON.
  *
  * **When to use**
  *
- * Use when you have a single Schema AST and need a schema representation
- * document.
- *
- * **Details**
- *
- * Shared/recursive sub-schemas are extracted into the `references` map.
- *
- * **Example** (Converting a Schema to a Document)
+ * Use when reading a representation document from storage or transport before inspecting it or passing it to `fromRepresentation`.
  *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
- *
- * const Person = Schema.Struct({
- *   name: Schema.String,
- *   age: Schema.Number
- * })
+ * **Gotchas**
  *
- * const doc = SchemaRepresentation.fromAST(Person.ast)
- * console.log(doc.representation._tag)
- * // "Objects"
- * ```
+ * Invalid documents throw a schema decoding error. Decoding does not reconstruct runtime callbacks.
  *
- * @see {@link Document}
- * @see {@link fromASTs}
+ * @see {@link toJson} for encoding a document
+ * @see {@link fromRepresentation} for reconstructing a runtime schema
+ * @see {@link fromJsonMultiDocument} for multiple roots sharing references
  *
- * @category constructors
+ * @category decoding
  * @since 4.0.0
  */
-export const fromAST: (ast: SchemaAST.AST) => Document = InternalRepresentation.fromAST
+export function fromJson(input: Schema.Json): Document {
+  return decodeDocument(input)
+}
 
 /**
- * Converts one or more Schema ASTs into a {@link MultiDocument}.
+ * Decodes a persisted multi-root representation document from JSON.
  *
  * **When to use**
  *
- * Use when you have multiple Schema ASTs and need one schema representation
- * `MultiDocument` with shared references.
+ * Use when reading multiple representation roots that share references before inspecting them or passing them to `fromRepresentations`.
  *
- * **Details**
+ * **Gotchas**
  *
- * All schemas share a single `references` map.
+ * Invalid documents throw a schema decoding error. Decoding does not reconstruct runtime callbacks.
  *
- * @see {@link MultiDocument}
- * @see {@link fromAST}
+ * @see {@link toJsonMultiDocument} for encoding a multi-document
+ * @see {@link fromRepresentations} for reconstructing runtime schemas
+ * @see {@link fromJson} for a single root
  *
- * @category constructors
+ * @category decoding
  * @since 4.0.0
  */
-export const fromASTs: (asts: readonly [SchemaAST.AST, ...Array<SchemaAST.AST>]) => MultiDocument =
-  InternalRepresentation.fromASTs
+export function fromJsonMultiDocument(input: Schema.Json): MultiDocument {
+  return decodeMultiDocument(input)
+}
 
 /**
- * Schema that decodes a {@link Document} from JSON and encodes it back.
+ * Reconstructs a runtime schema from a representation document.
  *
  * **When to use**
  *
- * Use when you need a JSON codec for schema representation documents with
- * `Schema.decodeUnknownSync` or `Schema.encodeSync`.
+ * Use when you have decoded or constructed a document whose declaration and check annotations may require revivers.
  *
- * **Example** (Round-tripping a Document through JSON)
- *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
+ * **Gotchas**
  *
- * const doc = SchemaRepresentation.fromAST(Schema.String.ast)
- * const json = Schema.encodeSync(SchemaRepresentation.DocumentFromJson)(doc)
- * const back = Schema.decodeUnknownSync(SchemaRepresentation.DocumentFromJson)(json)
- * ```
+ * Revivers are resolved locally by `id`; none are installed implicitly. Reviver results are used directly, and exceptions raised by a reviver pass through unchanged.
  *
- * @see {@link $Document}
- * @see {@link MultiDocumentFromJson}
+ * @see {@link fromJson} for decoding a persisted document
+ * @see {@link fromRepresentations} for multiple roots sharing references
  *
- * @category schemas
+ * @category transforming
  * @since 4.0.0
  */
-export const DocumentFromJson: Schema.Codec<Document, Schema.Json> = Schema.toCodecJson($Document)
+export function fromRepresentation(
+  document: Document,
+  options: { readonly revivers: ReadonlyArray<AnyReviver> }
+): Schema.Top {
+  return InternalFromRepresentation.fromRepresentation(document, options.revivers)
+}
 
 /**
- * Schema for `MultiDocument` values encoded as JSON.
+ * Reconstructs multiple runtime schemas and their shared definitions from a representation multi-document.
  *
- * @see {@link $MultiDocument}
- * @see {@link DocumentFromJson}
+ * **When to use**
  *
- * @category schemas
- * @since 4.0.0
- */
-export const MultiDocumentFromJson: Schema.Codec<MultiDocument, Schema.Json> = Schema.toCodecJson($MultiDocument)
-
-/**
- * Wraps a single {@link Document} as a {@link MultiDocument} with one
- * representation.
+ * Use when every root and named definition must be rebuilt in one shared reference environment.
  *
- * **When to use**
+ * **Gotchas**
  *
- * Use when you need to pass a single schema representation `Document` where an
- * API expects a `MultiDocument`.
+ * Every definition is revived, including definitions not reachable from a root. Revivers are resolved locally by `id`; none are installed implicitly.
  *
- * @see {@link Document}
- * @see {@link MultiDocument}
+ * @see {@link fromJsonMultiDocument} for decoding a persisted multi-document
+ * @see {@link fromRepresentation} for a single root
  *
  * @category transforming
  * @since 4.0.0
  */
-export function toMultiDocument(document: Document): MultiDocument {
-  return {
-    representations: [document.representation],
-    references: document.references
-  }
+export function fromRepresentations(
+  document: MultiDocument,
+  options: { readonly revivers: ReadonlyArray<AnyReviver> }
+): SchemaMultiDocument {
+  return InternalFromRepresentation.fromRepresentations(document, options.revivers)
 }
 
 /**
- * A callback that handles {@link Declaration} nodes during reconstruction
- * ({@link toSchema}) or code generation ({@link toCodeDocument}).
+ * Imports a JSON Schema Draft 2020-12 document as a runtime schema.
  *
- * **Details**
+ * **When to use**
  *
- * Return a value to handle the declaration. Return `undefined` to fall back to
- * default behavior, which uses `encodedSchema` for `toSchema` or the
- * `generation` annotation for `toCodeDocument`. `recur` processes child
- * representations recursively.
+ * Use when you need to validate or transform values described by an external JSON Schema document.
  *
- * @see {@link toSchema}
- * @see {@link toSchemaDefaultReviver}
- * @see {@link toCodeDocument}
+ * **Gotchas**
  *
- * @category models
- * @since 4.0.0
- */
-export type Reviver<T> = (declaration: Declaration, recur: (representation: Representation) => T) => T | undefined
-
-/**
- * Default {@link Reviver} for {@link toSchema} that handles built-in Effect
- * types, including Option, Result, Redacted, Cause, Exit, ReadonlyMap, HashMap,
- * ReadonlySet, Date, Duration, URL, and RegExp.
- *
- * **When to use**
- *
- * Use when you need the default `options.reviver` for {@link toSchema} to
- * reconstruct runtime schemas for built-in Effect declarations.
- *
- * **Details**
- *
- * The reviver returns `undefined` for unrecognized declarations, causing
- * fallback to `encodedSchema`.
- *
- * @see {@link toSchema}
- * @see {@link Reviver}
- *
- * @category transforming
- * @since 4.0.0
- */
-export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
-  const typeConstructor = s.annotations?.typeConstructor
-  if (Predicate.isObject(typeConstructor) && typeof typeConstructor._tag === "string") {
-    const typeParameters = s.typeParameters.map(recur)
-    switch (typeConstructor._tag) {
-      // built-in types
-      case "Date":
-        return Schema.Date
-      case "Error":
-        return Schema.Error(typeConstructor.options as Schema.ErrorOptions | undefined)
-      case "File":
-        return Schema.File
-      case "FormData":
-        return Schema.FormData
-      case "ReadonlyMap":
-        return Schema.ReadonlyMap(typeParameters[0], typeParameters[1])
-      case "ReadonlySet":
-        return Schema.ReadonlySet(typeParameters[0])
-      case "RegExp":
-        return Schema.RegExp
-      case "Uint8Array":
-        return Schema.Uint8Array
-      case "URL":
-        return Schema.URL
-      case "URLSearchParams":
-        return Schema.URLSearchParams
-      // effect types
-      case "effect/Option":
-        return Schema.Option(typeParameters[0])
-      case "effect/Result":
-        return Schema.Result(typeParameters[0], typeParameters[1])
-      case "effect/Redacted":
-        return Schema.Redacted(typeParameters[0], typeConstructor.options as any)
-      case "effect/DateTime.TimeZone":
-        return Schema.TimeZone
-      case "effect/DateTime.TimeZone.Named":
-        return Schema.TimeZoneNamed
-      case "effect/DateTime.TimeZone.Offset":
-        return Schema.TimeZoneOffset
-      case "effect/DateTime.Utc":
-        return Schema.DateTimeUtc
-      case "effect/DateTime.Zoned":
-        return Schema.DateTimeZoned
-      case "effect/BigDecimal":
-        return Schema.BigDecimal
-      case "effect/Chunk":
-        return Schema.Chunk(typeParameters[0])
-      case "effect/Cause":
-        return Schema.Cause(typeParameters[0], typeParameters[1])
-      case "effect/Cause/Failure":
-        return Schema.CauseReason(typeParameters[0], typeParameters[1])
-      case "effect/Duration":
-        return Schema.Duration
-      case "effect/Exit":
-        return Schema.Exit(typeParameters[0], typeParameters[1], typeParameters[2])
-      case "effect/Json":
-        return Schema.Json
-      case "effect/MutableJson":
-        return Schema.MutableJson
-      case "effect/HashMap":
-        return Schema.HashMap(typeParameters[0], typeParameters[1])
-      case "effect/HashSet":
-        return Schema.HashSet(typeParameters[0])
-    }
-  }
-}
-
-/**
- * Creates a runtime Schema from a {@link Document}.
- *
- * **When to use**
- *
- * Use when you have a serialized or computed schema representation document and
- * need a runtime Schema for decoding/encoding.
- *
- * **Details**
- *
- * Pass `options.reviver`, such as {@link toSchemaDefaultReviver}, to handle
- * {@link Declaration} nodes for types like `Date` and `Option`. Without a
- * reviver, declarations fall back to their `encodedSchema`. Circular references
- * are handled via lazy `Schema.suspend`.
- *
- * **Gotchas**
- *
- * This throws if a `$ref` is not found in `document.references`.
+ * Import is best-effort. Built-in declarations and checks are reconstructed with importer-owned revivers. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
- * **Example** (Reconstructing a Schema)
- *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
- *
- * const doc = SchemaRepresentation.fromAST(
- *   Schema.Struct({ name: Schema.String }).ast
- * )
- *
- * const schema = SchemaRepresentation.toSchema(doc)
- * console.log(JSON.stringify(Schema.toJsonSchemaDocument(schema), null, 2))
- * ```
- *
- * @see {@link Document}
- * @see {@link Reviver}
- * @see {@link toSchemaDefaultReviver}
- *
- * @category Runtime Generation
- * @since 4.0.0
- */
-export function toSchema<S extends Schema.Top = Schema.Top>(document: Document, options?: {
-  readonly reviver?: Reviver<Schema.Top> | undefined
-}): S {
-  type Slot = {
-    // 0 = not started, 1 = building, 2 = done
-    state: 0 | 1 | 2
-    value: Schema.Top | undefined
-    ref: Schema.Top
-  }
-
-  const slots = new Map<string, Slot>()
-
-  return recur(document.representation) as S
-
-  function recur(r: Representation): Schema.Top {
-    let out = on(r)
-    if ("annotations" in r && r.annotations) out = out.annotate(r.annotations)
-    out = toSchemaChecks(out, r)
-    return out
-  }
-
-  function getSlot(identifier: string): Slot {
-    const existing = slots.get(identifier)
-    if (existing) return existing
-
-    // Create the slot *before* resolving, so self-references can see it.
-    const slot: Slot = {
-      state: 0,
-      value: undefined,
-      ref: Schema.suspend(() => {
-        if (slot.value === undefined) {
-          return Schema.Unknown
-        }
-        return slot.value
-      })
-    }
-    slots.set(identifier, slot)
-    return slot
-  }
-
-  function resolveReference($ref: string): Schema.Top {
-    const definition = document.references[$ref]
-    if (definition === undefined) {
-      throw new Error(`Reference ${$ref} not found`)
-    }
-
-    const slot = getSlot($ref)
-
-    if (slot.state === 2) {
-      // Already built: return the built schema directly
-      return slot.value!
-    }
-
-    if (slot.state === 1) {
-      // Circular: we're currently building this identifier.
-      return slot.ref
-    }
-
-    // First time: build it.
-    slot.state = 1
-    try {
-      slot.value = recur(definition)
-      slot.state = 2
-      return slot.value
-    } catch (e) {
-      // Leave the slot in a safe state so future thunks don't silently succeed.
-      slot.state = 0
-      slot.value = undefined
-      throw e
-    }
-  }
-
-  function on(r: Representation): Schema.Top {
-    switch (r._tag) {
-      case "Declaration":
-        return options?.reviver?.(r, recur) ?? recur(r.encodedSchema)
-      case "Reference":
-        return resolveReference(r.$ref)
-      case "Suspend":
-        return recur(r.thunk)
-      case "Null":
-        return Schema.Null
-      case "Undefined":
-        return Schema.Undefined
-      case "Void":
-        return Schema.Void
-      case "Never":
-        return Schema.Never
-      case "Unknown":
-        return Schema.Unknown
-      case "Any":
-        return Schema.Any
-      case "String": {
-        const contentMediaType = r.contentMediaType
-        const contentSchema = r.contentSchema
-        if (contentMediaType === "application/json" && contentSchema !== undefined) {
-          return Schema.fromJsonString(recur(contentSchema))
-        }
-        return Schema.String
-      }
-      case "Number":
-        return Schema.Number
-      case "Boolean":
-        return Schema.Boolean
-      case "BigInt":
-        return Schema.BigInt
-      case "Symbol":
-        return Schema.Symbol
-      case "Literal":
-        return Schema.Literal(r.literal)
-      case "UniqueSymbol":
-        return Schema.UniqueSymbol(r.symbol)
-      case "ObjectKeyword":
-        return Schema.ObjectKeyword
-      case "Enum":
-        return Schema.Enum(Object.fromEntries(r.enums))
-      case "TemplateLiteral": {
-        const parts = r.parts.map(recur) as Schema.TemplateLiteral.Parts
-        return Schema.TemplateLiteral(parts)
-      }
-      case "Arrays": {
-        const elements = r.elements.map((e) => {
-          const s = recur(e.type)
-          return e.isOptional ? Schema.optionalKey(s) : s
-        })
-        const rest = r.rest.map(recur)
-        if (Arr.isArrayNonEmpty(rest)) {
-          if (r.elements.length === 0 && r.rest.length === 1) {
-            return Schema.Array(rest[0])
-          }
-          return Schema.TupleWithRest(Schema.Tuple(elements), rest)
-        }
-        return Schema.Tuple(elements)
-      }
-      case "Objects": {
-        const fields: Record<PropertyKey, Schema.Top> = {}
-
-        for (const ps of r.propertySignatures) {
-          const s = recur(ps.type)
-          const withOptional = ps.isOptional ? Schema.optionalKey(s) : s
-          fields[ps.name] = ps.isMutable ? Schema.mutableKey(withOptional) : withOptional
-        }
-
-        const indexSignatures = r.indexSignatures.map((is) =>
-          Schema.Record(recur(is.parameter) as Schema.Record.Key, recur(is.type))
-        )
-
-        if (Arr.isArrayNonEmpty(indexSignatures)) {
-          if (r.propertySignatures.length === 0 && indexSignatures.length === 1) {
-            return indexSignatures[0]
-          }
-          return Schema.StructWithRest(Schema.Struct(fields), indexSignatures)
-        }
-
-        return Schema.Struct(fields)
-      }
-      case "Union": {
-        if (r.types.length === 0) return Schema.Never
-        if (r.types.every((t) => t._tag === "Literal")) {
-          if (r.types.length === 1) {
-            return Schema.Literal(r.types[0].literal)
-          }
-          return Schema.Literals(r.types.map((t) => t.literal))
-        }
-        return Schema.Union(r.types.map(recur), { mode: r.mode })
-      }
-    }
-  }
-
-  function toSchemaChecks(top: Schema.Top, schema: Representation): Schema.Top {
-    switch (schema._tag) {
-      default:
-        return top
-      case "String":
-      case "Number":
-      case "BigInt":
-      case "Arrays":
-      case "Objects":
-      case "Declaration": {
-        const checks = schema.checks.map(toSchemaCheck)
-        return Arr.isArrayNonEmpty(checks) ? top.check(...checks) : top
-      }
-    }
-  }
-
-  function toSchemaCheck(check: Check<Meta>): SchemaAST.Check<any> {
-    switch (check._tag) {
-      case "Filter":
-        return toSchemaFilter(check)
-      case "FilterGroup": {
-        return Schema.makeFilterGroup(Arr.map(check.checks, toSchemaCheck), check.annotations)
-      }
-    }
-  }
-
-  function toSchemaFilter(filter: Filter<Meta>): SchemaAST.Check<any> {
-    const a = filter.annotations
-    switch (filter.meta._tag) {
-      // String Meta
-      case "isStringFinite":
-        return Schema.isStringFinite(a)
-      case "isStringBigInt":
-        return Schema.isStringBigInt(a)
-      case "isStringSymbol":
-        return Schema.isStringSymbol(a)
-      case "isMinLength":
-        return Schema.isMinLength(filter.meta.minLength, a)
-      case "isMaxLength":
-        return Schema.isMaxLength(filter.meta.maxLength, a)
-      case "isLengthBetween":
-        return Schema.isLengthBetween(filter.meta.minimum, filter.meta.maximum, a)
-      case "isPattern":
-        return Schema.isPattern(filter.meta.regExp, a)
-      case "isTrimmed":
-        return Schema.isTrimmed(a)
-      case "isUUID":
-        return Schema.isUUID(filter.meta.version, a)
-      case "isGUID":
-        return Schema.isGUID(a)
-      case "isULID":
-        return Schema.isULID(a)
-      case "isBase64":
-        return Schema.isBase64(a)
-      case "isBase64Url":
-        return Schema.isBase64Url(a)
-      case "isStartsWith":
-        return Schema.isStartsWith(filter.meta.startsWith, a)
-      case "isEndsWith":
-        return Schema.isEndsWith(filter.meta.endsWith, a)
-      case "isIncludes":
-        return Schema.isIncludes(filter.meta.includes, a)
-      case "isUppercased":
-        return Schema.isUppercased(a)
-      case "isLowercased":
-        return Schema.isLowercased(a)
-      case "isCapitalized":
-        return Schema.isCapitalized(a)
-      case "isUncapitalized":
-        return Schema.isUncapitalized(a)
-
-      // Number Meta
-      case "isFinite":
-        return Schema.isFinite(a)
-      case "isInt":
-        return Schema.isInt(a)
-      case "isMultipleOf":
-        return Schema.isMultipleOf(filter.meta.divisor, a)
-      case "isGreaterThan":
-        return Schema.isGreaterThan(filter.meta.exclusiveMinimum, a)
-      case "isGreaterThanOrEqualTo":
-        return Schema.isGreaterThanOrEqualTo(filter.meta.minimum, a)
-      case "isLessThan":
-        return Schema.isLessThan(filter.meta.exclusiveMaximum, a)
-      case "isLessThanOrEqualTo":
-        return Schema.isLessThanOrEqualTo(filter.meta.maximum, a)
-      case "isBetween":
-        return Schema.isBetween(filter.meta, a)
-
-      // BigInt Meta
-      case "isGreaterThanBigInt":
-        return Schema.isGreaterThanBigInt(filter.meta.exclusiveMinimum, a)
-      case "isGreaterThanOrEqualToBigInt":
-        return Schema.isGreaterThanOrEqualToBigInt(filter.meta.minimum, a)
-      case "isLessThanBigInt":
-        return Schema.isLessThanBigInt(filter.meta.exclusiveMaximum, a)
-      case "isLessThanOrEqualToBigInt":
-        return Schema.isLessThanOrEqualToBigInt(filter.meta.maximum, a)
-      case "isBetweenBigInt":
-        return Schema.isBetweenBigInt(filter.meta, a)
-
-      // Object Meta
-      case "isMinProperties":
-        return Schema.isMinProperties(filter.meta.minProperties, a)
-      case "isMaxProperties":
-        return Schema.isMaxProperties(filter.meta.maxProperties, a)
-      case "isPropertiesLengthBetween":
-        return Schema.isPropertiesLengthBetween(filter.meta.minimum, filter.meta.maximum, a)
-      case "isPropertyNames":
-        return Schema.isPropertyNames(recur(filter.meta.propertyNames) as Schema.Record.Key, a)
-
-      // Arrays Meta
-      case "isUnique":
-        return Schema.isUnique(a)
-
-      // Date Meta
-      case "isDateValid":
-        return Schema.isDateValid(a)
-      case "isGreaterThanDate":
-        return Schema.isGreaterThanDate(filter.meta.exclusiveMinimum, a)
-      case "isGreaterThanOrEqualToDate":
-        return Schema.isGreaterThanOrEqualToDate(filter.meta.minimum, a)
-      case "isLessThanDate":
-        return Schema.isLessThanDate(filter.meta.exclusiveMaximum, a)
-      case "isLessThanOrEqualToDate":
-        return Schema.isLessThanOrEqualToDate(filter.meta.maximum, a)
-      case "isBetweenDate":
-        return Schema.isBetweenDate(filter.meta, a)
-
-      // Size Meta
-      case "isMinSize":
-        return Schema.isMinSize(filter.meta.minSize, a)
-      case "isMaxSize":
-        return Schema.isMaxSize(filter.meta.maxSize, a)
-      case "isSizeBetween":
-        return Schema.isSizeBetween(filter.meta.minimum, filter.meta.maximum, a)
-    }
-  }
-}
-
-/**
- * Converts a {@link Document} to a Draft 2020-12 JSON Schema document.
- *
- * **When to use**
- *
- * Use when you need to produce a standard JSON Schema document from a schema
- * representation `Document`.
- *
- * **Gotchas**
- *
- * JSON Schema generation is best-effort. Some Effect schema representation
- * semantics cannot be represented exactly in JSON Schema, and importing an
- * emitted JSON Schema may produce an equivalent approximation rather than the
- * original representation shape.
- *
- * **Example** (Generating JSON Schema)
- *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
- *
- * const doc = SchemaRepresentation.fromAST(Schema.String.ast)
- * const jsonSchema = SchemaRepresentation.toJsonSchemaDocument(doc)
- * console.log(jsonSchema.schema.type)
- * // "string"
- * ```
- *
- * @see {@link Document}
- * @see {@link toJsonSchemaMultiDocument}
- * @see {@link fromJsonSchemaDocument}
- *
- * @category transforming
- * @since 4.0.0
- */
-export const toJsonSchemaDocument: (
-  document: Document,
-  options?: Schema.ToJsonSchemaOptions
-) => JsonSchema.Document<"draft-2020-12"> = InternalRepresentation.toJsonSchemaDocument
-
-/**
- * Converts a {@link MultiDocument} to a Draft 2020-12 JSON Schema
- * multi-document.
- *
- * **When to use**
- *
- * Use when you need to export related schema representation documents together
- * so shared definitions stay in multi-document JSON Schema form.
- *
- * **Gotchas**
- *
- * JSON Schema generation is best-effort. Some Effect schema representation
- * semantics cannot be represented exactly in JSON Schema, and importing an
- * emitted JSON Schema may produce equivalent approximations rather than the
- * original representation shapes.
- *
- * @see {@link MultiDocument}
- * @see {@link toJsonSchemaDocument}
- * @see {@link fromJsonSchemaMultiDocument}
- *
- * @category transforming
- * @since 4.0.0
- */
-export const toJsonSchemaMultiDocument: (
-  document: MultiDocument,
-  options?: Schema.ToJsonSchemaOptions
-) => JsonSchema.MultiDocument<"draft-2020-12"> = InternalRepresentation.toJsonSchemaMultiDocument
-
-/**
- * A pair of TypeScript source strings for a schema: `runtime` is the
- * executable Schema expression, `Type` is the corresponding TypeScript type.
- *
- * @see {@link makeCode}
- * @see {@link CodeDocument}
- *
- * @category Code Generation
- * @since 4.0.0
- */
-export type Code = {
-  readonly runtime: string
-  readonly Type: string
-}
-
-/**
- * Constructs a {@link Code} value from a runtime expression string and a
- * TypeScript type string.
- *
- * @see {@link Code}
- *
- * @category Code Generation
- * @since 4.0.0
- */
-export function makeCode(runtime: string, Type: string): Code {
-  return { runtime, Type }
-}
-
-/**
- * An auxiliary code artifact produced during code generation — a symbol
- * declaration, an enum declaration, or an import statement.
- *
- * @see {@link CodeDocument}
- * @see {@link toCodeDocument}
- *
- * @category Code Generation
- * @since 4.0.0
- */
-export type Artifact =
-  | {
-    readonly _tag: "Symbol"
-    readonly identifier: string
-    readonly generation: Code
-  }
-  | {
-    readonly _tag: "Enum"
-    readonly identifier: string
-    readonly generation: Code
-  }
-  | {
-    readonly _tag: "Import"
-    readonly importDeclaration: string
-  }
-
-/**
- * The output of {@link toCodeDocument}: generated TypeScript code for one or
- * more schemas plus their shared references and auxiliary artifacts.
- *
- * **Details**
- *
- * `codes` contains one {@link Code} per input representation.
- * `references.nonRecursives` contains topologically sorted non-recursive
- * definitions. `references.recursives` contains definitions involved in cycles.
- * `artifacts` contains symbols, enums, and import statements needed by the
- * code.
- *
- * @see {@link toCodeDocument}
- * @see {@link Code}
- * @see {@link Artifact}
- *
- * @category Code Generation
- * @since 4.0.0
- */
-export type CodeDocument = {
-  readonly codes: ReadonlyArray<Code>
-  readonly references: {
-    readonly nonRecursives: ReadonlyArray<{
-      readonly $ref: string
-      readonly code: Code
-    }>
-    readonly recursives: {
-      readonly [$ref: string]: Code
-    }
-  }
-  readonly artifacts: ReadonlyArray<Artifact>
-}
-
-/**
- * Generates TypeScript code strings from a {@link MultiDocument}.
- *
- * **When to use**
- *
- * Use when you need to produce source code for Effect Schema definitions from a
- * schema representation `MultiDocument`.
- *
- * **Details**
- *
- * `options.reviver` can customize code generation for {@link Declaration}
- * nodes. Return `undefined` to fall back to the default logic, which uses
- * `generation` annotations or the encoded schema. References are
- * topologically sorted so non-recursive definitions are emitted before their
- * dependents. `$ref` keys are converted to sanitized JavaScript identifiers.
- *
- * **Example** (Generating TypeScript code)
- *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
- *
- * const Person = Schema.Struct({
- *   name: Schema.String,
- *   age: Schema.Int
- * })
- *
- * const multi = SchemaRepresentation.toMultiDocument(
- *   SchemaRepresentation.fromAST(Person.ast)
- * )
- * const codeDoc = SchemaRepresentation.toCodeDocument(multi)
- * console.log(codeDoc.codes[0].runtime)
- * // Schema.Struct({ ... })
- * ```
- *
- * @see {@link CodeDocument}
- * @see {@link MultiDocument}
- * @see {@link Reviver}
- *
- * @category Code Generation
- * @since 4.0.0
- */
-export function toCodeDocument(multiDocument: MultiDocument, options?: {
-  /**
-   * The reviver can return `undefined` to indicate that the generation should be generated by the default logic
-   */
-  readonly reviver?: Reviver<Code> | undefined
-}): CodeDocument {
-  const artifacts: Array<Artifact> = []
-
-  const ts = topologicalSort(multiDocument.references)
-
-  // Phase 1: Build sanitization map with collision handling
-  const sanitizedReferenceMap = new Map<string, string>()
-  const uniqueSanitizedReferences = new Set<string>()
-  const referenceCount = new Map<string, number>()
-
-  // Process all references first to build the map
-  const allRefs = [
-    ...ts.nonRecursives.map(({ $ref }) => $ref),
-    ...Object.keys(ts.recursives)
-  ]
-
-  for (const ref of allRefs) {
-    ensureUniqueSanitized(ref)
-  }
-
-  // Phase 2: Use the map when processing references
-  const nonRecursives = ts.nonRecursives.map(({ $ref, representation }) => ({
-    $ref: sanitizedReferenceMap.get($ref)!,
-    code: recur(representation)
-  }))
-  const recursives = Rec.mapEntries(ts.recursives, (representation, $ref) => [
-    sanitizedReferenceMap.get($ref)!,
-    recur(representation)
-  ])
-
-  const codes = multiDocument.representations.map(recur)
-
-  return {
-    codes,
-    references: {
-      nonRecursives: nonRecursives.filter(({ $ref }) => (referenceCount.get($ref) ?? 0) > 0),
-      recursives: Rec.filter(recursives, (_, $ref) => (referenceCount.get($ref) ?? 0) > 0)
-    },
-    artifacts
-  }
-
-  function ensureUniqueSanitized(originalRef: string): string {
-    // Check if already mapped (consistency)
-    const sanitized = sanitizedReferenceMap.get(originalRef)
-    if (sanitized !== undefined) {
-      return sanitized
-    }
-
-    // Find unique sanitized name
-    const seed = sanitizeJavaScriptIdentifier(originalRef)
-    let candidate = seed
-    let suffix = 0
-
-    while (uniqueSanitizedReferences.has(candidate)) {
-      candidate = `${seed}${++suffix}`
-    }
-
-    uniqueSanitizedReferences.add(candidate)
-    sanitizedReferenceMap.set(originalRef, candidate)
-    return candidate
-  }
-
-  function addSymbol(s: symbol): string {
-    const identifier = ensureUniqueSanitized("_symbol")
-    const key = globalThis.Symbol.keyFor(s)
-    const description = s.description
-    const generation = key === undefined
-      ? makeCode(`Symbol(${description === undefined ? "" : format(description)})`, `typeof ${identifier}`)
-      : makeCode(`Symbol.for(${format(key)})`, `typeof ${identifier}`)
-    artifacts.push({ _tag: "Symbol", identifier, generation })
-    return identifier
-  }
-
-  function addEnum(s: Enum): string {
-    const identifier = ensureUniqueSanitized("_Enum")
-    artifacts.push({
-      _tag: "Enum",
-      identifier,
-      generation: makeCode(
-        `enum ${identifier} { ${s.enums.map(([name, value]) => `${format(name)}: ${format(value)}`).join(", ")} }`,
-        `typeof ${identifier}`
-      )
-    })
-    return identifier
-  }
-
-  function addImport(importDeclaration: string) {
-    if (!artifacts.some((a) => a._tag === "Import" && a.importDeclaration === importDeclaration)) {
-      artifacts.push({ _tag: "Import", importDeclaration })
-    }
-  }
-
-  function recur(s: Representation): Code {
-    const g = on(s)
-    switch (s._tag) {
-      default:
-        return makeCode(
-          g.runtime + toRuntimeAnnotate(s.annotations) + toRuntimeBrand(s.annotations),
-          g.Type + toTypeBrand(s.annotations)
-        )
-      case "Reference":
-        return g
-      case "Declaration":
-      case "String":
-      case "Number":
-      case "BigInt":
-      case "Arrays":
-      case "Objects":
-      case "Suspend":
-        return makeCode(
-          g.runtime + toRuntimeAnnotate(s.annotations) + toRuntimeBrand(s.annotations) + toRuntimeChecks(s.checks),
-          g.Type + toTypeBrand(s.annotations) + toTypeChecks(s.checks)
-        )
-    }
-  }
-
-  function on(s: Representation): Code {
-    switch (s._tag) {
-      case "Declaration": {
-        // if there is a reviver, use it to generate the generation
-        if (options?.reviver !== undefined) {
-          // the reviver can return `undefined` to indicate that the generation should be generated by the default logic
-          const out = options.reviver(s, recur)
-          if (out !== undefined) {
-            return out
-          }
-        }
-        // otherwise, use the generation from the annotations
-        const generation = s.annotations?.generation
-        if (
-          Predicate.isObject(generation) && typeof generation.runtime === "string" &&
-          typeof generation.Type === "string"
-        ) {
-          const typeParameters = s.typeParameters.map(recur)
-          if (typeof generation.importDeclaration === "string") {
-            addImport(generation.importDeclaration)
-          }
-          return makeCode(
-            replacePlaceholders(generation.runtime, typeParameters.map((p) => p.runtime)),
-            replacePlaceholders(generation.Type, typeParameters.map((p) => p.Type))
-          )
-        }
-        // otherwise, use the generation from the encoded schema
-        return recur(s.encodedSchema)
-      }
-      case "Reference": {
-        const sanitized = ensureUniqueSanitized(s.$ref)
-        referenceCount.set(sanitized, (referenceCount.get(sanitized) ?? 0) + 1)
-        return makeCode(sanitized, sanitized)
-      }
-      case "Suspend": {
-        const thunk = recur(s.thunk)
-        return makeCode(
-          `Schema.suspend((): Schema.Codec<${thunk.Type}> => ${thunk.runtime})`,
-          thunk.Type
-        )
-      }
-      case "Null":
-        return makeCode(`Schema.Null`, "null")
-      case "Undefined":
-        return makeCode(`Schema.Undefined`, "undefined")
-      case "Void":
-        return makeCode(`Schema.Void`, "void")
-      case "Never":
-        return makeCode(`Schema.Never`, "never")
-      case "Unknown":
-        return makeCode(`Schema.Unknown`, "unknown")
-      case "Any":
-        return makeCode(`Schema.Any`, "any")
-      case "Number":
-        return makeCode(`Schema.Number`, "number")
-      case "Boolean":
-        return makeCode(`Schema.Boolean`, "boolean")
-      case "BigInt":
-        return makeCode(`Schema.BigInt`, "bigint")
-      case "Symbol":
-        return makeCode(`Schema.Symbol`, "symbol")
-      case "String": {
-        const contentMediaType = s.contentMediaType
-        const contentSchema = s.contentSchema
-        if (contentMediaType === "application/json" && contentSchema !== undefined) {
-          return makeCode(`Schema.fromJsonString(${recur(contentSchema)})`, "string")
-        } else {
-          return makeCode(`Schema.String`, "string")
-        }
-      }
-      case "Literal": {
-        const literal = format(s.literal)
-        return makeCode(`Schema.Literal(${literal})`, literal)
-      }
-      case "UniqueSymbol": {
-        const identifier = addSymbol(s.symbol)
-        return makeCode(`Schema.UniqueSymbol(${identifier})`, `typeof ${identifier}`)
-      }
-      case "ObjectKeyword":
-        return makeCode(`Schema.ObjectKeyword`, "object")
-      case "Enum": {
-        const identifier = addEnum(s)
-        return makeCode(`Schema.Enum(${identifier})`, `typeof ${identifier}`)
-      }
-      case "TemplateLiteral": {
-        const parts = s.parts.map(recur)
-        const type = toTypeParts(s.parts).map((p) => "`" + p + "`").join(" | ")
-        return makeCode(`Schema.TemplateLiteral([${parts.map((p) => p.runtime).join(", ")}])`, type)
-      }
-      case "Arrays": {
-        const elements = s.elements.map((e) => {
-          return {
-            isOptional: e.isOptional,
-            type: recur(e.type),
-            annotations: e.annotations
-          }
-        })
-
-        const rest = s.rest.map(recur)
-
-        if (Arr.isArrayNonEmpty(rest)) {
-          const item = rest[0]
-          if (elements.length === 0 && rest.length === 1) {
-            return makeCode(
-              `Schema.Array(${item.runtime})`,
-              `ReadonlyArray<${item.Type}>`
-            )
-          }
-          const post = rest.slice(1)
-          return makeCode(
-            `Schema.TupleWithRest(Schema.Tuple([${
-              elements.map((e) =>
-                toRuntimeIsOptional(e.isOptional, e.type.runtime) + toRuntimeAnnotateKey(e.annotations)
-              ).join(", ")
-            }]), [${rest.map((r) => r.runtime).join(", ")}])`,
-            `readonly [${
-              elements.map((e) => toTypeIsOptional(e.isOptional, e.type.Type)).join(", ")
-            }, ...Array<${item.Type}>${post.length > 0 ? `, ${post.map((p) => p.Type).join(", ")}` : ""}]`
-          )
-        }
-        return makeCode(
-          `Schema.Tuple([${
-            elements.map((e) => toRuntimeIsOptional(e.isOptional, e.type.runtime) + toRuntimeAnnotateKey(e.annotations))
-              .join(", ")
-          }])`,
-          `readonly [${elements.map((e) => toTypeIsOptional(e.isOptional, e.type.Type)).join(", ")}]`
-        )
-      }
-      case "Objects": {
-        const pss = s.propertySignatures.map((p) => {
-          const isSymbol = typeof p.name === "symbol"
-          const name = isSymbol ? addSymbol(p.name) : formatPropertyKey(p.name)
-          const nameType = toTypeIsOptional(
-            p.isOptional,
-            toTypeIsMutable(p.isMutable, isSymbol ? `[typeof ${name}]` : name)
-          )
-          const type = recur(p.type)
-          return makeCode(
-            `${isSymbol ? `[${name}]` : name}: ${
-              toRuntimeIsOptional(p.isOptional, toRuntimeIsMutable(p.isMutable, type.runtime))
-            }` +
-              toRuntimeAnnotateKey(p.annotations),
-            `${nameType}: ${type.Type}`
-          )
-        })
-
-        const iss = s.indexSignatures.map((is) => {
-          return {
-            parameter: recur(is.parameter),
-            type: recur(is.type)
-          }
-        })
-
-        if (iss.length === 0) {
-          // 1) Only properties -> Struct
-          return makeCode(
-            `Schema.Struct({ ${pss.map((p) => p.runtime).join(", ")} })`,
-            `{ ${pss.map((p) => p.Type).join(", ")} }`
-          )
-        } else if (pss.length === 0 && iss.length === 1) {
-          // 2) Only one index signature and no properties -> Record
-          return makeCode(
-            `Schema.Record(${iss[0].parameter.runtime}, ${iss[0].type.runtime})`,
-            `{ readonly [x: ${iss[0].parameter.Type}]: ${iss[0].type.Type} }`
-          )
-        } else {
-          // 3) Properties + index signatures -> StructWithRest
-          return makeCode(
-            `Schema.StructWithRest(Schema.Struct({ ${pss.map((p) => p.runtime).join(", ")} }), [${
-              iss.map((is) => `Schema.Record(${is.parameter.runtime}, ${is.type.runtime})`).join(", ")
-            }])`,
-            `{ ${pss.map((p) => p.Type).join(", ")}, ${
-              iss.map((is) => `readonly [x: ${is.parameter.Type}]: ${is.type.Type}`).join(", ")
-            } }`
-          )
-        }
-      }
-      case "Union": {
-        if (s.types.length === 0) {
-          return makeCode("Schema.Never", "never")
-        }
-        if (s.types.every((t) => t._tag === "Literal")) {
-          const literals = s.types.map((l) => format(l.literal))
-          if (literals.length === 1) {
-            return makeCode(`Schema.Literal(${literals[0]})`, literals[0])
-          }
-          return makeCode(`Schema.Literals([${literals.join(", ")}])`, literals.join(" | "))
-        }
-        const mode = s.mode === "anyOf" ? "" : `, { mode: "oneOf" }`
-        const types = s.types.map((t) => recur(t))
-        return makeCode(
-          `Schema.Union([${types.map((t) => t.runtime).join(", ")}]${mode})`,
-          types.map((t) => t.Type).join(" | ")
-        )
-      }
-    }
-  }
-
-  function toTypeBrand(annotations: Schema.Annotations.Annotations | undefined): string {
-    const brands = collectBrands(annotations)
-    if (brands.length === 0) return ""
-    addImport(`import type * as Brand from "effect/Brand"`)
-    return brands.map((b) => ` & Brand.Brand<${format(b)}>`).join("")
-  }
-
-  function toTypeChecks(checks: ReadonlyArray<Check<Meta>>): string {
-    return checks.map((c) => toTypeCheck(c)).join("")
-  }
-
-  function toTypeCheck(check: Check<Meta>): string {
-    switch (check._tag) {
-      case "Filter":
-        return toTypeBrand(check.annotations)
-      case "FilterGroup": {
-        return toTypeChecks(check.checks)
-      }
-    }
-  }
-
-  function toRuntimeChecks(checks: ReadonlyArray<Check<Meta>>): string {
-    return checks.map((c) => `.check(${toRuntimeCheck(c)})` + toRuntimeBrand(c.annotations)).join("")
-  }
-
-  function toRuntimeCheck(check: Check<Meta>): string {
-    switch (check._tag) {
-      case "Filter":
-        return toRuntimeFilter(check)
-      case "FilterGroup": {
-        const a = toRuntimeAnnotations(check.annotations)
-        const ca = a === "" ? "" : `, ${a}`
-        return `Schema.makeFilterGroup([${check.checks.map((c) => toRuntimeCheck(c)).join(", ")}]${ca})`
-      }
-    }
-  }
-
-  function toRuntimeFilter(filter: Filter<Meta>): string {
-    const a = toRuntimeAnnotations(filter.annotations)
-    const ca = a === "" ? "" : `, ${a}`
-    switch (filter.meta._tag) {
-      case "isTrimmed":
-      case "isGUID":
-      case "isULID":
-      case "isBase64":
-      case "isBase64Url":
-      case "isUppercased":
-      case "isLowercased":
-      case "isCapitalized":
-      case "isUncapitalized":
-      case "isFinite":
-      case "isInt":
-      case "isUnique":
-      case "isDateValid":
-        return `Schema.${filter.meta._tag}(${a})`
-
-      case "isStringFinite":
-      case "isStringBigInt":
-      case "isStringSymbol":
-      case "isPattern":
-        return `Schema.${filter.meta._tag}(${toRuntimeRegExp(filter.meta.regExp)}${ca})`
-
-      case "isMinLength":
-        return `Schema.isMinLength(${filter.meta.minLength}${ca})`
-      case "isMaxLength":
-        return `Schema.isMaxLength(${filter.meta.maxLength}${ca})`
-      case "isLengthBetween":
-        return `Schema.isLengthBetween(${filter.meta.minimum}, ${filter.meta.maximum}${ca})`
-      case "isUUID":
-        return `Schema.isUUID(${filter.meta.version}${ca})`
-      case "isStartsWith":
-        return `Schema.isStartsWith(${format(filter.meta.startsWith)}${ca})`
-      case "isEndsWith":
-        return `Schema.isEndsWith(${format(filter.meta.endsWith)}${ca})`
-      case "isIncludes":
-        return `Schema.isIncludes(${format(filter.meta.includes)}${ca})`
-
-      case "isGreaterThan":
-      case "isGreaterThanBigInt":
-      case "isGreaterThanDate":
-        return `Schema.${filter.meta._tag}(${toRuntimeValue(filter.meta.exclusiveMinimum)}${ca})`
-      case "isGreaterThanOrEqualTo":
-      case "isGreaterThanOrEqualToBigInt":
-      case "isGreaterThanOrEqualToDate":
-        return `Schema.${filter.meta._tag}(${toRuntimeValue(filter.meta.minimum)}${ca})`
-      case "isLessThan":
-      case "isLessThanBigInt":
-      case "isLessThanDate":
-        return `Schema.${filter.meta._tag}(${toRuntimeValue(filter.meta.exclusiveMaximum)}${ca})`
-      case "isLessThanOrEqualTo":
-      case "isLessThanOrEqualToBigInt":
-      case "isLessThanOrEqualToDate":
-        return `Schema.${filter.meta._tag}(${toRuntimeValue(filter.meta.maximum)}${ca})`
-      case "isBetween":
-      case "isBetweenBigInt":
-      case "isBetweenDate":
-        return `Schema.${filter.meta._tag}({ minimum: ${toRuntimeValue(filter.meta.minimum)}, maximum: ${
-          toRuntimeValue(filter.meta.maximum)
-        }, exclusiveMinimum: ${toRuntimeValue(filter.meta.exclusiveMinimum)}, exclusiveMaximum: ${
-          toRuntimeValue(filter.meta.exclusiveMaximum)
-        }${ca})`
-
-      case "isMultipleOf":
-        return `Schema.isMultipleOf(${filter.meta.divisor}${ca})`
-
-      case "isMinProperties":
-        return `Schema.isMinProperties(${filter.meta.minProperties}${ca})`
-      case "isMaxProperties":
-        return `Schema.isMaxProperties(${filter.meta.maxProperties}${ca})`
-      case "isPropertiesLengthBetween":
-        return `Schema.isPropertiesLengthBetween(${filter.meta.minimum}, ${filter.meta.maximum}${ca})`
-      case "isPropertyNames":
-        return `Schema.isPropertyNames(${recur(filter.meta.propertyNames).runtime}${ca})`
-
-      case "isMinSize":
-        return `Schema.isMinSize(${filter.meta.minSize}${ca})`
-      case "isMaxSize":
-        return `Schema.isMaxSize(${filter.meta.maxSize}${ca})`
-      case "isSizeBetween":
-        return `Schema.isSizeBetween(${filter.meta.minimum}, ${filter.meta.maximum}${ca})`
-    }
-  }
-}
-
-const VALID_ASCII_UPPER_JAVASCRIPT_IDENTIFIER_REGEXP = /^[A-Z_$][A-Za-z0-9_$]*$/
-
-/**
- * Converts an arbitrary string into a valid (ASCII) JavaScript identifier
- * starting with an uppercase letter, `$`, or `_`.
- *
- * - Replaces invalid identifier characters with `_`
- * - Uppercases a leading ASCII letter
- * - If the first character is a digit, prefixes `_`
- * - Empty input becomes `_`
- *
- * @internal
- */
-export function sanitizeJavaScriptIdentifier(s: string): string {
-  if (s.length === 0) return "_"
-  if (VALID_ASCII_UPPER_JAVASCRIPT_IDENTIFIER_REGEXP.test(s)) return s
-
-  const out: Array<string> = []
-  let needsPrefix = false
-  let i = 0
-
-  for (const ch of s) {
-    if (i === 0) {
-      if (ch === "_" || ch === "$" || (ch >= "A" && ch <= "Z")) {
-        out.push(ch)
-      } else if (ch >= "a" && ch <= "z") {
-        out.push(ch.toUpperCase())
-      } else if (ch >= "0" && ch <= "9") {
-        out.push(ch)
-        needsPrefix = true
-      } else {
-        out.push("_")
-      }
-    } else {
-      out.push(isAsciiIdPart(ch) ? ch : "_")
-    }
-    i++
-  }
-
-  return needsPrefix ? "_" + out.join("") : out.join("")
-}
-
-function isAsciiIdStart(ch: string): boolean {
-  return (
-    ch === "_" ||
-    ch === "$" ||
-    (ch >= "A" && ch <= "Z") ||
-    (ch >= "a" && ch <= "z")
-  )
-}
-
-function isAsciiIdPart(ch: string): boolean {
-  return isAsciiIdStart(ch) || (ch >= "0" && ch <= "9")
-}
-
-function replacePlaceholders(template: string, items: ReadonlyArray<string>) {
-  let i = 0
-  return template.replace(/\?/g, () => items[i++]);
-}
-
-function toTypeParts(parts: ReadonlyArray<Representation>): ReadonlyArray<string> {
-  if (parts.length === 0) {
-    return [""]
-  }
-  const [first, ...rest] = parts
-  const restPatterns = toTypeParts(rest)
-  return toTypePart(first).flatMap((f) => restPatterns.map((r) => f + r))
-}
-
-function toTypePart(r: Representation): ReadonlyArray<string> {
-  switch (r._tag) {
-    case "Literal":
-      return [globalThis.String(r.literal)]
-    case "String":
-      return ["${string}"]
-    case "Number":
-      return ["${number}"]
-    case "BigInt":
-      return ["${bigint}"]
-    case "TemplateLiteral":
-      return toTypeParts(r.parts)
-    case "Union":
-      return r.types.flatMap(toTypePart)
-    default:
-      return []
-  }
-}
-
-const toCodeAnnotationsBlacklist: Set<string> = new Set([
-  ...toJsonAnnotationsBlacklist,
-  "typeConstructor",
-  "generation",
-  "brands"
-])
-
-function toRuntimeAnnotations(annotations: Schema.Annotations.Annotations | undefined): string {
-  if (!annotations) return ""
-  const entries: Array<string> = []
-  for (const [key, value] of Object.entries(annotations)) {
-    if (toCodeAnnotationsBlacklist.has(key)) continue
-    entries.push(`${formatPropertyKey(key)}: ${format(value)}`)
-  }
-  if (entries.length === 0) return ""
-  return `{ ${entries.join(", ")} }`
-}
-
-function toRuntimeBrand(annotations: Schema.Annotations.Annotations | undefined): string {
-  const brands = collectBrands(annotations)
-  return brands.length > 0 ? `.pipe(${brands.map((b) => `Schema.brand(${format(b)})`).join(", ")})` : ""
-}
-
-function toRuntimeAnnotate(annotations: Schema.Annotations.Annotations | undefined): string {
-  const s = toRuntimeAnnotations(annotations)
-  return s === "" ? "" : `.annotate(${s})`
-}
-
-function toRuntimeAnnotateKey(annotations: Schema.Annotations.Annotations | undefined): string {
-  const s = toRuntimeAnnotations(annotations)
-  return s === "" ? "" : `.annotateKey(${s})`
-}
-
-function toRuntimeIsOptional(isOptional: boolean, runtime: string): string {
-  return isOptional ? `Schema.optionalKey(${runtime})` : runtime
-}
-
-function toTypeIsOptional(isOptional: boolean, type: string): string {
-  return isOptional ? `${type}?` : type
-}
-
-function toRuntimeIsMutable(isMutable: boolean, runtime: string): string {
-  return isMutable ? `Schema.mutableKey(${runtime})` : runtime
-}
-
-function toTypeIsMutable(isMutable: boolean, type: string): string {
-  return isMutable ? type : `readonly ${type}`
-}
-
-function toRuntimeValue(value: undefined | number | boolean | bigint | Date): string {
-  if (value instanceof Date) {
-    return `new Date(${value.getTime()})`
-  }
-  return format(value)
-}
-
-function toRuntimeRegExp(regExp: RegExp): string {
-  const args = [format(regExp.source)]
-  const flags = regExp.flags.trim()
-  if (flags !== "") {
-    args.push(format(flags))
-  }
-  return `new RegExp(${args.join(", ")})`
-}
-
-/**
- * Parses a Draft 2020-12 JSON Schema document into a {@link Document}.
- *
- * **When to use**
- *
- * Use when you need to import a Draft 2020-12 JSON Schema document into the
- * Effect schema representation system.
- *
- * **Details**
- *
- * `options.onEnter` is an optional hook called on each JSON Schema node before
- * processing, allowing pre-transformation.
- *
- * **Gotchas**
- *
- * JSON Schema import is best-effort. Some JSON Schema constructs do not map
- * exactly to Effect schema representations, and importing a schema previously
- * emitted by `toJsonSchemaDocument` may produce an equivalent approximation
- * rather than the original representation shape.
- *
- * This throws if a `$ref` cannot be resolved within the document's definitions.
- * Circular `$ref`s are detected and cause an error.
- *
- * @see {@link Document}
- * @see {@link toJsonSchemaDocument}
- * @see {@link fromJsonSchemaMultiDocument}
+ * @see {@link fromJsonSchemaMultiDocument} for multiple roots sharing definitions
+ * @see {@link toRepresentation} for converting the result to a representation document
  *
  * @category constructors
  * @since 4.0.0
  */
-export function fromJsonSchemaDocument(document: JsonSchema.Document<"draft-2020-12">, options?: {
-  readonly onEnter?: ((js: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
-}): Document {
-  const { references, representations: schemas } = fromJsonSchemaMultiDocument({
-    dialect: document.dialect,
-    schemas: [document.schema],
-    definitions: document.definitions
-  }, options)
-  return {
-    representation: schemas[0],
-    references
-  }
+export function fromJsonSchemaDocument(
+  document: JsonSchema.Document<"draft-2020-12">,
+  options?: FromJsonSchemaOptions
+): Schema.Top {
+  return InternalFromJsonSchemaDocument.fromJsonSchemaDocument(document, options)
 }
 
 /**
- * Parses a Draft 2020-12 JSON Schema multi-document into a
- * {@link MultiDocument}.
+ * Imports multiple JSON Schema Draft 2020-12 roots as runtime schemas with shared definitions.
  *
  * **When to use**
  *
- * Use when you need to import a Draft 2020-12 JSON Schema multi-document whose
- * schemas share definitions.
- *
- * **Details**
- *
- * `options.onEnter` is an optional hook called on each JSON Schema node before
- * processing.
+ * Use when multiple imported roots must preserve shared definitions, aliases, and recursion.
  *
  * **Gotchas**
  *
- * JSON Schema import is best-effort. Some JSON Schema constructs do not map
- * exactly to Effect schema representations, and importing schemas previously
- * emitted by `toJsonSchemaMultiDocument` may produce equivalent approximations
- * rather than the original representation shapes.
- *
- * This throws if a `$ref` cannot be resolved.
+ * Every definition is translated, including definitions that no root references. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
- * @see {@link MultiDocument}
- * @see {@link toJsonSchemaMultiDocument}
- * @see {@link fromJsonSchemaDocument}
+ * @see {@link fromJsonSchemaDocument} for a single root
+ * @see {@link fromSchemaMultiDocument} for converting the result to a representation document
  *
  * @category constructors
  * @since 4.0.0
  */
-export function fromJsonSchemaMultiDocument(document: JsonSchema.MultiDocument<"draft-2020-12">, options?: {
-  readonly onEnter?: ((js: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
-}): MultiDocument {
-  let definitionIdentifier: string | undefined
-  const references: Record<string, Representation> = {}
-
-  type ResolvedReference = Exclude<Representation, { _tag: "Reference" }>
-  const resolvedReferences = new Map<string, ResolvedReference | null>()
-
-  function resolveReference($ref: string): ResolvedReference {
-    const definition = document.definitions[$ref]
-    if (definition === undefined) {
-      throw new Error(`Reference ${$ref} not found`)
-    }
-
-    const resolved = resolvedReferences.get($ref)
-    if (resolved === null) {
-      throw new Error(`Circular reference detected: ${$ref}`)
-    }
-    if (resolved !== undefined) return resolved
-
-    resolvedReferences.set($ref, null)
-    const value = recur(definition)
-    const out = value._tag === "Reference" ? resolveReference(value.$ref) : value
-    resolvedReferences.set($ref, out)
-    return out
-  }
-
-  for (const [identifier, definition] of Object.entries(document.definitions)) {
-    definitionIdentifier = identifier
-    references[identifier] = unknownToJson(recur(definition))
-  }
-
-  definitionIdentifier = undefined
-  const representations = Arr.map(document.schemas, (schema) => unknownToJson(recur(schema)))
-  return {
-    representations,
-    references
-  }
-
-  function recur(u: unknown): Representation {
-    if (u === false) return never
-    if (!Predicate.isObject(u)) return unknown
-
-    let js: JsonSchema.JsonSchema = options?.onEnter?.(u) ?? u
-    if (Array.isArray(js.type)) {
-      if (js.type.every(isType)) {
-        const { type, ...rest } = js
-        js = {
-          anyOf: type.map((type) => ({ type })),
-          ...rest
-        }
-      } else {
-        js = {}
-      }
-    }
-
-    let out = on(js)
-
-    const annotations = collectAnnotations(js)
-    if (annotations !== undefined) {
-      out = combine(out, { _tag: "Unknown", annotations })
-    }
-
-    if (Array.isArray(js.allOf)) {
-      out = js.allOf.reduce((acc, curr) => combine(acc, recur(curr)), out)
-    }
-    if (Array.isArray(js.anyOf)) {
-      out = combine({ _tag: "Union", types: js.anyOf.map((type) => recur(type)), mode: "anyOf" }, out)
-    }
-    if (Array.isArray(js.oneOf)) {
-      out = combine({ _tag: "Union", types: js.oneOf.map((type) => recur(type)), mode: "oneOf" }, out)
-    }
-
-    return out
-  }
-
-  function on(js: JsonSchema.JsonSchema): Representation {
-    if (typeof js.$ref === "string") {
-      const $ref = js.$ref.slice(2).split("/").at(-1)
-      if ($ref !== undefined) {
-        const reference: Reference = { _tag: "Reference", $ref: unescapeToken($ref) }
-        if (definitionIdentifier === $ref) {
-          return { _tag: "Suspend", thunk: reference, checks: [] }
-        } else {
-          return reference
-        }
-      }
-    } else if ("const" in js) {
-      if (isLiteralValue(js.const)) {
-        return { _tag: "Literal", literal: js.const }
-      } else if (js.const === null) {
-        return null_
-      }
-    } else if (Array.isArray(js.enum)) {
-      const types: Array<Representation> = []
-      for (const e of js.enum) {
-        if (isLiteralValue(e)) {
-          types.push({ _tag: "Literal", literal: e })
-        } else if (e === null) {
-          types.push(null_)
-        } else {
-          types.push(recur(e))
-        }
-      }
-      if (types.length === 1) {
-        return types[0]
-      } else {
-        return { _tag: "Union", types, mode: "anyOf" }
-      }
-    }
-
-    const type = isType(js.type) ? js.type : getType(js)
-    if (type !== undefined) {
-      switch (type) {
-        case "null":
-          return null_
-        case "string": {
-          const checks = collectStringChecks(js)
-          if (checks.length > 0) {
-            return { ...string, checks }
-          }
-          return string
-        }
-        case "number":
-          return {
-            _tag: "Number",
-            checks: [{ _tag: "Filter", meta: { _tag: "isFinite" } }, ...collectNumberChecks(js)]
-          }
-        case "integer":
-          return {
-            _tag: "Number",
-            checks: [{ _tag: "Filter", meta: { _tag: "isInt" } }, ...collectNumberChecks(js)]
-          }
-        case "boolean":
-          return boolean
-        case "array": {
-          const minItems = typeof js.minItems === "number" ? js.minItems : 0
-
-          const elements: Array<Element> = (Array.isArray(js.prefixItems) ? js.prefixItems : []).map((e, i) => ({
-            isOptional: i + 1 > minItems,
-            type: recur(e)
-          }))
-
-          const rest: Array<Representation> = js.items !== undefined ?
-            [recur(js.items)]
-            : js.prefixItems !== undefined && typeof js.maxItems === "number"
-            ? []
-            : [unknown]
-
-          return { _tag: "Arrays", elements, rest, checks: collectArraysChecks(js) }
-        }
-        case "object": {
-          return {
-            _tag: "Objects",
-            propertySignatures: collectProperties(js),
-            indexSignatures: collectIndexSignatures(js),
-            checks: collectObjectsChecks(js)
-          }
-        }
-      }
-    }
-
-    return { _tag: "Unknown" }
-  }
-
-  function collectObjectsChecks(js: JsonSchema.JsonSchema): Array<Check<ObjectsMeta>> {
-    const checks: Array<Check<ObjectsMeta>> = []
-    if (typeof js.minProperties === "number") {
-      checks.push({ _tag: "Filter", meta: { _tag: "isMinProperties", minProperties: js.minProperties } })
-    }
-    if (typeof js.maxProperties === "number") {
-      checks.push({ _tag: "Filter", meta: { _tag: "isMaxProperties", maxProperties: js.maxProperties } })
-    }
-    if (js.propertyNames !== undefined) {
-      const propertyNames = recur(js.propertyNames)
-      checks.push({ _tag: "Filter", meta: { _tag: "isPropertyNames", propertyNames } })
-    }
-    return checks
-  }
-
-  function combine(a: Representation, b: Representation): Representation {
-    switch (a._tag) {
-      default:
-        return never
-      case "Reference":
-        return combine(resolveReference(a.$ref), b)
-      case "Never":
-        return a
-      case "Unknown": {
-        const resolved = b._tag === "Reference" ? resolveReference(b.$ref) : b
-        return { ...resolved, ...combineAnnotations(a.annotations, resolved.annotations) }
-      }
-      case "Null":
-      case "String":
-      case "Number":
-      case "Boolean":
-      case "Literal":
-      case "Arrays":
-      case "Objects":
-      case "Union":
-        break
-    }
-
-    if (b._tag === "Reference") {
-      return combine(a, resolveReference(b.$ref))
-    }
-    if (b._tag === "Unknown") {
-      return { ...a, ...combineAnnotations(a.annotations, b.annotations) }
-    }
-    if (a._tag === "Union") {
-      const types = a.types.map((s) => combine(s, b)).filter((s) => s !== never)
-      if (types.length === 0) return never
-      return {
-        _tag: "Union",
-        types,
-        mode: a.mode,
-        ...makeAnnotations(a.annotations)
-      }
-    }
-    if (b._tag === "Union") {
-      return combine(b, a)
-    }
-
-    switch (a._tag) {
-      case "Null":
-        return b._tag === "Null" ? { ...a, ...combineAnnotations(a.annotations, b.annotations) } : never
-      case "String": {
-        if (b._tag === "Literal") {
-          return satisfiesLiteral(a, b) ? { ...b, ...combineAnnotations(a.annotations, b.annotations) } : never
-        }
-        if (b._tag !== "String") return never
-        const checks = combineChecks(a.checks, b.checks, b.annotations)
-        return {
-          _tag: "String",
-          checks: checks ?? a.checks,
-          ...combineAnnotations(a.annotations, checks ? undefined : b.annotations)
-        }
-      }
-      case "Number": {
-        if (b._tag === "Literal") {
-          return satisfiesLiteral(a, b) ? { ...b, ...combineAnnotations(a.annotations, b.annotations) } : never
-        }
-        if (b._tag !== "Number") return never
-        const checks = combineNumberChecks(a.checks, b.checks, b.annotations)
-        return {
-          _tag: "Number",
-          checks: checks ?? a.checks,
-          ...combineAnnotations(a.annotations, checks ? undefined : b.annotations)
-        }
-      }
-      case "Boolean":
-        if (b._tag === "Boolean") {
-          return { _tag: "Boolean", ...combineAnnotations(a.annotations, b.annotations) }
-        }
-        return b._tag === "Literal" && typeof b.literal === "boolean"
-          ? { ...b, ...combineAnnotations(a.annotations, b.annotations) }
-          : never
-      case "Literal":
-        switch (b._tag) {
-          case "Literal":
-            return a.literal === b.literal
-              ? { ...a, ...combineAnnotations(a.annotations, b.annotations) }
-              : never
-          case "String":
-          case "Number":
-            return satisfiesLiteral(b, a) ? { ...a, ...combineAnnotations(a.annotations, b.annotations) } : never
-          case "Boolean":
-            return typeof a.literal === "boolean"
-              ? { ...a, ...combineAnnotations(a.annotations, b.annotations) }
-              : never
-          default:
-            return never
-        }
-      case "Arrays": {
-        if (b._tag !== "Arrays") return never
-        const arrays = combineArrays(a, b)
-        if (arrays === undefined) return never
-        const checks = combineArraysChecks(a.checks, b.checks, b.annotations)
-        return {
-          _tag: "Arrays",
-          elements: arrays.elements,
-          rest: arrays.rest,
-          checks: checks ?? a.checks,
-          ...combineAnnotations(a.annotations, checks ? undefined : b.annotations)
-        }
-      }
-      case "Objects": {
-        if (b._tag !== "Objects") return never
-        const checks = combineChecks(a.checks, b.checks, b.annotations)
-        return {
-          _tag: "Objects",
-          propertySignatures: combinePropertySignatures(a.propertySignatures, b.propertySignatures),
-          indexSignatures: combineIndexSignatures(a.indexSignatures, b.indexSignatures),
-          checks: checks ?? a.checks,
-          ...combineAnnotations(a.annotations, checks ? undefined : b.annotations)
-        }
-      }
-      default:
-        return never
-    }
-  }
-
-  function satisfiesPrimitiveCheck(check: Check<Meta>, value: unknown): boolean {
-    if (check._tag === "FilterGroup") {
-      return check.checks.every((check) => satisfiesPrimitiveCheck(check, value))
-    }
-    const meta = check.meta
-    switch (meta._tag) {
-      case "isMinLength":
-        return typeof value === "string" && value.length >= meta.minLength
-      case "isMaxLength":
-        return typeof value === "string" && value.length <= meta.maxLength
-      case "isPattern":
-        return typeof value === "string" && meta.regExp.test(value)
-      case "isFinite":
-        return typeof value === "number" && globalThis.Number.isFinite(value)
-      case "isInt":
-        return typeof value === "number" && globalThis.Number.isSafeInteger(value)
-      case "isMultipleOf":
-        return typeof value === "number" && remainder(value, meta.divisor) === 0
-      case "isGreaterThan":
-        return typeof value === "number" && value > meta.exclusiveMinimum
-      case "isGreaterThanOrEqualTo":
-        return typeof value === "number" && value >= meta.minimum
-      case "isLessThan":
-        return typeof value === "number" && value < meta.exclusiveMaximum
-      case "isLessThanOrEqualTo":
-        return typeof value === "number" && value <= meta.maximum
-      default:
-        return false
-    }
-  }
-
-  function satisfiesLiteral(type: String | Number, literal: Literal): boolean {
-    const value = literal.literal
-    if (type._tag === "String" ? typeof value !== "string" : typeof value !== "number") {
-      return false
-    }
-    return type.checks.every((check) => satisfiesPrimitiveCheck(check, value))
-  }
-
-  function collectProperties(js: JsonSchema.JsonSchema): Array<PropertySignature> {
-    const properties: Record<string, unknown> = Predicate.isObject(js.properties) ? js.properties : {}
-    const required = Array.isArray(js.required) ? js.required : []
-    required.forEach((key) => {
-      if (!Object.hasOwn(properties, key)) {
-        properties[key] = {}
-      }
-    })
-    return Object.entries(properties).map(([key, v]) => ({
-      name: key,
-      type: recur(v),
-      isOptional: !required.includes(key),
-      isMutable: false
-    }))
-  }
-
-  function collectIndexSignatures(js: JsonSchema.JsonSchema): Array<IndexSignature> {
-    const out: Array<IndexSignature> = []
-
-    if (Predicate.isObject(js.patternProperties)) {
-      for (const [pattern, value] of Object.entries(js.patternProperties)) {
-        out.push({ parameter: recur({ pattern }), type: recur(value) })
-      }
-    }
-
-    if (js.additionalProperties === undefined || js.additionalProperties === true) {
-      out.push({ parameter: string, type: unknown })
-    } else if (Predicate.isObject(js.additionalProperties)) {
-      out.push({ parameter: string, type: recur(js.additionalProperties) })
-    }
-
-    return out
-  }
-
-  function combineArrays(a: Arrays, b: Arrays): Pick<Arrays, "elements" | "rest"> | undefined {
-    const elements: Array<Element> = []
-    const len = Math.max(a.elements.length, b.elements.length)
-    for (let i = 0; i < len; i++) {
-      const ae = a.elements[i]
-      const be = b.elements[i]
-      const isOptional = ae?.isOptional !== false && be?.isOptional !== false
-      const at = ae?.type ?? a.rest[0]
-      const bt = be?.type ?? b.rest[0]
-      if (at === undefined || bt === undefined) {
-        return isOptional ? { elements, rest: [] } : undefined
-      }
-      const type = combine(at, bt)
-      if (type === never) {
-        return isOptional ? { elements, rest: [] } : undefined
-      }
-      elements.push({ isOptional, type })
-    }
-
-    const ar = a.rest[0]
-    const br = b.rest[0]
-    if (ar === undefined || br === undefined) {
-      return { elements, rest: [] }
-    }
-    const rest = combine(ar, br)
-    return { elements, rest: rest === never ? [] : [rest] }
-  }
-
-  function combinePropertySignatures(
-    a: ReadonlyArray<PropertySignature>,
-    b: ReadonlyArray<PropertySignature>
-  ): Array<PropertySignature> {
-    const propertySignatures: Array<PropertySignature> = []
-    const thatPropertiesMap: Record<PropertyKey, PropertySignature> = {}
-    for (const p of b) {
-      thatPropertiesMap[p.name] = p
-    }
-    const keys = new Set<PropertyKey>()
-    for (const p of a) {
-      keys.add(p.name)
-      const thatp = thatPropertiesMap[p.name]
-      if (thatp) {
-        propertySignatures.push(
-          {
-            name: p.name,
-            type: combine(p.type, thatp.type),
-            isOptional: p.isOptional && thatp.isOptional,
-            isMutable: p.isMutable
-          }
-        )
-      } else {
-        propertySignatures.push(p)
-      }
-    }
-    for (const p of b) {
-      if (!keys.has(p.name)) propertySignatures.push(p)
-    }
-    return propertySignatures
-  }
-
-  function combineIndexSignatures(
-    a: ReadonlyArray<IndexSignature>,
-    b: ReadonlyArray<IndexSignature>
-  ): Array<IndexSignature> {
-    if (a.length === 0 || b.length === 0) return []
-    const out: Array<IndexSignature> = [...a]
-    for (const is of b) {
-      if (is.parameter === string) {
-        const i = a.findIndex((is) => is.parameter === string)
-        if (i !== -1) {
-          out[i] = { parameter: string, type: combine(a[i].type, is.type) }
-        } else {
-          out.push(is)
-        }
-      } else {
-        out.push(is)
-      }
-    }
-    return out
-  }
-
-  function unknownToJson(representation: Representation): Representation {
-    switch (representation._tag) {
-      case "Unknown":
-        return representation.annotations === undefined ?
-          json :
-          {
-            ...json,
-            annotations: {
-              ...json.annotations,
-              ...representation.annotations
-            }
-          }
-      case "Suspend": {
-        const thunk = unknownToJson(representation.thunk)
-        return thunk === representation.thunk ? representation : { ...representation, thunk }
-      }
-      case "String": {
-        if (representation.contentSchema === undefined) return representation
-        const contentSchema = unknownToJson(representation.contentSchema)
-        return contentSchema === representation.contentSchema ? representation : { ...representation, contentSchema }
-      }
-      case "Arrays": {
-        const elements = SchemaAST.mapOrSame(representation.elements, (element) => {
-          const type = unknownToJson(element.type)
-          return type === element.type ? element : { ...element, type }
-        })
-        const rest = SchemaAST.mapOrSame(representation.rest, unknownToJson)
-        return elements === representation.elements && rest === representation.rest ?
-          representation :
-          { ...representation, elements, rest }
-      }
-      case "Objects": {
-        const propertySignatures = SchemaAST.mapOrSame(representation.propertySignatures, (propertySignature) => {
-          const type = unknownToJson(propertySignature.type)
-          return type === propertySignature.type ? propertySignature : { ...propertySignature, type }
-        })
-        const indexSignatures = SchemaAST.mapOrSame(representation.indexSignatures, (indexSignature) => {
-          const type = unknownToJson(indexSignature.type)
-          return type === indexSignature.type ? indexSignature : { ...indexSignature, type }
-        })
-        return propertySignatures === representation.propertySignatures &&
-            indexSignatures === representation.indexSignatures ?
-          representation :
-          { ...representation, propertySignatures, indexSignatures }
-      }
-      case "Union": {
-        const types = SchemaAST.mapOrSame(representation.types, unknownToJson)
-        return types === representation.types ? representation : { ...representation, types }
-      }
-      default:
-        return representation
-    }
-  }
-}
-
-function asChecks<M>(
-  checks: ReadonlyArray<Check<M>>,
-  annotations: Schema.Annotations.Annotations | undefined
-): ReadonlyArray<Check<M>> | undefined {
-  if (Arr.isReadonlyArrayNonEmpty(checks)) {
-    if (annotations !== undefined) {
-      if (checks.length === 1) {
-        const check = checks[0]
-        if (check.annotations === undefined) {
-          return [{ ...check, annotations }]
-        } else {
-          return [{ _tag: "FilterGroup", checks, annotations }]
-        }
-      } else {
-        return [{ _tag: "FilterGroup", checks, annotations }]
-      }
-    }
-    return checks
-  }
-}
-
-function combineChecks<M>(
-  a: ReadonlyArray<Check<M>>,
-  b: ReadonlyArray<Check<M>>,
-  annotations: Schema.Annotations.Annotations | undefined
-): Array<Check<M>> | undefined {
-  const checks = asChecks(b, annotations)
-  if (checks) {
-    return [...a, ...checks]
-  }
-}
-
-function combineNumberChecks(
-  a: ReadonlyArray<Check<NumberMeta>>,
-  b: ReadonlyArray<Check<NumberMeta>>,
-  annotations: Schema.Annotations.Annotations | undefined
-): Array<Check<NumberMeta>> | undefined {
-  if (a.some((c) => c._tag === "Filter" && c.meta._tag === "isFinite")) {
-    b = b.filter((c) => c._tag !== "Filter" || c.meta._tag !== "isFinite")
-  }
-  if (a.some((c) => c._tag === "Filter" && c.meta._tag === "isInt")) {
-    b = b.filter((c) => c._tag !== "Filter" || c.meta._tag !== "isInt")
-  }
-  return combineChecks(a, b, annotations)
-}
-
-function combineArraysChecks(
-  a: ReadonlyArray<Check<ArraysMeta>>,
-  b: ReadonlyArray<Check<ArraysMeta>>,
-  annotations: Schema.Annotations.Annotations | undefined
-): Array<Check<ArraysMeta>> | undefined {
-  if (a.some((c) => c._tag === "Filter" && c.meta._tag === "isUnique")) {
-    b = b.filter((c) => c._tag !== "Filter" || c.meta._tag !== "isUnique")
-  }
-  return combineChecks(a, b, annotations)
-}
-
-function makeAnnotations(
-  annotations: Schema.Annotations.Annotations | undefined
-): { annotations: Schema.Annotations.Annotations } | undefined {
-  return annotations ? { annotations } : undefined
-}
-
-function combineAnnotations(
-  a: Schema.Annotations.Annotations | undefined,
-  b: Schema.Annotations.Annotations | undefined
-): { annotations: Schema.Annotations.Annotations } | undefined {
-  if (a === undefined) return makeAnnotations(b)
-  if (b === undefined) return makeAnnotations(a)
-  return { annotations: { ...a, ...b } } // TODO: better merge
-}
-
-function collectStringChecks(js: JsonSchema.JsonSchema): Array<Check<StringMeta>> {
-  const checks: Array<Check<StringMeta>> = []
-  if (typeof js.minLength === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isMinLength", minLength: js.minLength } })
-  }
-  if (typeof js.maxLength === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isMaxLength", maxLength: js.maxLength } })
-  }
-  if (typeof js.pattern === "string") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isPattern", regExp: new RegExp(js.pattern) } })
-  }
-  return checks
-}
-
-function collectNumberChecks(js: JsonSchema.JsonSchema): Array<Check<NumberMeta>> {
-  const checks: Array<Check<NumberMeta>> = []
-  if (typeof js.minimum === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isGreaterThanOrEqualTo", minimum: js.minimum } })
-  }
-  if (typeof js.maximum === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isLessThanOrEqualTo", maximum: js.maximum } })
-  }
-  if (typeof js.exclusiveMinimum === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isGreaterThan", exclusiveMinimum: js.exclusiveMinimum } })
-  }
-  if (typeof js.exclusiveMaximum === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isLessThan", exclusiveMaximum: js.exclusiveMaximum } })
-  }
-  if (typeof js.multipleOf === "number") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isMultipleOf", divisor: js.multipleOf } })
-  }
-  return checks
-}
-
-function collectArraysChecks(js: JsonSchema.JsonSchema): Array<Check<ArraysMeta>> {
-  const checks: Array<Check<ArraysMeta>> = []
-  if (js.prefixItems === undefined) {
-    if (typeof js.minItems === "number") {
-      checks.push({ _tag: "Filter", meta: { _tag: "isMinLength", minLength: js.minItems } })
-    }
-    if (typeof js.maxItems === "number") {
-      checks.push({ _tag: "Filter", meta: { _tag: "isMaxLength", maxLength: js.maxItems } })
-    }
-  }
-  if (typeof js.uniqueItems === "boolean") {
-    checks.push({ _tag: "Filter", meta: { _tag: "isUnique" } })
-  }
-  return checks
-}
-
-const unknown: Unknown = { _tag: "Unknown" }
-const json: Declaration = {
-  _tag: "Declaration",
-  annotations: {
-    expected: "JSON value",
-    generation: {
-      Type: "Schema.Json",
-      runtime: "Schema.Json"
-    },
-    typeConstructor: {
-      _tag: "effect/Json"
-    }
-  },
-  checks: [],
-  encodedSchema: unknown,
-  typeParameters: []
-}
-const never: Never = { _tag: "Never" }
-const null_: Null = { _tag: "Null" }
-const string: String = { _tag: "String", checks: [] }
-const boolean: Boolean = { _tag: "Boolean" }
-
-function collectAnnotations(
-  schema: JsonSchema.JsonSchema
-): Schema.Annotations.Annotations | undefined {
-  const as: Record<string, unknown> = {}
-
-  if (typeof schema.title === "string") as.title = schema.title
-  if (typeof schema.description === "string") as.description = schema.description
-  if (schema.default !== undefined) as.default = schema.default
-  if (Array.isArray(schema.examples)) as.examples = schema.examples
-  if (typeof schema.readOnly === "boolean") as.readOnly = schema.readOnly
-  if (typeof schema.writeOnly === "boolean") as.writeOnly = schema.writeOnly
-  if (typeof schema.format === "string") as.format = schema.format
-  if (typeof schema.contentEncoding === "string") as.contentEncoding = schema.contentEncoding
-  if (typeof schema.contentMediaType === "string") as.contentMediaType = schema.contentMediaType
-
-  return Rec.isEmptyRecord(as) ? undefined : as
-}
-
-function isLiteralValue(value: unknown): value is SchemaAST.LiteralValue {
-  return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
-}
-
-const stringKeys = ["minLength", "maxLength", "pattern", "format", "contentMediaType", "contentSchema"]
-const numberKeys = ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"]
-const objectKeys = [
-  "properties",
-  "required",
-  "additionalProperties",
-  "patternProperties",
-  "propertyNames",
-  "minProperties",
-  "maxProperties"
-]
-const arrayKeys = ["items", "prefixItems", "additionalItems", "minItems", "maxItems", "uniqueItems"]
-
-function getType(js: JsonSchema.JsonSchema): JsonSchema.Type | undefined {
-  if (stringKeys.some((key) => js[key] !== undefined)) {
-    return "string"
-  }
-  if (numberKeys.some((key) => js[key] !== undefined)) {
-    return "number"
-  }
-  if (objectKeys.some((key) => js[key] !== undefined)) {
-    return "object"
-  }
-  if (arrayKeys.some((key) => js[key] !== undefined)) {
-    return "array"
-  }
-}
-
-const types = ["null", "string", "number", "integer", "boolean", "object", "array"]
-
-function isType(type: unknown): type is JsonSchema.Type {
-  return typeof type === "string" && types.includes(type)
-}
-
-/** @internal */
-export type TopologicalSort = {
-  /**
-   * The definitions that are not recursive.
-   * The definitions that depends on other definitions are placed after the definitions they depend on
-   */
-  readonly nonRecursives: ReadonlyArray<{
-    readonly $ref: string
-    readonly representation: Representation
-  }>
-  /**
-   * The recursive definitions (with no particular order).
-   */
-  readonly recursives: {
-    readonly [$ref: string]: Representation
-  }
-}
-
-/** @internal */
-export function topologicalSort(references: References): TopologicalSort {
-  const identifiers = Object.keys(references)
-  const identifierSet = new Set(identifiers)
-
-  const collectRefs = (root: Representation): Set<string> => {
-    const refs = new Set<string>()
-    const visited = new WeakSet<object>()
-    const stack: Array<Representation> = [root]
-
-    while (stack.length > 0) {
-      const r = stack.pop()!
-      if (visited.has(r)) continue
-      visited.add(r)
-
-      if (r._tag === "Reference") {
-        if (identifierSet.has(r.$ref)) {
-          refs.add(r.$ref)
-        }
-      }
-
-      // Push nested Representation schemas onto the stack
-      switch (r._tag) {
-        case "Declaration":
-          for (const typeParam of r.typeParameters) stack.push(typeParam)
-          stack.push(r.encodedSchema)
-          break
-        case "Suspend":
-          stack.push(r.thunk)
-          break
-        case "String":
-          if (r.contentSchema !== undefined) stack.push(r.contentSchema)
-          break
-        case "TemplateLiteral":
-          for (const part of r.parts) stack.push(part)
-          break
-        case "Arrays":
-          for (const element of r.elements) stack.push(element.type)
-          for (const rest of r.rest) stack.push(rest)
-          break
-        case "Objects":
-          for (const propertySignature of r.propertySignatures) stack.push(propertySignature.type)
-          for (const indexSignature of r.indexSignatures) {
-            stack.push(indexSignature.parameter)
-            stack.push(indexSignature.type)
-          }
-          break
-        case "Union":
-          for (const type of r.types) stack.push(type)
-          break
-      }
-    }
-
-    return refs
-  }
-
-  // identifier -> internal identifiers it depends on
-  const dependencies = new Map<string, Set<string>>(
-    identifiers.map((id) => [id, collectRefs(references[id])])
-  )
-
-  // Mark only nodes that are part of cycles
-  const recursive = new Set<string>()
-  const state = new Map<string, 0 | 1 | 2>() // 0 = new, 1 = visiting, 2 = done
-  const stack: Array<string> = []
-  const indexInStack = new Map<string, number>()
-
-  const dfs = (id: string): void => {
-    const s = state.get(id) ?? 0
-    if (s === 1) {
-      const start = indexInStack.get(id)
-      if (start !== undefined) {
-        for (let i = start; i < stack.length; i++) {
-          recursive.add(stack[i])
-        }
-      }
-      return
-    }
-    if (s === 2) return
-
-    state.set(id, 1)
-    indexInStack.set(id, stack.length)
-    stack.push(id)
-
-    for (const dep of dependencies.get(id) ?? []) {
-      dfs(dep)
-    }
-
-    stack.pop()
-    indexInStack.delete(id)
-    state.set(id, 2)
-  }
-
-  for (const id of identifiers) dfs(id)
-
-  // Topologically sort the non-recursive nodes (ignoring edges to recursive nodes)
-  const inDegree = new Map<string, number>()
-  const dependents = new Map<string, Set<string>>() // dep -> nodes that depend on it
-
-  for (const id of identifiers) {
-    if (!recursive.has(id)) {
-      inDegree.set(id, 0)
-      dependents.set(id, new Set())
-    }
-  }
-
-  for (const [id, deps] of dependencies) {
-    if (recursive.has(id)) continue
-    for (const dep of deps) {
-      if (recursive.has(dep)) continue
-      inDegree.set(id, (inDegree.get(id) ?? 0) + 1)
-      dependents.get(dep)?.add(id)
-    }
-  }
-
-  const queue: Array<string> = []
-  for (const [id, deg] of inDegree) {
-    if (deg === 0) queue.push(id)
-  }
-
-  const nonRecursives: Array<{ readonly $ref: string; readonly representation: Representation }> = []
-  for (let i = 0; i < queue.length; i++) {
-    const $ref = queue[i]
-    nonRecursives.push({ $ref, representation: references[$ref] })
-
-    for (const next of dependents.get($ref) ?? []) {
-      const deg = (inDegree.get(next) ?? 0) - 1
-      inDegree.set(next, deg)
-      if (deg === 0) queue.push(next)
-    }
-  }
-
-  const recursives: Record<string, Representation> = {}
-  for (const $ref of recursive) {
-    recursives[$ref] = references[$ref]
-  }
-
-  return { nonRecursives, recursives }
+export function fromJsonSchemaMultiDocument(
+  document: JsonSchema.MultiDocument<"draft-2020-12">,
+  options?: FromJsonSchemaOptions
+): SchemaMultiDocument {
+  return InternalFromJsonSchemaDocument.fromJsonSchemaMultiDocument(document, options)
 }