synthra 0.1.0

data/lib/synthra/errors.rb

@@ -0,0 +1,1169 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Error Classes
+# =============================================================================
+#
+# This file defines all error classes used throughout Synthra.
+# Errors are organized into categories:
+#
+# 1. **Parsing Errors** - Raised during DSL parsing (syntax, type, indentation)
+# 2. **Generation Errors** - Raised during data generation (uniqueness, references)
+# 3. **Resource Limit Errors** - Raised when configured limits are exceeded
+# 4. **Simulated Errors** - Intentionally raised by behaviors for testing
+#
+# All errors inherit from Synthra::Errors::Error which inherits from StandardError.
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Container module for all Synthra error classes
+  #
+  # This module provides a namespace for error organization. All errors
+  # are also aliased at the Synthra module level for convenience.
+  #
+  # @example Catching any Synthra error
+  #   begin
+  #     schema.generate
+  #   rescue Synthra::Error => e
+  #     puts "Synthra error: #{e.message}"
+  #   end
+  #
+  # @example Catching specific error types
+  #   begin
+  #     registry.load_file("schema.dsl")
+  #   rescue Synthra::ParseError => e
+  #     puts "Parse error at line #{e.line}: #{e.message}"
+  #   rescue Synthra::GenerationError => e
+  #     puts "Generation error: #{e.message}"
+  #   end
+  #
+
+  module Errors
+
+    # Base error class for all Synthra errors
+    #
+    # All Synthra errors inherit from this class, allowing you to
+    # catch all gem-related errors with a single rescue clause.
+    #
+    # @example Catch all Synthra errors
+    #   begin
+    #     Synthra.load("schema.dsl").generate
+    #   rescue Synthra::Errors::Error => e
+    #     logger.error("Synthra error: #{e.message}")
+    #   end
+    #
+
+    class Error < StandardError
+
+      # Machine-readable error code for programmatic error handling
+      ERROR_CODE = "SYNTHRA_ERROR"
+    end
+
+    # ============================================================================
+
+    # Parsing Errors
+    # ============================================================================
+    #
+    # These errors are raised when there are problems parsing DSL files.
+    # They include location information (line, column) to help identify
+    # the source of the problem.
+
+
+
+    # Base class for parsing errors with location information
+    #
+    # ParseError and its subclasses include line and column numbers
+    # to help locate the source of syntax problems in DSL files.
+    # The error message is automatically formatted to include this
+    # location information.
+    #
+    # @!attribute [r] line
+    #   @return [Integer, nil] the line number where the error occurred (1-based)
+    #
+    # @!attribute [r] column
+    #   @return [Integer, nil] the column number where the error occurred (1-based)
+    #
+    # @!attribute [r] source_line
+    #   @return [String, nil] the content of the source line with the error
+    #
+    # @!attribute [r] source_context
+    #   @return [Array<String>, nil] lines before/after for context
+    #
+    # @!attribute [r] suggestions
+    #   @return [Array<String>, nil] "did you mean" suggestions
+    #
+    # @example Error with location
+    #   begin
+    #     Synthra.load("bad.dsl")
+    #   rescue Synthra::ParseError => e
+    #     puts "Error at line #{e.line}, column #{e.column}"
+    #     puts e.message
+    #     # Output:
+    #     # Error at line 5, column 10
+    #     #
+    #     #     3 | User:
+    #     #     4 |   id: uuid
+    #     #   > 5 |   name: strng
+    #     #               ^^^^^
+    #     #     6 |   email: email
+    #     #
+    #     # Unknown type 'strng'. Did you mean: string, text?
+    #   end
+    #
+
+    # Raised when a schema references an unknown mixin. Was referenced in mixin.rb but never
+    # defined, so the unknown-mixin path raised NameError instead of this clean error.
+    class MixinError < Error
+      ERROR_CODE = "MIXIN_ERROR"
+    end
+
+    class ParseError < Error
+      ERROR_CODE = "PARSE_ERROR"
+      attr_reader :line, :column, :source_line, :source_context, :suggestions
+
+
+      # Create a new ParseError with location information
+      #
+      # @param message [String] the error message describing the problem
+      # @param line [Integer, nil] line number where error occurred (1-based)
+      # @param column [Integer, nil] column number where error occurred (1-based)
+      # @param source_line [String, nil] the source line content for context
+      # @param source_context [Array<String>, nil] surrounding lines for context
+      # @param suggestions [Array<String>, nil] "did you mean" suggestions
+      #
+      # @example
+      #   raise ParseError.new("Unexpected token", line: 5, column: 10, source_line: "  bad: ^invalid")
+      #
+
+      def initialize(message, line: nil, column: nil, source_line: nil, source_context: nil, suggestions: nil)
+        @line = line
+        @column = column
+        @source_line = source_line
+        @source_context = source_context
+        @suggestions = suggestions
+
+        full_message = build_message(message)
+        super(full_message)
+      end
+
+      private
+
+
+      # Build a formatted error message with location context
+      #
+      # Creates a user-friendly error message that includes:
+      # - The base error message
+      # - Line and column numbers
+      # - Source context with line numbers and pointer
+      # - "Did you mean" suggestions
+      #
+      # @param message [String] the base error message
+      # @return [String] the formatted message with location context
+      #
+
+      def build_message(message)
+        parts = [message]
+        parts << "at line #{line}" if line
+        parts << "column #{column}" if column
+
+        # Add source context if available
+        if source_context&.any?
+          parts << "\n\n#{format_source_context}"
+        elsif source_line
+          parts << "\n  #{source_line}"
+          parts << "\n  #{" " * ([column.to_i - 1, 0].max)}^" if column
+        end
+
+        # Add suggestions if available
+        if suggestions&.any?
+          parts << "\n\n#{Utils::StringDistance.format_suggestions(suggestions)}"
+        end
+
+        parts.join(" ").strip
+      end
+
+
+      # Format source context with line numbers
+      #
+      # @return [String] formatted source context
+      #
+      # :nocov:
+      def format_source_context
+        return "" unless source_context&.any?
+
+        lines = []
+        context_start_line = [line.to_i - source_context.length / 2, 1].max
+
+        source_context.each_with_index do |content, idx|
+          current_line = context_start_line + idx
+          line_num = current_line.to_s.rjust(5)
+
+          if current_line == line
+            lines << "  > #{line_num} | #{content}"
+            if column && column > 0
+              pointer = " " * (10 + [column - 1, 0].max) + "^"
+              lines << pointer
+            end
+          else
+            lines << "    #{line_num} | #{content}"
+          end
+        end
+
+        lines.join("\n")
+      end
+      # :nocov:
+    end
+
+
+    # Syntax error in DSL file
+    #
+    # Raised when the parser encounters invalid syntax that doesn't
+    # match the expected DSL grammar.
+    #
+    # @example
+    #   # Missing colon after field name
+    #   # User:
+    #   #   name text  <- SyntaxError: expected ':'
+    #
+
+    class SyntaxError < ParseError
+      ERROR_CODE = "SYNTAX_ERROR"
+    end
+
+
+    # Unknown type referenced in DSL
+    #
+    # Raised when a field uses a type that hasn't been registered.
+    # This could be a typo or a custom type that wasn't defined.
+    # Includes "did you mean" suggestions for similar type names.
+    #
+    # @!attribute [r] type_name
+    #   @return [String] the unknown type name that was referenced
+    #
+    # @example
+    #   # User:
+    #   #   name: strng  <- UnknownTypeError: Unknown type 'strng'. Did you mean: string, text?
+    #
+
+    class UnknownTypeError < ParseError
+      ERROR_CODE = "UNKNOWN_TYPE_ERROR"
+      attr_reader :type_name
+
+
+      # Create a new UnknownTypeError
+      #
+      # @param type_name [String] the type name that wasn't found
+      # @param suggestions [Array<String>] similar type names
+      # @param kwargs [Hash] location information (line, column, source_line)
+      #
+
+      def initialize(type_name, suggestions: nil, **kwargs)
+        @type_name = type_name
+        super("Unknown type '#{type_name}'", suggestions: suggestions, **kwargs)
+      end
+    end
+
+
+    # Invalid path in copy() reference
+    #
+    # Raised when a copy() type references a path that doesn't exist
+    # in the schema structure. Includes "did you mean" suggestions
+    # for similar paths.
+    #
+    # @!attribute [r] path
+    #   @return [String] the invalid path that was referenced
+    #
+    # @!attribute [r] available_paths
+    #   @return [Array<String>] list of valid paths available
+    #
+    # @example
+    #   # copy("users.snder.id")  <- PathError: Path 'users.snder.id' not found.
+    #   #                            Did you mean: users.sender.id?
+    #
+
+    class PathError < ParseError
+      ERROR_CODE = "PATH_ERROR"
+      attr_reader :path, :available_paths
+
+
+      # Create a new PathError
+      #
+      # @param path [String] the path that wasn't found
+      # @param available_paths [Array<String>] list of valid paths
+      # @param suggestions [Array<String>] similar paths
+      # @param kwargs [Hash] location information (line, column, source_line)
+      #
+
+      def initialize(path, available_paths: [], suggestions: nil, **kwargs)
+        @path = path
+        @available_paths = available_paths
+        super("Path '#{path}' not found in schema", suggestions: suggestions, **kwargs)
+      end
+    end
+
+
+    # Circular schema reference detected
+    #
+    # Raised when schemas reference each other in a cycle that would cause
+    # infinite recursion during data generation.
+    #
+    # @!attribute [r] cycle
+    #   @return [Array<String>] the schemas involved in the cycle
+    #
+    # @example Circular reference
+    #   # Parent:
+    #   #   child: Child
+    #   # Child:
+    #   #   parent: Parent  <- Circular!
+    #
+
+    class CycleError < ParseError
+      ERROR_CODE = "CYCLE_ERROR"
+      attr_reader :cycle
+
+
+      # Create a new CycleError
+      #
+      # @param cycle [Array<String>] list of schema names in the cycle
+      # @param kwargs [Hash] additional options
+      #
+
+      def initialize(cycle, **kwargs)
+        @cycle = cycle
+        cycle_path = cycle.join(" -> ")
+        super("Circular schema reference detected: #{cycle_path}", **kwargs)
+      end
+    end
+
+
+    # Field order error for copy() references
+    #
+    # Raised when a copy() field references another field that is defined
+    # after it in the schema. Since fields are generated in definition order,
+    # this would result in nil values.
+    #
+    # @!attribute [r] field_name
+    #   @return [String] the name of the copy field
+    #
+    # @!attribute [r] copy_path
+    #   @return [String] the path being copied
+    #
+    # @!attribute [r] schema_name
+    #   @return [String] the schema containing the error
+    #
+    # @example Field order problem
+    #   # Order:
+    #   #   user_id: copy("user.id")  <- ERROR: user not defined yet!
+    #   #   user: User
+    #
+
+    class FieldOrderError < ParseError
+      ERROR_CODE = "FIELD_ORDER_ERROR"
+      attr_reader :field_name, :copy_path, :schema_name
+
+
+      # Create a new FieldOrderError
+      #
+      # @param field_name [String] the copy field name
+      # @param copy_path [String] the path being copied
+      # @param schema_name [String] the schema name
+      # @param suggestion [String] how to fix the error
+      # @param kwargs [Hash] additional options
+      #
+
+      def initialize(field_name:, copy_path:, schema_name:, suggestion: nil, **kwargs)
+        @field_name = field_name
+        @copy_path = copy_path
+        @schema_name = schema_name
+
+        message = "Field order error in '#{schema_name}': " \
+                  "'#{field_name}' uses copy(\"#{copy_path}\") but the source field is defined after it"
+        
+        super(message, suggestions: suggestion ? [suggestion] : nil, **kwargs)
+      end
+    end
+
+
+    # Invalid probability specification
+    #
+    # Raised when enum probabilities exceed 100% total.
+    #
+    # @!attribute [r] total
+    #   @return [Numeric] the total probability that exceeded 100%
+    #
+    # @example
+    #   # status: enum(active:60%, inactive:60%)  <- total 120% > 100%
+    #
+
+    class InvalidProbabilityError < ParseError
+      ERROR_CODE = "INVALID_PROBABILITY_ERROR"
+      attr_reader :total
+
+
+      # Create a new InvalidProbabilityError
+      #
+      # @param total [Numeric] the total probability percentage
+      # @param kwargs [Hash] location information (line, column, source_line)
+      #
+
+      def initialize(total, **kwargs)
+        @total = total
+        super("Probability total #{total}% exceeds 100%", **kwargs)
+      end
+    end
+
+
+    # Indentation error in DSL file
+    #
+    # Raised when indentation doesn't match the expected pattern.
+    # Synthra uses 2-space indentation consistently.
+    #
+    # @!attribute [r] expected
+    #   @return [Integer] the expected number of spaces
+    #
+    # @!attribute [r] actual
+    #   @return [Integer] the actual number of spaces found
+    #
+    # @example
+    #   # User:
+    #   #    name: text  <- 3 spaces instead of 2
+    #
+
+    class IndentationError < ParseError
+      ERROR_CODE = "INDENTATION_ERROR"
+      attr_reader :expected, :actual
+
+
+      # Create a new IndentationError
+      #
+      # @param expected [Integer] expected number of spaces
+      # @param actual [Integer] actual number of spaces found
+      # @param kwargs [Hash] location information (line, column, source_line)
+      #
+
+      def initialize(expected:, actual:, **kwargs)
+        @expected = expected
+        @actual = actual
+        super("Invalid indentation: expected #{expected} spaces, got #{actual}", **kwargs)
+      end
+    end
+
+    # ============================================================================
+
+    # Simulyra DSL Validation Errors
+    # ============================================================================
+    #
+    # These errors are raised when validating Simulyra DSL structure.
+    # They enforce the strict separation between Schema, API, and Scenario layers.
+
+
+    # Base class for Simulyra DSL validation errors
+    #
+    # ValidationError provides structured error messages with suggestions
+    # for how to fix the problem.
+    #
+    # @!attribute [r] suggestion
+    #   @return [String, nil] suggestion for how to fix the error
+    #
+
+    class ValidationError < ParseError
+      ERROR_CODE = "VALIDATION_ERROR"
+      attr_reader :suggestion
+
+      # Create a new ValidationError
+      #
+      # @param message [String] error description
+      # @param line [Integer, nil] line number where error occurred
+      # @param suggestion [String, nil] suggestion for fixing the error
+      #
+      def initialize(message, line: nil, suggestion: nil, **kwargs)
+        @suggestion = suggestion
+        full_message = message
+        full_message += " -> #{suggestion}" if suggestion
+        super(full_message, line: line, **kwargs)
+      end
+    end
+
+
+    # Schema-level validation error
+    #
+    # Raised when there are problems with schema definitions.
+    #
+    # @example Duplicate schema names
+    #   # SchemaError: Duplicate schema "User" -> Defined again at line 15
+    #
+
+    class SchemaError < ValidationError
+      ERROR_CODE = "SCHEMA_ERROR"
+    end
+
+
+    # API-level validation error
+    #
+    # Raised when there are problems with API definitions.
+    #
+    # @example API without scenarios
+    #   # ApiError: API GET /users must define at least one scenario
+    #
+
+    class ApiError < ValidationError
+      ERROR_CODE = "API_ERROR"
+    end
+
+
+    # Scenario-level validation error
+    #
+    # Raised when there are problems with scenario definitions.
+    #
+    # @example Missing @status directive
+    #   # ScenarioError: Scenario "Success" must define @status
+    #
+
+    class ScenarioError < ValidationError
+      ERROR_CODE = "SCENARIO_ERROR"
+    end
+
+
+    # Reference resolution error
+    #
+    # Raised when a schema(:Name) reference cannot be resolved.
+    #
+    # @example Unknown schema reference
+    #   # ReferenceError: Schema "Users" is not defined -> Did you mean: User?
+    #
+
+    class ReferenceError < ValidationError
+      ERROR_CODE = "REFERENCE_ERROR"
+    end
+
+
+    # Context separation error
+    #
+    # Raised when DSL elements are used in the wrong context.
+    #
+    # @example HTTP directive in schema
+    #   # ContextError: HTTP directives are not allowed inside schema definitions
+    #
+
+    class ContextError < ValidationError
+      ERROR_CODE = "CONTEXT_ERROR"
+    end
+
+
+    # Type-level validation error
+    #
+    # Raised when type definitions have invalid syntax or unknown types.
+    #
+    # @example Invalid array syntax
+    #   # TypeError: Arrays can only be created from schema references
+    #
+
+    class TypeError < ValidationError
+      ERROR_CODE = "TYPE_ERROR"
+    end
+
+    # ============================================================================
+
+    # Generation Errors
+    # ============================================================================
+    #
+    # These errors are raised during data generation when something goes wrong.
+    # They indicate problems with schema definitions, references, or constraints.
+
+
+
+    # Base class for errors that occur during data generation
+    #
+    # GenerationError and its subclasses are raised when the schema is valid
+    # but something goes wrong during the actual data generation process.
+    #
+    # @example
+    #   begin
+    #     schema.generate(count: 1000)
+    #   rescue Synthra::GenerationError => e
+    #     puts "Could not generate data: #{e.message}"
+    #   end
+    #
+
+    class GenerationError < Error
+      ERROR_CODE = "GENERATION_ERROR"
+    end
+
+    # Raised when a DSL feature needs a dangerous opt-in that is disabled by
+    # default — e.g. the `formula` type's eval. Default-safe: surfaces a clear
+    # error instead of silently executing tenant-supplied Ruby. Inherits from
+    # Error (not GenerationError) so a generic `rescue` in a type generator
+    # cannot swallow it back into a silent value.
+    class SecurityError < Error
+      ERROR_CODE = "SECURITY_ERROR"
+    end
+
+
+    # Uniqueness constraint could not be satisfied
+    #
+    # Raised when the generator cannot produce a unique value after
+    # multiple attempts. This typically happens when generating many
+    # records with unique fields that have limited possible values.
+    #
+    # @!attribute [r] field
+    #   @return [String] the field name that requires uniqueness
+    #
+    # @!attribute [r] attempts
+    #   @return [Integer] number of attempts made before giving up
+    #
+    # @!attribute [r] last_values
+    #   @return [Array] the last few values that were rejected as duplicates
+    #
+    # @example
+    #   # When generating 1000 users with unique emails from small domain
+    #   # UniquenessError: Could not generate unique value for 'email' after 100 attempts
+    #
+
+    class UniquenessError < GenerationError
+      ERROR_CODE = "UNIQUENESS_ERROR"
+      attr_reader :field, :attempts, :last_values, :schema_name
+
+
+      # Create a new UniquenessError
+      #
+      # @param field [String] the field name that requires uniqueness
+      # @param attempts [Integer] number of generation attempts made
+      # @param last_values [Array] the last values attempted (for debugging)
+      # @param schema_name [String, nil] the schema name where the error occurred
+      #
+
+      def initialize(field:, attempts: nil, last_values: nil, schema_name: nil)
+        @field = field
+        @attempts = attempts || Synthra.configuration.max_unique_retries
+        @last_values = last_values || []
+        @schema_name = schema_name
+        message = "Could not generate unique value for '#{field}'"
+        message += " in schema '#{schema_name}'" if schema_name
+        message += " after #{@attempts} attempts"
+        message += ". Last values: #{@last_values.first(5).inspect}" unless @last_values.empty?
+        super(message)
+      end
+    end
+
+
+    # Cyclic reference detected between schemas
+    #
+    # Raised when schemas reference each other in a cycle, which would
+    # cause infinite recursion during generation.
+    #
+    # @!attribute [r] cycle
+    #   @return [Array<String>] the schema names forming the cycle
+    #
+    # @example
+    #   # User references Order, Order references User
+    #   # CyclicReferenceError: Cyclic reference detected: User -> Order -> User
+    #
+
+    class CyclicReferenceError < GenerationError
+      ERROR_CODE = "CYCLIC_REFERENCE_ERROR"
+      attr_reader :cycle
+
+
+      # Create a new CyclicReferenceError
+      #
+      # @param cycle [Array<String>] the schema names in the reference cycle
+      #
+
+      def initialize(cycle)
+        @cycle = cycle
+        cycle_str = cycle.join(" -> ")
+        super("Cyclic reference detected: #{cycle_str}")
+      end
+    end
+
+
+    # Referenced schema or field not found
+    #
+    # Raised when a Ref() references a schema or field that doesn't exist.
+    #
+    # @!attribute [r] schema_name
+    #   @return [String] the schema name that was referenced
+    #
+    # @!attribute [r] field_path
+    #   @return [String, nil] the field path within the schema (if applicable)
+    #
+    # @example
+    #   # user_id: Ref(NonExistent.id)
+    #   # MissingReferenceError: Reference not found: NonExistent.id
+    #
+
+    class MissingReferenceError < GenerationError
+      ERROR_CODE = "MISSING_REFERENCE_ERROR"
+      attr_reader :schema_name, :field_path
+
+
+      # Create a new MissingReferenceError
+      #
+      # @param schema_name [String] the schema name that wasn't found
+      # @param field_path [String, nil] the field path if referencing a specific field
+      #
+
+      def initialize(schema_name:, field_path: nil)
+        @schema_name = schema_name
+        @field_path = field_path
+
+        message = if field_path
+                    "Reference not found: #{schema_name}.#{field_path}"
+                  else
+                    "Schema not found: #{schema_name}"
+                  end
+        super(message)
+      end
+    end
+
+
+    # Custom function not registered
+    #
+    # Raised when a custom() type references a function that hasn't
+    # been registered with Synthra.register_function.
+    #
+    # @!attribute [r] function_name
+    #   @return [Symbol] the function name that wasn't found
+    #
+    # @example
+    #   # full_name: custom(:compute_name)
+    #   # MissingFunctionError: Custom function not registered: compute_name
+    #
+
+    class MissingFunctionError < GenerationError
+      ERROR_CODE = "MISSING_FUNCTION_ERROR"
+      attr_reader :function_name
+
+
+      # Create a new MissingFunctionError
+      #
+      # @param function_name [Symbol, String] the function name that wasn't registered
+      #
+
+      def initialize(function_name)
+        @function_name = function_name
+        super("Custom function not registered: #{function_name}")
+      end
+    end
+
+
+    # Error evaluating a conditional field
+    #
+    # Raised when the condition expression for a conditional field
+    # cannot be evaluated, typically due to referencing a non-existent field.
+    #
+    # @!attribute [r] condition
+    #   @return [String] the condition expression that failed
+    #
+    # @!attribute [r] original_error
+    #   @return [Exception, nil] the underlying error if one occurred
+    #
+    # @example
+    #   # admin_note: text if is_admin
+    #   # ConditionError: Error evaluating condition 'is_admin'
+    #
+
+    class ConditionError < GenerationError
+      ERROR_CODE = "CONDITION_ERROR"
+      attr_reader :condition, :original_error
+
+
+      # Create a new ConditionError
+      #
+      # @param condition [String] the condition expression that failed
+      # @param original_error [Exception, nil] the underlying error
+      #
+
+      def initialize(condition:, original_error: nil)
+        @condition = condition
+        @original_error = original_error
+
+        message = "Error evaluating condition '#{condition}'"
+        message += ": #{original_error.message}" if original_error
+        super(message)
+      end
+    end
+
+    # ============================================================================
+
+    # Resource Limit Errors
+    # ============================================================================
+    #
+    # These errors are raised when configured resource limits are exceeded.
+    # They protect against runaway generation (infinite loops, huge arrays, etc.)
+
+
+
+    # Base class for resource limit exceeded errors
+    #
+    # ResourceLimitError and its subclasses are raised when generation
+    # would exceed configured safety limits. These limits prevent accidental
+    # resource exhaustion during testing.
+    #
+    # @example Handling limit errors
+    #   begin
+    #     schema.generate
+    #   rescue Synthra::ResourceLimitError => e
+    #     puts "Limit exceeded: #{e.message}"
+    #     puts "Configure limits via Synthra.configure"
+    #   end
+    #
+
+    class ResourceLimitError < Error
+      ERROR_CODE = "RESOURCE_LIMIT_ERROR"
+    end
+
+
+    # Latency exceeds configured maximum
+    #
+    # Raised when the @latency behavior specifies a delay that exceeds
+    # the configured max_latency_ms limit.
+    #
+    # @!attribute [r] requested
+    #   @return [Integer] the requested latency in milliseconds
+    #
+    # @!attribute [r] max_allowed
+    #   @return [Integer] the maximum allowed latency in milliseconds
+    #
+    # @example
+    #   # @latency 60000  <- 60 seconds exceeds default 10 second max
+    #   # LatencyLimitError: Latency 60000ms exceeds maximum allowed 10000ms
+    #
+
+    class LatencyLimitError < ResourceLimitError
+      ERROR_CODE = "LATENCY_LIMIT_ERROR"
+      attr_reader :requested, :max_allowed
+
+
+      # Create a new LatencyLimitError
+      #
+      # @param requested [Integer] the requested latency in milliseconds
+      # @param max_allowed [Integer] the configured maximum latency
+      #
+
+      def initialize(requested:, max_allowed:)
+        @requested = requested
+        @max_allowed = max_allowed
+        super(
+          "Latency #{requested}ms exceeds maximum allowed #{max_allowed}ms. " \
+          "Configure via Synthra.configure { |c| c.limits.max_latency_ms = N }"
+        )
+      end
+    end
+
+
+    # Recursion depth exceeds configured maximum
+    #
+    # Raised when nested schema generation exceeds the maximum recursion
+    # depth, which could indicate a circular reference or overly deep nesting.
+    #
+    # @!attribute [r] depth
+    #   @return [Integer] the current recursion depth
+    #
+    # @!attribute [r] max_allowed
+    #   @return [Integer] the maximum allowed recursion depth
+    #
+    # @example
+    #   # Deeply nested: User -> Profile -> Settings -> Preferences -> ...
+    #   # RecursionLimitError: Recursion depth 11 exceeds maximum allowed 10
+    #
+
+    class RecursionLimitError < ResourceLimitError
+      ERROR_CODE = "RECURSION_LIMIT_ERROR"
+      attr_reader :depth, :max_allowed
+
+
+      # Create a new RecursionLimitError
+      #
+      # @param depth [Integer] the current recursion depth
+      # @param max_allowed [Integer] the configured maximum depth
+      #
+
+      def initialize(depth:, max_allowed:)
+        @depth = depth
+        @max_allowed = max_allowed
+        super(
+          "Recursion depth #{depth} exceeds maximum allowed #{max_allowed}. " \
+          "Configure via Synthra.configure { |c| c.limits.max_recursion = N }"
+        )
+      end
+    end
+
+
+    # Array size exceeds configured maximum
+    #
+    # Raised when generating an array with more elements than the
+    # configured max_array_size limit.
+    #
+    # @!attribute [r] size
+    #   @return [Integer] the requested array size
+    #
+    # @!attribute [r] max_allowed
+    #   @return [Integer] the maximum allowed array size
+    #
+    # @example
+    #   # items: array(Item, 10000)  <- exceeds default 1000 max
+    #   # ArraySizeLimitError: Array size 10000 exceeds maximum allowed 1000
+    #
+
+    class ArraySizeLimitError < ResourceLimitError
+      ERROR_CODE = "ARRAY_SIZE_LIMIT_ERROR"
+      attr_reader :size, :max_allowed
+
+
+      # Create a new ArraySizeLimitError
+      #
+      # @param size [Integer] the requested array size
+      # @param max_allowed [Integer] the configured maximum size
+      #
+
+      def initialize(size:, max_allowed:)
+        @size = size
+        @max_allowed = max_allowed
+        super(
+          "Array size #{size} exceeds maximum allowed #{max_allowed}. " \
+          "Configure via Synthra.configure { |c| c.limits.max_array_size = N }"
+        )
+      end
+    end
+
+
+    # Text length exceeds configured maximum
+    #
+    # Raised when generating text with more characters than the
+    # configured max_text_length limit.
+    #
+    # @!attribute [r] length
+    #   @return [Integer] the requested text length
+    #
+    # @!attribute [r] max_allowed
+    #   @return [Integer] the maximum allowed text length
+    #
+    # @example
+    #   # body: text(1..50000)  <- exceeds default 10000 max
+    #   # TextLengthLimitError: Text length 50000 exceeds maximum allowed 10000
+    #
+
+    class TextLengthLimitError < ResourceLimitError
+      ERROR_CODE = "TEXT_LENGTH_LIMIT_ERROR"
+      attr_reader :length, :max_allowed
+
+
+      # Create a new TextLengthLimitError
+      #
+      # @param length [Integer] the requested text length
+      # @param max_allowed [Integer] the maximum allowed text length
+      #
+
+      def initialize(length:, max_allowed:)
+        @length = length
+        @max_allowed = max_allowed
+        super(
+          "Text length #{length} exceeds maximum allowed #{max_allowed}. " \
+          "Configure via Synthra.configure { |c| c.limits.max_text_length = N }"
+        )
+      end
+    end
+
+    # ============================================================================
+
+    # Simulated Errors (Expected behavior for testing)
+    # ============================================================================
+    #
+    # These errors are intentionally raised by behaviors to simulate failure
+    # scenarios. They are expected errors, not bugs, and are useful for testing
+    # error handling in applications that consume generated data.
+
+
+
+    # Base class for simulated behavior errors
+    #
+    # Simulated errors are raised intentionally by behaviors like @failure,
+    # @close_connection, and @simulate_error. They help test how consuming
+    # applications handle various failure scenarios.
+    #
+    # @example Testing error handling
+    #   begin
+    #     api_mock.generate  # Schema has @failure 10%
+    #   rescue Synthra::SimulatedBehaviorError => e
+    #     # This is expected - test that your app handles it correctly
+    #     expect(app.last_error).to eq("Service unavailable")
+    #   end
+    #
+
+    class SimulatedBehaviorError < Error
+      ERROR_CODE = "SIMULATED_BEHAVIOR_ERROR"
+    end
+
+
+    # Simulated failure (service unavailable)
+    #
+    # Raised by the @failure behavior to simulate a service being unavailable.
+    # Useful for testing retry logic and error handling.
+    #
+    # @!attribute [r] probability
+    #   @return [Integer, nil] the configured failure probability percentage
+    #
+    # @example DSL usage
+    #   # API:
+    #   #   @failure 10%  <- 10% chance of SimulatedFailure
+    #   #   id: uuid
+    #
+
+    class SimulatedFailure < SimulatedBehaviorError
+      ERROR_CODE = "SIMULATED_FAILURE"
+      attr_reader :probability
+
+
+      # Create a new SimulatedFailure
+      #
+      # @param probability [Integer, nil] the probability percentage if configured
+      #
+
+      def initialize(probability: nil)
+        @probability = probability
+        message = "Simulated failure"
+        message += " (#{probability}% probability)" if probability
+        super(message)
+      end
+    end
+
+
+    # Simulated connection drop
+    #
+    # Raised by the @close_connection behavior to simulate the connection
+    # being closed unexpectedly. Useful for testing reconnection logic.
+    #
+    # @!attribute [r] probability
+    #   @return [Integer, nil] the configured probability percentage
+    #
+    # @example DSL usage
+    #   # Stream:
+    #   #   @close_connection 5%  <- 5% chance of SimulatedConnectionDrop
+    #   #   data: text
+    #
+
+    class SimulatedConnectionDrop < SimulatedBehaviorError
+      ERROR_CODE = "SIMULATED_CONNECTION_DROP"
+      attr_reader :probability
+
+
+      # Create a new SimulatedConnectionDrop
+      #
+      # @param probability [Integer, nil] the probability percentage if configured
+      #
+
+      def initialize(probability: nil)
+        @probability = probability
+        message = "Simulated connection drop"
+        message += " (#{probability}% probability)" if probability
+        super(message)
+      end
+    end
+
+
+    # Simulated HTTP error
+    #
+    # Raised by the @simulate_error behavior to simulate specific HTTP
+    # error responses. Useful for testing how applications handle various
+    # HTTP status codes.
+    #
+    # @!attribute [r] code
+    #   @return [Integer] the HTTP status code being simulated
+    #
+    # @!attribute [r] probability
+    #   @return [Integer, nil] the configured probability percentage
+    #
+    # @example DSL usage
+    #   # API:
+    #   #   @simulate_error 429:5%  <- 5% chance of 429 Too Many Requests
+    #   #   @simulate_error 500:1%  <- 1% chance of 500 Internal Server Error
+    #   #   id: uuid
+    #
+
+    class SimulatedError < SimulatedBehaviorError
+      ERROR_CODE = "SIMULATED_ERROR"
+      attr_reader :code, :probability
+
+
+      # Create a new SimulatedError
+      #
+      # @param code [Integer] the HTTP status code to simulate
+      # @param probability [Integer, nil] the probability percentage if configured
+      #
+
+      def initialize(code:, probability: nil)
+        @code = code
+        @probability = probability
+        message = "Simulated HTTP error: #{code}"
+        message += " (#{probability}% probability)" if probability
+        super(message)
+      end
+    end
+  end
+
+  # ============================================================================
+
+  # Module-Level Aliases
+  # ============================================================================
+  #
+  # These aliases allow you to reference error classes directly from the
+  # Synthra module without the Errors:: namespace prefix.
+  #
+  # @example Both of these work
+  #   rescue Synthra::Errors::ParseError => e
+  #   rescue Synthra::ParseError => e  # Preferred
+
+
+
+  # @!parse
+  #   # Base error class (alias of Errors::Error)
+  #   class Error < StandardError; end
+
+  Error = Errors::Error
+
+
+  # Parsing errors
+  ParseError = Errors::ParseError
+  SyntaxError = Errors::SyntaxError
+  UnknownTypeError = Errors::UnknownTypeError
+  PathError = Errors::PathError
+  InvalidProbabilityError = Errors::InvalidProbabilityError
+  IndentationError = Errors::IndentationError
+
+  # Simulyra DSL validation errors
+  ValidationError = Errors::ValidationError
+  SchemaError = Errors::SchemaError
+  ApiError = Errors::ApiError
+  ScenarioError = Errors::ScenarioError
+  ReferenceError = Errors::ReferenceError
+  ContextError = Errors::ContextError
+  # Note: Don't alias TypeError as it conflicts with Ruby's built-in TypeError
+
+  # Generation errors
+  GenerationError = Errors::GenerationError
+  UniquenessError = Errors::UniquenessError
+  CyclicReferenceError = Errors::CyclicReferenceError
+  MissingReferenceError = Errors::MissingReferenceError
+  MissingFunctionError = Errors::MissingFunctionError
+  ConditionError = Errors::ConditionError
+
+
+  # Resource limit errors
+  ResourceLimitError = Errors::ResourceLimitError
+  LatencyLimitError = Errors::LatencyLimitError
+  RecursionLimitError = Errors::RecursionLimitError
+  ArraySizeLimitError = Errors::ArraySizeLimitError
+  TextLengthLimitError = Errors::TextLengthLimitError
+
+
+  # Simulated behavior errors
+  SimulatedBehaviorError = Errors::SimulatedBehaviorError
+  SimulatedFailure = Errors::SimulatedFailure
+  SimulatedConnectionDrop = Errors::SimulatedConnectionDrop
+  SimulatedError = Errors::SimulatedError
+end