effect 4.0.0-beta.104 → 4.0.0-beta.106

package/dist/Schema.js

@@ -55,7 +55,6 @@ import * as SchemaIssue from "./SchemaIssue.js";
 import * as SchemaParser from "./SchemaParser.js";
 import * as SchemaTransformation from "./SchemaTransformation.js";
 import * as Struct_ from "./Struct.js";
-import * as FastCheck from "./testing/FastCheck.js";
 const TypeId = InternalSchema.TypeId;
 /**
  * Creates a schema for a **parametric** type (a generic container such as
@@ -81,7 +80,7 @@ const TypeId = InternalSchema.TypeId;
  * **Example** (Schema for a parametric `Box<A>` type)
  *
  * ```ts import.meta.vitest
- * import { Effect, Schema, SchemaIssue as Issue, SchemaParser } from "effect"
+ * import { Effect, Schema, SchemaIssue, SchemaParser } from "effect"
  *
  * interface Box<A> {
  *   readonly value: A
@@ -96,7 +95,7 @@ const TypeId = InternalSchema.TypeId;
  *     ([itemCodec]) =>
  *       (u, ast, options) => {
  *         if (!isBox(u)) {
- *           return Effect.fail(new SchemaIssue.InvalidType(ast))
+ *           return Effect.fail(new SchemaIssue.InvalidType(ast, u, options))
  *         }
  *         return Effect.map(
  *           SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options),
@@ -150,7 +149,7 @@ export function declareConstructor() {
  * @since 3.10.0
  */
 export function declare(is, annotations) {
-  return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast)), annotations);
+  return declareConstructor()([], () => (input, ast, options) => is(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, input, options)), annotations);
 }
 /**
  * Returns a schema widened to the fully-parameterized {@link Bottom} interface,
@@ -338,10 +337,12 @@ isSchemaError,
  *
  * The `issue` field contains a structured {@link SchemaIssue.Issue} tree describing
  * every validation failure, including the path to the problematic value and
- * the expected type or constraint. Built-in issues have no `actual` field,
- * and built-in messages do not include the rejected value. Other Issue fields
- * and custom annotations or messages are not sanitized. `message` renders the
- * issue tree as a human-readable string.
+ * the expected type or constraint. Parsing with `reportInput: true` adds an
+ * enumerable `input` field to value-bearing issues created by the parser.
+ * Built-in messages may include reported input. Other issue fields and
+ * custom annotations or messages are not sanitized.
+ * `message` renders the issue tree as a human-readable string and can disclose
+ * retained input.
  *
  * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
  *
@@ -584,6 +585,9 @@ export const is = SchemaParser.is;
  *
  * The input is narrowed if the assertion succeeds. If schema validation fails,
  * the assertion throws an `Error` whose cause is `SchemaIssue.Issue`.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -641,9 +645,12 @@ export const asserts = SchemaParser.asserts;
 export function decodeUnknownEffect(schema, options) {
   const parser = SchemaParser.decodeUnknownEffect(schema, options);
   return (input, options) => {
-    return InternalSchema.fromIssueEffect(parser(input, options));
+    return fromIssueEffect(parser(input, options));
   };
 }
+function fromIssueEffect(self) {
+  return Effect.catchCause(self, cause => Effect.failCauseSync(() => Cause_.map(cause, issue => new SchemaError(issue))));
+}
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Effect` that succeeds with the decoded value or fails with a
@@ -1050,7 +1057,7 @@ export const decodeSync = decodeUnknownSync;
 export function encodeUnknownEffect(schema, options) {
   const parser = SchemaParser.encodeUnknownEffect(schema, options);
   return (input, options) => {
-    return InternalSchema.fromIssueEffect(parser(input, options));
+    return fromIssueEffect(parser(input, options));
   };
 }
 /**
@@ -1467,7 +1474,12 @@ export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
  * @category combinators
  * @since 3.10.0
  */
-export const optional = /*#__PURE__*/Struct_.lambda(self => optionalKey(UndefinedOr(self)));
+export const optional = /*#__PURE__*/Struct_.lambda(self => {
+  const schema = UndefinedOr(self);
+  return make(SchemaAST.optional(self.ast), {
+    schema
+  });
+});
 /**
  * Reverses `optional` and returns the inner schema.
  *
@@ -2657,7 +2669,7 @@ export function decodeTo(to, transformation) {
  * ```
  *
  * @category transforming
- * @since 3.10.0
+ * @since 4.0.0
  */
 export function decode(transformation) {
   return self => {
@@ -2693,7 +2705,7 @@ export function encodeTo(to, transformation) {
  * ```
  *
  * @category transforming
- * @since 3.10.0
+ * @since 4.0.0
  */
 export function encode(transformation) {
   return self => {
@@ -2706,7 +2718,7 @@ export function encode(transformation) {
  * **Details**
  *
  * Constructor defaults are applied only during `make*`, not during decoding or
- * encoding.
+ * encoding. Failures are represented directly as `SchemaIssue.Issue` values.
  *
  * **Example** (Defining an optional field with a static default)
  *
@@ -2730,7 +2742,7 @@ export function withConstructorDefault(
 // `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
 // it makes easier to define the default value if there are nested defaults
 defaultValue) {
-  return schema => make(SchemaAST.withConstructorDefault(schema.ast, toIssueEffect(defaultValue)), {
+  return schema => make(SchemaAST.withConstructorDefault(schema.ast, defaultValue), {
     schema
   });
 }
@@ -5903,7 +5915,7 @@ export function isPropertyNames(keySchema, annotations) {
       }
     }
     if (Arr.isArrayNonEmpty(issues)) {
-      return new SchemaIssue.Composite(ast, issues);
+      return new SchemaIssue.Composite(ast, issues, input, options);
     }
     return true;
   }, {
@@ -6037,10 +6049,10 @@ export function Option(value) {
       }
       return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(input.value, options), {
         onSuccess: Option_.some,
-        onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)])
+        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "value", issue, input, options)
       });
     }
-    return Effect.fail(new SchemaIssue.InvalidType(ast));
+    return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
   }, {
     representation: {
       id: "effect/schema/Option",
@@ -6208,18 +6220,18 @@ export function OptionFromOptionalNullOr(schema, options) {
 export function Result(success, failure) {
   const schema = declareConstructor()([success, failure], ([success, failure]) => (input, ast, options) => {
     if (!Result_.isResult(input)) {
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }
     switch (input._tag) {
       case "Success":
         return Effect.mapBothEager(SchemaParser.decodeEffect(success)(input.success, options), {
           onSuccess: Result_.succeed,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["success"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "success", issue, input, options)
         });
       case "Failure":
         return Effect.mapBothEager(SchemaParser.decodeEffect(failure)(input.failure, options), {
           onSuccess: Result_.fail,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["failure"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "failure", issue, input, options)
         });
     }
   }, {
@@ -6340,11 +6352,11 @@ export function Redacted(value, options) {
         onSuccess: () => input,
         onFailure: (/** ignore the issue because of security reasons */
         ) => {
-          return new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], new SchemaIssue.InvalidValue())]);
+          return new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], new SchemaIssue.InvalidValue(undefined, input, poptions))], input, poptions);
         }
       }));
     }
-    return Effect.fail(new SchemaIssue.InvalidType(ast));
+    return Effect.fail(new SchemaIssue.InvalidType(ast, input, poptions));
   }, {
     representation: {
       id: "effect/schema/Redacted",
@@ -6442,18 +6454,18 @@ export function RedactedFromValue(value, options) {
 export function CauseReason(error, defect) {
   const schema = declareConstructor()([error, defect], ([error, defect]) => (input, ast, options) => {
     if (!Cause_.isReason(input)) {
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }
     switch (input._tag) {
       case "Fail":
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(error)(input.error, options), {
           onSuccess: Cause_.makeFailReason,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["error"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "error", issue, input, options)
         });
       case "Die":
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(defect)(input.defect, options), {
           onSuccess: Cause_.makeDieReason,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["defect"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "defect", issue, input, options)
         });
       case "Interrupt":
         return Effect.succeed(input);
@@ -6581,11 +6593,11 @@ export function Cause(error, defect) {
     const failures = ArraySchema(CauseReason(error, defect));
     return (input, ast, options) => {
       if (!Cause_.isCause(input)) {
-        return Effect.fail(new SchemaIssue.InvalidType(ast));
+        return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
       }
       return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(failures)(input.reasons, options), {
         onSuccess: Cause_.fromReasons,
-        onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["failures"], issue)])
+        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "failures", issue, input, options)
       });
     };
   }, {
@@ -6806,18 +6818,18 @@ export function Exit(value, error, defect) {
     const cause = Cause(error, defect);
     return (input, ast, options) => {
       if (!Exit_.isExit(input)) {
-        return Effect.fail(new SchemaIssue.InvalidType(ast));
+        return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
       }
       switch (input._tag) {
         case "Success":
           return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(value)(input.value, options), {
             onSuccess: Exit_.succeed,
-            onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)])
+            onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "value", issue, input, options)
           });
         case "Failure":
           return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(cause)(input.cause, options), {
             onSuccess: Exit_.failCause,
-            onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["cause"], issue)])
+            onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "cause", issue, input, options)
           });
       }
     };
@@ -6961,10 +6973,10 @@ export function ReadonlyMap(key, value) {
       if (input instanceof globalThis.Map) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(array)([...input], options), {
           onSuccess: array => new globalThis.Map(array),
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["entries"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "entries", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7030,10 +7042,10 @@ export function HashMap(key, value) {
       if (HashMap_.isHashMap(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(entries)(HashMap_.toEntries(input), options), {
           onSuccess: HashMap_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["entries"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "entries", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7100,10 +7112,10 @@ export function ReadonlySet(value) {
       if (input instanceof globalThis.Set) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(array)([...input], options), {
           onSuccess: array => new globalThis.Set(array),
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7168,10 +7180,10 @@ export function HashSet(value) {
       if (HashSet_.isHashSet(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
           onSuccess: HashSet_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7236,10 +7248,10 @@ export function Chunk(value) {
       if (Chunk_.isChunk(input)) {
         return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(values)(Arr.fromIterable(input), options), {
           onSuccess: Chunk_.fromIterable,
-          onFailure: issue => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["values"], issue)])
+          onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "values", issue, input, options)
         });
       }
-      return Effect.fail(new SchemaIssue.InvalidType(ast));
+      return Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     };
   }, {
     representation: {
@@ -7315,11 +7327,11 @@ export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
     source: String,
     flags: String
   }), SchemaTransformation.transformOrFail({
-    decode: e => Effect.try({
+    decode: (e, options) => Effect.try({
       try: () => new globalThis.RegExp(e.source, e.flags),
       catch: () => new SchemaIssue.InvalidValue({
-        message: "Expected valid RegExp source and flags"
-      })
+        expected: "valid RegExp source and flags"
+      }, e, options)
     }),
     encode: regExp => Effect.succeed({
       source: regExp.source,
@@ -7894,10 +7906,10 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
     name: String,
     lastModified: Int
   }), SchemaTransformation.transformOrFail({
-    decode: e => Result_.match(Encoding.decodeBase64(e.data), {
+    decode: (e, options) => Result_.match(Encoding.decodeBase64(e.data), {
       onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
-        message: "Expected a valid Base64 string"
-      })),
+        expected: "a valid Base64 string"
+      }, e.data, options)),
       onSuccess: bytes => {
         const buffer = new globalThis.Uint8Array(bytes);
         return Effect.succeed(new globalThis.File([buffer], e.name, {
@@ -7906,7 +7918,7 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
         }));
       }
     }),
-    encode: file => Effect.tryPromise({
+    encode: (file, options) => Effect.tryPromise({
       try: async () => {
         const bytes = new globalThis.Uint8Array(await file.arrayBuffer());
         return {
@@ -7917,8 +7929,8 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
         };
       },
       catch: () => new SchemaIssue.InvalidValue({
-        message: "Expected File to be readable"
-      })
+        expected: "a readable File"
+      }, file, options)
     })
   }))
 });
@@ -8988,8 +9000,8 @@ function getClassSchemaFactory(from, identifier, annotations) {
     const ClassTypeId = getClassTypeId(identifier);
     const isClassValue = input => input instanceof self || Predicate.hasProperty(input, ClassTypeId);
     const transformation = getClassTransformation(self);
-    const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast) => {
-      return isClassValue(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast));
+    const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast, options) => {
+      return isClassValue(input) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, input, options));
     }, {
       identifier,
       [InternalAnnotations.CONSTRUCTOR_ANNOTATION_KEY]: ([from]) => ({
@@ -9013,8 +9025,8 @@ function isStruct(schema) {
 }
 /**
  * Creates a schema-backed class whose constructor validates input against a
- * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input.
+ * {@link Struct} schema. Construction throws an `Error` with a
+ * `SchemaIssue.Issue` in its `cause` on invalid input.
  *
  * **When to use**
  *
@@ -9204,35 +9216,41 @@ export const TaggedError = identifier => {
   };
 };
 /**
- * Derives a {@link LazyArbitrary} from a schema. The result is memoized so
- * repeated calls with the same schema are cheap.
+ * Returns an {@link Arbitrary} factory derived from a schema. The generated
+ * values satisfy the schema and use its decoded `Type`.
+ *
+ * **When to use**
+ *
+ * Use when you need a fast-check generator for values accepted by a schema.
  *
  * **Details**
  *
- * Prefer {@link toArbitrary} when you need the arbitrary directly, or when you
- * want derivation diagnostics via `{ report: true }`. Unsupported schema
- * nodes, impossible constraints, invalid candidates, and recursive schemas
- * without a finite terminal path fail immediately.
+ * Constraints refine base generators; candidates add weighted sources while
+ * filters still validate every value. Recursive schemas use terminal branches
+ * and fail when no finite terminal path exists. The result is memoized so
+ * repeated calls with the same schema are cheap.
+ *
+ * **Example** (Generating arbitrary values)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import * as FastCheck from "fast-check"
+ *
+ * const makePersonArbitrary = Schema.toArbitrary(
+ *   Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * )
+ *
+ * const PersonArbitrary = makePersonArbitrary(FastCheck)
+ * FastCheck.sample(PersonArbitrary, 1)
+ * ```
  *
  * @category generators
  * @since 4.0.0
  */
-export function toArbitraryLazy(schema) {
+export function toArbitrary(schema) {
   const lawc = InternalArbitrary.memoized(schema.ast);
   return fc => lawc(fc, {});
 }
-export function toArbitrary(schema, options) {
-  if (options?.report === true) {
-    const lawc = InternalArbitrary.memoized(schema.ast);
-    const report = InternalArbitrary.makeReport();
-    InternalArbitrary.collectReport(schema.ast, report);
-    return {
-      value: lawc(FastCheck, {}),
-      report: InternalArbitrary.toReport(report)
-    };
-  }
-  return toArbitraryLazy(schema)(FastCheck);
-}
 // -----------------------------------------------------------------------------
 // Formatter
 // -----------------------------------------------------------------------------
@@ -9480,7 +9498,7 @@ export function toRepresentation(schema) {
  * @since 4.0.0
  */
 export function toJsonSchemaDocument(schema, options) {
-  const document = InternalToRepresentation.toRepresentation(toCodecJsonAST(schema.ast));
+  const document = InternalToRepresentation.toRepresentation(toCodecJsonAST(schema.ast), InternalToJsonSchemaDocument.toRepresentationOptions);
   return InternalToJsonSchemaDocument.toJsonSchemaDocument(document, options);
 }
 /**
@@ -9503,14 +9521,13 @@ export function toCodecJson(schema) {
     schema
   });
 }
-const toCodecJsonASTBase = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
-  const out = toCodecJsonBase(ast, toCodecJsonAST);
+/** @internal */
+export const toCodecJsonAST = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncodingIdempotent(ast => {
+  const out = toCodecJsonASTStep(ast, toCodecJsonAST);
   const context = ast.context;
   if (out === ast || context === undefined) return out;
   return SchemaAST.replaceContextLastLink(out, withoutConstructorDefault(context));
 });
-/** @internal */
-export const toCodecJsonAST = /*#__PURE__*/memoize(toCodecJsonASTBase);
 function withoutConstructorDefault(context) {
   return context.constructorDefault === undefined ? context : new SchemaAST.Context(context.isOptional, context.isMutable, undefined, context.annotations);
 }
@@ -9554,7 +9571,7 @@ const toCodecJsonReorder = /*#__PURE__*/makeReorder(ast => {
       return 1;
   }
 });
-function toCodecJsonBase(ast, recur) {
+function toCodecJsonASTStep(ast, recur) {
   switch (ast._tag) {
     case "Declaration":
       {
@@ -9607,13 +9624,13 @@ function toCodecJsonBase(ast, recur) {
  * @since 4.0.0
  */
 export function toCodecIso(schema) {
-  return make(toCodecIsoTop(SchemaAST.toType(schema.ast)));
+  return make(toCodecIsoAST(SchemaAST.toType(schema.ast)));
 }
-const toCodecIsoTop = /*#__PURE__*/memoize(ast => {
-  const out = toCodecIsoBase(ast, toCodecIsoTop);
+const toCodecIsoAST = /*#__PURE__*/memoize(ast => {
+  const out = toCodecIsoASTStep(ast, toCodecIsoAST);
   return out !== ast && ast.context !== undefined ? SchemaAST.replaceContextLastLink(out, withoutConstructorDefault(ast.context)) : out;
 });
-function toCodecIsoBase(ast, recur) {
+function toCodecIsoASTStep(ast, recur) {
   switch (ast._tag) {
     case "Declaration":
       {
@@ -9646,7 +9663,7 @@ function toCodecIsoBase(ast, recur) {
  * @since 4.0.0
  */
 export function toCodecStringTree(schema) {
-  return make(serializerStringTree(schema.ast), {
+  return make(toCodecStringTreeAST(schema.ast), {
     schema
   });
 }
@@ -9669,7 +9686,7 @@ export function toCodecStringTree(schema) {
  * @since 4.0.0
  */
 export function toCodecArrayFromSingle(schema) {
-  return make(toCodecArrayFromSingleTop(schema.ast));
+  return make(toCodecArrayFromSingleAST(schema.ast));
 }
 /**
  * Derives an XML encoder from a codec.
@@ -9793,7 +9810,7 @@ const toStringTreeReorder = /*#__PURE__*/makeReorder(ast => {
       return 1;
   }
 });
-function serializerTree(ast, recur, onMissingAnnotation) {
+function toCodecStringTreeASTStep(ast, recur, onMissingAnnotation) {
   switch (ast._tag) {
     case "Declaration":
       {
@@ -9846,13 +9863,10 @@ function serializerTree(ast, recur, onMissingAnnotation) {
 }
 const nullToString = /*#__PURE__*/new SchemaAST.Link(/*#__PURE__*/new SchemaAST.Literal("null"), /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(() => null), /*#__PURE__*/SchemaGetter.transform(() => "null")));
 const booleanToString = /*#__PURE__*/new SchemaAST.Link(/*#__PURE__*/new SchemaAST.Union([/*#__PURE__*/new SchemaAST.Literal("true"), /*#__PURE__*/new SchemaAST.Literal("false")], "anyOf"), /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(s => s === "true"), /*#__PURE__*/SchemaGetter.String()));
-const SERIALIZER_ENSURE_ARRAY = "~effect/Schema/SERIALIZER_ENSURE_ARRAY";
-const isSerializerArrayFromSingle = ast => SchemaAST.isUnion(ast) && ast.annotations?.[SERIALIZER_ENSURE_ARRAY] === true;
-const serializerStringTree = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
-  if (isSerializerArrayFromSingle(ast)) {
-    return ast;
-  }
-  const out = serializerTree(ast, serializerStringTree, ast => {
+const arrayFromSingleTransformation = /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(input => typeof input === "string" ? [input] : input), /*#__PURE__*/SchemaGetter.passthrough());
+const isCodecArrayFromSingleLink = link => link.transformation === arrayFromSingleTransformation;
+const toCodecStringTreeAST = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncodingIdempotent(ast => {
+  const out = toCodecStringTreeASTStep(ast, toCodecStringTreeAST, ast => {
     throw new globalThis.Error("Missing structural codec for StringTree", {
       cause: ast
     });
@@ -9861,24 +9875,22 @@ const serializerStringTree = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncodin
     return SchemaAST.replaceContextLastLink(out, withoutConstructorDefault(ast.context));
   }
   return out;
+}, {
+  stopAt: isCodecArrayFromSingleLink
 });
 const toArrayFromSingleInputElement = ast => SchemaAST.isOptional(ast) ? SchemaAST.optionalKey(SchemaAST.unknown) : SchemaAST.unknown;
-const arrayFromSingleTransformation = /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(input => typeof input === "string" ? [input] : input), /*#__PURE__*/SchemaGetter.passthrough());
-const toCodecArrayFromSingleTop = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
-  if (isSerializerArrayFromSingle(ast)) {
-    return ast;
-  }
-  const out = onSerializerArrayFromSingle(ast);
+const toCodecArrayFromSingleAST = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncodingIdempotent(ast => {
+  const out = toCodecArrayFromSingleASTStep(ast);
   if (SchemaAST.isArrays(out)) {
-    const ensure = SchemaAST.decodeTo(new SchemaAST.Union([new SchemaAST.Arrays(out.isMutable, out.elements.map(toArrayFromSingleInputElement), out.rest.map(toArrayFromSingleInputElement)), SchemaAST.string], "anyOf", {
-      [SERIALIZER_ENSURE_ARRAY]: true
-    }), out, arrayFromSingleTransformation);
+    const ensure = SchemaAST.decodeTo(new SchemaAST.Union([new SchemaAST.Arrays(out.isMutable, out.elements.map(toArrayFromSingleInputElement), out.rest.map(toArrayFromSingleInputElement)), SchemaAST.string], "anyOf"), out, arrayFromSingleTransformation);
     return SchemaAST.isOptional(ast) ? SchemaAST.optionalKey(ensure) : ensure;
   }
   return out;
+}, {
+  stopAt: isCodecArrayFromSingleLink
 });
-function onSerializerArrayFromSingle(ast) {
-  return ast._tag === "Declaration" || ast._tag === "Arrays" || ast._tag === "Objects" || ast._tag === "Union" || ast._tag === "Suspend" ? ast.recur(toCodecArrayFromSingleTop) : ast;
+function toCodecArrayFromSingleASTStep(ast) {
+  return ast._tag === "Declaration" || ast._tag === "Arrays" || ast._tag === "Objects" || ast._tag === "Union" || ast._tag === "Suspend" ? ast.recur(toCodecArrayFromSingleAST) : ast;
 }
 /**
  * Reviver for persisted `isGreaterThanDate` checks.
@@ -10073,6 +10085,18 @@ export const isBetweenBigIntReviver = /*#__PURE__*/InternalSchema.makeFilterRevi
  * Derives an `Iso` optic from a schema that isomorphically converts between
  * the schema's `Type` and its `Iso` (intermediate / serialized form).
  *
+ * **Details**
+ *
+ * Reading through the `Iso` encodes the schema value, while replacing through
+ * it decodes the new focus.
+ *
+ * **Gotchas**
+ *
+ * Either direction can throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -10132,6 +10156,19 @@ export function overrideToCodecIso(to, transformation) {
  * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
  * and new values, and can apply patches back to the typed value.
  *
+ * **Details**
+ *
+ * `diff` encodes both values before computing the patch. `patch` encodes the old
+ * value, applies the patch to its JSON representation, and decodes the result.
+ *
+ * **Gotchas**
+ *
+ * Schema encoding or decoding failures throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed. Errors produced by {@link JsonPatch.apply}
+ * for invalid patch operations are separate from schema validation failures.
+ *
  * @category converting
  * @since 4.0.0
  */