effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/ai/AiError.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 Effect from "../../Effect.ts"
@@ -117,7 +119,8 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  * such as network connectivity problems, request encoding issues, or invalid
  * URLs.
  *
- * @example
+ * **Example** (Creating a network error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -138,8 +141,8 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class NetworkError extends Schema.ErrorClass<NetworkError>(
   "effect/ai/AiError/NetworkError"
@@ -150,14 +153,16 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
   description: Schema.optional(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `NetworkError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Transport errors are retryable; encoding and URL errors are not.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return this.reason === "TransportError"
@@ -166,7 +171,8 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
   /**
    * 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"
@@ -176,8 +182,8 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
    * const aiError = AiError.NetworkError.fromRequestError(platformError)
    * ```
    *
-   * @since 1.0.0
    * @category constructors
+   * @since 4.0.0
    */
   static fromRequestError(error: HttpClientError.RequestError): NetworkError {
     return new NetworkError({
@@ -248,8 +254,8 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ProviderMetadata: Schema.$Record<
   Schema.String,
@@ -257,96 +263,101 @@ export const ProviderMetadata: Schema.$Record<
 > = Schema.Record(Schema.String, Schema.NullOr(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
+ * @since 4.0.0
  */
 export interface RateLimitErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `QuotaExhaustedError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface QuotaExhaustedErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `AuthenticationError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface AuthenticationErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `ContentPolicyError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface ContentPolicyErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `InvalidRequestError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface InvalidRequestErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `InternalProviderError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface InternalProviderErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `InvalidOutputError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface InvalidOutputErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `StructuredOutputError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface StructuredOutputErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `UnsupportedSchemaError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @since 4.0.0
  */
 export interface UnsupportedSchemaErrorMetadata extends ProviderMetadata {}
 
 /**
  * Provider-specific metadata attached to `UnknownError`.
  *
- * @since 1.0.0
  * @category provider options
+ * @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 const UsageInfo = Schema.Struct({
   promptTokens: Schema.optional(Schema.Number),
@@ -357,8 +368,8 @@ export const UsageInfo = Schema.Struct({
 /**
  * Combined HTTP context for error reporting.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const HttpContext = Schema.Struct({
   request: HttpRequestDetails,
@@ -376,7 +387,8 @@ export const HttpContext = 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"
@@ -389,8 +401,8 @@ export const HttpContext = Schema.Struct({
  * console.log(rateLimitError.message) // "Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
   "effect/ai/AiError/RateLimitError"
@@ -401,14 +413,16 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `RateLimitError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Rate limit errors are always retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -426,7 +440,8 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
  *
  * Quota exhausted errors are not retryable without user action.
  *
- * @example
+ * **Example** (Creating a quota exhausted error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -437,8 +452,8 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
  * // "Quota exhausted. Check your account billing and usage limits."
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
   "effect/ai/AiError/QuotaExhaustedError"
@@ -449,14 +464,16 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `QuotaExhaustedError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Quota exhausted errors require user action and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -474,7 +491,8 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
  *
  * Authentication errors are never retryable without credential changes.
  *
- * @example
+ * **Example** (Creating an authentication error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -487,8 +505,8 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
  * // "InvalidKey: Verify your API key is correct"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
   "effect/ai/AiError/AuthenticationError"
@@ -499,14 +517,16 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `AuthenticationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Authentication errors require credential changes and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -529,7 +549,8 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
  *
  * Content policy errors are never retryable without content changes.
  *
- * @example
+ * **Example** (Creating a content policy error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -542,8 +563,8 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
  * // "Content policy violation: Input contains prohibited content"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
   "effect/ai/AiError/ContentPolicyError"
@@ -554,14 +575,16 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ContentPolicyError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Content policy errors require content changes and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -577,7 +600,8 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  *
  * 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"
  *
@@ -592,8 +616,8 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  * // "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 class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
   "effect/ai/AiError/InvalidRequestError"
@@ -606,14 +630,16 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidRequestError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Invalid request errors require fixing the request and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -633,7 +659,8 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
  *
  * Internal provider errors are typically transient and are retryable.
  *
- * @example
+ * **Example** (Creating an internal provider error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -646,8 +673,8 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
  * // "Internal provider error: Server encountered an unexpected error"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InternalProviderError extends Schema.ErrorClass<InternalProviderError>(
   "effect/ai/AiError/InternalProviderError"
@@ -658,14 +685,16 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InternalProviderError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Internal provider errors are typically transient and are retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -681,7 +710,8 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
  *
  * 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"
  *
@@ -694,8 +724,8 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
  * // "Invalid output: Expected a string but received a number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
   "effect/ai/AiError/InvalidOutputError"
@@ -706,14 +736,16 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
   usage: Schema.optional(UsageInfo)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidOutputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Invalid output errors are retryable since LLM outputs are non-deterministic.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -722,7 +754,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
   /**
    * 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"
@@ -732,8 +765,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
    * const parseError = AiError.InvalidOutputError.fromSchemaError(schemaError)
    * ```
    *
-   * @since 1.0.0
    * @category constructors
+   * @since 4.0.0
    */
   static fromSchemaError(error: Schema.SchemaError): InvalidOutputError {
     return new InvalidOutputError({
@@ -752,7 +785,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  *
  * 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"
  *
@@ -766,8 +800,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  * // "Structured output validation failed: Expected a valid JSON object"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputError>(
   "effect/ai/AiError/StructuredOutputError"
@@ -779,14 +813,16 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
   usage: Schema.optional(UsageInfo)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `StructuredOutputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Structured output errors are retryable since LLM outputs are non-deterministic.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -795,7 +831,8 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
   /**
    * 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"
@@ -806,8 +843,8 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
    * 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 {
     return new StructuredOutputError({
@@ -828,7 +865,8 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  * 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"
  *
@@ -841,8 +879,8 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  * // "Unsupported schema: Unions are not supported in Anthropic structured output"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaError>(
   "effect/ai/AiError/UnsupportedSchemaError"
@@ -852,14 +890,16 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
   metadata: providerMetadataWithDefaults<UnsupportedSchemaErrorMetadata>()
 }) {
   /**
-   * @since 1.0.0
+   * Marks `UnsupportedSchemaError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Unsupported schema errors are not retryable because they indicate a programmer error.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -875,7 +915,8 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
  *
  * 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"
  *
@@ -888,8 +929,8 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
  * // "An unexpected error occurred"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class UnknownError extends Schema.ErrorClass<UnknownError>(
   "effect/ai/AiError/UnknownError"
@@ -900,14 +941,16 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
   http: Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `UnknownError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Unknown errors are not retryable by default.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -928,7 +971,8 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  * 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"
  *
@@ -942,8 +986,8 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  * // "Tool 'unknownTool' not found. Available tools: GetWeather, GetTime"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
   "effect/ai/AiError/ToolNotFoundError"
@@ -953,14 +997,16 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
   availableTools: Schema.Array(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolNotFoundError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Tool not found errors are retryable because the model may self-correct.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -978,7 +1024,8 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  * 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"
  *
@@ -993,8 +1040,8 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  * // "Invalid parameters for tool 'GetWeather': Expected string, got number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolParameterValidationError extends Schema.ErrorClass<ToolParameterValidationError>(
   "effect/ai/AiError/ToolParameterValidationError"
@@ -1005,14 +1052,16 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolParameterValidationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Parameter validation errors are retryable because the model may correct parameters.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return true
@@ -1030,7 +1079,8 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  * 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"
  *
@@ -1044,8 +1094,8 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  * // "Tool 'GetWeather' returned invalid result: missing 'temperature' field"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultError>(
   "effect/ai/AiError/InvalidToolResultError"
@@ -1055,14 +1105,16 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidToolResultError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * 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 {
     return false
@@ -1079,23 +1131,24 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  * 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 class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodingError>(
   "effect/ai/AiError/ToolResultEncodingError"
@@ -1106,14 +1159,16 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolResultEncodingError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Encoding errors are not retryable because they indicate a code bug.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -1130,7 +1185,8 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  * 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"
  *
@@ -1144,8 +1200,8 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  * // "Invalid configuration for tool 'OpenAiCodeInterpreter': Invalid container ID format"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationError>(
   "effect/ai/AiError/ToolConfigurationError"
@@ -1155,14 +1211,16 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolConfigurationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Configuration errors are not retryable because they indicate a code bug.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -1179,7 +1237,8 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
  * 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"
  *
@@ -1192,8 +1251,8 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
  * // "Toolkit required to resolve pending tool approvals: GetWeather, SendEmail"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError>(
   "effect/ai/AiError/ToolkitRequiredError"
@@ -1203,14 +1262,16 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
   description: Schema.optional(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolkitRequiredError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Toolkit required errors are not retryable without providing a toolkit.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -1229,21 +1290,22 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
  * 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 class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputError>(
   "effect/ai/AiError/InvalidUserInputError"
@@ -1252,14 +1314,16 @@ export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputErr
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidUserInputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
    * Invalid user input errors require fixing the input and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return false
@@ -1277,14 +1341,12 @@ export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputErr
 /**
  * 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
@@ -1309,8 +1371,8 @@ export type AiErrorReason =
 /**
  * Schema for validating and parsing AI error reasons.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const AiErrorReason: Schema.Union<[
   typeof RateLimitError,
@@ -1368,7 +1430,8 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  *
  * 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"
@@ -1386,8 +1449,8 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  * )
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export class AiError extends Schema.ErrorClass<AiError>(
   "effect/ai/AiError/AiError"
@@ -1403,7 +1466,7 @@ export class AiError extends Schema.ErrorClass<AiError>(
   /**
    * Delegates to the underlying reason's `isRetryable` getter.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable(): boolean {
     return this.reason.isRetryable
@@ -1412,7 +1475,7 @@ export class AiError extends Schema.ErrorClass<AiError>(
   /**
    * Delegates to the underlying reason's `retryAfter` if present.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get retryAfter(): Duration.Duration | undefined {
     return "retryAfter" in this.reason ? this.reason.retryAfter : undefined
@@ -1426,8 +1489,8 @@ export class AiError extends Schema.ErrorClass<AiError>(
 /**
  * The encoded (serialized) form of an `AiError`.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export type AiErrorEncoded = typeof AiError["Encoded"]
 
@@ -1437,7 +1500,8 @@ export type AiErrorEncoded = typeof AiError["Encoded"]
  * @param u - The value to check
  * @returns `true` if the value is an `AiError`, `false` otherwise
  *
- * @example
+ * **Example** (Checking for an AI error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1452,8 +1516,8 @@ export type AiErrorEncoded = typeof AiError["Encoded"]
  * console.log(AiError.isAiError(aiError)) // true
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isAiError = (u: unknown): u is AiError => Predicate.hasProperty(u, TypeId)
 
@@ -1463,7 +1527,8 @@ export const isAiError = (u: unknown): u is AiError => Predicate.hasProperty(u,
  * @param u - The value to check
  * @returns `true` if the value is an `AiErrorReason`, `false` otherwise
  *
- * @example
+ * **Example** (Checking for an AI error reason)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1474,15 +1539,16 @@ export const isAiError = (u: unknown): u is AiError => Predicate.hasProperty(u,
  * console.log(AiError.isAiErrorReason(genericError)) // false
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.hasProperty(u, ReasonTypeId)
 
 /**
  * Creates an `AiError` with the given reason.
  *
- * @example
+ * **Example** (Creating an AI error)
+ *
  * ```ts
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -1499,8 +1565,8 @@ export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.has
  * // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (params: {
   readonly module: string
@@ -1513,7 +1579,8 @@ export 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"
  *
@@ -1525,8 +1592,8 @@ export const make = (params: {
  * console.log(reason._tag) // "RateLimitError"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const reasonFromHttpStatus = (params: {
   readonly status: number