effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/SchemaIssue.ts

@@ -5,8 +5,7 @@
  * An `Issue` records what failed and, for nested data, where the failure
  * happened. The Schema system uses these values for missing keys, unexpected
  * keys, invalid types, invalid values, failed filters, failed transformations,
- * and alternatives that did not match. This module also formats issues and
- * supports redaction for sensitive values.
+ * and alternatives that did not match. This module also formats issues.
  *
  * @since 4.0.0
  */
@@ -14,9 +13,8 @@ import type { StandardSchemaV1 } from "@standard-schema/spec"
 import * as Arr from "./Array.ts"
 import { format, formatPath, type Formatter as FormatterI } from "./Formatter.ts"
 import * as InternalAnnotations from "./internal/schema/annotations.ts"
-import * as Option from "./Option.ts"
+import * as InternalParser from "./internal/schema/parser.ts"
 import { hasProperty } from "./Predicate.ts"
-import * as Redacted from "./Redacted.ts"
 import type * as Schema from "./Schema.ts"
 import type * as SchemaAST from "./SchemaAST.ts"
 
@@ -37,14 +35,12 @@ const TypeId = "~effect/SchemaIssue/Issue"
  *
  * **Example** (Type-guarding an unknown error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaIssue } from "effect"
  *
  * const issue = new SchemaIssue.MissingKey(undefined)
- * console.log(SchemaIssue.isIssue(issue))
- * // true
- * console.log(SchemaIssue.isIssue("not an issue"))
- * // false
+ * SchemaIssue.isIssue(issue) // => true
+ * SchemaIssue.isIssue("not an issue") // => false
  * ```
  *
  * @see {@link Issue}
@@ -53,7 +49,40 @@ const TypeId = "~effect/SchemaIssue/Issue"
  * @since 4.0.0
  */
 export function isIssue(u: unknown): u is Issue {
-  return hasProperty(u, TypeId)
+  return hasProperty(u, TypeId) && u[TypeId] === TypeId
+}
+
+/**
+ * Returns `true` when an issue contains an input reported by the schema parser.
+ *
+ * **When to use**
+ *
+ * Use when reading `Issue.input`, especially when `undefined` is a valid input
+ * value.
+ *
+ * **Details**
+ *
+ * Reported input is stored as an own property. This guard checks for that
+ * property and narrows `input` from optional to required.
+ *
+ * **Example** (Reading a reported input)
+ *
+ * ```ts import.meta.vitest
+ * import { Result, Schema, SchemaIssue } from "effect"
+ *
+ * const result = Schema.decodeUnknownResult(Schema.String)(1, { reportInput: true })
+ * if (Result.isFailure(result) && SchemaIssue.hasInput(result.failure.issue)) {
+ *   result.failure.issue.input // => 1
+ * }
+ * ```
+ *
+ * @see {@link Issue} for the complete issue model
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export function hasInput(issue: Issue): issue is Issue & { readonly input: unknown } {
+  return Object.hasOwn(issue, "input")
 }
 
 /**
@@ -96,13 +125,17 @@ export type Leaf =
  * Every node has a `_tag` field for pattern-matching. The union includes both
  * terminal {@link Leaf} types and composite types that wrap inner issues:
  * {@link Filter}, {@link Encoding}, {@link Pointer}, {@link Composite},
- * {@link AnyOf}. All `Issue` instances have a `toString()` that delegates to
- * the default formatter, so `String(issue)` produces a human-readable message.
+ * {@link AnyOf}. Use {@link makeFormatterDefault} when a human-readable
+ * representation is needed. When parsing with `reportInput: true`,
+ * value-bearing issues expose the rejected value through an enumerable `input`
+ * field. Built-in formatters may include reported input in default messages. This
+ * is not a general sanitization boundary: paths, ASTs, union successes, and
+ * custom annotations or messages are preserved as supplied and remain the
+ * caller's responsibility.
  *
  * @see {@link Leaf} — the terminal subset
  * @see {@link isIssue} — type guard
- * @see {@link getActual} — extract the actual value from any issue
- *
+ * @see {@link hasInput} — checks whether an issue reports an input
  * @category models
  * @since 4.0.0
  */
@@ -117,8 +150,15 @@ export type Issue =
 
 class Base {
   readonly [TypeId] = TypeId
-  toString(this: Issue): string {
-    return defaultFormatter(this)
+  /**
+   * The input reported by the schema parser, when input reporting is enabled
+   * and the issue is associated with a present value.
+   */
+  declare readonly input?: unknown
+  constructor(input?: unknown, options?: SchemaAST.ParseOptions) {
+    if (options?.reportInput === true && input !== InternalParser.missing) {
+      this.input = input
+    }
   }
 }
 
@@ -132,22 +172,28 @@ class Base {
  *
  * **Details**
  *
- * - `actual` is the raw input value that was tested (plain `unknown`, not
- *   wrapped in `Option`).
  * - `filter` is the AST filter node that produced this issue.
  * - `issue` is the inner issue describing the failure reason.
  *
  * **Example** (Matching a Filter issue)
  *
- * ```ts
- * import { SchemaIssue } from "effect"
+ * ```ts import.meta.vitest
+ * import { SchemaAST, SchemaIssue } from "effect"
+ *
+ * const formatIssue = SchemaIssue.makeFormatterDefault()
  *
  * function describe(issue: SchemaIssue.Issue): string {
  *   if (issue._tag === "Filter") {
- *     return `Filter failed on: ${JSON.stringify(issue.actual)}`
+ *     return `Filter failed: ${formatIssue(issue.issue)}`
  *   }
- *   return String(issue)
+ *   return formatIssue(issue)
  * }
+ *
+ * const issue = new SchemaIssue.Filter(
+ *   SchemaAST.isPattern(/^valid$/),
+ *   new SchemaIssue.InvalidValue()
+ * )
+ * describe(issue) // => `Filter failed: Expected a valid value`
  * ```
  *
  * @see {@link Leaf} — terminal issue types that commonly appear as the inner `issue`
@@ -158,10 +204,6 @@ class Base {
  */
 export class Filter extends Base {
   readonly _tag = "Filter"
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: unknown
   /**
    * The filter that failed.
    */
@@ -172,10 +214,6 @@ export class Filter extends Base {
   readonly issue: Issue
 
   constructor(
-    /**
-     * The input value that caused the issue.
-     */
-    actual: unknown,
     /**
      * The filter that failed.
      */
@@ -183,10 +221,18 @@ export class Filter extends Base {
     /**
      * The issue that occurred.
      */
-    issue: Issue
+    issue: Issue,
+    /**
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
+     */
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
-    this.actual = actual
+    super(input, options)
     this.filter = filter
     this.issue = issue
   }
@@ -203,8 +249,6 @@ export class Filter extends Base {
  * **Details**
  *
  * - `ast` is the AST node for the transformation that failed.
- * - `actual` is `Option.some(value)` when the input was present, or
- *   `Option.none()` when it was absent.
  * - `issue` is the inner issue describing the failure.
  *
  * @see {@link Filter} — failure from a refinement check (not a transformation)
@@ -219,10 +263,6 @@ export class Encoding extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.AST
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: Option.Option<unknown>
   /**
    * The issue that occurred.
    */
@@ -234,17 +274,21 @@ export class Encoding extends Base {
      */
     ast: SchemaAST.AST,
     /**
-     * The input value that caused the issue.
+     * The issue that occurred.
      */
-    actual: Option.Option<unknown>,
+    issue: Issue,
     /**
-     * The issue that occurred.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    issue: Issue
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
     this.issue = issue
   }
 }
@@ -261,11 +305,9 @@ export class Encoding extends Base {
  * **Details**
  *
  * - `path` is an array of property keys (strings, numbers, or symbols).
- * - Has no `actual` value — {@link getActual} returns `Option.none()`.
  * - Formatters concatenate nested `Pointer` paths into a single path like
  *   `["a"]["b"][0]`.
  *
- * @see {@link getActual} — returns `Option.none()` for `Pointer`
  * @see {@link Composite} — groups multiple issues under one schema node
  *
  * @category models
@@ -307,7 +349,6 @@ export class Pointer extends Base {
  *
  * **Details**
  *
- * - Has no `actual` value — {@link getActual} returns `Option.none()`.
  * - `annotations` may contain a custom `messageMissingKey` for formatting.
  *
  * @see {@link Pointer} — wraps this issue with the missing key's path
@@ -345,9 +386,10 @@ export class MissingKey extends Base {
  *
  * **Details**
  *
- * - `actual` is the raw value at the unexpected key (plain `unknown`).
  * - `ast` is the schema that was being validated against.
  * - `annotations` on `ast` may contain a custom `messageUnexpectedKey`.
+ * - The default formatter renders this as `"Expected no excess property"`, or
+ *   `"Unexpected key with value <input>"` when the issue reports an input.
  *
  * @see {@link MissingKey} — the opposite case (required key absent)
  * @see {@link Pointer} — wraps this issue with the unexpected key's path
@@ -361,24 +403,23 @@ export class UnexpectedKey extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.AST
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: unknown
-
   constructor(
     /**
      * The schema that caused the issue.
      */
     ast: SchemaAST.AST,
     /**
-     * The input value that caused the issue.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
+     */
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
      */
-    actual: unknown
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
   }
 }
 
@@ -393,8 +434,6 @@ export class UnexpectedKey extends Base {
  * **Details**
  *
  * - `issues` is a non-empty readonly array (at least one child).
- * - `actual` is `Option.some(value)` when the input was present, or
- *   `Option.none()` when absent.
  * - Formatters flatten `Composite` by recursing into each child.
  *
  * @see {@link AnyOf} — used for union no-match errors (similar but different semantics)
@@ -409,10 +448,6 @@ export class Composite extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.AST
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: Option.Option<unknown>
   /**
    * The issues that occurred.
    */
@@ -424,24 +459,28 @@ export class Composite extends Base {
      */
     ast: SchemaAST.AST,
     /**
-     * The input value that caused the issue.
+     * The issues that occurred.
      */
-    actual: Option.Option<unknown>,
+    issues: readonly [Issue, ...Array<Issue>],
     /**
-     * The issues that occurred.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    issues: readonly [Issue, ...Array<Issue>]
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
     this.issues = issues
   }
 }
 
 /**
  * Represents a schema issue produced when the runtime type of the input does not match the type
- * expected by the schema (e.g. got `null` when `string` was expected).
+ * expected by the schema.
  *
  * **When to use**
  *
@@ -451,23 +490,17 @@ export class Composite extends Base {
  * **Details**
  *
  * - `ast` is the schema node that expected a different type.
- * - `actual` is `Option.some(value)` when the input was present, or
- *   `Option.none()` when no value was provided.
- * - The default formatter renders this as `"Expected <type>, got <actual>"`.
+ * - The default formatter renders this as `"Expected <type>"`, adding
+ *   `", got <input>"` when the issue reports an input.
  *
- * **Example** (Formatting output)
+ * **Example** (Formatting a type mismatch)
  *
- * ```ts
- * import { Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Schema, SchemaIssue } from "effect"
  *
- * try {
- *   Schema.decodeUnknownSync(Schema.String)(42)
- * } catch (e) {
- *   if (Schema.isSchemaError(e)) {
- *     console.log(String(e.issue))
- *     // "Expected string, got 42"
- *   }
- * }
+ * const formatIssue = SchemaIssue.makeFormatterDefault()
+ * const issue = new SchemaIssue.InvalidType(Schema.String.ast)
+ * formatIssue(issue) // => "Expected string"
  * ```
  *
  * @see {@link InvalidValue} — the input has the right type but fails a value constraint
@@ -481,24 +514,23 @@ export class InvalidType extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.AST
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: Option.Option<unknown>
-
   constructor(
     /**
      * The schema that caused the issue.
      */
     ast: SchemaAST.AST,
     /**
-     * The input value that caused the issue.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    actual: Option.Option<unknown>
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
   }
 }
 
@@ -513,23 +545,22 @@ export class InvalidType extends Base {
  *
  * **Details**
  *
- * - `actual` is `Option.some(value)` when the failing value is known, or
- *   `Option.none()` when absent.
- * - `annotations` optionally carries a `message` string for formatting.
- * - The default formatter renders this as `"Invalid data <actual>"` unless a
- *   custom `message` annotation is provided.
+ * - A `message` annotation is returned unchanged and takes precedence over all
+ *   other default formatting.
+ * - Without `message`, an `expected` annotation is formatted as
+ *   `"Expected <expected>"`, adding `", got <input>"` when input is reported.
+ * - Without either annotation, the default formatter renders
+ *   `"Expected a valid value"`, or `"Invalid data <input>"` when input is
+ *   reported.
  *
  * **Example** (Returning InvalidValue from a custom filter)
  *
- * ```ts
- * import { Option, SchemaIssue } from "effect"
+ * ```ts import.meta.vitest
+ * import { SchemaIssue } from "effect"
  *
- * const issue = new SchemaIssue.InvalidValue(
- *   Option.some(""),
- *   { message: "must not be empty" }
- * )
- * console.log(String(issue))
- * // "must not be empty"
+ * const formatIssue = SchemaIssue.makeFormatterDefault()
+ * const issue = new SchemaIssue.InvalidValue({ message: "must not be empty" })
+ * formatIssue(issue) // => "must not be empty"
  * ```
  *
  * @see {@link InvalidType} — the input has the wrong type entirely
@@ -540,10 +571,6 @@ export class InvalidType extends Base {
  */
 export class InvalidValue extends Base {
   readonly _tag = "InvalidValue"
-  /**
-   * The value that caused the issue.
-   */
-  readonly actual: Option.Option<unknown>
   /**
    * The metadata for the issue.
    */
@@ -551,20 +578,40 @@ export class InvalidValue extends Base {
 
   constructor(
     /**
-     * The value that caused the issue.
+     * The metadata for the issue.
      */
-    actual: Option.Option<unknown>,
+    annotations?: Schema.Annotations.Issue | undefined,
     /**
-     * The metadata for the issue.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    annotations?: Schema.Annotations.Issue | undefined
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
-    this.actual = actual
+    super(input, options)
     this.annotations = annotations
   }
 }
 
+/** @internal */
+export function makeCompositeAtKey(
+  compositeAst: SchemaAST.AST,
+  pointerKey: PropertyKey,
+  pointerIssue: Issue,
+  compositeInput: unknown,
+  parseOptions?: SchemaAST.ParseOptions
+): Composite {
+  return new Composite(
+    compositeAst,
+    [new Pointer([pointerKey], pointerIssue)],
+    compositeInput,
+    parseOptions
+  )
+}
+
 /**
  * Represents a schema issue produced when a forbidden operation is encountered during parsing,
  * such as an asynchronous Effect running inside `Schema.decodeUnknownSync`.
@@ -576,22 +623,19 @@ export class InvalidValue extends Base {
  *
  * **Details**
  *
- * - `actual` is `Option.some(value)` when the input is known, or
- *   `Option.none()` when absent.
  * - `annotations` optionally carries a `message` string.
  * - The default formatter renders this as `"Forbidden operation"`.
  *
  * **Example** (Creating a Forbidden issue)
  *
- * ```ts
- * import { Option, SchemaIssue } from "effect"
+ * ```ts import.meta.vitest
+ * import { SchemaIssue } from "effect"
  *
+ * const formatIssue = SchemaIssue.makeFormatterDefault()
  * const issue = new SchemaIssue.Forbidden(
- *   Option.none(),
  *   { message: "async operation not allowed in sync context" }
  * )
- * console.log(String(issue))
- * // "async operation not allowed in sync context"
+ * formatIssue(issue) // => "async operation not allowed in sync context"
  * ```
  *
  * @see {@link InvalidValue} — for value-constraint failures (not operation failures)
@@ -601,10 +645,6 @@ export class InvalidValue extends Base {
  */
 export class Forbidden extends Base {
   readonly _tag = "Forbidden"
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: Option.Option<unknown>
   /**
    * The metadata for the issue.
    */
@@ -612,16 +652,20 @@ export class Forbidden extends Base {
 
   constructor(
     /**
-     * The input value that caused the issue.
+     * The metadata for the issue.
      */
-    actual: Option.Option<unknown>,
+    annotations: Schema.Annotations.Issue | undefined,
     /**
-     * The metadata for the issue.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    annotations: Schema.Annotations.Issue | undefined
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
+     */
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
-    this.actual = actual
+    super(input, options)
     this.annotations = annotations
   }
 }
@@ -637,9 +681,13 @@ export class Forbidden extends Base {
  * **Details**
  *
  * - `ast` is the `Union` AST node.
- * - `actual` is the raw input value (plain `unknown`).
- * - `issues` contains per-member failures. When empty, the formatter falls
- *   back to the union's `expected` annotation.
+ * - `issues` contains the per-member failures.
+ *
+ * **Gotchas**
+ *
+ * `issues` is empty when no union member was applicable. In that case, the
+ * default formatter reports the expected type for the union and appends
+ * `", got <input>"` when input is reported.
  *
  * @see {@link OneOf} — the opposite: *too many* members matched
  * @see {@link Composite} — groups multiple issues under a non-union schema
@@ -653,10 +701,6 @@ export class AnyOf extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.Union
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: unknown
   /**
    * The issues that occurred.
    */
@@ -668,17 +712,21 @@ export class AnyOf extends Base {
      */
     ast: SchemaAST.Union,
     /**
-     * The input value that caused the issue.
+     * The issues that occurred.
+     */
+    issues: ReadonlyArray<Issue>,
+    /**
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    actual: unknown,
+    input?: unknown,
     /**
-     * The issues that occurred.
+     * The effective parse options controlling input retention.
      */
-    issues: ReadonlyArray<Issue>
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
     this.issues = issues
   }
 }
@@ -695,10 +743,11 @@ export class AnyOf extends Base {
  * **Details**
  *
  * - `ast` is the `Union` AST node.
- * - `actual` is the raw input value (plain `unknown`).
  * - `successes` lists the AST nodes of each member that accepted the input.
  * - The default formatter renders this as
- *   `"Expected exactly one member to match the input <actual>"`.
+ *   `"Expected exactly one member to match"`, or
+ *   `"Expected exactly one member to match the input <input>"` when input is
+ *   reported.
  *
  * @see {@link AnyOf} — the opposite: *no* members matched
  *
@@ -711,10 +760,6 @@ export class OneOf extends Base {
    * The schema that caused the issue.
    */
   readonly ast: SchemaAST.Union
-  /**
-   * The input value that caused the issue.
-   */
-  readonly actual: unknown
   /**
    * The schemas that were successful.
    */
@@ -726,110 +771,73 @@ export class OneOf extends Base {
      */
     ast: SchemaAST.Union,
     /**
-     * The input value that caused the issue.
+     * The schemas that were successful.
      */
-    actual: unknown,
+    successes: ReadonlyArray<SchemaAST.AST>,
     /**
-     * The schemas that were successful.
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
+     */
+    input?: unknown,
+    /**
+     * The effective parse options controlling input retention.
      */
-    successes: ReadonlyArray<SchemaAST.AST>
+    options?: SchemaAST.ParseOptions
   ) {
-    super()
+    super(input, options)
     this.ast = ast
-    this.actual = actual
     this.successes = successes
   }
 }
 
-/**
- * Extracts the actual input value from any {@link Issue} variant.
- *
- * **When to use**
- *
- * Use when you need to retrieve an `Issue`'s offending input value for logging
- * or custom error rendering.
- *
- * **Details**
- *
- * - Returns `Option.none()` for `Pointer` and `MissingKey` (they carry no
- *   value).
- * - Returns the existing `Option` for variants that already store `actual` as
- *   `Option<unknown>` (`InvalidType`, `InvalidValue`, `Forbidden`, `Encoding`,
- *   `Composite`).
- * - Wraps `actual` with `Option.some` for variants that store it as plain
- *   `unknown` (`AnyOf`, `UnexpectedKey`, `OneOf`, `Filter`).
- *
- * **Example** (Extracting the actual value)
- *
- * ```ts
- * import { Option, SchemaIssue } from "effect"
- *
- * const issue = new SchemaIssue.MissingKey(undefined)
- * console.log(SchemaIssue.getActual(issue))
- * // { _tag: "None" }
- * ```
- *
- * @see {@link Issue}
- * @see {@link isIssue}
- *
- * @category getters
- * @since 4.0.0
- */
-export function getActual(issue: Issue): Option.Option<unknown> {
-  switch (issue._tag) {
-    case "Pointer":
-    case "MissingKey":
-      return Option.none()
-    case "InvalidType":
-    case "InvalidValue":
-    case "Forbidden":
-    case "Encoding":
-    case "Composite":
-      return issue.actual
-    case "AnyOf":
-    case "UnexpectedKey":
-    case "OneOf":
-    case "Filter":
-      return Option.some(issue.actual)
-  }
-}
-
-function makeFilterIssue(input: unknown, entry: Schema.FilterIssue): Issue {
+function makeFilterIssue(
+  entry: Schema.FilterIssue,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+): Issue {
   if (isIssue(entry)) {
     return entry
   }
   if (typeof entry === "string") {
-    return new InvalidValue(Option.some(input), { message: entry })
+    return new InvalidValue({ message: entry }, input, options)
   }
   const inner = typeof entry.issue === "string"
-    ? new InvalidValue(Option.some(input), { message: entry.issue })
+    ? new InvalidValue({ message: entry.issue }, input, options)
     : entry.issue
   return new Pointer(entry.path, inner)
 }
 
 /** @internal */
-export function makeSingle(input: unknown, out: undefined | boolean | Schema.FilterIssue): Issue | undefined {
+export function makeSingle(
+  out: undefined | boolean | Schema.FilterIssue,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+): Issue | undefined {
   if (out === undefined) {
     return undefined
   }
   if (typeof out === "boolean") {
-    return out ? undefined : new InvalidValue(Option.some(input))
+    return out ? undefined : new InvalidValue(undefined, input, options)
   }
-  return makeFilterIssue(input, out)
+  return makeFilterIssue(out, input, options)
 }
 
 /** @internal */
-export function make(input: unknown, ast: SchemaAST.AST, out: Schema.FilterOutput): Issue | undefined {
+export function normalizeFilterOutput(
+  ast: SchemaAST.AST,
+  out: Schema.FilterOutput,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+): Issue | undefined {
   if (Array.isArray(out)) {
-    if (Arr.isReadonlyArrayNonEmpty(out)) {
-      if (out.length === 1) {
-        return makeFilterIssue(input, out[0])
-      }
-      return new Composite(ast, Option.some(input), Arr.map(out, (entry) => makeFilterIssue(input, entry)))
+    if (!Arr.isReadonlyArrayNonEmpty(out)) {
+      return undefined
     }
-    return undefined
+    return out.length === 1
+      ? makeFilterIssue(out[0], input, options)
+      : new Composite(ast, Arr.map(out, (entry) => makeFilterIssue(entry, input, options)), input, options)
   }
-  return makeSingle(input, out as undefined | boolean | Schema.FilterIssue)
+  return makeSingle(out as undefined | boolean | Schema.FilterIssue, input, options)
 }
 
 /**
@@ -840,7 +848,7 @@ export function make(input: unknown, ast: SchemaAST.AST, out: Schema.FilterOutpu
  * @see {@link makeFormatterDefault} — creates a `Formatter<string>`
  * @see {@link makeFormatterStandardSchemaV1} — creates a `Formatter<StandardSchemaV1.FailureResult>`
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
@@ -856,7 +864,7 @@ export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
  * @see {@link defaultLeafHook} — the built-in implementation
  * @see {@link Leaf} — the union of terminal issue types
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export type LeafHook = (issue: Leaf) => string
@@ -871,28 +879,34 @@ export type LeafHook = (issue: Leaf) => string
  * **Details**
  *
  * - Checks for a `message` annotation first; returns it if present.
- * - Otherwise generates a default message per `_tag`:
- *   - `InvalidType` → `"Expected <type>, got <actual>"`
- *   - `InvalidValue` → `"Invalid data <actual>"`
+ * - For `InvalidValue`, an `expected` annotation uses the standard expected
+ *   value message and includes reported input when available.
+ * - Otherwise generates a default message per `_tag`. When the issue reports
+ *   input, the message includes its formatted value where applicable:
+ *   - `InvalidType` → `"Expected <type>"` or `"Expected <type>, got <input>"`
+ *   - `InvalidValue` → `"Expected a valid value"` or `"Invalid data <input>"`
  *   - `MissingKey` → `"Missing key"`
- *   - `UnexpectedKey` → `"Unexpected key with value <actual>"`
+ *   - `UnexpectedKey` → `"Expected no excess property"` or
+ *     `"Unexpected key with value <input>"`
  *   - `Forbidden` → `"Forbidden operation"`
- *   - `OneOf` → `"Expected exactly one member to match the input <actual>"`
+ *   - `OneOf` → `"Expected exactly one member to match"` or
+ *     `"Expected exactly one member to match the input <input>"`
  *
  * **Example** (Formatting Standard Schema issues with defaultLeafHook)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaIssue } from "effect"
  *
  * const formatter = SchemaIssue.makeFormatterStandardSchemaV1({
  *   leafHook: SchemaIssue.defaultLeafHook
  * })
+ * formatter(new SchemaIssue.MissingKey(undefined)) // => { issues: [{ path: [], message: "Missing key" }] }
  * ```
  *
  * @see {@link LeafHook}
  * @see {@link makeFormatterStandardSchemaV1}
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export const defaultLeafHook: LeafHook = (issue): string => {
@@ -900,17 +914,27 @@ export const defaultLeafHook: LeafHook = (issue): string => {
   if (message !== undefined) return message
   switch (issue._tag) {
     case "InvalidType":
-      return getExpectedMessage(InternalAnnotations.getExpected(issue.ast), formatOption(issue.actual))
-    case "InvalidValue":
-      return `Invalid data ${formatOption(issue.actual)}`
+      return getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
+    case "InvalidValue": {
+      const expected = findExpected(issue)
+      if (expected !== undefined) return getExpectedMessage(expected, issue)
+      const input = formatInput(issue)
+      return input === undefined ? "Expected a valid value" : `Invalid data ${input}`
+    }
     case "MissingKey":
       return "Missing key"
-    case "UnexpectedKey":
-      return `Unexpected key with value ${format(issue.actual)}`
+    case "UnexpectedKey": {
+      const input = formatInput(issue)
+      return input === undefined ? "Expected no excess property" : `Unexpected key with value ${input}`
+    }
     case "Forbidden":
       return "Forbidden operation"
-    case "OneOf":
-      return `Expected exactly one member to match the input ${format(issue.actual)}`
+    case "OneOf": {
+      const input = formatInput(issue)
+      return input === undefined
+        ? "Expected exactly one member to match"
+        : `Expected exactly one member to match the input ${input}`
+    }
   }
 }
 
@@ -926,11 +950,10 @@ export const defaultLeafHook: LeafHook = (issue): string => {
  *
  * - Returns `string` to override the message, or `undefined` to fall back to
  *   the default formatting.
- *
  * @see {@link defaultCheckHook} — the built-in implementation
  * @see {@link Filter} — the issue type this hook formats
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export type CheckHook = (issue: Filter) => string | undefined
@@ -947,17 +970,16 @@ export type CheckHook = (issue: Filter) => string | undefined
  * - Looks for a `message` annotation on the inner issue first, then on the
  *   filter itself.
  * - Returns `undefined` when no annotation is found, causing the formatter to
- *   fall back to `"Expected <filter>, got <actual>"`.
+ *   fall back to `"Expected <filter>"` or, when the filter reports input,
+ *   `"Expected <filter>, got <input>"`.
  *
  * @see {@link CheckHook}
  * @see {@link makeFormatterStandardSchemaV1}
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
-export const defaultCheckHook: CheckHook = (issue): string | undefined => {
-  return findMessage(issue.issue) ?? findMessage(issue)
-}
+export const defaultCheckHook: CheckHook = (issue): string | undefined => findMessage(issue.issue) ?? findMessage(issue)
 
 /**
  * Creates a {@link Formatter} that produces a `StandardSchemaV1.FailureResult`.
@@ -975,20 +997,30 @@ export const defaultCheckHook: CheckHook = (issue): string | undefined => {
  * - `Pointer` paths are accumulated to produce full property paths.
  * - Falls back to {@link defaultLeafHook} / {@link defaultCheckHook} when no
  *   hooks are provided.
+ * - Default messages include reported input when the issue that produces the
+ *   message has an `input` field. The returned Standard Schema issues do not
+ *   receive an `input` field.
+ *
+ * **Gotchas**
+ *
+ * Reported input can appear inside the Standard Schema `message` string even
+ * though it is not exposed as a separate property. Custom hooks control their
+ * complete message and are not modified.
  *
  * **Example** (Creating a Standard Schema V1 formatter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaIssue } from "effect"
  *
  * const formatter = SchemaIssue.makeFormatterStandardSchemaV1()
+ * formatter(new SchemaIssue.MissingKey(undefined)).issues[0].message // => "Missing key"
  * ```
  *
  * @see {@link makeFormatterDefault} — produces a plain string instead
  * @see {@link LeafHook}
  * @see {@link CheckHook}
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export function makeFormatterStandardSchemaV1(options?: {
@@ -1006,8 +1038,18 @@ type DefaultIssue = {
   readonly path: ReadonlyArray<PropertyKey>
 }
 
-function getExpectedMessage(expected: string, actual: string): string {
-  return `Expected ${expected}, got ${actual}`
+function formatInput(issue: Issue): string | undefined {
+  return hasInput(issue) ? format(issue.input) : undefined
+}
+
+function findExpected(issue: InvalidValue): string | undefined {
+  const expected = issue.annotations?.expected
+  return typeof expected === "string" ? expected : undefined
+}
+
+function getExpectedMessage(expected: string, issue: Issue): string {
+  const input = formatInput(issue)
+  return input === undefined ? `Expected ${expected}` : `Expected ${expected}, got ${input}`
 }
 
 function toDefaultIssues(
@@ -1022,15 +1064,16 @@ function toDefaultIssues(
       if (message !== undefined) {
         return [{ path, message }]
       }
-      switch (issue.issue._tag) {
-        case "InvalidValue":
-          return [{
-            path,
-            message: getExpectedMessage(formatCheck(issue.filter), format(issue.actual))
-          }]
-        default:
-          return toDefaultIssues(issue.issue, path, leafHook, checkHook)
+      if (issue.issue._tag !== "InvalidValue") {
+        return toDefaultIssues(issue.issue, path, leafHook, checkHook)
       }
+      const expected = findExpected(issue.issue)
+      return [{
+        path,
+        message: expected === undefined
+          ? getExpectedMessage(formatCheck(issue.filter), issue)
+          : getExpectedMessage(expected, issue.issue)
+      }]
     }
     case "Encoding":
       return toDefaultIssues(issue.issue, path, leafHook, checkHook)
@@ -1039,12 +1082,11 @@ function toDefaultIssues(
     case "Composite":
       return issue.issues.flatMap((issue) => toDefaultIssues(issue, path, leafHook, checkHook))
     case "AnyOf": {
-      const message = findMessage(issue)
       if (issue.issues.length === 0) {
-        if (message !== undefined) return [{ path, message }]
-
-        const expected = getExpectedMessage(InternalAnnotations.getExpected(issue.ast), format(issue.actual))
-        return [{ path, message: expected }]
+        return [{
+          path,
+          message: findMessage(issue) ?? getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
+        }]
       }
       return issue.issues.flatMap((issue) => toDefaultIssues(issue, path, leafHook, checkHook))
     }
@@ -1076,101 +1118,92 @@ function formatCheck<T>(check: SchemaAST.Check<T>): string {
  *
  * **Details**
  *
- * This is the default formatter used by `SchemaIssue.toString()`.
- *
  * - Flattens the issue tree into `{ message, path }` entries using
  *   {@link defaultLeafHook} and {@link defaultCheckHook}.
+ * - Includes reported input in default messages when the node producing the
+ *   message has an `input` field.
  * - Each entry is rendered as `"<message>"` or `"<message>\n  at <path>"`.
  * - Multiple entries are joined with newlines.
  *
+ * **Gotchas**
+ *
+ * Formatting an issue can disclose input retained with `reportInput: true`.
+ * Wrapper inputs are not inherited by child messages, and custom messages are
+ * returned unchanged.
+ *
  * **Example** (Formatting an issue as a string)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaIssue } from "effect"
  *
  * const formatter = SchemaIssue.makeFormatterDefault()
+ * formatter(new SchemaIssue.MissingKey(undefined)) // => "Missing key"
  * ```
  *
  * @see {@link makeFormatterStandardSchemaV1} — produces Standard Schema V1 format instead
  * @see {@link Formatter}
  *
- * @category Formatter
+ * @category formatting
  * @since 4.0.0
  */
 export function makeFormatterDefault(): Formatter<string> {
-  return (issue) =>
-    toDefaultIssues(issue, [], defaultLeafHook, defaultCheckHook)
-      .map(formatDefaultIssue)
-      .join("\n")
+  return (issue) => formatIssue(issue, "")
 }
 
 /** @internal */
 export const defaultFormatter = makeFormatterDefault()
 
-function formatDefaultIssue(issue: DefaultIssue): string {
-  let out = issue.message
-  if (issue.path && issue.path.length > 0) {
-    const path = formatPath(issue.path as ReadonlyArray<PropertyKey>)
-    out += `\n  at ${path}`
-  }
-  return out
-}
-
-function findMessage(issue: Issue): string | undefined {
+function formatIssue(issue: Issue, path: string): string {
+  let message: string
   switch (issue._tag) {
-    case "InvalidType":
-    case "OneOf":
-    case "Composite":
-    case "AnyOf":
-      return getMessageAnnotation(issue.ast.annotations)
-    case "InvalidValue":
-    case "Forbidden":
-      return getMessageAnnotation(issue.annotations)
-    case "MissingKey":
-      return getMessageAnnotation(issue.annotations, "messageMissingKey")
-    case "UnexpectedKey":
-      return getMessageAnnotation(issue.ast.annotations, "messageUnexpectedKey")
-    case "Filter":
-      return getMessageAnnotation(issue.filter.annotations)
+    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 "Encoding":
-      return findMessage(issue.issue)
+      return formatIssue(issue.issue, path)
+    case "Pointer":
+      return formatIssue(issue.issue, path + formatPath(issue.path))
+    case "Composite":
+    case "AnyOf": {
+      if (issue._tag === "Composite" || issue.issues.length > 0) {
+        return issue.issues.map((issue) => formatIssue(issue, path)).join("\n")
+      }
+      message = findMessage(issue) ?? getExpectedMessage(InternalAnnotations.getExpected(issue.ast), issue)
+      break
+    }
+    default:
+      message = defaultLeafHook(issue)
+      break
   }
+  return path ? `${message}\n  at ${path}` : message
 }
 
-function getMessageAnnotation(
-  annotations: Schema.Annotations.Annotations | undefined,
-  type: "message" | "messageMissingKey" | "messageUnexpectedKey" = "message"
-): string | undefined {
-  const message = annotations?.[type]
+function findMessage(issue: Issue): string | undefined {
+  if (issue._tag === "Pointer") return
+  if (issue._tag === "Encoding") return findMessage(issue.issue)
+  const annotations = issue._tag === "Filter"
+    ? issue.filter.annotations
+    : "annotations" in issue
+    ? issue.annotations
+    : issue.ast.annotations
+  const message = annotations?.[
+    issue._tag === "MissingKey"
+      ? "messageMissingKey"
+      : issue._tag === "UnexpectedKey"
+      ? "messageUnexpectedKey"
+      : "message"
+  ]
   if (typeof message === "string") return message
 }
-
-function formatOption(actual: Option.Option<unknown>): string {
-  if (Option.isNone(actual)) return "no value provided"
-  return format(actual.value)
-}
-
-/** @internal */
-export function redact(issue: Issue): Issue {
-  switch (issue._tag) {
-    case "MissingKey":
-      return issue
-    case "Forbidden":
-      return new Forbidden(Option.map(issue.actual, Redacted.make), issue.annotations)
-    case "Filter":
-      return new Filter(Redacted.make(issue.actual), issue.filter, redact(issue.issue))
-    case "Pointer":
-      return new Pointer(issue.path, redact(issue.issue))
-
-    case "Encoding":
-    case "InvalidType":
-    case "InvalidValue":
-    case "Composite":
-      return new InvalidValue(Option.map(issue.actual, Redacted.make))
-
-    case "AnyOf":
-    case "OneOf":
-    case "UnexpectedKey":
-      return new InvalidValue(Option.some(Redacted.make(issue.actual)))
-  }
-}