effect 4.0.0-rc.113 → 4.0.0-rc.114

package/src/Effect.ts

@@ -13941,8 +13941,8 @@ export const onExitFilter: {
 export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>> = internal.cached
 
 /**
- * Returns an effect that caches its result for a specified `Duration`,
- * known as "timeToLive" (TTL).
+ * Returns an effect that caches its result for a fixed duration or a duration
+ * computed from its `Exit`, known as "timeToLive" (TTL).
  *
  * **When to use**
  *
@@ -13961,6 +13961,17 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * After the specified duration has passed, the cache expires, and the effect
  * will be recomputed upon the next evaluation.
  *
+ * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+ * `Duration.Input`. The function runs once after each fresh computation,
+ * including failures, so successes and failures can have different TTLs. It
+ * does not run when the cache is created or when a cached result is reused.
+ * The callback also receives interruption exits, which are cached for the
+ * returned duration.
+ *
+ * The TTL starts when the computation completes. Concurrent callers share the
+ * pending computation. A zero TTL expires immediately, and an infinite TTL
+ * keeps the result indefinitely.
+ *
  * **Example** (Memoizing an effect with TTL)
  *
  * ```ts import.meta.vitest
@@ -13985,6 +13996,26 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * output // => ["expensive task...", "result 1", "result 1", "result 1"]
  * ```
  *
+ * **Example** (Caching successes while retrying failures)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Exit } from "effect"
+ *
+ * let attempts = 0
+ * const task = Effect.suspend(() =>
+ *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+ * )
+ * const program = Effect.gen(function*() {
+ *   const cached = yield* task.pipe(
+ *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+ *   )
+ *   yield* Effect.exit(cached)
+ *   return yield* cached
+ * })
+ *
+ * Effect.runSync(program) // => 42
+ * ```
+ *
  * @see {@link cached} for a similar function that caches the result
  * indefinitely.
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -13994,8 +14025,8 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  */
 export const cachedWithTTL: {
   /**
-   * Returns an effect that caches its result for a specified `Duration`,
-   * known as "timeToLive" (TTL).
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
    *
    * **When to use**
    *
@@ -14014,6 +14045,17 @@ export const cachedWithTTL: {
    * After the specified duration has passed, the cache expires, and the effect
    * will be recomputed upon the next evaluation.
    *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
    * **Example** (Memoizing an effect with TTL)
    *
    * ```ts import.meta.vitest
@@ -14038,6 +14080,110 @@ export const cachedWithTTL: {
    * output // => ["expensive task...", "result 1", "result 1", "result 1"]
    * ```
    *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
+   * @category caching
+   * @since 2.0.0
+   */
+  <A, E>(timeToLive: (exit: Exit.Exit<A, E>) => Duration.Input): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
+  /**
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
+   *
+   * **When to use**
+   *
+   * Use when you need a costly effect result to be reused for a bounded duration
+   * before being recomputed.
+   *
+   * **Details**
+   *
+   * This function is used to cache the result of an effect for a specified amount
+   * of time. This means that the first time the effect is evaluated, its result
+   * is computed and stored.
+   *
+   * If the effect is evaluated again within the specified `timeToLive`, the
+   * cached result will be used, avoiding recomputation.
+   *
+   * After the specified duration has passed, the cache expires, and the effect
+   * will be recomputed upon the next evaluation.
+   *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
+   * **Example** (Memoizing an effect with TTL)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * const output: Array<unknown> = []
+   * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+   *
+   * let i = 1
+   * const expensiveTask = Effect.sync(() => {
+   *   void output.push("expensive task...")
+   *   return `result ${i++}`
+   * })
+   *
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   * })
+   *
+   * Effect.runSync(program)
+   * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+   * ```
+   *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
    * @see {@link cached} for a similar function that caches the result
    * indefinitely.
    * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -14047,8 +14193,92 @@ export const cachedWithTTL: {
    */
   (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
   /**
-   * Returns an effect that caches its result for a specified `Duration`,
-   * known as "timeToLive" (TTL).
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
+   *
+   * **When to use**
+   *
+   * Use when you need a costly effect result to be reused for a bounded duration
+   * before being recomputed.
+   *
+   * **Details**
+   *
+   * This function is used to cache the result of an effect for a specified amount
+   * of time. This means that the first time the effect is evaluated, its result
+   * is computed and stored.
+   *
+   * If the effect is evaluated again within the specified `timeToLive`, the
+   * cached result will be used, avoiding recomputation.
+   *
+   * After the specified duration has passed, the cache expires, and the effect
+   * will be recomputed upon the next evaluation.
+   *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
+   * **Example** (Memoizing an effect with TTL)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * const output: Array<unknown> = []
+   * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+   *
+   * let i = 1
+   * const expensiveTask = Effect.sync(() => {
+   *   void output.push("expensive task...")
+   *   return `result ${i++}`
+   * })
+   *
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   * })
+   *
+   * Effect.runSync(program)
+   * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+   * ```
+   *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
+   * @category caching
+   * @since 2.0.0
+   */
+  <A, E>(timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
+  /**
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
    *
    * **When to use**
    *
@@ -14067,6 +14297,17 @@ export const cachedWithTTL: {
    * After the specified duration has passed, the cache expires, and the effect
    * will be recomputed upon the next evaluation.
    *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
    * **Example** (Memoizing an effect with TTL)
    *
    * ```ts import.meta.vitest
@@ -14091,6 +14332,26 @@ export const cachedWithTTL: {
    * output // => ["expensive task...", "result 1", "result 1", "result 1"]
    * ```
    *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
    * @see {@link cached} for a similar function that caches the result
    * indefinitely.
    * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -14098,7 +14359,10 @@ export const cachedWithTTL: {
    * @category caching
    * @since 2.0.0
    */
-  <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<Effect<A, E, R>>
+  <A, E, R>(
+    self: Effect<A, E, R>,
+    timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)
+  ): Effect<Effect<A, E, R>>
 } = internal.cachedWithTTL
 
 /**

package/src/Effectable.ts

@@ -8,7 +8,7 @@
  */
 import type * as Effect from "./Effect.ts"
 import type * as Fiber from "./Fiber.ts"
-import { type EffectTypeId, evaluate, makePrimitiveProto } from "./internal/core.ts"
+import { evaluate, makePrimitiveProto } from "./internal/core.ts"
 
 /**
  * Create a low-level `Effect` prototype.
@@ -78,7 +78,7 @@ type AsEffectReturn<Self> = Self extends {
 
 declare abstract class MixinBase extends Class<any, any, any> {
   constructor(...args: ReadonlyArray<any>)
-  override readonly [EffectTypeId]: AsEffectReturn<this>[typeof EffectTypeId]
+  override readonly [Effect.TypeId]: AsEffectReturn<this>[Effect.TypeId]
   override [Symbol.iterator](): Effect.EffectIterator<AsEffectReturn<this>>
 }
 

package/src/FileSystem.ts

@@ -906,10 +906,9 @@ export declare namespace File {
    * permissions, and size information. This structure is returned by file
    * stat operations.
    *
-   * Node and Bun preserve `size` and `blksize` exactly. Unsafe numeric metadata
-   * (such as `ino` or `dev`) fails the entire stat operation with `BadArgument`,
-   * including optional fields. Inode values above `Number.MAX_SAFE_INTEGER`
-   * can therefore prevent stat and HTTP file serving even for small files.
+   * Node and Bun preserve `size` and `blksize` exactly. Optional `number`
+   * metadata is `Option.none()` when absent or outside the safe integer range.
+   * Unsafe `dev` or `mode` values fail the stat operation with `BadArgument`.
    *
    * **Example** (Inspecting file information)
    *

package/src/Match.ts

@@ -22,7 +22,7 @@ const TypeId = internal.TypeId
 
 // The conditional must stay deferred until P is inferred. Replacing it with an
 // intersection loses contextual typing for nested generic calls (microsoft/TypeScript#52864).
-type Contextual<P, Fallback> = internal.Contextual<P, Fallback>
+type Contextual<P, Fallback> = [P] extends [never] ? Fallback : P
 
 type TagHandlers<D extends string, R, Ret> = {
   readonly [Tag in Types.Tags<D, R> & string]: (_: Extract<R, Record<D, Tag>>) => Ret

package/src/Schema.ts

@@ -15512,9 +15512,6 @@ export function resolveAnnotations<S extends Constraint>(
 export function resolveAnnotationsKey<S extends Constraint>(schema: S): Annotations.Key<S["Type"]> | undefined {
   return schema.ast.context?.annotations
 }
-/** @internal */
-type AnnotationSchemaConstraint = Constraint
-
 /**
  * The `Annotations` namespace groups all annotation interfaces used to attach
  * metadata to schemas. Annotations control documentation, validation messages,
@@ -15833,7 +15830,7 @@ export declare namespace Annotations {
      *
      * @since 4.0.0
      */
-    readonly arbitraryConstraint?: ToArbitrary.Constraint<any> | undefined
+    readonly arbitraryConstraint?: ToArbitrary.FilterConstraint<any> | undefined
     /**
      * Marks the filter as *structural*, meaning it applies to the shape or
      * structure of the container (e.g., array length, object keys) rather than
@@ -15899,7 +15896,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface Constraint<T = unknown> extends GenerationConstraint<T> {
+    interface FilterConstraint<T = unknown> extends GenerationConstraint<T> {
       readonly order?: Order.Order<T> | undefined
     }
     /**
@@ -15908,7 +15905,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface DeclarationInput<T, Parameters extends ReadonlyArray<AnnotationSchemaConstraint>> {
+    interface DeclarationInput<T, Parameters extends ReadonlyArray<Constraint>> {
       readonly typeParameters: TypeParameters.Type<Parameters>
       readonly constraint: GenerationConstraint<T> | undefined
     }
@@ -15918,7 +15915,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface Declaration<T, Parameters extends ReadonlyArray<AnnotationSchemaConstraint>> {
+    interface Declaration<T, Parameters extends ReadonlyArray<Constraint>> {
       (input: DeclarationInput<T, Parameters>): SchemaAST.Link
     }
   }

package/src/SchemaRepresentation.ts

@@ -2175,7 +2175,8 @@ const jsonSchemaRevivers: ReadonlyArray<AnyReviver> = [
  * **Gotchas**
  *
  * Use `patterns: "apply"` only for trusted documents because regular expression evaluation may block for an unbounded
- * amount of time. `patterns: "ignore"` weakens validation by accepting values that the source document may reject.
+ * amount of time. `patterns: "ignore"` can admit values the source rejects, but can also reject previously valid
+ * values inside `oneOf` when removing constraints makes multiple branches match.
  * Ignoring `patternProperties` also skips its value constraints and `additionalProperties`, because matching keys cannot
  * be determined without evaluating the patterns.
  * `onEnter` must return a JSON Schema object. Its result is used directly, and exceptions raised by the callback pass
@@ -2835,30 +2836,39 @@ export function fromRepresentations(
  *
  * **Details**
  *
- * For the Draft 2020-12 subset translated exactly by this importer, compiling the imported schema through
- * {@link toRepresentation} and {@link toJsonSchemaDocument} produces a document that accepts the same JSON values as
- * the input. This is a semantic round-trip guarantee; keyword layout, definitions, and annotations may be normalized.
+ * Translates a Draft 2020-12 subset using Effect schemas and built-in checks. Validation follows those checks and the
+ * decoder's parse options, so import and re-export do not guarantee identical accepted values or a lossless round trip.
+ * Import errors explain the unsupported constraint or reference and include its source path.
  *
  * **Gotchas**
  *
- * - `$dynamicRef`, `contains`, `dependentRequired`, `dependentSchemas`, `not`, active `if` / `then` / `else`,
- *   `unevaluatedItems`, and `unevaluatedProperties` throw an `Unsupported JSON Schema keyword` error. Inactive
+ * - `{ not: {} }` imports as `Never`. Other uses of `not` are unsupported.
+ * - When `additionalProperties` is `true`, `{}`, or omitted, additional values use `Schema.Json` and are retained.
+ *   Closed objects normally strip excess properties by default; pass `onExcessProperty: "error"` to reject them.
+ *   Closed empty objects instead use `Schema.Record(Schema.String, Schema.Never)` and reject string-keyed entries
+ *   regardless of that option.
+ *   Object keyword scopes still constrain declared properties in intersections. Combinations requiring index
+ *   signatures that exclude explicit properties or patterned keys are rejected with an explanation of the limitation.
+ * - Property count and name checks run on the decoded object, after excess properties have been stripped.
+ * - String length checks count UTF-16 code units. `integer` uses `Schema.isInt`, which requires safe integers.
+ *   Applied patterns use `Schema.isPattern` without adding a Unicode flag.
+ * - `$dynamicRef`, `contains`, `dependentRequired`, `dependentSchemas`, active `if` / `then` / `else`,
+ *   `unevaluatedItems`, and `unevaluatedProperties` are rejected with an error identifying the unsupported keyword. Inactive
  *   conditional keywords and `minContains` / `maxContains` without `contains` have no validation effect and are ignored.
- * - Objects and arrays used as `const` values or `enum` members throw an `Unsupported structured JSON Schema value`
- *   error.
+ * - Objects and arrays used as `const` values or `enum` members are rejected. Only strings, numbers, booleans, and null
+ *   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, throw an
- *   `Unsupported intersection of overlapping unions` error.
+ *   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 throw an `Unsupported reference` error. A direct
- *   reference to a missing definition throws an `Invalid reference` error.
+ *   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.
  * - Pattern constraints reached during translation cause an error by default. Use `patterns: "apply"` only for trusted
- *   documents, or `patterns: "ignore"` to weaken validation explicitly; ignored patterns are outside the round-trip
- *   guarantee.
- * - `onEnter` results replace the corresponding input nodes, so the round-trip guarantee applies to the rewritten
- *   document.
+ *   documents, or `patterns: "ignore"` to skip them. Ignoring patterns can both admit invalid values and reject valid
+ *   values when `oneOf` branches start overlapping.
+ * - `onEnter` results replace the corresponding input nodes before translation.
  * - Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
  * @see {@link fromJsonSchemaMultiDocument} for multiple roots sharing definitions
@@ -2881,21 +2891,26 @@ export function fromJsonSchemaDocument(
  *
  * Use when multiple imported roots share reachable definitions, aliases, or recursion.
  *
+ * **Details**
+ *
+ * Uses the same best-effort translation, built-in checks, and excess-property behavior as {@link fromJsonSchemaDocument}.
+ *
  * **Gotchas**
  *
  * - Only definitions reachable from a root are translated.
- * - Unsupported standard validation and applicator keywords throw an `Unsupported JSON Schema keyword` error. Unknown
+ * - Unsupported standard validation and applicator keywords are rejected with an error identifying the keyword. Unknown
  *   extension keywords are ignored and their semantics are not enforced.
- * - Objects and arrays used as `const` values or `enum` members throw an `Unsupported structured JSON Schema value`
- *   error.
+ * - Objects and arrays used as `const` values or `enum` members are rejected. Only strings, numbers, booleans, and null
+ *   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, throw an
- *   `Unsupported intersection of overlapping unions` error.
+ *   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 throw an `Unsupported reference` error. A direct
- *   reference to a missing definition throws an `Invalid reference` error.
+ *   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.
  * - Pattern constraints reached during translation cause an error by default. Use `patterns: "apply"` only for trusted
- *   documents, or `patterns: "ignore"` to weaken validation explicitly.
+ *   documents, or `patterns: "ignore"` to skip them. Ignoring patterns can both admit invalid values and reject valid
+ *   values when `oneOf` branches start overlapping.
  * - Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
  * @see {@link fromJsonSchemaDocument} for a single root