effect 4.0.5 → 4.0.7

package/src/SchemaAST.ts

@@ -480,7 +480,7 @@ export type Encoding = readonly [Link, ...Array<Link>]
  *
  * **Details**
  *
- * Pass to `Schema.decodeUnknown`, `Schema.encode`, and related APIs to customize
+ * Pass to `Schema.decodeUnknownEffect`, `Schema.encodeEffect`, and related APIs to customize
  * error reporting, excess property handling, check execution, and product
  * concurrency. Options apply throughout the parse; schema annotations do not
  * override them.
@@ -814,7 +814,13 @@ export const Declaration: new(
     let run: ReturnType<typeof this.run>
     return (input, options) => {
       if (input === InternalParser.missing) return InternalParser.missingExit
-      return (run ??= this.run(this.typeParameters))(input, this, options)
+      // Keep this declaration's initialization errors outside its callback catch.
+      run ??= this.run(this.typeParameters)
+      try {
+        return run(input, this, options)
+      } catch (error) {
+        return Effect.die(error)
+      }
     }
   }
   private _rebuild(
@@ -2435,7 +2441,7 @@ export const Arrays: new(
         input,
         len,
         tailThreshold: Math.max(elementLen, len - tailLen),
-        output: new globalThis.Array(len),
+        output: [],
         issues: undefined,
         options
       }
@@ -2599,9 +2605,12 @@ const wrapPropertyKeyIssue = (
 
 /**
  * floating point or integer, with optional exponent
+ *
+ * The mantissa alternation keeps rejection linear: `\d*\.?\d+` retries
+ * every split of a long digit run.
  * @internal
  */
-export const FINITE_PATTERN = "[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?"
+export const FINITE_PATTERN = "[+-]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:[Ee][+-]?\\d+)?"
 
 /**
  * Returns the object keys that match the index signature parameter schema.
@@ -2730,8 +2739,10 @@ function isIndexSignatureParameter(ast: AST): ast is IndexSignatureParameter {
  *
  * **Gotchas**
  *
- * Using `Schema.optionalKey` on the value type is not allowed for index
- * signatures (throws at construction); use `Schema.optional` instead.
+ * Using `Schema.optionalKey` or `Schema.optional` on the value type is not
+ * allowed for index signatures (throws at construction). Index signatures
+ * already allow keys to be absent; use `Schema.UndefinedOr` to allow
+ * `undefined` values.
  *
  * @see {@link Objects}
  * @see {@link PropertySignature}
@@ -2764,8 +2775,10 @@ export const IndexSignature: new(parameter: AST, type: AST) => IndexSignature =
     }
     this.parameter = parameter
     this.type = type
-    if (isOptional(type) && !containsUndefined(type)) {
-      throw new Error("Cannot use `Schema.optionalKey` with index signatures, use `Schema.optional` instead.")
+    if (isOptional(type) || (type.encoding !== undefined && isOptional(toEncoded(type)))) {
+      throw new Error(
+        "Cannot use `Schema.optionalKey` or `Schema.optional` with index signatures. Index signatures already allow keys to be absent; use `Schema.UndefinedOr` to allow `undefined` values."
+      )
     }
   }
 }
@@ -3101,12 +3114,14 @@ export const Objects: new(
     // Resumes at the property whose parser suspended, without replaying the
     // properties already parsed.
     const resume = (
-      state: ObjectParserState,
+      snapshot: ObjectParserState,
       index: number,
       pending: Effect.Effect<unknown, SchemaIssue.Issue, any>
     ): Effect.Effect<unknown, SchemaIssue.Issue, any> => {
       const property = properties![index]
       return Effect.flatMap(Effect.exit(pending), (exit) => {
+        // Copy the parsed prefix per execution so reruns cannot overwrite earlier results.
+        const state: ObjectParserState = { ...snapshot, out: { ...snapshot.out } }
         const terminal = stepProperty(state, property, exit)
         if (terminal) return terminal
         const done = () => InternalParser.succeed(state.out)
@@ -4278,7 +4293,7 @@ const numberToJson = new Link(
  *
  * **Details**
  *
- * The filter can be used with `Schema.filter` or attached directly to a
+ * The filter can be used with `Schema.check` or attached directly to a
  * `String` AST node through checks. The regular expression is cloned and its
  * `lastIndex` is reset before each test, so global and sticky expressions are
  * deterministic and the provided regular expression is not mutated. The
@@ -4587,16 +4602,24 @@ function parseParameter(ast: AST): {
 } {
   const literals: Array<PropertyKey> = []
   const parameters: Array<AST> = []
+  function addLiteral(literal: PropertyKey) {
+    if (!literals.includes(literal)) {
+      literals.push(literal)
+    }
+  }
   function go(ast: AST) {
     switch (ast._tag) {
       case "Literal":
-        if (Predicate.isPropertyKey(ast.literal) && !literals.includes(ast.literal)) {
-          literals.push(ast.literal)
+        if (Predicate.isPropertyKey(ast.literal)) {
+          addLiteral(ast.literal)
         }
         return
       case "UniqueSymbol":
-        if (!literals.includes(ast.symbol)) {
-          literals.push(ast.symbol)
+        addLiteral(ast.symbol)
+        return
+      case "Enum":
+        for (const [, value] of ast.enums) {
+          addLiteral(value)
         }
         return
       case "Never":
@@ -4777,7 +4800,7 @@ function flipEncoding(ast: AST, encoding: Encoding): AST {
  * **Details**
  *
  * After flipping, what was decoding becomes encoding and vice versa. This is
- * the core operation behind `Schema.encode` — encoding a value is decoding
+ * the core operation behind `Schema.encodeEffect` — encoding a value is decoding
  * with a flipped SchemaAST.
  *
  * - Memoized: same input reference → same output reference.
@@ -4801,18 +4824,6 @@ export const flip = memoize((ast: AST): AST => {
   return "flip" in ast ? ast.flip(flip) : "recur" in ast ? ast.recur(flip) : ast
 })
 
-/** @internal */
-export function containsUndefined(ast: AST): boolean {
-  switch (ast._tag) {
-    case "Undefined":
-      return true
-    case "Union":
-      return ast.types.some(containsUndefined)
-    default:
-      return false
-  }
-}
-
 function fromConst<const T>(
   ast: AST,
   value: T
@@ -5110,7 +5121,7 @@ export function getConstructorDescriptor(ast: AST): ConstructorDescriptor | unde
  * **Details**
  *
  * If the node has {@link Checks}, returns annotations from the last check
- * (which is where user-supplied annotations end up after `.pipe(Schema.annotations(...))`).
+ * (which is where user-supplied annotations end up after `.pipe(Schema.annotate(...))`).
  * Otherwise returns the node's `annotations` directly.
  *
  * **Example** (Reading annotations)
@@ -5153,7 +5164,7 @@ export const resolveAt: <A>(key: string) => (ast: AST) => A | undefined = Intern
  *
  * **Details**
  *
- * The identifier is typically set by `Schema.annotations({ identifier: "..." })`
+ * The identifier is typically set by `Schema.annotate({ identifier: "..." })`
  * and is used for error messages and schema identification.
  *
  * @see {@link resolve}

package/src/SchemaGetter.ts

@@ -1159,7 +1159,8 @@ export function Boolean<E>(): Getter<boolean, E> {
  * **Details**
  *
  * - Delegates to `globalThis.BigInt`.
- * - Throws at runtime if the input cannot be converted (e.g. non-numeric string).
+ * - Fails with `SchemaIssue.InvalidValue` if the input cannot be converted
+ *   (e.g. a non-numeric string or a non-integer number).
  *
  * **Example** (Coercing to a bigint)
  *
@@ -1175,7 +1176,19 @@ export function Boolean<E>(): Getter<boolean, E> {
  * @since 4.0.0
  */
 export function BigInt<E extends string | number | bigint | boolean>(): Getter<bigint, E> {
-  return transform(globalThis.BigInt)
+  return transformEffect((input, options) => {
+    try {
+      return Effect.succeed(globalThis.BigInt(input))
+    } catch {
+      return Effect.fail(
+        new SchemaIssue.InvalidValue(
+          { expected: "a value that can be converted to a bigint" },
+          input,
+          options
+        )
+      )
+    }
+  })
 }
 
 /**
@@ -1677,7 +1690,8 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
  *
  * **Details**
  *
- * The getter is pure and never fails.
+ * The getter is pure and never fails. The output is unpadded unless
+ * `padding` is `true`.
  *
  * **Example** (Encoding to Base64Url)
  *
@@ -1697,8 +1711,11 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
  * @category encoding
  * @since 4.0.0
  */
-export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string, E> {
-  return transform(Base64Url.encode)
+export function encodeBase64Url<E extends Uint8Array | string>(options?: {
+  /** Keep the `=` padding. Defaults to `false`. */
+  readonly padding?: boolean | undefined
+}): Getter<string, E> {
+  return transform(options?.padding ? Base64Url.encodePadded : Base64Url.encode)
 }
 
 /**

package/src/SchemaIssue.ts

@@ -720,8 +720,8 @@ export const InvalidType: new(
  *
  * **When to use**
  *
- * Use when you need to detect constraint violations from `Schema.filter`,
- * `Schema.minLength`, `Schema.greaterThan`, or similar checks.
+ * Use when you need to detect constraint violations from `Schema.check` with
+ * `Schema.isMinLength`, `Schema.isGreaterThan`, or similar checks.
  *
  * **Details**
  *
@@ -1242,8 +1242,8 @@ export type CheckHook = (issue: Filter) => string | undefined
  *
  * **Details**
  *
- * - Looks for a `message` annotation on the inner issue first, then on the
- *   filter itself.
+ * - Looks for a `message` annotation on the filter first, then on the inner
+ *   issue.
  * - Returns `undefined` when no annotation is found, causing the formatter to
  *   fall back to `"Expected <filter>"` or, when the filter reports input,
  *   `"Expected <filter>, got <input>"`.
@@ -1255,7 +1255,7 @@ export type CheckHook = (issue: Filter) => string | undefined
  * @category formatting
  * @since 4.0.0
  */
-export const defaultCheckHook: CheckHook = (issue): string | undefined => findMessage(issue.issue) ?? findMessage(issue)
+export const defaultCheckHook: CheckHook = (issue): string | undefined => findMessage(issue) ?? findMessage(issue.issue)
 
 /**
  * Creates a {@link Formatter} that produces a `StandardSchemaV1.FailureResult`.
@@ -1329,46 +1329,48 @@ function getExpectedMessage(expected: string, issue: Issue): string {
   return input === undefined ? `Expected ${expected}` : `Expected ${expected}, got ${input}`
 }
 
+function getFilterMessage(issue: Filter, checkHook: CheckHook): string | undefined {
+  const message = checkHook(issue)
+  if (message !== undefined || issue.issue._tag !== "InvalidValue") return message
+  const expected = findExpected(issue.issue)
+  return expected === undefined
+    ? getExpectedMessage(formatCheck(issue.filter), issue)
+    : getExpectedMessage(expected, issue.issue)
+}
+
 function toDefaultIssues(
   issue: Issue,
   path: ReadonlyArray<PropertyKey>,
   leafHook: LeafHook,
-  checkHook: CheckHook
+  checkHook: CheckHook,
+  messageOverride?: string
 ): Array<DefaultIssue> {
   switch (issue._tag) {
-    case "Filter": {
-      const message = checkHook(issue)
-      if (message !== undefined) {
-        return [{ path, message }]
-      }
-      if (issue.issue._tag !== "InvalidValue") {
-        return toDefaultIssues(issue.issue, path, leafHook, checkHook)
-      }
-      const expected = findExpected(issue.issue)
-      return [{
+    case "Filter":
+      return toDefaultIssues(
+        issue.issue,
         path,
-        message: expected === undefined
-          ? getExpectedMessage(formatCheck(issue.filter), issue)
-          : getExpectedMessage(expected, issue.issue)
-      }]
-    }
+        leafHook,
+        checkHook,
+        messageOverride ?? getFilterMessage(issue, checkHook)
+      )
     case "Encoding":
-      return toDefaultIssues(issue.issue, path, leafHook, checkHook)
+      return toDefaultIssues(issue.issue, path, leafHook, checkHook, messageOverride)
     case "Pointer":
-      return toDefaultIssues(issue.issue, [...path, ...issue.path], leafHook, checkHook)
+      return toDefaultIssues(issue.issue, [...path, ...issue.path], leafHook, checkHook, messageOverride)
     case "Composite":
-      return issue.issues.flatMap((issue) => toDefaultIssues(issue, path, leafHook, checkHook))
     case "AnyOf": {
-      if (issue.issues.length === 0) {
-        return [{
-          path,
-          message: findMessage(issue) ?? getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
-        }]
+      if (issue._tag === "Composite" || issue.issues.length > 0) {
+        return issue.issues.flatMap((issue) => toDefaultIssues(issue, path, leafHook, checkHook, messageOverride))
       }
-      return issue.issues.flatMap((issue) => toDefaultIssues(issue, path, leafHook, checkHook))
+      return [{
+        path,
+        message: messageOverride ?? findMessage(issue) ??
+          getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
+      }]
     }
     default:
-      return [{ path, message: leafHook(issue) }]
+      return [{ path, message: messageOverride ?? leafHook(issue) }]
   }
 }
 
@@ -1431,45 +1433,34 @@ export function makeFormatterDefault(): Formatter<string> {
 /** @internal */
 export const defaultFormatter = makeFormatterDefault()
 
-function formatIssue(issue: Issue, path: string): string {
+function formatIssue(issue: Issue, path: string, messageOverride?: string): string {
   let message: string
   switch (issue._tag) {
-    case "Filter": {
-      const annotated = defaultCheckHook(issue)
-      if (annotated !== undefined) {
-        message = annotated
-      } else {
-        if (issue.issue._tag !== "InvalidValue") {
-          return formatIssue(issue.issue, path)
-        }
-        const expected = findExpected(issue.issue)
-        message = expected === undefined
-          ? getExpectedMessage(formatCheck(issue.filter), issue)
-          : getExpectedMessage(expected, issue.issue)
-      }
-      break
-    }
+    case "Filter":
+      return formatIssue(issue.issue, path, messageOverride ?? getFilterMessage(issue, defaultCheckHook))
     case "Encoding":
-      return formatIssue(issue.issue, path)
+      return formatIssue(issue.issue, path, messageOverride)
     case "Pointer":
-      return formatIssue(issue.issue, path + formatPath(issue.path))
+      return formatIssue(issue.issue, path + formatPath(issue.path), messageOverride)
     case "Composite":
     case "AnyOf": {
       if (issue._tag === "Composite" || issue.issues.length > 0) {
-        return issue.issues.map((issue) => formatIssue(issue, path)).join("\n")
+        return issue.issues.map((issue) => formatIssue(issue, path, messageOverride)).join("\n")
       }
-      message = findMessage(issue) ?? getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
+      message = messageOverride ?? findMessage(issue) ??
+        getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
       break
     }
     default:
-      message = defaultLeafHook(issue)
+      message = messageOverride ?? defaultLeafHook(issue)
       break
   }
   return path ? `${message}\n  at ${path}` : message
 }
 
 function findMessage(issue: Issue): string | undefined {
-  if (issue._tag === "Pointer") return
+  // A Composite's ast describes the whole schema, not the failures it groups.
+  if (issue._tag === "Pointer" || issue._tag === "Composite") return
   if (issue._tag === "Encoding") return findMessage(issue.issue)
   const annotations = issue._tag === "Filter"
     ? issue.filter.annotations

package/src/SchemaParser.ts

@@ -1136,29 +1136,62 @@ function runSync<T>(effect: Effect.Effect<T, SchemaIssue.Issue>, message: string
   throw new Error("Schema validation failed", { cause: issue })
 }
 
+const constructorDefectMessage = "Constructor adapter can only throw schema issues"
+
+function throwConstructorDefect(error: unknown): never {
+  throw new Error(constructorDefectMessage, { cause: Cause.die(error) })
+}
+
 function makeConstructorSync<T, E>(
   ast: SchemaAST.AST
 ): (input: E, options?: Schema.MakeOptions) => T {
   let entry: CompilerRegistry.Entry | undefined
-  let parser: Parser | undefined
-  return (input, options) => {
-    entry ??= CompilerRegistry.resolve(ast)
-    const parseOptions = options?.disableChecks
-      ? options.parseOptions ? { ...options.parseOptions, disableChecks: true } : { disableChecks: true }
-      : options?.parseOptions ?? SchemaAST.defaultParseOptions
-    const make = entry.make
-    if (make !== undefined && input !== InternalParser.missing) {
-      let output: unknown
-      try {
-        output = make(input, parseOptions)
-      } catch (error) {
-        InternalSchemaCause.getSchemaIssueOrThrow(Cause.die(error), "Constructor adapter can only throw schema issues")
-        throw error
-      }
-      if (output !== CompilerRegistry.invalid && output !== InternalParser.missing) return output as T
+  return (input, options) => constructSync(entry ??= CompilerRegistry.resolve(ast), input, options)
+}
+
+function constructSync<T>(entry: CompilerRegistry.Entry, input: unknown, options: Schema.MakeOptions | undefined): T {
+  const parseOptions = options?.disableChecks
+    ? options.parseOptions ? { ...options.parseOptions, disableChecks: true } : { disableChecks: true }
+    : options?.parseOptions ?? SchemaAST.defaultParseOptions
+  const make = entry.make
+  if (make !== undefined && input !== InternalParser.missing) {
+    let output: unknown
+    try {
+      output = make(input, parseOptions)
+    } catch (error) {
+      throwConstructorDefect(error)
     }
-    const result = (parser ??= entry.makeEffect)(input, parseOptions)
-    return runSync(parserResult<T, never>(result, input), "Constructor adapter can only throw schema issues")
+    if (output !== CompilerRegistry.invalid && output !== InternalParser.missing) return output as T
+  }
+  return runSync(parserResult<T, never>(entry.makeEffect(input, parseOptions), input), constructorDefectMessage)
+}
+
+/**
+ * Constructs a class instance from its type-side declaration.
+ *
+ * When the declaration has no compiled constructor, the fields are validated first
+ * and the instance is built outside the parser, so stacks captured by the
+ * class constructor keep the caller's frames.
+ *
+ * @internal
+ */
+export function makeClassSync<T>(
+  ast: SchemaAST.AST,
+  input: unknown,
+  options: Schema.MakeOptions | undefined,
+  construct: (fields: object) => T
+): T {
+  const entry = CompilerRegistry.resolve(ast)
+  const descriptor = SchemaAST.getConstructorDescriptor(ast)
+  if (descriptor === undefined || entry.make !== undefined || entry.compiledMakeEffect !== undefined) {
+    return constructSync(entry, input, options)
+  }
+  if (descriptor.isConstructed(input)) return input as T
+  const fields = constructSync<object>((entry.resolve ?? CompilerRegistry.resolve)(descriptor.link.to), input, options)
+  try {
+    return construct(fields)
+  } catch (error) {
+    throwConstructorDefect(error)
   }
 }
 

package/src/SchemaRepresentation.ts

@@ -288,13 +288,19 @@ export interface Unknown extends Keyword<"Unknown"> {}
 export interface Any extends Keyword<"Any"> {}
 
 /**
- * A string representation.
+ * A string representation, optionally describing its content through a media
+ * type and a schema for the value encoded in the string.
  *
  * @stability stable
  * @category models
  * @since 4.0.0
  */
-export interface String extends Keyword<"String"> {}
+export interface String extends Keyword<"String"> {
+  readonly content?: {
+    readonly mediaType: string
+    readonly schema?: Representation | undefined
+  } | undefined
+}
 
 /**
  * A number representation.
@@ -1944,6 +1950,32 @@ export const BigDecimalReviver: DeclarationReviver<null> = makeFixedDeclarationR
   Schema.BigDecimal
 )
 
+/**
+ * Reviver for persisted {@link Schema.SemVer} declarations.
+ *
+ * @see {@link Schema.SemVer} for the corresponding schema
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVerReviver: DeclarationReviver<null> = makeFixedDeclarationReviver(
+  "effect/schema/SemVer",
+  Schema.SemVer
+)
+
+/**
+ * Reviver for persisted {@link Schema.SemVerRange} declarations.
+ *
+ * @see {@link Schema.SemVerRange} for the corresponding schema
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVerRangeReviver: DeclarationReviver<null> = makeFixedDeclarationReviver(
+  "effect/schema/SemVerRange",
+  Schema.SemVerRange
+)
+
 /**
  * Reviver for persisted `File` declarations.
  *
@@ -2362,32 +2394,13 @@ export const MutableJsonReviver: DeclarationReviver<null> = makeFixedDeclaration
   Schema.MutableJson
 )
 
-const jsonSchemaRevivers: ReadonlyArray<AnyReviver> = [
-  JsonReviver,
-  isPatternReviver,
-  isFiniteReviver,
-  isGreaterThanReviver,
-  isGreaterThanOrEqualToReviver,
-  isLessThanReviver,
-  isLessThanOrEqualToReviver,
-  isMultipleOfReviver,
-  isIntReviver,
-  isMinLengthReviver,
-  isMaxLengthReviver,
-  isMinCodePointsReviver,
-  isMaxCodePointsReviver,
-  isMinPropertiesReviver,
-  isMaxPropertiesReviver,
-  isPropertyNamesReviver,
-  isUniqueReviver
-]
-
 /**
  * Options for importing JSON Schema Draft 2020-12 documents.
  *
  * **When to use**
  *
- * Use when you need to configure pattern handling or transform each JSON Schema node before translation.
+ * Use when you need to configure pattern handling, preserve custom annotations, or transform each JSON Schema node
+ * before translation.
  *
  * **Details**
  *
@@ -2422,6 +2435,42 @@ export interface FromJsonSchemaOptions {
    * @default "error"
    */
   readonly patterns?: "error" | "ignore" | "apply" | undefined
+  /**
+   * Selects additional JSON Schema keys to preserve as Effect schema annotations.
+   *
+   * **Details**
+   *
+   * Standard annotations such as `title` and `description` are imported independently of this predicate.
+   * Other keys are ignored by default. Selected values must be JSON-compatible and are kept as opaque metadata.
+   * Selection runs after `onEnter`. JSON Schema structural and validation keywords, Effect's reserved annotation
+   * keys, and keys starting with `~` are excluded before calling the predicate. Exceptions from the predicate
+   * pass through unchanged.
+   *
+   * **Gotchas**
+   *
+   * Import normalizes the schema. Selected annotations stay on surviving values when checks simplify, and
+   * annotations from eliminated alternatives or unreachable children are discarded. When schemas merge,
+   * later annotations overwrite earlier values for the same key, following the importer's merge order.
+   * Retaining an annotation does not enforce its semantics or preserve the original JSON Schema structure.
+   *
+   * **Example** (Preserving custom metadata on import and export)
+   *
+   * ```ts import.meta.vitest
+   * import { JsonSchema, Schema, SchemaRepresentation } from "effect"
+   *
+   * const document = JsonSchema.fromSchemaDraft2020_12({
+   *   type: "string",
+   *   "x-sensitive": true
+   * })
+   * const options = { includeAnnotationKey: (key: string) => key.startsWith("x-") }
+   * const schema = SchemaRepresentation.fromJsonSchemaDocument(document, options)
+   *
+   * Schema.toJsonSchemaDocument(schema, options).schema // => { type: "string", "x-sensitive": true }
+   * ```
+   *
+   * @see Schema.ToJsonSchemaOptions
+   */
+  readonly includeAnnotationKey?: ((key: string) => boolean) | undefined
 }
 
 /**
@@ -2902,7 +2951,14 @@ const RepresentationUnion = Schema.Union([
   makeKeywordSchema("Never"),
   makeKeywordSchema("Unknown"),
   makeKeywordSchema("Any"),
-  makeKeywordSchema("String"),
+  Schema.Struct({
+    _tag: Schema.tag("String"),
+    ...KeywordFields,
+    content: Schema.optional(Schema.Struct({
+      mediaType: Schema.String,
+      schema: Schema.optional(RepresentationSchema)
+    }))
+  }),
   makeKeywordSchema("Number"),
   makeKeywordSchema("Boolean"),
   makeKeywordSchema("BigInt"),
@@ -3129,11 +3185,13 @@ export function fromRepresentations(
  * - Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive `anyOf`
  *   literal sets. Other union intersections, including cases that would duplicate a nested choice, are rejected.
  * - Unknown extension keywords are ignored and their semantics are not enforced.
- * - Only direct local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported. Root
- *   references, external references, and pointers below a definition are rejected with the supported reference format.
- *   Missing definitions are reported by name. References reached inside nested schema
- *   resources introduced by `$id` are rejected instead of resolved against the top-level definitions.
- * - Built-in declarations and checks are reconstructed with importer-owned revivers.
+ * - Only local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported, optionally
+ *   followed by a pointer below the definition. A pointer target becomes a definition keyed by its escaped tokens, such
+ *   as `Name/properties/field`, and is rejected if a top-level definition already uses that key. Root references and
+ *   external references are rejected with the supported reference format. Missing definitions are reported by name.
+ *   References reached inside nested schema resources introduced by `$id` are rejected instead of resolved against the
+ *   top-level definitions.
+ * - Imported constraints use built-in schemas and checks.
  * - Pattern constraints reached during translation cause an error by default. Use `patterns: "apply"` only for trusted
  *   documents, or `patterns: "ignore"` to skip them. Ignoring patterns can both admit invalid values and reject valid
  *   values when `oneOf` branches start overlapping.
@@ -3151,7 +3209,7 @@ export function fromJsonSchemaDocument(
   document: JsonSchema.Document<"draft-2020-12">,
   options?: FromJsonSchemaOptions
 ): Schema.Top {
-  return InternalFromJsonSchemaDocument.fromJsonSchemaDocument(document, options, jsonSchemaRevivers)
+  return InternalFromJsonSchemaDocument.fromJsonSchemaDocument(document, options)
 }
 
 /**
@@ -3175,10 +3233,12 @@ export function fromJsonSchemaDocument(
  *   are supported.
  * - Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive `anyOf`
  *   literal sets. Other union intersections, including cases that would duplicate a nested choice, are rejected.
- * - Only direct local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported. Root
- *   references, external references, and pointers below a definition are rejected with the supported reference format.
- *   Missing definitions are reported by name. References reached inside nested schema
- *   resources introduced by `$id` are rejected instead of resolved against the top-level definitions.
+ * - Only local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported, optionally
+ *   followed by a pointer below the definition. A pointer target becomes a definition keyed by its escaped tokens, such
+ *   as `Name/properties/field`, and is rejected if a top-level definition already uses that key. Root references and
+ *   external references are rejected with the supported reference format. Missing definitions are reported by name.
+ *   References reached inside nested schema resources introduced by `$id` are rejected instead of resolved against the
+ *   top-level definitions.
  * - Pattern constraints reached during translation cause an error by default. Use `patterns: "apply"` only for trusted
  *   documents, or `patterns: "ignore"` to skip them. Ignoring patterns can both admit invalid values and reject valid
  *   values when `oneOf` branches start overlapping.
@@ -3195,5 +3255,5 @@ export function fromJsonSchemaMultiDocument(
   document: JsonSchema.MultiDocument<"draft-2020-12">,
   options?: FromJsonSchemaOptions
 ): readonly [Schema.Top, ...Array<Schema.Top>] {
-  return InternalFromJsonSchemaDocument.fromJsonSchemaMultiDocument(document, options, jsonSchemaRevivers)
+  return InternalFromJsonSchemaDocument.fromJsonSchemaMultiDocument(document, options)
 }