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

package/dist/SchemaIssue.d.ts

@@ -5,14 +5,12 @@
  * 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
  */
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { type Formatter as FormatterI } from "./Formatter.ts";
-import * as Option from "./Option.ts";
 import type * as Schema from "./Schema.ts";
 import type * as SchemaAST from "./SchemaAST.ts";
 declare const TypeId = "~effect/SchemaIssue/Issue";
@@ -31,14 +29,12 @@ declare 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}
@@ -47,6 +43,38 @@ declare const TypeId = "~effect/SchemaIssue/Issue";
  * @since 4.0.0
  */
 export declare function isIssue(u: unknown): u is Issue;
+/**
+ * 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 declare function hasInput(issue: Issue): issue is Issue & {
+    readonly input: unknown;
+};
 /**
  * Union of all terminal (leaf) issue types that have no inner `Issue` children.
  *
@@ -80,20 +108,29 @@ export type Leaf = InvalidType | InvalidValue | MissingKey | UnexpectedKey | For
  * 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
  */
 export type Issue = Leaf | Filter | Encoding | Pointer | Composite | AnyOf;
 declare class Base {
     readonly [TypeId] = "~effect/SchemaIssue/Issue";
-    toString(this: Issue): string;
+    /**
+     * The input reported by the schema parser, when input reporting is enabled
+     * and the issue is associated with a present value.
+     */
+    readonly input?: unknown;
+    constructor(input?: unknown, options?: SchemaAST.ParseOptions);
 }
 /**
  * Represents a schema issue produced when a schema filter (refinement check) fails.
@@ -105,22 +142,28 @@ declare 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`
@@ -131,10 +174,6 @@ declare class Base {
  */
 export declare class Filter extends Base {
     readonly _tag = "Filter";
-    /**
-     * The input value that caused the issue.
-     */
-    readonly actual: unknown;
     /**
      * The filter that failed.
      */
@@ -144,10 +183,6 @@ export declare class Filter extends Base {
      */
     readonly issue: Issue;
     constructor(
-    /**
-     * The input value that caused the issue.
-     */
-    actual: unknown, 
     /**
      * The filter that failed.
      */
@@ -155,7 +190,16 @@ export declare 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);
 }
 /**
  * Represents a schema issue produced when a schema transformation (encode/decode step) fails.
@@ -168,8 +212,6 @@ export declare 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)
@@ -184,10 +226,6 @@ export declare 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.
      */
@@ -198,13 +236,18 @@ export declare 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);
 }
 /**
  * Wraps an inner {@link Issue} with a property-key path, indicating *where* in
@@ -218,11 +261,9 @@ export declare 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
@@ -257,7 +298,6 @@ export declare 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
@@ -289,9 +329,10 @@ export declare 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
@@ -305,19 +346,20 @@ export declare 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);
 }
 /**
  * Represents a schema issue that groups multiple child issues under a single schema node.
@@ -330,8 +372,6 @@ export declare 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)
@@ -346,10 +386,6 @@ export declare 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.
      */
@@ -360,17 +396,22 @@ export declare 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);
 }
 /**
  * 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**
  *
@@ -380,23 +421,17 @@ export declare 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
@@ -410,19 +445,20 @@ export declare 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);
 }
 /**
  * Represents a schema issue produced when the input has the correct type but its value violates a
@@ -435,23 +471,22 @@ export declare 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
@@ -462,23 +497,24 @@ export declare class InvalidType extends Base {
  */
 export declare class InvalidValue extends Base {
     readonly _tag = "InvalidValue";
-    /**
-     * The value that caused the issue.
-     */
-    readonly actual: Option.Option<unknown>;
     /**
      * The metadata for the issue.
      */
     readonly annotations: Schema.Annotations.Issue | undefined;
     constructor(
     /**
-     * The value that caused the issue.
+     * The metadata for the issue.
+     */
+    annotations?: Schema.Annotations.Issue | undefined, 
+    /**
+     * The present input associated with the issue. It is retained only when
+     * `options.reportInput` is `true`.
      */
-    actual: Option.Option<unknown>, 
+    input?: unknown, 
     /**
-     * The metadata for the issue.
+     * The effective parse options controlling input retention.
      */
-    annotations?: Schema.Annotations.Issue | undefined);
+    options?: SchemaAST.ParseOptions);
 }
 /**
  * Represents a schema issue produced when a forbidden operation is encountered during parsing,
@@ -491,22 +527,19 @@ export declare 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)
@@ -516,23 +549,24 @@ export declare class InvalidValue extends Base {
  */
 export declare class Forbidden extends Base {
     readonly _tag = "Forbidden";
-    /**
-     * The input value that caused the issue.
-     */
-    readonly actual: Option.Option<unknown>;
     /**
      * The metadata for the issue.
      */
     readonly annotations: Schema.Annotations.Issue | undefined;
     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`.
+     */
+    input?: unknown, 
+    /**
+     * The effective parse options controlling input retention.
      */
-    annotations: Schema.Annotations.Issue | undefined);
+    options?: SchemaAST.ParseOptions);
 }
 /**
  * Represents a schema issue produced when a value does not match *any* member of a union schema.
@@ -545,9 +579,13 @@ export declare 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
@@ -561,10 +599,6 @@ export declare 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.
      */
@@ -575,13 +609,18 @@ export declare class AnyOf extends Base {
      */
     ast: SchemaAST.Union, 
     /**
-     * The input value that caused the issue.
+     * The issues that occurred.
      */
-    actual: unknown, 
+    issues: ReadonlyArray<Issue>, 
     /**
-     * The issues that occurred.
+     * 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.
      */
-    issues: ReadonlyArray<Issue>);
+    options?: SchemaAST.ParseOptions);
 }
 /**
  * Represents a schema issue produced when a value matches *multiple* members of a union that is
@@ -595,10 +634,11 @@ export declare 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
  *
@@ -611,10 +651,6 @@ export declare 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.
      */
@@ -625,49 +661,19 @@ export declare 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);
 }
-/**
- * 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 declare function getActual(issue: Issue): Option.Option<unknown>;
 /**
  * A function type that converts an {@link Issue} into a formatted
  * representation. Specialisation of the generic `Formatter` from
@@ -676,7 +682,7 @@ export declare function getActual(issue: Issue): Option.Option<unknown>;
  * @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> {
@@ -692,7 +698,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;
@@ -706,28 +712,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 declare const defaultLeafHook: LeafHook;
@@ -743,11 +755,10 @@ export declare const defaultLeafHook: LeafHook;
  *
  * - 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;
@@ -763,12 +774,13 @@ 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 declare const defaultCheckHook: CheckHook;
@@ -788,20 +800,30 @@ export declare const defaultCheckHook: CheckHook;
  * - `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 declare function makeFormatterStandardSchemaV1(options?: {
@@ -819,25 +841,32 @@ export declare function makeFormatterStandardSchemaV1(options?: {
  *
  * **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 declare function makeFormatterDefault(): Formatter<string>;