effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/ai/AiError.d.ts

@@ -35,7 +35,8 @@
  * Each reason type has an `isRetryable` getter indicating whether the error is
  * transient. Some errors also provide a `retryAfter` duration hint.
  *
- * @example
+ * **Example** (Handling AI errors by reason)
+ *
  * ```ts
  * import { Effect, Match } from "effect"
  * import type { AiError } from "effect/unstable/ai"
@@ -58,7 +59,8 @@
  * )
  * ```
  *
- * @example
+ * **Example** (Creating an AI error with a reason)
+ *
  * ```ts
  * import { Duration, Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -76,7 +78,7 @@
  * console.log(error.message) // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Duration from "../../Duration.ts";
 import * as Schema from "../../Schema.ts";
@@ -101,7 +103,8 @@ declare const NetworkError_base: Schema.Class<NetworkError, Schema.Struct<{
  * such as network connectivity problems, request encoding issues, or invalid
  * URLs.
  *
- * @example
+ * **Example** (Creating a network error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -122,24 +125,27 @@ declare const NetworkError_base: Schema.Class<NetworkError, Schema.Struct<{
  * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class NetworkError extends NetworkError_base {
     /**
-     * @since 1.0.0
+     * Marks `NetworkError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Transport errors are retryable; encoding and URL errors are not.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     /**
      * Creates a NetworkError from a platform HttpClientError.RequestError.
      *
-     * @example
+     * **Example** (Creating a network error from a request error)
+     *
      * ```ts
      * import { AiError } from "effect/unstable/ai"
      * import type { HttpClientError } from "effect/unstable/http"
@@ -149,8 +155,7 @@ export declare class NetworkError extends NetworkError_base {
      * const aiError = AiError.NetworkError.fromRequestError(platformError)
      * ```
      *
-     * @since 1.0.0
-     * @category constructors
+     * @since 4.0.0
      */
     static fromRequestError(error: HttpClientError.RequestError): NetworkError;
     get message(): string;
@@ -168,100 +173,105 @@ export declare class NetworkError extends NetworkError_base {
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ProviderMetadata: Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson>>>;
 /**
- * @since 1.0.0
+ * Type of provider-specific metadata attached to AI error reasons.
+ *
+ * Metadata is keyed by provider name, and each provider value is either mutable
+ * JSON metadata or `null`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ProviderMetadata = typeof ProviderMetadata.Type;
 /**
  * Provider-specific metadata attached to `RateLimitError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface RateLimitErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `QuotaExhaustedError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface QuotaExhaustedErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `AuthenticationError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface AuthenticationErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `ContentPolicyError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ContentPolicyErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `InvalidRequestError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface InvalidRequestErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `InternalProviderError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface InternalProviderErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `InvalidOutputError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface InvalidOutputErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `StructuredOutputError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface StructuredOutputErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `UnsupportedSchemaError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface UnsupportedSchemaErrorMetadata extends ProviderMetadata {
 }
 /**
  * Provider-specific metadata attached to `UnknownError`.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface UnknownErrorMetadata extends ProviderMetadata {
 }
 /**
  * Token usage information from AI operations.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const UsageInfo: Schema.Struct<{
     readonly promptTokens: Schema.optional<Schema.Number>;
@@ -271,8 +281,8 @@ export declare const UsageInfo: Schema.Struct<{
 /**
  * Combined HTTP context for error reporting.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const HttpContext: Schema.Struct<{
     readonly request: Schema.Struct<{
@@ -291,7 +301,7 @@ export declare const HttpContext: Schema.Struct<{
 declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
     readonly _tag: Schema.tag<"RateLimitError">;
     readonly retryAfter: Schema.optional<Schema.Duration>;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<RateLimitErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<RateLimitErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -313,7 +323,8 @@ declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
  * Rate limit errors are always retryable. When `retryAfter` is provided,
  * callers should wait that duration before retrying.
  *
- * @example
+ * **Example** (Creating a rate limit error)
+ *
  * ```ts
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -326,18 +337,20 @@ declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
  * console.log(rateLimitError.message) // "Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class RateLimitError extends RateLimitError_base {
     /**
-     * @since 1.0.0
+     * Marks `RateLimitError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Rate limit errors are always retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -345,7 +358,7 @@ export declare class RateLimitError extends RateLimitError_base {
 declare const QuotaExhaustedError_base: Schema.Class<QuotaExhaustedError, Schema.Struct<{
     readonly _tag: Schema.tag<"QuotaExhaustedError">;
     readonly resetAt: Schema.optional<Schema.DateTimeUtc>;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<QuotaExhaustedErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<QuotaExhaustedErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -366,7 +379,8 @@ declare const QuotaExhaustedError_base: Schema.Class<QuotaExhaustedError, Schema
  *
  * Quota exhausted errors are not retryable without user action.
  *
- * @example
+ * **Example** (Creating a quota exhausted error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -377,18 +391,20 @@ declare const QuotaExhaustedError_base: Schema.Class<QuotaExhaustedError, Schema
  * // "Quota exhausted. Check your account billing and usage limits."
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class QuotaExhaustedError extends QuotaExhaustedError_base {
     /**
-     * @since 1.0.0
+     * Marks `QuotaExhaustedError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Quota exhausted errors require user action and are not retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -396,7 +412,7 @@ export declare class QuotaExhaustedError extends QuotaExhaustedError_base {
 declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema.Struct<{
     readonly _tag: Schema.tag<"AuthenticationError">;
     readonly kind: Schema.Literals<readonly ["InvalidKey", "ExpiredKey", "MissingKey", "InsufficientPermissions", "Unknown"]>;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<AuthenticationErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<AuthenticationErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -417,7 +433,8 @@ declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema
  *
  * Authentication errors are never retryable without credential changes.
  *
- * @example
+ * **Example** (Creating an authentication error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -430,18 +447,20 @@ declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema
  * // "InvalidKey: Verify your API key is correct"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class AuthenticationError extends AuthenticationError_base {
     /**
-     * @since 1.0.0
+     * Marks `AuthenticationError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Authentication errors require credential changes and are not retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -449,7 +468,7 @@ export declare class AuthenticationError extends AuthenticationError_base {
 declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.Struct<{
     readonly _tag: Schema.tag<"ContentPolicyError">;
     readonly description: Schema.String;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<ContentPolicyErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<ContentPolicyErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -470,7 +489,8 @@ declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.S
  *
  * Content policy errors are never retryable without content changes.
  *
- * @example
+ * **Example** (Creating a content policy error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -483,18 +503,20 @@ declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.S
  * // "Content policy violation: Input contains prohibited content"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ContentPolicyError extends ContentPolicyError_base {
     /**
-     * @since 1.0.0
+     * Marks `ContentPolicyError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Content policy errors require content changes and are not retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -504,7 +526,7 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
     readonly parameter: Schema.optional<Schema.String>;
     readonly constraint: Schema.optional<Schema.String>;
     readonly description: Schema.optional<Schema.String>;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InvalidRequestErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InvalidRequestErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -525,7 +547,8 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
  *
  * Invalid request errors require fixing the request and are not retryable.
  *
- * @example
+ * **Example** (Creating an invalid request error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -540,18 +563,20 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
  * // "Invalid request: parameter 'temperature' must be between 0 and 2. Temperature value 5 is out of range"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class InvalidRequestError extends InvalidRequestError_base {
     /**
-     * @since 1.0.0
+     * Marks `InvalidRequestError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Invalid request errors require fixing the request and are not retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -559,7 +584,7 @@ export declare class InvalidRequestError extends InvalidRequestError_base {
 declare const InternalProviderError_base: Schema.Class<InternalProviderError, Schema.Struct<{
     readonly _tag: Schema.tag<"InternalProviderError">;
     readonly description: Schema.String;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InternalProviderErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InternalProviderErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -580,7 +605,8 @@ declare const InternalProviderError_base: Schema.Class<InternalProviderError, Sc
  *
  * Internal provider errors are typically transient and are retryable.
  *
- * @example
+ * **Example** (Creating an internal provider error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -593,18 +619,20 @@ declare const InternalProviderError_base: Schema.Class<InternalProviderError, Sc
  * // "Internal provider error: Server encountered an unexpected error"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class InternalProviderError extends InternalProviderError_base {
     /**
-     * @since 1.0.0
+     * Marks `InternalProviderError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Internal provider errors are typically transient and are retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -612,7 +640,7 @@ export declare class InternalProviderError extends InternalProviderError_base {
 declare const InvalidOutputError_base: Schema.Class<InvalidOutputError, Schema.Struct<{
     readonly _tag: Schema.tag<"InvalidOutputError">;
     readonly description: Schema.String;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InvalidOutputErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InvalidOutputErrorMetadata>>, never>;
     readonly usage: Schema.optional<Schema.Struct<{
         readonly promptTokens: Schema.optional<Schema.Number>;
         readonly completionTokens: Schema.optional<Schema.Number>;
@@ -624,7 +652,8 @@ declare const InvalidOutputError_base: Schema.Class<InvalidOutputError, Schema.S
  *
  * Invalid output errors are retryable since LLM outputs are non-deterministic.
  *
- * @example
+ * **Example** (Creating an invalid output error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -637,24 +666,27 @@ declare const InvalidOutputError_base: Schema.Class<InvalidOutputError, Schema.S
  * // "Invalid output: Expected a string but received a number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class InvalidOutputError extends InvalidOutputError_base {
     /**
-     * @since 1.0.0
+     * Marks `InvalidOutputError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Invalid output errors are retryable since LLM outputs are non-deterministic.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     /**
      * Creates an InvalidOutputError from a Schema error.
      *
-     * @example
+     * **Example** (Creating an invalid output error from a schema error)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { AiError } from "effect/unstable/ai"
@@ -664,8 +696,7 @@ export declare class InvalidOutputError extends InvalidOutputError_base {
      * const parseError = AiError.InvalidOutputError.fromSchemaError(schemaError)
      * ```
      *
-     * @since 1.0.0
-     * @category constructors
+     * @since 4.0.0
      */
     static fromSchemaError(error: Schema.SchemaError): InvalidOutputError;
     get message(): string;
@@ -674,7 +705,7 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
     readonly _tag: Schema.tag<"StructuredOutputError">;
     readonly description: Schema.String;
     readonly responseText: Schema.String;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<StructuredOutputErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<StructuredOutputErrorMetadata>>, never>;
     readonly usage: Schema.optional<Schema.Struct<{
         readonly promptTokens: Schema.optional<Schema.Number>;
         readonly completionTokens: Schema.optional<Schema.Number>;
@@ -687,7 +718,8 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
  *
  * Structured output errors are retryable since LLM outputs are non-deterministic.
  *
- * @example
+ * **Example** (Creating a structured output error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -701,24 +733,27 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
  * // "Structured output validation failed: Expected a valid JSON object"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class StructuredOutputError extends StructuredOutputError_base {
     /**
-     * @since 1.0.0
+     * Marks `StructuredOutputError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Structured output errors are retryable since LLM outputs are non-deterministic.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     /**
      * Creates a StructuredOutputError from a Schema error.
      *
-     * @example
+     * **Example** (Creating a structured output error from a schema error)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { AiError } from "effect/unstable/ai"
@@ -729,8 +764,7 @@ export declare class StructuredOutputError extends StructuredOutputError_base {
      * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, rawText)
      * ```
      *
-     * @since 1.0.0
-     * @category constructors
+     * @since 4.0.0
      */
     static fromSchemaError(error: Schema.SchemaError, responseText: string): StructuredOutputError;
     get message(): string;
@@ -738,7 +772,7 @@ export declare class StructuredOutputError extends StructuredOutputError_base {
 declare const UnsupportedSchemaError_base: Schema.Class<UnsupportedSchemaError, Schema.Struct<{
     readonly _tag: Schema.tag<"UnsupportedSchemaError">;
     readonly description: Schema.String;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<UnsupportedSchemaErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<UnsupportedSchemaErrorMetadata>>, never>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
  * Error indicating a codec transformer rejected a schema because it contains
@@ -747,7 +781,8 @@ declare const UnsupportedSchemaError_base: Schema.Class<UnsupportedSchemaError,
  * Unsupported schema errors are not retryable because they indicate a
  * programmer error where the schema is incompatible with the provider.
  *
- * @example
+ * **Example** (Creating an unsupported schema error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -760,18 +795,20 @@ declare const UnsupportedSchemaError_base: Schema.Class<UnsupportedSchemaError,
  * // "Unsupported schema: Unions are not supported in Anthropic structured output"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class UnsupportedSchemaError extends UnsupportedSchemaError_base {
     /**
-     * @since 1.0.0
+     * Marks `UnsupportedSchemaError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Unsupported schema errors are not retryable because they indicate a programmer error.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -779,7 +816,7 @@ export declare class UnsupportedSchemaError extends UnsupportedSchemaError_base
 declare const UnknownError_base: Schema.Class<UnknownError, Schema.Struct<{
     readonly _tag: Schema.tag<"UnknownError">;
     readonly description: Schema.optional<Schema.String>;
-    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<UnknownErrorMetadata>>>;
+    readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<UnknownErrorMetadata>>, never>;
     readonly http: Schema.optional<Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -800,7 +837,8 @@ declare const UnknownError_base: Schema.Class<UnknownError, Schema.Struct<{
  *
  * Unknown errors are not retryable by default since the cause is unknown.
  *
- * @example
+ * **Example** (Creating an unknown error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -813,18 +851,20 @@ declare const UnknownError_base: Schema.Class<UnknownError, Schema.Struct<{
  * // "An unexpected error occurred"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class UnknownError extends UnknownError_base {
     /**
-     * @since 1.0.0
+     * Marks `UnknownError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Unknown errors are not retryable by default.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -840,7 +880,8 @@ declare const ToolNotFoundError_base: Schema.Class<ToolNotFoundError, Schema.Str
  * This error is retryable because the model may self-correct when provided
  * with the list of available tools.
  *
- * @example
+ * **Example** (Creating a tool not found error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -854,18 +895,20 @@ declare const ToolNotFoundError_base: Schema.Class<ToolNotFoundError, Schema.Str
  * // "Tool 'unknownTool' not found. Available tools: GetWeather, GetTime"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ToolNotFoundError extends ToolNotFoundError_base {
     /**
-     * @since 1.0.0
+     * Marks `ToolNotFoundError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Tool not found errors are retryable because the model may self-correct.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -882,7 +925,8 @@ declare const ToolParameterValidationError_base: Schema.Class<ToolParameterValid
  * This error is retryable because the model may correct its parameters
  * on subsequent attempts.
  *
- * @example
+ * **Example** (Creating a tool parameter validation error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -897,18 +941,20 @@ declare const ToolParameterValidationError_base: Schema.Class<ToolParameterValid
  * // "Invalid parameters for tool 'GetWeather': Expected string, got number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ToolParameterValidationError extends ToolParameterValidationError_base {
     /**
-     * @since 1.0.0
+     * Marks `ToolParameterValidationError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Parameter validation errors are retryable because the model may correct parameters.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -925,7 +971,8 @@ declare const InvalidToolResultError_base: Schema.Class<InvalidToolResultError,
  * This error is not retryable because invalid results indicate a bug in the
  * tool handler implementation.
  *
- * @example
+ * **Example** (Creating an invalid tool result error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -939,18 +986,20 @@ declare const InvalidToolResultError_base: Schema.Class<InvalidToolResultError,
  * // "Tool 'GetWeather' returned invalid result: missing 'temperature' field"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class InvalidToolResultError extends InvalidToolResultError_base {
     /**
-     * @since 1.0.0
+     * Marks `InvalidToolResultError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Invalid tool result errors are not retryable because they indicate a bug in the handler.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -967,33 +1016,36 @@ declare const ToolResultEncodingError_base: Schema.Class<ToolResultEncodingError
  * This error is not retryable because encoding failures indicate a bug in the
  * tool schema definitions.
  *
- * @example
+ * **Example** (Creating a tool result encoding error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
  *   toolName: "GetWeather",
- *   toolResult: { circular: "ref" },
- *   description: "Cannot encode circular reference"
+ *   toolResult: { temperature: 72n },
+ *   description: "Cannot encode bigint values as JSON"
  * })
  *
  * console.log(error.isRetryable) // false
  * console.log(error.message)
- * // "Failed to encode result for tool 'GetWeather': Cannot encode circular reference"
+ * // "Failed to encode result for tool 'GetWeather': Cannot encode bigint values as JSON"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ToolResultEncodingError extends ToolResultEncodingError_base {
     /**
-     * @since 1.0.0
+     * Marks `ToolResultEncodingError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Encoding errors are not retryable because they indicate a code bug.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -1009,7 +1061,8 @@ declare const ToolConfigurationError_base: Schema.Class<ToolConfigurationError,
  * This error is not retryable because it indicates a programming error in the
  * tool configuration that must be fixed in code.
  *
- * @example
+ * **Example** (Creating a tool configuration error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1023,18 +1076,20 @@ declare const ToolConfigurationError_base: Schema.Class<ToolConfigurationError,
  * // "Invalid configuration for tool 'OpenAiCodeInterpreter': Invalid container ID format"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ToolConfigurationError extends ToolConfigurationError_base {
     /**
-     * @since 1.0.0
+     * Marks `ToolConfigurationError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Configuration errors are not retryable because they indicate a code bug.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -1050,7 +1105,8 @@ declare const ToolkitRequiredError_base: Schema.Class<ToolkitRequiredError, Sche
  * This error occurs when tool approval responses are present in the prompt
  * but no toolkit was provided to resolve them.
  *
- * @example
+ * **Example** (Creating a toolkit required error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1063,18 +1119,20 @@ declare const ToolkitRequiredError_base: Schema.Class<ToolkitRequiredError, Sche
  * // "Toolkit required to resolve pending tool approvals: GetWeather, SendEmail"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class ToolkitRequiredError extends ToolkitRequiredError_base {
     /**
-     * @since 1.0.0
+     * Marks `ToolkitRequiredError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Toolkit required errors are not retryable without providing a toolkit.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -1090,31 +1148,34 @@ declare const InvalidUserInputError_base: Schema.Class<InvalidUserInputError, Sc
  * valid but not supported by the provider (e.g., unsupported media types,
  * unsupported file formats, etc.).
  *
- * @example
+ * **Example** (Creating an invalid user input error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidUserInputError({
- *   description: "Unsupported media type 'video/mp4'. Supported types: image/*, application/pdf, text/plain"
+ *   description: "Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
  * })
  *
  * console.log(error.isRetryable) // false
  * console.log(error.message)
- * // "Invalid user input: Unsupported media type 'video/mp4'. Supported types: image/*, application/pdf, text/plain"
+ * // "Invalid user input: Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export declare class InvalidUserInputError extends InvalidUserInputError_base {
     /**
-     * @since 1.0.0
+     * Marks `InvalidUserInputError` as a semantic AI error reason for runtime guards.
+     *
+     * @since 4.0.0
      */
     readonly [ReasonTypeId]: "~effect/unstable/ai/AiError/Reason";
     /**
      * Invalid user input errors require fixing the input and are not retryable.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     get message(): string;
@@ -1122,21 +1183,19 @@ export declare class InvalidUserInputError extends InvalidUserInputError_base {
 /**
  * Union type of all semantic error reasons that can occur during AI operations.
  *
- * Each reason type provides:
- * - Semantic categorization of the failure mode
- * - `isRetryable` getter indicating if the error is transient
- * - Optional `retryAfter` duration for rate limit/throttling errors
- * - Rich context including provider metadata and HTTP details
+ * Every reason carries a semantic `_tag`, a human-readable message, and an
+ * `isRetryable` getter. Provider-facing reasons may also include retry timing,
+ * provider metadata, usage information, or HTTP context.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AiErrorReason = RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | NetworkError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError;
 /**
  * Schema for validating and parsing AI error reasons.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const AiErrorReason: Schema.Union<[
     typeof RateLimitError,
@@ -1175,7 +1234,8 @@ declare const AiError_base: Schema.Class<AiError, Schema.Struct<{
  *
  * Use with `Effect.catchReason` for ergonomic error handling:
  *
- * @example
+ * **Example** (Handling an AI error by tag)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -1193,8 +1253,8 @@ declare const AiError_base: Schema.Class<AiError, Schema.Struct<{
  * )
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare class AiError extends AiError_base {
     readonly [TypeId]: "~effect/unstable/ai/AiError/AiError";
@@ -1202,13 +1262,13 @@ export declare class AiError extends AiError_base {
     /**
      * Delegates to the underlying reason's `isRetryable` getter.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get isRetryable(): boolean;
     /**
      * Delegates to the underlying reason's `retryAfter` if present.
      *
-     * @since 1.0.0
+     * @since 4.0.0
      */
     get retryAfter(): Duration.Duration | undefined;
     get message(): string;
@@ -1216,17 +1276,15 @@ export declare class AiError extends AiError_base {
 /**
  * The encoded (serialized) form of an `AiError`.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export type AiErrorEncoded = typeof AiError["Encoded"];
 /**
  * Type guard to check if a value is an `AiError`.
  *
- * @param u - The value to check
- * @returns `true` if the value is an `AiError`, `false` otherwise
+ * **Example** (Checking for an AI error)
  *
- * @example
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1241,17 +1299,15 @@ export type AiErrorEncoded = typeof AiError["Encoded"];
  * console.log(AiError.isAiError(aiError)) // true
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isAiError: (u: unknown) => u is AiError;
 /**
  * Type guard to check if a value is an `AiErrorReason`.
  *
- * @param u - The value to check
- * @returns `true` if the value is an `AiErrorReason`, `false` otherwise
+ * **Example** (Checking for an AI error reason)
  *
- * @example
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1262,14 +1318,15 @@ export declare const isAiError: (u: unknown) => u is AiError;
  * console.log(AiError.isAiErrorReason(genericError)) // false
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isAiErrorReason: (u: unknown) => u is AiErrorReason;
 /**
  * Creates an `AiError` with the given reason.
  *
- * @example
+ * **Example** (Creating an AI error)
+ *
  * ```ts
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -1286,8 +1343,8 @@ export declare const isAiErrorReason: (u: unknown) => u is AiErrorReason;
  * // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: (params: {
     readonly module: string;
@@ -1299,7 +1356,8 @@ export declare const make: (params: {
  *
  * Provider packages can use this as a base for provider-specific mapping.
  *
- * @example
+ * **Example** (Mapping an HTTP status to a reason)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1311,8 +1369,8 @@ export declare const make: (params: {
  * console.log(reason._tag) // "RateLimitError"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const reasonFromHttpStatus: (params: {
     readonly status: number;